Visão geral do backend de pagamentos
Um backend de pagamentos é a sua própria cópia da API de um provedor de pagamento. Esses provedores costumam ser chamados de PSP, de payment service provider, e o app usa essa palavra também.
O backend recebe as chamadas que a sua integração já faz, nos mesmos caminhos, e responde nos formatos e códigos de status do próprio PSP.
O que deixa ele útil é que ele guarda estado. Autorize um pagamento, capture numa chamada depois, e então estorne uma parte: continua sendo um pagamento só do começo ao fim, não três respostas sem ligação.
Esse estado dura pouco de propósito. Um pagamento e o histórico dele ficam por perto de um dia, uma sessão de checkout hospedada 15 minutos, e um desafio de 3D Secure 5. Dá para uma execução de testes ou uma tarde de depuração, e não é lugar para guardar registro.
O ciclo de vida de um pagamento
Um pagamento passa pelos estados que o fornecedor usa:
- Autorizar segura o dinheiro. Um pagamento que não precisa de captura separada é liquidado na hora, do jeito que alguns provedores trabalham.
- Capturar recebe o dinheiro. Capture o valor inteiro, uma parte, ou várias vezes até o que foi autorizado.
- Estornar devolve, inteiro ou em partes.
- Cancelar libera uma autorização que nunca foi capturada.
- Ajustar sobe ou desce uma autorização antes da captura.
Duas bordas são modeladas porque as integrações de verdade esbarram nelas: estornar um pagamento que nunca foi capturado, o que na prática cancela ele, e cancelar um que já foi capturado, o que na prática estorna. Uma autorização de valor zero para verificar o cartão também funciona.
Nem todo PSP faz tudo isso, e o backend não finge o contrário. Cada marca declara o que suporta, versão por versão, e o app mostra na aba Visão geral da marca como capacidades do tipo capture, partialCapture, partialRefund, threeDS e idempotency.
3D Secure sem uma pessoa
Os pagamentos com cartão que precisam de autenticação rodam o fluxo 3DS2 inteiro. Dependendo do que você pedir, um pagamento pode:
- passar sem atrito, sem desafio nenhum,
- coletar primeiro uma impressão do dispositivo, e deixar isso decidir se quem paga é desafiado,
- ou parar num desafio, como um código de uso único, um redirecionamento, ou uma aprovação no app do banco.
O backend serve a página do desafio, então um teste consegue levar ele até o fim. Essa é a parte que costuma ser impossível de automatizar contra o sandbox de um fornecedor, porque alguém precisa clicar em alguma coisa.
Métodos que tiram o pagador do seu site
As carteiras, os redirecionamentos bancários e os métodos locais mandam quem paga para outro lugar e ficam esperando ele voltar. O backend serve essa página também, e o pagamento fica em estado pendente até ser aprovado ou cancelado, exatamente como seria em produção. Os provedores com página de checkout hospedada funcionam igual: você cria a sessão, recebe uma URL, e terminar ela liquida o pagamento.
Chaves de idempotência
Mande a mesma chave de idempotência duas vezes e você recebe o primeiro resultado em vez de uma segunda cobrança, nos provedores que suportam isso. É um dos comportamentos mais difíceis de testar em qualquer outro lugar, já que precisa de um fornecedor que lembre mesmo da sua chave.
O que volta
Os corpos das respostas, os nomes dos campos e os códigos de status HTTP são os do PSP. Uma biblioteca cliente escrita para o fornecedor funciona sem mudança, que é justamente a ideia: você troca uma URL base e mais nada.
Cada pagamento carrega o próprio histórico, então as capturas e os estornos dele são parte dele e não registros soltos para costurar depois. Dá para percorrer eles no app por referência, valor, status, método ou pagador.
Veja Atividade do backend.
Decidir o que acontece
Você não fica esperando para ver o que o backend resolve fazer. Dê ao portador do cartão, ao e-mail de quem paga ou ao valor o nome do resultado que você quer, e é isso que volta, no código de recusa do próprio provedor.
Veja Cenários de pagamento.
Onde ele responde
Cada versão de um provedor responde sob o próprio caminho, que carrega a marca, a API e a versão. Num backend hospedado, esse caminho fica no próprio host do backend:
https://<hostname>.pay.mockz.io/adyen/checkout/v71/paymentsTudo depois desse caminho é a rota do próprio provedor. Um backend pode servir vários provedores ao mesmo tempo, cada um no próprio caminho.
Veja Criar um backend hospedado.