Integração com gateway de pagamento: o que conferir antes

A integração com o gateway costuma ser a parte do projeto que todo mundo acha resolvida. O provedor tem documentação, um SDK, um ambiente de testes, e em poucos dias o primeiro pagamento aprovado aparece na tela. A equipe comemora, o sistema vai ao ar.

Os problemas chegam semanas depois. Um cliente pagou o Pix e o pedido continua "aguardando pagamento". Um estorno feito no painel do gateway não refletiu no sistema, e o produto foi despachado mesmo assim. O financeiro fecha o mês e o valor recebido não bate com o vendido, sem que ninguém consiga dizer quais transações explicam a diferença.

Nada disso é defeito do gateway. É desenho que ficou de fora. Uma integração com gateway de pagamento bem feita vai além de aprovar a primeira cobrança: ela confirma o pagamento por webhook validado, trata estornos e contestações dentro do sistema, concilia o vendido com o que caiu na conta e mantém o provedor isolado numa camada própria, para que trocá-lo não exija reescrever o sistema. Este texto lista o que avaliar e implementar antes de o dinheiro começar a circular.

O checklist em uma página

Para quem quer a resposta curta, estes são os pontos que uma integração de pagamento séria precisa cobrir. Cada um é detalhado nas seções seguintes.

1. Papel do provedor: gateway, subadquirente ou adquirente, e o que isso muda em contrato, repasse e suporte.
2. Meios de pagamento: cartão (com tokenização), Pix e boleto, cada um com seu ciclo de vida.
3. Split: se a plataforma recebe em nome de terceiros, quem recebe quanto e quem arca com o estorno.
4. Confirmação confiável: webhooks validados, idempotentes e com consulta de reforço.
5. Caminho inverso: cancelamento, estorno parcial, chargeback e devolução de Pix.
6. Conciliação: vendido contra autorizado, autorizado contra liquidado, liquidado contra extrato.
7. Segurança: nenhum dado de cartão trafegando ou guardado no seu sistema, credenciais protegidas.
8. Troca de provedor: uma camada própria que isola o gateway do resto do sistema.

Se algum desses itens não tem dono nem resposta escrita, ele vai virar trabalho manual depois.

Gateway, subadquirente e adquirente: diferenças práticas

Os nomes se misturam no mercado, mas a diferença importa porque define quem é responsável por quê.

Na prática, muitos provedores acumulam papéis: oferecem a API (gateway), recebem em nome do lojista (subadquirente) e ainda emitem boleto e Pix. Para o Pix, compare também Pix direto no banco ou gateway. Antes de assinar, vale responder:

• Quem recebe o dinheiro primeiro, e em que conta ele fica até o repasse.
• Qual o prazo de repasse de cada meio e se existe antecipação.
• Que relatórios e arquivos de liquidação o provedor entrega, e em que formato.
• Como funciona o suporte quando uma transação fica presa entre "aprovada" e "liquidada".

As taxas também entram na decisão, mas comparar só a taxa é o erro mais comum. Um provedor com relatório de liquidação ruim pode sair mais caro em horas de conferência do que a diferença de taxa.

Meios de pagamento e experiência do cliente

Cada meio tem um ciclo de vida diferente, e o sistema precisa modelar os três sem tratá-los como variações do mesmo fluxo.

Cartão de crédito e débito

O cartão passa por autorização, eventual análise antifraude e captura. Em alguns negócios faz sentido autorizar agora e capturar depois, por exemplo quando o pedido só é confirmado após checar estoque ou disponibilidade de agenda. Autorização não capturada expira, e o sistema precisa saber disso.

O ponto mais importante: o número do cartão não deve passar pelo seu servidor. O formulário de pagamento do provedor, ou um componente dele embutido na página, transforma o cartão em um token, e é esse token que o seu sistema usa. Isso reduz drasticamente o escopo de conformidade com o padrão PCI DSS e o risco de vazamento. Para cobrança recorrente, guarde o token do cartão, nunca o cartão.

Pix

O Pix confirma em segundos, o que muda a expectativa do cliente: ele paga e quer ver o pedido aprovado na hora. A integração precisa de:

• Cobrança com identificador único por pedido, para casar o pagamento com quem pagou.
• Prazo de expiração do QR Code alinhado à reserva de estoque ou de vaga.
• Regra para pagamento fora do esperado: Pix que chega quando o pedido já foi cancelado ou a reserva já foi liberada, valor diferente do cobrado ou pagamento duplicado. Conforme o tipo de cobrança e o provedor, esses casos acontecem, e o sistema precisa decidir se aceita, devolve ou aciona o atendimento.

Para assinaturas e mensalidades, o Pix Automático muda o desenho da cobrança; os detalhes estão em cobrança recorrente com Pix Automático.

Boleto

O boleto é o meio mais lento: a confirmação chega depois da compensação, em dias úteis. O pedido fica pendente mais tempo, a reserva precisa durar mais e uma parte dos boletos simplesmente não é paga. O sistema precisa expirar esses pedidos e liberar o que estava reservado, sem intervenção manual.

