Pagamento online na loja virtual: o Hub sem cair em cilada
O que separa um meio de pagamento que está na lista de um meio que realmente cobra o seu cliente amanhã de manhã.
Escolhi o provedor pelo nome. Abri a lista, vi uma marca conhecida, marquei e fui embora feliz configurar outra coisa. Duas semanas depois, com data de abertura marcada, descobri que aquele operador dependia de convênio e homologação externa que nem tinham começado. Foi assim que eu aprendi como funciona de verdade o pagamento online na loja virtual.
O Hub de Pagamentos é a fachada única da plataforma para criar cobrança, consultar status, estornar quando o driver suporta e dar baixa por origem. A loja é uma das origens ligadas nele, junto com contas a receber, assinaturas, boletos, pedidos e ordens de serviço.
Isso evita que cada canal invente sua própria integração financeira. A loja pede a cobrança, o Hub escolhe o driver conforme a configuração da empresa e o retorno volta pelo mesmo caminho para todo mundo. Se a loja ainda nem existe, comece por configurar a loja passo a passo.
O que o Hub entrega ao pagamento online na loja virtual
- Catálogo central de 35 operadores entre PSPs, carteiras, adquirentes e bancos.
- Configuração de credenciais, ambiente, meios aceitos e prioridade por empresa.
- Fachada única para criar cobrança, consultar status e dar baixa por origem.
- Estorno quando o driver do provedor suporta.
- Webhooks idempotentes com reconfirmação server-to-server dos estados pago e estornado.
- API interna de cobrança e consulta de status.
Catálogo e driver não são a mesma coisa
Essa é a distinção que me custou o cronograma. O catálogo lista 35 operadores, mas os drivers escritos no código são Mercado Pago, Pagar.me, PagBank, Efi, Banco Inter e Banco do Brasil, conforme os meios que cada provedor suporta. O estorno, hoje, está implementado para Mercado Pago.
Os demais nomes da lista não são drivers completos. Eles dependem de convênio, credenciais, implementação, ativação e homologação externa. Marcar um deles e esperar funcionar na segunda-feira é a causa mais comum de frustração no lançamento. Já vi isso acontecer três vezes.
| Item | Como está hoje | O que isso significa para você |
|---|---|---|
| Catálogo de operadores | 35 opções cadastradas | Serve de referência, não de garantia |
| Drivers implementados | Mercado Pago, Pagar.me, PagBank, Efi, Inter, BB | Caminho seguro para abrir |
| Estorno | Implementado para Mercado Pago | Nos outros, trate direto com o provedor |
| Demais operadores | Dependem de convênio e homologação | Prazo fora do seu controle |
Configuração, na ordem
- Escolha o operadorPara abrir, prefira um provedor com driver já implementado no Hub. Ambição vem depois.
- Cadastre credenciais e confirme o ambienteCredencial de teste em produção gera cobrança que nunca confirma. Confira duas vezes, é rápido.
- Defina os meios aceitosHabilite apenas os meios que o provedor suporta e que você consegue conciliar depois.
- Ajuste a prioridade por empresaCom mais de um operador configurado, diga qual é o preferencial.
- Ligue os meios na lojaAs formas de pagamento da loja precisam bater com o que está ativo no Hub.
- Teste de ponta a pontaPedido real de valor baixo, cobrança criada, status mudando. Sem isso você não sabe se funciona.
Webhook idempotente, explicado sem enrolação
Os webhooks do Hub são idempotentes. Quer dizer que a mesma notificação chegando duas vezes não produz efeito dobrado. Junto disso existe a reconfirmação server-to-server dos estados críticos pago e estornado, ou seja, o sistema pergunta ao provedor em vez de acreditar apenas no que recebeu.
Isso protege contra dois clássicos do comércio eletrônico: notificação repetida gerando baixa duplicada e notificação forjada mudando o estado de um pedido. Nada disso, porém, dispensa você de olhar os pedidos que ficam presos no meio do caminho.
A API interna e o token que ninguém lembra
O Hub expõe uma API interna de cobrança e consulta de status, protegida por Bearer, e essa proteção depende de um token configurado. Ambiente publicado sem esse token é pendência de bloqueio, não item de melhoria. Eu trato isso na mesma linha em que trato senha de banco.
- Token de proteção da API interna configurado no ambiente exposto.
- Credenciais do operador cadastradas no ambiente certo.
- Meios ligados na loja compatíveis com os meios aceitos no Hub.
- Teste de cobrança real concluído, com mudança de status confirmada.
O que chega no financeiro
A cobrança criada pela loja usa a mesma infraestrutura de baixa por origem que as outras frentes da plataforma. A conciliação fica mais simples porque a venda online deixa de ser um evento à parte e vira mais uma origem tratada pelo mesmo mecanismo. O acompanhamento contábil segue no módulo financeiro.
Próximo passo
Com o pagamento validado, revise o resto da finalização em carrinho e checkout e confirme a comunicação de estados em status do pedido e rastreamento. Se travar alguma coisa, os erros comuns da loja cobrem quase tudo.