Hub de Pagamentos: o que é e como usar sem apanhar

Chegou um dia em que a gente tinha uma integração de pagamento pra loja, outra pro delivery e uma terceira pras contas a receber. Três lugares pra configurar credencial, três comportamentos diferentes de retorno e três pessoas que sabiam mexer em uma coisa só. Quando o provedor mudou uma regra, a gente descobriu por reclamação de cliente. O Hub de Pagamentos existe pra isso não acontecer: uma porta só, com todos os provedores atrás dela.

A ideia é velha e continua boa. Em vez de cada módulo saber conversar com cada provedor, todo mundo conversa com uma fachada única. Criar cobrança, consultar status, estornar quando o provedor suporta e baixar o título por origem. O módulo que pede não precisa saber quem vai atender.

O catálogo central reúne 35 operadores entre PSPs, carteiras, adquirentes e bancos. E aqui vai o aviso que eu gostaria de ter recebido: catálogo não é o mesmo que integração pronta.

O que o Hub de Pagamentos entrega de fato

• Catálogo central com 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, estornar quando há suporte e baixar por origem.
• Integração com Foods, contas a receber, assinaturas, loja, boletos, pedidos e ordens de serviço.
• API interna v1/hub/cobranca e consulta de status.

Os drivers efetivamente implementados no código são Mercado Pago, Pagar.me, PagBank, Efi, Banco Inter e Banco do Brasil, cada um conforme os meios que o provedor suporta. O estorno pelo hub está implementado hoje para o Mercado Pago.

Por que centralizar muda a vida de quem opera

A vantagem não aparece no dia da instalação. Aparece no dia em que você quer trocar de provedor. Com integrações espalhadas, trocar significa mexer em cada módulo. Com hub, você configura o novo provedor, ajusta a prioridade e testa. O resto do sistema nem percebe.

A segunda vantagem é auditoria. Quando toda cobrança nasce pelo mesmo caminho, existe um lugar único para responder o que foi cobrado, por qual provedor, com qual status. Antes, essa pergunta exigia três consultas e uma dose de fé.

Configuração por empresa, não por sistema

1. Cadastre as credenciais no ambiente certoTeste e produção separados, sempre. Já vi credencial de produção em ambiente de teste gerar cobrança de verdade num cliente real.
2. Escolha os meios aceitosHabilite só o que você quer receber. Meio habilitado por descuido aparece na fatura no fim do mês.
3. Defina a prioridadeSe houver mais de um provedor, decida quem atende primeiro e o que acontece quando o preferido não responde.
4. Teste o caminho completoCobrança de valor baixo, pagamento real, retorno, baixa do título. O teste que importa é o que chega até o título fechado.
5. Proteja a API internaA proteção Bearer da API interna depende de hub.apiToken. Mantenha esse token configurado em qualquer ambiente exposto.

A API interna e quem deveria usar

Existe uma API interna, v1/hub/cobranca, com consulta de status. Ela serve para sistemas próprios que precisam criar cobrança sem passar pela tela. É um recurso poderoso e por isso mesmo merece cuidado: token configurado, ambiente controlado e alguém responsável por revisar quem tem acesso.

O controle de quem pode configurar provedor e ver credencial faz parte das definições gerais, tratadas no módulo de ERP e gestão. Credencial de pagamento é o tipo de dado que não deveria estar visível pra equipe inteira.

O retorno é onde mora o risco

Criar cobrança é a parte fácil. Receber a confirmação e transformar isso em título baixado, uma única vez, é a parte que quebra. O hub trabalha com webhooks idempotentes e reconfirmação server-to-server dos estados críticos, pago e estornado. Traduzindo: quando o provedor avisa que pagou, o sistema confere direto com o provedor antes de acreditar.

Isso parece paranoia até você receber a primeira notificação repetida ou a primeira notificação de origem duvidosa. O detalhe de como isso funciona está em webhooks de pagamento idempotentes, e o efeito no título em baixa automática de títulos por origem.

Onde eu vi projeto se enrolar

• Prometer um provedor do catálogo que ainda não tem driver implementado.
• Configurar credencial de produção antes de terminar o teste.
• Habilitar todos os meios de pagamento e descobrir o custo na fatura.
• Esquecer o token da API interna em ambiente exposto.
• Não definir quem trata estorno e contestação no dia a dia.

O último item é o que mais dói depois. Cobrança digital funciona sozinha até o dia em que não funciona, e nesse dia alguém precisa saber o que fazer sem improvisar. Vale combinar isso antes de ligar o primeiro provedor.

Por onde começar sem se perder

Comece por um provedor, um meio e um módulo. Rode assim por algumas semanas até a rotina estar redonda, e só então acrescente. A tentação de ligar tudo no primeiro dia é grande, e o preço dela é não saber qual peça está falhando quando algo falha.

A porta de entrada mais confortável costuma ser cobrança PIX e link de pagamento amarrada aos títulos de contas a pagar e a receber. Quem tem volume vindo de food service deve olhar como a cobrança se comporta em food service antes de escalar.