Split de pagamento em plataformas e marketplaces

Quando a sua plataforma vende produtos ou serviços de terceiros (fornecedores, prestadores, franqueados), entra o split: o pagamento do cliente é dividido entre as partes no momento da transação, e cada uma recebe direto a sua parte.

O split resolve o problema de receber tudo na conta da plataforma e repassar depois, o que pode trazer riscos fiscais e operacionais (o tratamento tributário deve ser validado com o contador). Mas ele exige decisões antes do código:

• Regra de divisão: percentual, valor fixo ou combinação, e se varia por produto, categoria ou vendedor.
• Quem paga a taxa do provedor: a plataforma, o vendedor ou rateio.
• Quem absorve estorno e chargeback: se o cliente contesta uma compra, de qual parte sai o valor devolvido.
• Cadastro dos recebedores: cada vendedor precisa ser cadastrado e validado no provedor antes de receber, e isso tem prazo.
• Frete e comissão: entram no split ou ficam com a plataforma.

A regra de estorno é a que mais gera conflito, porque costuma ser lembrada só no primeiro chargeback. Se você está estruturando uma plataforma desse tipo, o texto sobre como desenvolver um marketplace B2B cobre o restante do desenho.

Webhooks e confirmação de pagamento confiável

O webhook é a notificação que o provedor envia ao seu sistema quando algo acontece: pagamento aprovado, recusado, estornado, contestado. É aqui que nasce a maioria dos pedidos "pagos e não liberados".

O que a integração precisa garantir:

• Validar a origem. Todo webhook deve ser autenticado, por assinatura ou segredo compartilhado, conforme o provedor oferece. Um endpoint que aceita qualquer requisição permite que alguém marque pedidos como pagos sem pagar. Esse e outros descuidos comuns estão em segurança de APIs: erros comuns.
• Idempotência. O provedor reenvia a notificação quando não recebe confirmação a tempo. Receber o mesmo evento três vezes precisa ter o mesmo efeito que recebê-lo uma vez: um pedido liberado, um e-mail enviado, uma baixa no financeiro.
• Responder rápido e processar depois. O endpoint grava o evento e responde; o processamento pesado vai para uma fila. Assim uma lentidão interna não faz o provedor reenviar tudo.
• Ordem dos eventos. Um "estornado" pode chegar antes de um "aprovado" atrasado. O sistema compara o estado e a data do evento antes de mudar o pedido de status.
• Consulta de reforço. Webhook pode falhar. Uma rotina periódica consulta no provedor as transações pendentes há mais tempo do que o normal e corrige o status. Nunca dependa só da notificação.
• Registro completo. Guarde cada evento recebido, com o conteúdo original, para auditoria e para reprocessar quando necessário.

Uma regra que evita muita confusão: o retorno da tela de pagamento não confirma pagamento. O cliente pode fechar o navegador, perder a conexão ou voltar para a página por outro caminho. Quem confirma é o provedor, pelo webhook ou pela consulta.

Estornos, chargebacks e cancelamentos

O caminho inverso costuma ficar para depois e acaba resolvido no painel do provedor, fora do sistema. Isso cria divergência imediata: o dinheiro voltou, mas o pedido, o estoque e o financeiro não sabem.

Três cuidados práticos:

• Estorno parcial precisa saber quais itens foram devolvidos, não só o valor, para que estoque e nota fiscal acompanhem. O tratamento fiscal da devolução deve ser validado com o contador.
• Chargeback tem prazo para resposta, e a defesa depende de evidências: comprovante de entrega, registro de acesso, comunicação com o cliente. Se o sistema não guarda isso de forma organizada, a contestação é perdida por falta de documento.
• Estorno só pelo sistema. Se a equipe estorna direto no painel do provedor, o webhook precisa trazer essa informação de volta e o sistema tem de tratá-la como qualquer outro estorno.

Conciliação do que foi vendido x recebido

Pagamento aprovado não é dinheiro na conta. Entre os dois existem taxas, parcelamento, antecipação, prazos de repasse, estornos e chargebacks descontados de repasses futuros. A conciliação de pagamentos responde a três perguntas, em camadas:

1. Vendido x autorizado: cada pedido tem uma transação aprovada correspondente, e cada transação aprovada tem um pedido.
2. Autorizado x liquidado: o provedor repassou o que devia, na data prevista, com a taxa contratada.
3. Liquidado x extrato: o repasse caiu de fato na conta bancária.

Para isso, o sistema precisa guardar o identificador da transação no provedor junto com o pedido e importar os relatórios ou arquivos de liquidação que o provedor disponibiliza. Divergência vira alerta com dono, não descoberta no fechamento. A terceira camada, a do extrato, está detalhada em conciliação bancária automática.

