Diagrama de integração com gateway de pagamento: autorização, 3-D Secure, captura e webhooks

Na maioria dos diagramas de arquitetura, um pagamento é uma seta da loja para a "Stripe" ou a "Adyen". Em produção, é uma cadeia de participantes e duas linhas do tempo: o que acontece enquanto o cliente espera na página de checkout e o que chega minutos ou dias depois por webhook. A maioria dos bugs de pagamento mora no intervalo entre as duas.

Este guia desenha um pagamento com cartão do ponto de vista da engenharia do lojista: os participantes, o caminho feliz, por que o resultado no navegador não é a fonte da verdade, o que acontece depois da autorização e um diagrama que mostra onde o dinheiro e o estado do pedido mudam. Ele é neutro em relação a fornecedores; Stripe e Adyen aparecem só como exemplos de como os provedores de serviços de pagamento documentam os detalhes.

Os participantes

O caminho feliz

1. O cliente seleciona Pagar. O frontend pede ao seu backend para iniciar o checkout de um pedido.
2. O backend cria um pagamento no PSP com o valor, a moeda, o ID do pedido e uma chave de idempotência, e repassa ao frontend o token de cliente do PSP.
3. O frontend coleta os dados do cartão nos campos do PSP, geralmente iframes ou um SDK, então o número do cartão vai do navegador direto para o PSP e nunca toca os seus servidores.
4. O emissor decide sobre o 3-D Secure. A EMVCo descreve dois fluxos: no fluxo sem atrito, o emissor aprova com base em uma análise de risco sem perguntar nada ao cliente; no fluxo com desafio, o cliente confirma, por exemplo com um código de uso único ou com o app do banco. Em algumas regiões, é assim que se cumpre a autenticação forte do cliente.
5. O PSP envia a autorização pelo adquirente e pela bandeira até o emissor, que aprova e reserva o valor.
6. O frontend mostra o resultado. Exibir "Obrigado" não tem problema, mas não é o momento de despachar.
7. O PSP envia um webhook dizendo que o pagamento foi autorizado. Seu backend verifica o webhook e atualiza o pedido.
8. O backend captura o pagamento quando o pedido é despachado, ou na hora no caso de produtos digitais.
9. O PSP faz os repasses, em lotes e já descontadas as taxas, e um job de conciliação casa os repasses com os pedidos.

Os campos de cartão importam para a conformidade. Quando um e-commerce apenas incorpora o formulário de pagamento de um PSP e não armazena, processa nem transmite dados de cartão por conta própria, ele pode se enquadrar no SAQ A do PCI DSS em vez do SAQ A-EP, muito mais longo. No PCI DSS v4.0.1, isso também exige proteger a página contra scripts maliciosos, como explica o PCI Security Standards Council. Confirme o questionário certo com o seu adquirente.

Por que o navegador não é a fonte da verdade

O cliente pode fechar a aba durante o 3-D Secure, perder a conexão depois que o emissor aprovou ou atualizar a página na hora errada. Se o estado dos seus pedidos depende do retorno do navegador, alguns pedidos pagos vão continuar como não pagos e alguns que falharam vão parecer pagos. A fonte da verdade são os webhooks do PSP, ou a API dele. Trate os webhooks como qualquer outro fluxo de mensagens:

• Verifique a assinatura. PSPs assinam as requisições de webhook; a Stripe, por exemplo, em um header Stripe-Signature, e a Adyen com assinaturas HMAC. Rejeite tudo o que não for verificado.
• Responda rápido, processe depois. O guia de webhooks da Stripe pede uma resposta 2xx antes de qualquer lógica complexa. Coloque o evento verificado em uma fila e responda.
• Espere duplicatas. Endpoints podem receber o mesmo evento mais de uma vez. Registre os IDs de eventos processados e ignore as repetições.
• Não confie na ordem. A Stripe afirma que não garante a entrega na ordem em que os eventos foram gerados. Quando chegar um evento que não combina com o estado atual, busque o pagamento na API do PSP.
• Espere novas tentativas. No modo live, a Stripe tenta de novo as entregas que falharam por até três dias, com backoff exponencial; um endpoint lento recebe o mesmo evento outra vez mais tarde.

A mesma disciplina vale no sentido contrário. Envie uma chave de idempotência em toda requisição que cria ou altera um pagamento e reutilize a chave quando repetir a chamada depois de um timeout, para que uma nova tentativa não cobre duas vezes. As chaves não duram para sempre: a Stripe pode removê-las depois de 24 horas, e a Adyen as mantém por 7 a 14 dias.

Depois da autorização: captura, reembolsos, chargebacks e repasses

