Arquitetura de Integração de Pagamentos: Cartões, Carteiras, Faturas e Status de Pedidos

Integração de pagamentos raramente é tão simples quanto adicionar um único SDK. Em nossos projetos na DigiForge, vimos projetos crescerem demais porque as equipes subestimaram a complexidade de lidar com múltiplos métodos de pagamento — cartões, carteiras digitais, pagamentos por fatura — e depois vinculá-los a um ciclo de vida de pedido. Cada tipo de pagamento tem suas peculiaridades, e juntá-los sem uma arquitetura coerente leva a código frágil e reconciliação dolorosa. Este artigo detalha como é uma camada de integração de pagamentos unificada, baseando-se tanto em padrões estabelecidos quanto em novos desenvolvimentos, como cartões lastreados em stablecoins.

Cartões: Tokenização, Tokens de Rede e a Ascensão dos Cartões Lastreados em Stablecoins

Os pagamentos com cartão continuam sendo a espinha dorsal do e-commerce e de muitos negócios SaaS. A regra de ouro é nunca lidar com números de cartão brutos. A tokenização por meio de um gateway compatível com PCI (Stripe, Braintree, Adyen) é o mínimo. Mas há uma camada mais sutil: os tokens de rede. São tokens específicos de dispositivo, de uso único, emitidos pelas próprias redes de cartão, oferecendo melhores taxas de autorização e redução de fraudes. Geralmente incentivamos os clientes a adotar a tokenização de rede cedo, especialmente se processam pagamentos recorrentes, porque a vida útil dos tokens é maior e as atualizações são tratadas pela rede.

Uma nova onda é o cartão lastreado em stablecoin. No final de 2025, o volume de cartões cripto atingiu uma taxa anualizada de US$ 18 bilhões, crescendo 106% ao ano desde 2023 (comunicado de imprensa da Wirex/Crossmint). A arquitetura aqui é diferente: em vez de sacar de uma conta bancária ou linha de crédito, o cartão utiliza uma carteira de stablecoin. Para os desenvolvedores, isso significa integrar com um provedor de carteira (como a smart wallet da Crossmint) e um emissor de cartão (como a Wirex). O desafio é a conformidade — o comunicado observa que as fintechs anteriormente precisavam montar estruturas de carteira, emissor e conformidade separadamente. Na DigiForge, trabalhamos em integrações semelhantes com vários fornecedores e descobrimos que uma camada de abstração com um modelo de transação unificado é essencial. Caso contrário, depurar uma falha de pagamento se torna uma caça aos culpados em três painéis de provedores diferentes.

Carteiras Digitais: UPI, Google Pay e Integração Hospedada vs. Baseada em API

Carteiras digitais não são monolíticas. O Google Pay (agora parte do ecossistema Google Payments) opera de forma diferente das carteiras baseadas em UPI da Índia, como o Paytm, e ambas diferem de carteiras específicas de aplicativos. A decisão arquitetural é usar um checkout hospedado (mais simples, menos controle) ou uma integração orientada por API (mais complexa, UX mais rica).

Para carteiras como Google Pay, Apple Pay e PayPal, o padrão comum é um botão de carteira que aciona uma folha ou redirecionamento. A integração geralmente é feita através do checkout unificado do gateway de pagamento — o Payment Element do Stripe, por exemplo, renderiza todas as carteiras automaticamente. Isso é suficiente para muitos casos, mas encontramos limitações quando você precisa de estilização personalizada ou deseja coletar dados adicionais antes do pagamento. Uma integração mais profunda via SDK próprio da carteira oferece mais controle, mas compromete você a manter caminhos de código separados.

Carteiras baseadas em UPI, como o Paytm, operam de forma diferente. UPI (Unified Payments Interface) é um sistema de pagamento instantâneo que permite transferências diretas entre bancos. Ao integrar o Paytm como método de pagamento, o fluxo típico é: o usuário seleciona Paytm, o backend gera uma solicitação de pagamento, o usuário autoriza no aplicativo Paytm e o Paytm envia um callback. O desafio aqui é a idempotência — pagamentos UPI podem ser bem-sucedidos no lado do banco, mas reportar falha ao comerciante devido a timeouts de rede. Sempre construímos um job de reconciliação que compara nosso status de pedido com o status da transação do Paytm a cada poucos minutos.

Faturas: Solicitações de Pagamento e Reconciliação

Pagamentos faturados — quando uma empresa gera uma fatura e o cliente paga depois — introduzem um conjunto diferente de problemas. A página de Pagamentos do IRS (irs.gov/payments) é um exemplo de sistema de faturamento em larga escala: você consulta seu saldo (através de um aviso ou conta online) e depois paga usando conta bancária (Direct Pay) ou plano de parcelamento. A arquitetura precisa lidar tanto com o ciclo de vida da fatura (emitida, enviada, vencida, paga) quanto com o ciclo de vida do pagamento (iniciado, pendente, liquidado, falhou).

