O que é gateway de pagamento e como integrar ao seu sistema?

Gateway, adquirente e intermediador: quem faz o quê

Um pagamento com cartão passa por várias empresas, e o nome comercial de um provedor nem sempre diz qual papel ele cumpre. Saber quem faz o quê explica as taxas, o prazo de repasse e quem responde quando algo dá errado.

• Gateway: A camada de tecnologia que recebe os dados do checkout, aplica o antifraude contratado e encaminha a transação; o gateway puro não movimenta o dinheiro da venda.
• Adquirente: A instituição que credencia a empresa a aceitar cartões, captura as vendas aprovadas e repassa o valor, descontadas as taxas.
• Intermediador ou subadquirente: Recebe o pagamento em nome da empresa e repassa depois, com cadastro simples e as taxas e os prazos que ele define; muitos provedores vendidos como gateway no Brasil atuam assim.
• Emissor e bandeira: O banco que emitiu o cartão aprova ou recusa a compra, e a bandeira define as regras da rede.
• Pix e boleto: O Pix é o pagamento instantâneo do Banco Central, e o boleto é compensado pela rede bancária; nos dois, o gateway ou o banco gera a cobrança e avisa quando ela é paga.

Como funciona uma transação, do checkout à conciliação

1. Checkout: O cliente escolhe a forma de pagamento; os dados do cartão vão direto para o gateway, que devolve um token no lugar do número.
2. Autorização: O gateway envia a transação ao adquirente, que consulta o emissor pela bandeira; a resposta, aprovada ou recusada, volta em segundos.
3. Captura: A venda aprovada é confirmada na hora ou depois, por exemplo quando o pedido é faturado; antes da captura, a autorização pode ser cancelada.
4. Notificação: O gateway avisa o seu sistema por webhook a cada mudança de status, como paga, recusada, estornada ou contestada.
5. Liquidação e repasse: O valor chega à conta da empresa no prazo do contrato, descontadas as taxas; no Pix, a transferência é liquidada em segundos.
6. Conciliação: Cada pedido é cruzado com o valor recebido, as taxas e o repasse, e o que não fecha vira exceção para o financeiro.

No Pix e no boleto não há dados de cartão: a integração cria a cobrança por API, recebe o QR Code ou a linha digitável e espera o webhook de pagamento. Para o Pix, o Banco Central padronizou a API Pix, que as instituições participantes usam quando oferecem integração por API aos clientes.

Formas de integrar: checkout hospedado, campos incorporados ou API

A forma de integrar define a experiência do cliente, o esforço de desenvolvimento e a parte do PCI DSS, a norma de segurança de dados de cartão, que fica com a empresa. Em linhas gerais, quanto menos o seu site toca nos dados do cartão, menor o escopo.

A validação de conformidade é feita pela empresa junto ao adquirente ou ao provedor. O papel da integração é escolher a forma que mantém esse trabalho pequeno sem prejudicar a conversão.

Integrar o gateway ao ERP: pedidos, estornos, repasses e conciliação

O pagamento aprovado é metade do trabalho. O financeiro sente o que acontece depois, no ERP, e é ali que uma integração incompleta vira planilha.

• Pedido: O status do pagamento atualiza o pedido, e o ERP libera faturamento e expedição só quando a cobrança é confirmada.
• Estornos e contestações: O estorno total ou parcial e o chargeback, a contestação feita pelo dono do cartão, voltam ao ERP como lançamentos ligados ao pedido original.
• Repasses e taxas: Cada repasse traz o valor bruto, as taxas e o líquido, e o ERP precisa registrar os três, não só o que caiu na conta.
• Conciliação: O cruzamento automático entre pedidos, recebimentos e extrato aponta só as divergências, como uma taxa inesperada ou um repasse em atraso.

No Mahout ERP, cliente da Master Timm, o hub de integrações reunia Moip/Wirecard e Asaas nos pagamentos, Melhor Envio no frete e conciliação bancária por arquivos OFX. Também contribuímos com os módulos oficiais PagSeguro e Mercado Pago para Magento 2, que somam 214 mil instalações.

Erros que mais derrubam integrações de pagamento

• Webhook sem validação: Qualquer um pode chamar o endereço; confira a assinatura ou consulte o status na API antes de dar baixa no pedido.
• Retentativa que duplica: Um timeout não quer dizer recusa, e reenviar a cobrança sem chave de idempotência pode cobrar o cliente duas vezes.
• Eventos repetidos ou fora de ordem: O mesmo webhook pode chegar duas vezes, e o de estorno, antes do de pagamento; o sistema decide pelo status atual da transação.
• Teste só do caminho feliz: Recusa, timeout, estorno parcial e contestação precisam estar nos testes do ambiente de homologação antes da produção.
• Sem log por transação: Quando o cliente reclama, ninguém consegue mostrar o que foi enviado e o que o provedor respondeu.

Como escolher um gateway: o que pesar além da taxa

O custo de um gateway raramente é um número só. Em geral, há um percentual por venda no cartão, que muda com o parcelamento, tarifas fixas por Pix ou boleto em alguns provedores, o custo de antecipar recebíveis e uma tarifa por contestação. Compare o custo total com o seu mix de vendas, não a taxa do anúncio.

• Meios de pagamento: Pix, cartão à vista e parcelado, boleto e as carteiras digitais que o seu cliente usa.
• Prazo de repasse: Quando o dinheiro chega e quanto custa adiantá-lo.
• API e homologação: Documentação, ambiente de testes com casos de erro, webhooks assinados e suporte a chaves de idempotência.
• Split de pagamento: Necessário se a operação é um marketplace e cada venda se divide entre vendedores.
• Antifraude e contestações: O que o provedor cobre e quem arca com o prejuízo de um chargeback.
• Saída: Como levar os cartões tokenizados e o histórico se um dia trocar de provedor.