Integração por API de pagamentos: guia para programadores
Integrar pagamentos deve parecer usar uma API bem documentada - não um protocolo SOAP opaco dos anos 2000. Segue o roteiro: interface segura, webhooks fiáveis e ambiente de testes (sandbox) sólido.
Dos redirecionamentos externos ao modelo JSON atual
As arquiteturas atuais (RoxPay, Stripe ou similares) permitem componentes incorporados na sua página ou campos sensíveis alojados pelo fornecedor; o cliente não abandona visualmente o seu site e os dados sensíveis são tokenizados do lado do PSP - isto reduz fortemente o âmbito PCI desde que esteja bem implementado.
Escolha o modo de integração
1) Interface pré-construída ou campos alojados (rápido): menor âmbito PCI (muitas vezes SAQ A ou equivalente).
2) Servidor a servidor com dados de cartão em claro: máxima personalização, mas âmbito PCI grande (SAQ‑D e auditorias) - só para necessidade forte e equipa de segurança capacitada.
3) Página de pagamento alojada no PSP: redirecionamento para o site da passarela - rápido de lançar e com menor carga PCI, mas com menor controlo sobre o fluxo visual.
Regra de ouro: webhooks em primeiro lugar
Pagamentos são assíncronos: um desafio 3DS pode demorar minutos. A interface deve mostrar estado «pendente» enquanto o backend confirma com um POST assinado do gateway (por exemplo evento de pagamento concluído). Não confie apenas na resposta imediata da primeira chamada HTTP.
Ambiente de testes e idempotência
Use sempre um ambiente de testes com números de cartão sintéticos que cubram fundos insuficientes, 3DS anulado e falhas de rede.
Um identificador de idempotência evita cobrança dupla quando o seu servidor repete o mesmo POST por timeout - é indispensável em produção.
Perguntas frequentes
Preciso mesmo de PCI DSS?
Se não trata dados de cartão PAN no seu lado (usa iframes ou componentes da passarela), a maior parte dos requisitos PCI recai sobre o PSP; preenche questionários mais leves. Se o servidor armazena ou transmite PAN completos sem tokenização forte, o âmbito dispara.
Quanto tempo leva uma integração sólida?
Com uma API REST moderna e uma equipa técnica experiente, uma integração baseada em campos alojados e webhooks pode ficar estável em menos de dois dias úteis. Integrações bancárias antigas ainda demoram muitas vezes semanas.
Também pode gostar de
Gateway de pagamento de alto risco
Processamento seguro para setores de alto risco, com encaminhamento para vários adquirentes e proteção contra contestações.
Soluções de pagamento para pequenas empresas
Preços IC++ transparentes, terminal Smart POS incluído e ativação em 24 horas para pequenos negócios.
Integrações de pagamento para e-commerce
Plugins de instalação rápida para Shopify, WooCommerce, Magento e PrestaShop, com acesso completo à API.
Otimize os seus pagamentos hoje
Pronto para codificar? Explore as APIs RoxPay, SDKs e documentação pensada para equipas de produto e engenharia.
✓ Sem custos fixos mensais · ✓ Ativação em 24 horas · ✓ Suporte técnico dedicado
