Arquitetura de Sistemas · Insper · Lab 14

Lab 14 — Pagamentos em Sandbox

Um provedor de pagamento real, sem dinheiro real: o modo de teste da Stripe atrás do adaptador do lab 9 — chaves, webhooks, reconciliação

A história até aqui

aula 3 · lab 9uma chave por pedido, contra um provedor falso
→
capítulo 10 · lab 14o sandbox de um provedor real: modo de teste da Stripe
→
depois · aula 15isso se sustenta às 10:00?

O cliente do lab 9 desiste depois de 1 s e 3 tentativas. Num dia de provedor lento, 133 de 1.000 checkouts terminam UNKNOWN: cobrados, mas ninguém sabe. Quem nos conta o que aconteceu?

  • O provedor conta — depois, talvez duas vezes — se a gente verificar e escutar.

O que um provedor real acrescenta

o falso do lab 9 (WireMock)
sandbox da Stripe
acesso
nenhum
uma secret keysk_test_…, no .env, nunca no Git
dinheiro
um decimal
centavosR$ 350,00 → amount=35000
"não"
nunca
HTTP 402 card_erroruma recusa é uma resposta
depois
nada
webhooksassinados, pelo menos uma vez, em qualquer ordem
  • Nenhum dinheiro se move: livemode: false. O serviço se recusa a subir com uma chave de produção.

2 · Uma interface, dois provedores

ordervê AUTHORIZED / DECLINED
→
payment · Pspboxoffice.psp.provider
→
implementações
PspClient · fakeo padrão: os labs de caos e o CI não precisam de chave
StripePsp · stripePOST /v1/payment_intents, confirm=true
  • O order nunca sabe qual provedor cobrou: o adaptador do lab 9, agora com uma junta.
  • Números de cartão nunca tocam o BoxOffice: um meio de pagamento de teste (pm_card_visa) faz o papel do que o Stripe.js entrega num navegador.

3 · Cobrar, repetir, recusar

chave sandbox-1
POST /payments
→
PaymentIntentIdempotency-Key: sandbox-1
→
201 AUTHORIZEDpi_…
sandbox-1 de novo
POST /payments
→
achado em paymentsa Stripe não é chamada
→
200 · o mesmo pi_…um pagamento no Dashboard
chave sandbox-2
pm_card_visa_chargeDeclined
→
HTTP 402 card_error
→
201 DECLINEDnão é exceção: sem retry, sem breaker
  • De ponta a ponta pelo order: CONFIRMED — ou um 503 quando a Stripe passa do timeout de 1 s; pague de novo.

4 · Webhooks: o provedor conta depois

Stripepayment_intent.succeeded
→
stripe-cli listensem endereço público
→
assinatura?HMAC de t.corpo · ≤ 5 min
→
já visto?stripe_events, id evt_…
→
aplica · 200atualiza ou cria o pagamento
assinado, novo
assinado, de novo
falsificado
send-webhook.sh
applied 200
duplicate 200
bad signature 400
  • HMAC: código de autenticação de mensagem baseado em hash (hash-based message authentication code), com a chave whsec_…. Um evento do sandbox é reenviado três vezes em poucas horas, pode chegar duas vezes e fora de ordem.

5 · A resposta perdida

pedido criado
→
a Stripe cobrachave order-<id> · metadados
→
o payment morresem linha: UNKNOWN
→
webhookcria a linha a partir dos metadados
→
paga de novoCONFIRMED · uma cobrança
  • A linha curada leva a mesma chave de idempotência que o order envia: exatamente o que o retry procura.
  • Se o payment tivesse chamado a Stripe de novo, a chave repetiria o mesmo PaymentIntent.

Uma chave por pedido, de ponta a ponta: o order, a tabela payments e a Idempotency-Key da Stripe são o mesmo valor.

Simulador: os checkouts UNKNOWN

