Como integrar um gateway de pagamento à loja virtual: plugin, API ou checkout hospedado
Compare as formas de integrar um gateway à sua loja online, veja o passo a passo, os testes necessários e os erros de integração que mais derrubam a aprovação.
Há três formas principais de integrar um gateway de pagamento à sua loja: usar um plugin pronto da plataforma, programar via API ou SDK, ou direcionar o cliente a um checkout hospedado pelo provedor. O plugin é o mais rápido, a API dá mais controle, e o checkout hospedado reduz a responsabilidade com dados de cartão. A escolha depende da sua plataforma, da equipe técnica e do quanto você quer personalizar a experiência de compra.
As três formas de integração
| Forma | Como funciona | Vantagens | Pontos de atenção |
|---|---|---|---|
| Plugin ou aplicativo oficial | Você instala na plataforma e informa as chaves de acesso | Rápido, pouca programação | Limitado às funções do plugin; depende de atualizações |
| API ou SDK | O seu sistema chama o provedor por código | Flexível, controle total do fluxo | Exige desenvolvimento, testes e manutenção |
| Checkout hospedado ou link | O cliente é levado à página segura do provedor | Menos responsabilidade com dados de cartão, rápido de lançar | Menos personalização e possível quebra da experiência de marca |
Em lojas pequenas, o plugin costuma ser suficiente. Em operações maiores, a API permite fluxos próprios, como regras de antifraude e roteamento entre provedores.
Antes de começar
- Tenha a conta do provedor aprovada ou, ao menos, o acesso ao ambiente de testes.
- Obtenha as chaves de teste e as de produção, e guarde ambas em local seguro.
- Leia a documentação oficial do provedor e a da sua plataforma.
- Defina meios de pagamento, parcelamento e regras de validade do Pix e do boleto.
- Prepare uma lista de cenários de teste (veja abaixo).
Passo a passo da integração
Passo 1: instale e configure no ambiente de testes
No caso de plugin, instale na loja, informe as chaves de teste e ative os meios de pagamento. Em API, crie as chamadas de criação de cobrança, consulta de status e estorno. Mantenha as chaves em variáveis de ambiente, nunca no código aberto ou em repositórios públicos.
Passo 2: configure os webhooks
Webhooks são notificações que o provedor envia ao seu sistema quando o status de um pagamento muda. Eles são essenciais para Pix e boleto, porque a confirmação chega depois da compra. Cuide de três pontos: verificar a assinatura da notificação para garantir que veio do provedor, responder rapidamente com sucesso e tratar eventos repetidos sem duplicar a baixa do pedido (idempotência).
Passo 3: trate os estados do pagamento
Um pedido pode estar aguardando pagamento, pago, recusado, cancelado, estornado ou em disputa. Garanta que cada estado atualiza o pedido, o estoque e a comunicação com o cliente corretamente. Não libere o produto ou o acesso antes da confirmação do pagamento.
Passo 4: ajuste o checkout
Um checkout simples converte mais. Peça só os dados necessários, ofereça o Pix com destaque, mostre o valor das parcelas e deixe claros o total e os prazos. Valide o CPF ou CNPJ e o formato dos campos, e mostre mensagens de erro compreensíveis.
Passo 5: teste os cenários
| Cenário | Resultado esperado |
|---|---|
| Cartão aprovado | Pedido pago, e-mail de confirmação |
| Cartão recusado | Mensagem clara e possibilidade de tentar outro meio |
| Pix pago | Confirmação por webhook e baixa automática |
| Pix expirado | Pedido cancelado ou reaberto conforme a regra |
| Boleto pago e vencido | Baixa na compensação e cancelamento no vencimento |
| Estorno | Valor devolvido e pedido ajustado |
| Falha de rede | Sem duplicidade de cobrança |
| Webhook repetido | Processamento único |
Passo 6: vá para produção
Troque as chaves de teste pelas de produção, faça uma compra real de baixo valor e confira o repasse. Monitore os primeiros dias.
Erros de integração que mais custam caro
- Cobrança duplicada por clique repetido ou por nova tentativa sem chave de idempotência.
- Pedidos pagos sem baixa porque o webhook falhou ou não foi configurado.
- Pedidos liberados sem pagamento por confiar apenas no retorno do navegador do cliente.
- Chaves expostas em código público ou no navegador.
- Dados do cartão armazenados sem necessidade, ampliando a exposição e as obrigações de segurança.
- Mensagens de erro genéricas que levam o cliente a abandonar a compra.
- Tempo limite curto demais nas chamadas, causando falhas em horários de pico.
Segurança na integração
Use sempre HTTPS. Prefira soluções que mantêm os dados de cartão no ambiente do provedor, como campos hospedados ou tokenização, para reduzir o escopo das exigências do padrão PCI DSS. Restrinja o acesso ao painel com autenticação em dois fatores e permissões por função. Veja o guia de segurança, PCI DSS e LGPD.
Aprovação de pagamentos e integração
A forma como você envia os dados afeta a aprovação. Dados completos do comprador, o uso correto da autenticação do emissor quando exigida e a coerência entre valor, parcelas e descrição aumentam a chance de aprovação. Veja o guia sobre pagamento recusado e aprovação.
Quando contratar ajuda técnica
Se a sua loja tem fluxos complexos (assinaturas, split, múltiplos provedores), vale contratar um desenvolvedor ou agência com experiência em pagamentos. O custo de uma integração mal feita costuma aparecer depois, em vendas perdidas e retrabalho. Para trocas futuras, veja o guia de migração de gateway.
Perguntas frequentes
Preciso programar para integrar um gateway?
Não necessariamente. Plugins e links de pagamento dispensam código. Para sites próprios, a integração via API exige programação.
O que é sandbox?
É um ambiente de testes do provedor, que simula pagamentos sem movimentar dinheiro real. Use-o para validar todos os fluxos antes de ir para produção.
Posso guardar os dados do cartão do cliente?
Em geral, é melhor não guardar. Use a tokenização do provedor, que permite novas cobranças sem armazenar o número do cartão no seu sistema.
Como evitar cobrança duplicada?
Use chaves de idempotência quando a API oferecer, desabilite o botão após o clique e trate corretamente os eventos repetidos de webhook.
Fontes e referências
- PCI Security Standards Council — padrões de segurança para dados de cartão.
- Autoridade Nacional de Proteção de Dados (ANPD) — orientações sobre a LGPD.
- Banco Central do Brasil — regras do Pix e dos pagamentos.