Para SaaS B2B ou aplicações web personalizadas, frequentemente construímos um módulo de faturamento que gera PDFs e hospeda um portal de pagamento. O portal deve aceitar múltiplos métodos: cartão, carteira ou transferência bancária. O truque é vincular o ID da fatura ao ID da transação de pagamento no gateway e, em seguida, usar webhooks para atualizar o status da fatura. Um erro comum é depender do recurso de fatura hospedada do gateway, mas perder o controle sobre a conciliação. Preferimos armazenar nossos próprios registros de fatura e usar o gateway apenas como processador de pagamento.

// Example webhook handler for invoice payment confirmation
app.post('/webhooks/stripe', async (req, res) => {
  const event = req.body;
  if (event.type === 'checkout.session.completed') {
    const session = event.data.object;
    const invoiceId = session.metadata.invoice_id;
    await db.invoices.update({ id: invoiceId }, { status: 'paid' });
  }
  res.json({ received: true });
});

O código acima é simplista, mas ilustra a ideia central: mapear o evento do gateway para seu próprio modelo de domínio. O campo de metadados é sua tábua de salvação. Sem ele, você teria que consultar o Stripe para corresponder às sessões, o que adiciona latência e complexidade.

Status do Pedido: Mapeando Eventos de Pagamento para o Ciclo de Vida

Um pedido pode passar por vários status: pending_payment, payment_received, processing, fulfilled, cancelled. O evento de pagamento deve ser apenas um dos muitos gatilhos. A decisão arquitetural chave é usar uma máquina de estados ou um campo de status mais simples. Recomendamos fortemente máquinas de estados para qualquer sistema com mais de quatro status ou com transições complexas (por exemplo, um pedido pode ir de 'payment_received' para 'processing' para 'shipped', mas também de 'pending_payment' para 'cancelled'). A gem StateMachines do Rails ou uma máquina de estados finita personalizada em Node.js funcionam bem.

Webhooks de gateways de pagamento devem alimentar diretamente a máquina de estados. Por exemplo, um evento payment_intent.succeeded deve transicionar o pedido de 'pending_payment' para 'payment_received'. Mas proteja-se contra condições de corrida: se o webhook chegar duas vezes (a maioria dos gateways garante entrega pelo menos uma vez), sua máquina de estados deve ser idempotente — ou seja, transicionar do mesmo estado atual para o mesmo próximo estado deve ser uma operação nula. Armazenamos um event_id com cada webhook para desduplicação.

Idempotência não é opcional. Se o manipulador de webhook de pagamento não for idempotente, você acabará cobrando duas vezes um cliente ou criando pedidos fantasmas. Testar isso sob carga normal é difícil; simulamos webhooks atrasados e duplicados em nosso pipeline de CI.

O status do pedido também precisa ser exposto aos clientes. Uma página de status simples (como uma barra de progresso) funciona, mas apenas se as transições subjacentes forem precisas. Já vimos sistemas onde o frontend consulta uma API que armazena em cache o status do pedido — mas o cache pode estar desatualizado se o webhook ainda não foi processado. A solução é usar um canal em tempo real (WebSocket ou Server-Sent Events) que empurre as mudanças de status, para que a UI seja atualizada imediatamente quando o webhook for processado. Para projetos mais simples, um cache de curta duração com TTL de 30 segundos é aceitável.

Opinião da DigiForge: Construa uma Camada de Integração de Pagamento, Não uma Bagunça

Depois de integrar dezenas de métodos de pagamento em vários projetos, nosso conselho é abstrair o processamento de pagamentos por trás de uma fina camada de serviço. Essa camada deve normalizar os eventos de cada provedor de pagamento em um formato comum de eventos, lidar com novas tentativas e manter um registro de transações. O sistema de pedidos nunca fala diretamente com Stripe, Paytm ou qualquer emissor — ele fala com seu serviço de pagamento. Isso facilita muito a adição de novos métodos de pagamento (por exemplo, um cartão stablecoin) sem tocar na lógica do pedido.

Também recomendamos tratar as faturas como um domínio separado, não apenas um status em um pedido. Uma fatura tem seu próprio ciclo de vida (rascunho, enviada, vencida, paga) e pode ser associada a vários pedidos (por exemplo, uma assinatura mensal). Da mesma forma, o status do pedido deve ser orientado por uma máquina de estados que lida com todas as transições possíveis, incluindo pagamentos parciais, reembolsos e estornos.

Se você está construindo uma integração de pagamento do zero, comece mapeando todos os métodos de pagamento que planeja suportar e identifique os eventos comuns que eles emitem. Em seguida, projete sua máquina de estados e o manipulador de webhooks. Acertar isso, e o resto é encanamento. Se você quiser uma segunda opinião sobre sua arquitetura, a equipe da DigiForge já viu casos extremos suficientes para te poupar algumas noites em claro.