sem chave
uma chave por pedido
cobranças para 1.000 fãs
392 fãs pagam duas vezes ou mais
1.000 · 0 duplicadas
checkouts UNKNOWN
—
133 · cada um cobrado uma vez
  • O cliente do lab 9 (1 s, 3 tentativas) contra um provedor lento: 40,2% das chamadas estouram o timeout.
  • A chave remove as duplicadas; o webhook e a reconciliação resolvem os UNKNOWN.

Seção 5 da página · simulador idempotent-retry, chave "order", provedor lento.

6 · Reconciliar: o provedor é a fonte da verdade

os nossos pagamentosúltimas 2 horas, só pi_…
→
consulta cada PaymentIntent
→
comparasucceeded ↔ AUTHORIZED
→
divergências
a repetição assinada (passo 4)
depois de removê-la
uma linha virou DECLINED
relatório
nosso AUTHORIZEDstripe: missing
[]
nosso DECLINEDstripe: succeeded
  • Webhooks podem se perder; dinheiro precisa de uma segunda conferência. Em produção: um agendamento, um alerta, uma correção.

7 · Pix com o Mercado Pago

MercadoPagoPsp
→
POST /v1/ordersX-Idempotency-Key (obrigatório)
→
pendente + QR codeqr_code, qr_code_base64
→
o fã pagano app do banco
→
webhook · x-signatureo único "pago"
  • Com cartões, o webhook é uma rede de segurança; com Pix, é o caminho principal.
  • O order precisa de um terceiro estado, "aguardando pagamento". Resultados de teste: nome do titular APRO, OTHE, CONT, FUND.

Confira a documentação atual do Mercado Pago: os nomes da Orders API diferem dos da Payments API, mais antiga.

Armadilhas

Sintoma Causa
o payment sai: precisa ser chave de teste chave vazia ou de produção com PSP_PROVIDER=stripe
Stripe answered 401 chave copiada errada ou trocada
400 sobre a moeda o país da conta não aceita BRL: STRIPE_CURRENCY=usd
400 sobre idempotência uma chave reusada com outros parâmetros
webhooks 400 bad signature STRIPE_WEBHOOK_SECRET ≠ listen --print-secret ou o payment não foi reiniciado
primeiro pay → 503 a Stripe passou do timeout de 1 s do order: pague de novo

O que quebra em seguida

lab 14cada checkout cobrado uma vez, toda cobrança conhecida
→
saber não é consertarestornos, 3-D Secure, Pix pendente, chaves de produção e PCI DSS
→
aula 15 · projetotudo isso se sustenta às 10:00, com 2 M de fãs?
  • O PCI DSS (Payment Card Industry Data Security Standard) fica pequeno porque números de cartão nunca tocam o BoxOffice.

Pontos-chave

  1. Um sandbox é um provedor real sem dinheiro real; uma chave de produção é um bug.
  2. Mantenha o provedor atrás de uma interface; o order vê só AUTHORIZED / DECLINED.
  3. Uma chave de idempotência por pedido, de ponta a ponta: nenhum retry, em lugar nenhum, cobra duas vezes.
  4. Uma recusa é uma resposta, não uma falha para o retry e o breaker.
  5. Webhooks: verifique a assinatura no corpo bruto, processe cada evento uma vez, responda rápido.
  6. Reconcilie com o provedor: o que os webhooks perdem, uma segunda conferência encontra.

Capítulo 10, segundo lab: amarra as aulas 3 (um "comprar" repetido pode cobrar duas vezes), 10 (o provedor de pagamento) e 12 (provar quem chama). Roteiro: (1) um sandbox e uma chave de teste; (2) o adaptador Psp; (3) cobrar, repetir, recusar; (4) webhooks assinados, uma vez por evento; (5) a resposta perdida; (6) reconciliação; (7) Pix com o Mercado Pago.

A história da disciplina (visão geral de 2027.1); os 133 vêm do simulador idempotent-retry com o cliente do lab 9 e o provedor lento.