Como integrar um gateway de pagamento no site

Integrar um gateway é conectar seu site ou app ao provedor para autorizar e confirmar pagamentos. O fluxo típico: criar conta, obter chaves, testar no sandbox, montar a UI (redirect, transparente ou link), tratar webhooks e só então ir a produção. Antes de codar, escolha meios, documentação e como o provedor reduz o escopo de dados do cartão (PCI).

Segurança e escopo de cartão: o que é PCI DSS. Este guia é o caminho ponta a ponta; a documentação viva fica em /desenvolvedores.

O que significa “integrar um gateway”

Na prática, o seu sistema:

Cria uma cobrança (Pix, boleto, cartão ou checkout)
Mostra ao cliente o QR, o boleto, os campos de cartão ou o link
Recebe a confirmação (webhook e/ou consulta de status)
Libera o pedido, a assinatura ou o acesso

Não é “colar um botão” sem backend: mesmo com link de pagamento, alguém precisa saber quando a cobrança foi paga.

Antes de codar — escolher o gateway

Checklist rápido antes da primeira chave de API:

Meios no Brasil — Pix, boleto, cartão (sob consulta na AbacatePay)
Taxas e prazo — no Pix da AbacatePay, R$ 0,80 fixo com saldo na hora; tabela: /pricing
Documentação — endpoints, sandbox, webhooks
Modelo de checkout — transparente, redirect ou link
PCI / tokenização — o PAN precisa passar pelo seu servidor? Guia: o que é PCI DSS e tokenização de cartão

Decisão de produto: como escolher um gateway de pagamento. Comparativo de APIs: melhores APIs de pagamento no Brasil.

Passo a passo genérico

Conta — cadastro e verificação (na AbacatePay: CNPJ; MEI serve).
Chaves de API — teste e produção separadas.
Sandbox / modo de teste — simule pagamento sem dinheiro real: como testar o gateway no sandbox.
UI de pagamento — redirect, checkout transparente ou link.
Backend — criar cobrança, guardar IDs, tratar erros.
Webhooks — endpoint HTTPS, secret e assinatura: o que é webhook de pagamento.
Testes — pagamento, falha, reembolso, idempotência do id do evento.
Produção — chaves de prod, URL final do webhook, monitoramento.

O tempo depende da stack e do escopo (só Pix vs Pix+cartão+assinatura). Não há SLA de “X horas” neste guia — siga a documentação atual.

Dois caminhos: plataforma ou API própria

Conector / plataforma

Se a loja já roda em plataforma listada em /integracoes (e-commerce, automação, SDKs), o caminho pode ser o conector ou o acompanhamento com o time — sem reinventar o checkout do zero.

API própria

Controle total no seu código: /desenvolvedores, /api-pix e /checkout. Ideal para SaaS, app e loja com front próprio.

Checkout transparente vs redirect vs link

Modelo	Quando usar
Link de pagamento	Cobrança rápida, WhatsApp, time comercial — /link-de-pagamento
Redirect	Você aceita o cliente sair para a página do provedor
Checkout transparente	Pagamento no seu domínio, com a sua marca — /checkout

Comparativo editorial: link de pagamento ou checkout transparente. Dá para começar no link e evoluir para API depois.

Pix, boleto e cartão na mesma integração

Trate cada meio pelo status e pelo webhook, não por “polling eterno”.

Pix — QR dinâmico, confirmação automática: /pix, como gerar QR Code Pix via API, confirmar pagamento Pix automaticamente, /api-pix.
Boleto — geração sem taxa até o pagamento; mínimo R$ 5,00; vencimento padrão em 3 dias úteis (até 365 dias). Não é método de assinatura; sem carnê, boleto recorrente, desconto por antecipação ou split no boleto. Produto: /boleto. Taxa quando pago: R$ 2,50.
Cartão — ativado sob consulta; tokenização no navegador. Produto: /cartao.

Eventos que mais importam (tabela oficial das docs de webhooks): checkout.completed / refunded / disputed, transparent.completed / refunded / disputed, subscription.completed / cancelled / renewed, além de saque e Pix de chave fixa. Use só os nomes da tabela oficial.

Segurança do webhook: secret na URL e HMAC-SHA256 no header X-Webhook-Signature. Responda 2xx em até 30 segundos; 410 Gone desativa o webhook; redirects 3xx não são seguidos — cadastre a URL final.

Fale com o time sobre integração e go-live.

Segurança mínima

HTTPS em site, API e webhook
Nunca logar PAN, CVV ou dados completos de cartão
Tokenização — tokenização de cartão
3DS e antifraude no cartão — /3ds, /antifraude, o que é 3D Secure
PCI — entenda o escopo: o que é PCI DSS

Este guia não afirma certificação PCI DSS da AbacatePay. O objetivo é reduzir a exposição do PAN e seguir a doc.

Como fazer na AbacatePay

Siga a documentação atual (ela muda; não cole snippet desatualizado neste post):

Conta e verificação em app.abacatepay.com
Hub e SDKs: /desenvolvedores
Pix por API: /api-pix
Checkout transparente: /checkout
Catálogo de conectores: /integracoes
Webhooks: docs de webhooks
Taxas: Pix R$ 0,80; boleto R$ 2,50; cartão sob consulta — /pricing

E-commerce e Pix na loja: Pix no e-commerce.

Checklist de go-live

Chaves de produção (não as de teste)
Webhook HTTPS na URL final (sem redirect 3xx)
Validação de secret + X-Webhook-Signature
Idempotência pelo id do evento
Teste de pagamento Pix (e boleto/cartão, se contratados)
Teste de reembolso / disputa se o fluxo existir
Monitoramento de falhas 4xx/5xx no endpoint
Meios e taxas conferidos em /pricing

Perguntas frequentes

Preciso ser desenvolvedor para integrar?

Para API e webhook, sim (ou um time técnico). Dá para começar sem código pesado com link de pagamento ou fluxos prontos de /checkout — e evoluir depois.

Quanto tempo leva uma integração básica de Pix?

Varia com a stack: de algumas horas a poucos dias é comum para um Pix com webhook. Não há prazo garantido — use o sandbox e a documentação atual.

O que é sandbox?

Ambiente de teste com chaves de teste e eventos simulados, para validar cobrança e webhook sem dinheiro real. Guia: sandbox AbacatePay.

Webhook é obrigatório?

Fortemente recomendado para confirmação automática. Sem webhook, você depende de polling ou conferência manual. Guia: o que é webhook de pagamento.

Consigo começar só com link de pagamento e depois ir para API?

Sim. Muitos times começam no link, validam o meio e o operacional, e só então montam checkout transparente ou API Pix.

Integração no app mobile é diferente?

Os princípios são os mesmos (chaves, cobrança, webhook, nunca logar PAN). SDKs e detalhes: /desenvolvedores e a documentação viva — sem lista inventada de SDKs aqui.

Onde entra PCI DSS?

Na escolha do modelo de integração e na forma como o cartão é coletado. Guia: o que é PCI DSS.