Uma pergunta que vale fazer ao provedor antes do contrato: o relatório de liquidação traz o identificador do pedido que o seu sistema enviou? Sem isso, a conciliação depende de cruzar valor e data, o que falha com parcelamento e com vendas de mesmo valor no mesmo dia.

Trocar de gateway sem reescrever o sistema

Empresas trocam de provedor por taxa, por instabilidade, por um meio de pagamento novo ou para ter um segundo provedor de contingência. Quando o código do gateway está espalhado pelo sistema (no checkout, no financeiro, na rotina de assinaturas), a troca vira um projeto inteiro.

O desenho que evita isso é uma camada de pagamentos própria, que fala com o resto do sistema numa linguagem interna (cobrar, capturar, estornar, consultar) e traduz para a API de cada provedor por meio de um adaptador. Na prática:

• Status internos próprios, como pendente, autorizado, pago, estornado e contestado, mapeados a partir dos status de cada provedor.
• Tabela de transações própria, com o identificador do provedor como referência, não como chave principal.
• Webhooks recebidos por adaptador, convertidos em eventos internos antes de chegar ao pedido.
• Tokens de cartão como ponto de atenção: o token pertence ao provedor. Migrar assinaturas com cartão salvo costuma exigir um processo de portabilidade apoiado pelos dois provedores ou um novo cadastro do cartão pelo cliente. Vale perguntar sobre isso já na contratação.

Essa camada também permite rotear transações entre provedores, por meio de pagamento ou em caso de falha. É uma decisão de arquitetura de software que custa pouco no começo e muito depois.

Critérios para validar antes de ir ao ar

Antes de liberar o primeiro cliente real, rode este roteiro no ambiente de testes do provedor e, depois, com transações reais de baixo valor:

• Pagamento aprovado em cada meio, com o pedido liberado sem intervenção.
• Cartão recusado, com mensagem clara e possibilidade de tentar de novo.
• Pix pago depois de o pedido ser cancelado ou a reserva expirar.
• Boleto não pago, com expiração e liberação da reserva.
• O mesmo webhook enviado várias vezes, sem duplicar efeitos.
• Webhook que não chega, corrigido pela consulta de reforço.
• Estorno total e parcial iniciados pelo sistema e pelo painel do provedor.
• Split com estorno, conferindo de qual parte saiu o valor.
• Relatório de liquidação importado e conciliado com os pedidos do período.
• Logs e telas sem dado de cartão e sem mais dado pessoal do que o necessário, em linha com a LGPD.

Se algum item não passar, ele vai aparecer em produção, só que com cliente e dinheiro reais.

Perguntas frequentes

O que é chargeback?

Chargeback é a contestação de uma compra feita pelo titular do cartão junto ao emissor, que pode levar à devolução do valor ao cliente e ao débito na conta do lojista. A empresa tem prazo para se defender, e a defesa do chargeback depende de evidências organizadas, como comprovante de entrega, registros de acesso e a comunicação com o cliente.

Preciso me preocupar com PCI DSS ao integrar um gateway?

Sim, mas o tamanho da preocupação depende de como o cartão é capturado. Quando o formulário ou componente do gateway transforma o cartão em token e o número nunca passa pelo servidor da empresa, o escopo de conformidade com o PCI DSS fica muito menor. Guardar ou trafegar dados de cartão no próprio sistema amplia as exigências e o risco.

Quanto tempo leva para integrar um gateway de pagamento?

O primeiro pagamento aprovado em ambiente de testes pode sair rápido, mas uma integração com gateway de pagamento pronta para produção leva mais, porque inclui webhooks validados, estornos, chargebacks, split e conciliação. O prazo real depende de quantos meios de pagamento, provedores e regras de divisão estão envolvidos, e só fica firme depois do diagnóstico.

Dá para usar dois gateways de pagamento ao mesmo tempo?

Sim, desde que o sistema tenha uma camada de pagamentos própria, com status internos e um adaptador para cada provedor. Com esse desenho, a empresa pode usar dois gateways de pagamento, rotear transações por meio de pagamento, manter um segundo provedor como contingência e trocar de fornecedor sem reescrever o checkout, o financeiro e as assinaturas.

Como a Pervian Tech trabalha pagamentos

Na Pervian Tech, uma integração de pagamento começa pelo mapa do dinheiro: quais meios a empresa aceita, quem recebe, como o valor é dividido, como o financeiro confere e o que hoje é resolvido no painel do provedor ou em planilha. A partir daí desenhamos a camada de pagamentos sob medida, com webhooks idempotentes, caminho inverso completo e conciliação desde o primeiro dia, aproveitando os recursos do provedor escolhido sem prender o sistema a ele. Esse trabalho faz parte da nossa atuação em integração de sistemas.

O diagnóstico inicial é gratuito, e o cronograma é definido depois dele, porque depende de quantos meios, provedores e regras de split estão envolvidos. O investimento é sob consulta. Se a sua empresa está escolhendo um gateway ou já convive com pedidos pagos que não aparecem como pagos, conte como o pagamento funciona hoje.