Integração de Gateway de Pagamento: Guia Completo para Programadores e Empresas
Integrar um gateway de pagamento é uma das decisões técnicas mais importantes que uma empresa de e-commerce ou uma equipa de software pode tomar. O método escolhido determina o âmbito PCI DSS, a taxa de conversão do checkout, a capacidade de gerir autenticação 3D Secure e a rapidez com que se podem suportar novos métodos de pagamento. Este guia abrange todas as opções de integração disponíveis, desde uma página alojada sem código até uma API REST completa servidor a servidor, e detalha os passos necessários para entrar em produção com a RoxPay. Quer seja um programador a construir um novo checkout ou um empresário a avaliar opções, este guia fornece uma visão completa.
O Que Significa a Integração de Gateway de Pagamento para o Seu Negócio
Uma integração de gateway de pagamento é a ligação técnica entre o seu website ou aplicação e a rede de processamento de pagamentos que autoriza, captura e liquida transações com cartão. Sem ela, os seus clientes não conseguem pagar. Com uma integração deficiente, perde receita através de transações falhadas, fluxos de checkout com demasiado atrito e uma experiência móvel fraca.
A integração afeta mais do que apenas os programadores. Os empresários precisam de compreender que o método escolhido determina a sua responsabilidade ao abrigo do PCI DSS, a capacidade de suportar métodos de pagamento locais e a velocidade com que novas funcionalidades como o Apple Pay ou transferências de open banking podem ser ativadas. Uma integração por página alojada move todo o processamento de dados de cartão para fora dos seus servidores e minimiza o seu encargo de conformidade. Uma integração direta via API oferece controlo máximo mas coloca o processamento de dados de cartão na sua infraestrutura, exigindo um nível mais elevado de certificação PCI.
Por que a qualidade da integração é importante para a conversão: O atrito no checkout é uma das principais causas de abandono de carrinho. Um gateway que exige múltiplos redirecionamentos e uma visita separada ao portal bancário converte pior do que uma experiência de checkout nativa e incorporada. As integrações REST API modernas permitem apresentar os campos de inserção de cartão diretamente na sua página de checkout sem o cliente sair do seu site, o que melhora as taxas de conclusão de forma mensurável.
Para comerciantes em setores de alto risco que também necessitam de um gateway de pagamento de alto risco, a camada de integração é ainda mais importante porque verificações adicionais, aplicação de 3D Secure e filtros antifraude interagem com a forma como o formulário de pagamento é construído e como os eventos são processados. Escolher um gateway que trate tanto o processamento padrão como o de alto risco numa única integração evita a complexidade de gerir dois sistemas separados.
Métodos de Integração: Página Alojada vs API vs SDK
Existem três formas principais de integrar um gateway de pagamento, cada uma com diferentes compromissos entre velocidade de implementação, âmbito PCI DSS e flexibilidade de personalização.
Página de Pagamento Alojada: A opção mais simples. Redireciona o cliente do seu checkout para uma página alojada e gerida pelo gateway de pagamento. O cliente insere os dados do cartão no domínio do gateway, não no seu. Isto elimina quase todos os requisitos PCI DSS do seu lado porque nunca processa dados de cartão. A desvantagem é a personalização limitada e a experiência de sair do site durante o checkout. Ideal para empresas que pretendem começar a aceitar pagamentos rapidamente com esforço de desenvolvimento mínimo.
IU Drop-in Incorporada (iFrame ou Elementos JS): Um caminho intermédio prático. O gateway fornece um fragmento JavaScript que injeta campos seguros de inserção de cartão diretamente na sua página de checkout. Os campos são apresentados dentro de iframes alojados no domínio do gateway, pelo que os dados do cartão nunca chegam ao seu servidor. Do ponto de vista do cliente, o checkout parece nativo do seu site. O âmbito PCI é mínimo (SAQ A). Esta é a abordagem recomendada para a maioria das empresas de e-commerce. A RoxPay suporta isto através da sua API REST e SDK frontend.
API Servidor a Servidor: Controlo máximo. O seu frontend recolhe os dados do cartão e o seu servidor envia-os diretamente para a API do gateway. Requer conformidade PCI DSS SAQ D, que implica auditorias de segurança rigorosas e controlos contínuos. É adequada para plataformas que constroem produtos de infraestrutura de pagamento, não para a maioria dos comerciantes.
Plugins e Módulos de Plataforma: Para comerciantes que utilizam plataformas de e-commerce como Magento, PrestaShop ou WooCommerce, módulos pré-construídos tratam os detalhes da integração dentro da arquitetura da plataforma. O método subjacente é tipicamente uma página alojada ou IU drop-in, pelo que o âmbito PCI permanece mínimo e o tempo de implementação é medido em horas em vez de dias.
Passo a Passo: Como Integrar a RoxPay via API REST
A RoxPay fornece uma API REST com corpos de pedido e resposta em JSON. A documentação completa está disponível em app.roxpay.eu/api/v4/docs. A integração segue um padrão de intenção de pagamento familiar a qualquer programador que tenha trabalhado com APIs de gateway modernas.
Passo 1: Crie a sua conta sandbox. Para iniciar a sua candidatura à RoxPay, aceda à página de onboarding. As credenciais sandbox são emitidas automaticamente após o registo, sem necessidade de informações de pagamento para começar a testar.
Passo 2: Autentique-se. Todas as chamadas à API utilizam a sua chave API no cabeçalho de autorização. As chaves têm âmbito na sua conta de comerciante e podem ser rotacionadas a partir do painel de controlo. Nunca exponha a sua chave API em JavaScript do lado do cliente nem a submeta ao controlo de versões.
Passo 3: Crie uma intenção de pagamento. Faça um POST para o endpoint de intenção de pagamento com o montante, moeda, métodos de pagamento aceites e uma referência de encomenda única do seu sistema. A API devolve um ID de intenção de pagamento e um segredo de cliente para utilização no frontend.
Passo 4: Monte a IU drop-in. Passe o segredo de cliente para a biblioteca RoxPay.js, que apresenta os campos de inserção de cartão na sua página. A biblioteca trata da formatação de números de cartão, validação, redirecionamentos 3D Secure e botões Apple Pay ou Google Pay com base no suporte do navegador.
Passo 5: Trate o resultado. Após pagamento bem-sucedido, a biblioteca desencadeia um callback de sucesso. O seu frontend notifica o seu backend, que verifica de forma independente o estado do pagamento via webhook antes de cumprir a encomenda. Nunca confie apenas na confirmação do frontend para o cumprimento de encomendas.
Passo 6: Reconcilie via painel de controlo. Todas as transações são visíveis no seu painel de controlo do comerciante com detalhes completos sobre montante, taxas, tipo de cartão e estado de liquidação. Exporte para CSV ou utilize a API para integração com sistemas de contabilidade.
Webhooks, Tratamento de Erros e Testes em Sandbox
Os webhooks são a espinha dorsal de uma integração de pagamento fiável. Permitem à RoxPay notificar o seu servidor de eventos de pagamento de forma assíncrona, sem depender de o browser do cliente permanecer aberto ou da ligação de rede permanecer estável durante a transação.
Configuração de webhooks: Registe um endpoint HTTPS no seu servidor no painel de controlo. A RoxPay fará um POST de um payload JSON assinado para este endpoint para cada evento significativo: payment.completed, payment.failed, payment.refunded, chargeback.created, entre outros. Verifique a assinatura em cada webhook recebido usando a chave secreta apresentada no seu painel. Rejeite qualquer pedido que falhe na validação de assinatura para prevenir ataques de repetição.
Idempotência: Os webhooks podem ser entregues mais de uma vez devido a condições de rede. O seu endpoint deve processar cada evento de forma idempotente, ou seja, processar o mesmo evento duas vezes produz o mesmo resultado. Guarde o ID do evento e ignore o processamento se já o tiver tratado.
Tratamento de erros na API: A RoxPay devolve códigos de estado HTTP padrão. 200 para sucesso, 400 para pedidos incorretos com parâmetros inválidos, 401 para falhas de autenticação, 422 para erros de processamento como recusa de cartão ou fundos insuficientes. Inspecione sempre o código de erro no corpo da resposta, não apenas o estado HTTP, para distinguir entre um erro técnico e uma rejeição de lógica de negócio.
Testes em sandbox: O ambiente sandbox espelha a produção exatamente. Utilize os números de cartão de teste fornecidos para simular transações aprovadas, recusas, desafios 3DS, fundos insuficientes, cartões expirados e respostas de cartão roubado. Teste o tratamento dos webhooks desencadeando cada tipo de evento em sandbox antes de tocar na produção. Confirme que a IU de erro funciona corretamente para todos os cenários de recusa que os seus clientes possam encontrar, não apenas o fluxo positivo.
Lógica de retentar: Implemente backoff exponencial no seu consumidor de webhooks. A RoxPay retenta webhooks não entregues durante um período definido. O seu endpoint deve ser idempotente antes de depender do comportamento de retentar.
Entrar em Produção: Checklist Antes de Processar Transações Reais
A passagem de sandbox para produção exige a conclusão de um conjunto de passos técnicos, de segurança e comerciais. Omitir qualquer um destes cria riscos para o seu negócio e para os seus clientes.
Checklist técnica:
Substitua as chaves API sandbox por chaves de produção e guarde-as em variáveis de ambiente, nunca em código fonte ou controlo de versões. Confirme que o seu endpoint de webhook está ativo, acessível via HTTPS com um certificado válido e a devolver respostas 200 de forma consistente. Teste o tratamento de idempotência com credenciais de produção antes de redirecionar o tráfego de clientes. Confirme que o 3D Secure está configurado de acordo com os requisitos do seu adquirente para a sua categoria de comerciante. Valide que a IU do checkout é apresentada corretamente em dispositivos móveis, particularmente para os botões Apple Pay e Google Pay.
Checklist PCI DSS:
Se utilizar a IU drop-in, preencha e arquive um questionário de autoavaliação SAQ A. Confirme que não está a registar ou guardar dados de cartão em bruto em nenhum lugar do seu sistema, incluindo registos de pedidos, registos de erros ou pipelines de análise. Garanta que a configuração TLS cumpre os padrões atuais (TLS 1.2 mínimo, TLS 1.3 preferível). Remova quaisquer integrações de pagamento antigas que possam ainda estar ativas na sua base de código.
Checklist de negócio:
Defina o seu descritor de faturação no painel de controlo. Este é o texto que aparece no extrato bancário do titular do cartão. Um descritor claro e reconhecível reduz significativamente as contestações de fraude amigável porque os clientes conseguem identificar o débito. Configure o seu IBAN de liquidação. A RoxPay liquida para qualquer conta bancária SEPA em 24 a 48 horas. Ative notificações por email para transações falhadas e contestações para poder responder dentro dos prazos de disputa. Reveja a sua política de reembolso e cancelamento e garanta que está claramente visível durante o checkout. Certifique-se de que o contacto de apoio ao cliente é fácil de encontrar, pois os clientes que o conseguem contactar diretamente têm muito menos probabilidade de iniciar uma disputa bancária.
Perguntas frequentes
Quanto tempo demora uma integração de gateway de pagamento?
Usando a abordagem de IU drop-in com a API REST da RoxPay, um programador experiente pode concluir uma integração pronta para produção em um a dois dias. Uma página alojada com redirecionamento demora menos de um dia. A integração completa API servidor a servidor com uma IU de checkout personalizada demora tipicamente uma a duas semanas e também exige um maior nível de trabalho de conformidade PCI DSS a par do esforço de desenvolvimento.
Preciso de estar certificado PCI DSS para integrar um gateway de pagamento?
Não certificado no sentido formal, mas deve estar em conformidade. Se utilizar uma página alojada ou IU drop-in (baseada em iFrame), o seu encargo de conformidade é mínimo e preenche um questionário de autoavaliação simples (SAQ A). Se processar dados de cartão em bruto nos seus próprios servidores via API servidor a servidor, necessita de SAQ D, que implica uma auditoria rigorosa. A maioria dos comerciantes escolhe a IU drop-in precisamente para evitar este requisito.
O que é uma intenção de pagamento e por que é utilizada?
Uma intenção de pagamento é um objeto do lado do servidor que representa a intenção de um cliente de pagar um montante específico. Acompanha o estado do pagamento através de autorização, desafio 3D Secure, captura e liquidação. A utilização de um modelo de intenção de pagamento previne cobranças duplas, permite o rastreamento fiável via webhook e permite que o pagamento sobreviva a atualizações de browser ou ligações interrompidas durante o checkout.
Posso testar a integração sem uma conta de comerciante ativa?
Sim. A RoxPay fornece um ambiente sandbox gratuito acessível imediatamente após o registo. O sandbox espelha o comportamento de produção exatamente e inclui cartões de teste para todos os cenários: aprovações, recusas, desafios 3DS, cartões expirados e fundos insuficientes. Não são necessárias informações de pagamento nem aprovação de conta ativa para começar a testar.
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
A RoxPay disponibiliza uma API REST com acesso sandbox gratuito, documentação completa e liquidação em 24 a 48 horas para qualquer banco SEPA. Certificada PCI DSS Level 1, preços IC++ a partir de 0,45%.
✓ Sem custos fixos mensais · ✓ Ativação em 24 horas · ✓ Suporte técnico dedicado