• A autorização reserva; a captura movimenta o dinheiro. Uma autorização expira se você não a capturar. Em pagamentos online com cartão, o prazo costuma ser de cerca de uma semana, e a Stripe lista o prazo por bandeira e por quem iniciou o pagamento. Capture antes que ele acabe, ou a reserva é liberada.
• Uma captura ainda pode falhar. A Adyen documenta casos raros em que a bandeira rejeita uma captura depois que o PSP a aceitou, então os estados do seu pedido precisam de um caminho para isso.
• Reembolsos são operações novas sobre um pagamento capturado. Eles terminam de forma assíncrona e também chegam como webhooks.
• Chargebacks vêm do emissor, às vezes semanas depois, quando o portador contesta um pagamento. Algumas bandeiras começam com uma consulta; responda, ou ela pode virar um chargeback difícil de ganhar.
• Repasses precisam de conciliação. Case cada repasse com os pagamentos, reembolsos, taxas e chargebacks que ele liquida, usando os relatórios de repasse ou de liquidação do PSP.

O diagrama

Como ler:

• As conexões contínuas são o checkout em si: pagar (1), iniciar o checkout (2), criar o pagamento (3), enviar os dados do cartão ao PSP pelos campos dele (4) e 3-D Secure e autorização entre o PSP e a bandeira (5).
• As conexões tracejadas acontecem depois: o webhook (6), o evento verificado em uma fila (7) e a API de pagamentos atualizando o pedido (8). O job noturno de conciliação lê os relatórios de repasse do PSP e casa os repasses com os pedidos.
• A moldura delimita os sistemas do lojista. Nenhum dado bruto de cartão entra nela; o número do cartão vai dos campos do PSP direto para o PSP.

Como desenhar um fluxo de pagamento

• Numere os passos. Pagamentos são sequências; números deixam a ordem legível sem um diagrama de sequência à parte.
• Separe o síncrono do assíncrono. Linha contínua para a requisição de checkout, tracejada para webhooks, filas e jobs em lote.
• Marque a fronteira dos dados de cartão. Mostre quais componentes podem ver números de cartão. Com campos hospedados, nenhum dos seus deveria ver.
• Mostre onde o estado do pedido muda. Um único componente deve ser o dono, alimentado por eventos verificados, não pelo navegador.
• Dê nome às operações de dinheiro. Autorizar, capturar, reembolsar e repassar são eventos diferentes, com tempos diferentes; rotule cada um.
• Desenhe os casos de falha que importam: timeout na criação (tentar de novo com a mesma chave de idempotência), webhook duplicado (deduplicar), desafio de 3-D Secure abandonado (expirar o pedido), autorização expirada (autorizar de novo ou cancelar).

Para uma visão em sequência do mesmo fluxo, veja o caso de uso de diagrama de fluxo de pagamento. Para o lado dos eventos, veja o guia do diagrama de arquitetura orientada a eventos e, para a revisão de segurança, os diagramas de fluxo de dados para modelagem de ameaças.

Monte no Archboard

1. Entre com Google ou GitHub e crie um diagrama.
2. Adicione uma Pessoa do pack Modelo C4 para o cliente e dois nós Sistema externo do pack Modelo C4: um para o provedor de serviços de pagamento e outro para o adquirente, a bandeira e o emissor.
3. Adicione uma Moldura do pack Básico para os sistemas do lojista e coloque dentro dela quatro nós Contêiner do pack Modelo C4: o app web de checkout, a API de pagamentos, o handler de webhooks e o job de conciliação.
4. Adicione dentro da moldura um Postgres do pack Dados para pedidos e pagamentos e uma Fila do pack Dados para os eventos de pagamento.
5. Numere as conexões na ordem, deixe tracejadas as do webhook, da fila e da conciliação e adicione um bloco Markdown do pack Básico explicando os estilos de linha.

O exemplo usa 11 nós de diagrama e fica dentro do plano Free.

Perguntas frequentes

Qual é a diferença entre um gateway de pagamento e um processador de pagamentos? O gateway é a interface com que os seus sistemas conversam: API, campos de cartão, webhooks. O processador leva a transação pelas bandeiras. Muitos PSPs oferecem os dois, junto com uma relação de adquirência.

Posso marcar um pedido como pago quando o navegador diz que o pagamento deu certo? Mostre uma confirmação ao cliente, mas mude o estado do pedido somente a partir de um webhook verificado ou de uma consulta à API do PSP.

Por que autorizar primeiro e capturar depois? Para cobrar só o que for despachado. A reserva garante o valor; a captura movimenta o dinheiro quando você entrega. Fique de olho na expiração da autorização.

Preciso tratar webhooks que chegam fora de ordem? Sim. Torne o handler idempotente, mantenha o pedido como uma máquina de estados que rejeita transições impossíveis e, na dúvida, busque o pagamento atual no PSP.

Usar campos hospedados me deixa em conformidade com o PCI? Reduz o escopo, mas não o elimina. Você ainda preenche um questionário de autoavaliação e protege a página de checkout. Pergunte ao seu adquirente qual questionário se aplica.

Comece grátis — um assento, sem cartão de crédito.