System Architecture · Insper · Lab 14

Lab 14 — Payments in a Sandbox

A real payment provider, no real money: Stripe's test mode behind lab 9's adapter — keys, webhooks, reconciliation

The story so far

class 3 · lab 9one key per order, against a fake provider
→
chapter 10 · lab 14a real provider's sandbox: Stripe test mode
→
next · class 15does it hold at 10:00?

Lab 9's client gives up after 1 s and 3 attempts. On a slow provider day, 133 of 1,000 checkouts end UNKNOWN: charged, but nobody knows. Who tells us what happened?

  • The provider does — later, maybe twice — if we verify it and listen.

What a real provider adds

lab 9's fake (WireMock)
Stripe sandbox
access
none
a secret keysk_test_…, in .env, never in Git
money
a decimal
centavosR$ 350.00 → amount=35000
"no"
never
HTTP 402 card_errora decline is an answer
later
nothing
webhookssigned, at least once, any order
  • No money moves: livemode: false. The service refuses to start with a live key.

2 · One interface, two providers

ordersees AUTHORIZED / DECLINED
→
payment · Pspboxoffice.psp.provider
→
implementations
PspClient · fakethe default: chaos labs and CI need no key
StripePsp · stripePOST /v1/payment_intents, confirm=true
  • order never learns which provider charged: the adapter of lab 9, now with a seam.
  • Card numbers never touch BoxOffice: a test payment method (pm_card_visa) stands for what Stripe.js gives in a browser.

3 · Charge, repeat, decline

key sandbox-1
POST /payments
→
PaymentIntentIdempotency-Key: sandbox-1
→
201 AUTHORIZEDpi_…
sandbox-1 again
POST /payments
→
found in paymentsStripe not called
→
200 · the same pi_…one payment in the Dashboard
key sandbox-2
pm_card_visa_chargeDeclined
→
HTTP 402 card_error
→
201 DECLINEDnot an exception: no retry, no breaker
  • End to end through order: CONFIRMED — or a 503 when Stripe beats the 1 s timeout; pay again.

4 · Webhooks: the provider tells you later

Stripepayment_intent.succeeded
→
stripe-cli listenno public address needed
→
signature?HMAC of t.body · ≤ 5 min
→
seen before?stripe_events, evt_… id
→
apply · 200update or create the payment
signed, new
signed, again
forged
send-webhook.sh
applied 200
duplicate 200
bad signature 400
  • HMAC: hash-based message authentication code, keyed with whsec_…. A sandbox event is retried three times within a few hours, may come twice and out of order.

5 · The lost answer

order created
→
Stripe chargeskey order-<id> · metadata
→
payment diesno row: UNKNOWN
→
webhookcreates the row from the metadata
→
pay againCONFIRMED · one charge
  • The healed row carries the same idempotency key order sends: exactly what the retry looks for.
  • Had payment called Stripe again, the key would have replayed the same PaymentIntent.

One key per order, end to end: order, the payments table and Stripe's Idempotency-Key are the same value.

Simulator: the UNKNOWN checkouts

no key
one key per order
charges for 1,000 fans
392 fans pay twice or more
1,000 · 0 duplicates
checkouts UNKNOWN
—
133 · each charged once
  • Lab 9's client (1 s, 3 attempts) against a slow provider: 40.2% of the calls time out.
  • The key removes the duplicates; the webhook and the reconciliation resolve the UNKNOWN.

Page section 5 · simulator idempotent-retry, key "order", slow provider.

6 · Reconcile: the provider is the source of truth

our paymentslast 2 hours, pi_… only
→
retrieve each PaymentIntent
→
comparesucceeded ↔ AUTHORIZED
→
mismatches
the signed replay (step 4)
after removing it
one row set to DECLINED
report
ours AUTHORIZEDstripe: missing
[]
ours DECLINEDstripe: succeeded
  • Webhooks can be missed; money needs a second check. In production: a schedule, an alert, a fix.

7 · Pix with Mercado Pago

MercadoPagoPsp
→
POST /v1/ordersX-Idempotency-Key (required)
→
pending + QR codeqr_code, qr_code_base64
→
the fan paysin the bank's app
→
webhook · x-signaturethe only "paid"
  • With cards the webhook is a safety net; with Pix it is the main path.
  • order needs a third state, "waiting for payment". Test outcomes: holder name APRO, OTHE, CONT, FUND.

Check the current Mercado Pago docs: the Orders API names differ from the older Payments API.

Pitfalls

Symptom Cause
payment exits: must be a test key empty or live key with PSP_PROVIDER=stripe
Stripe answered 401 key copied wrong or rolled
400 about the currency the account's country does not accept BRL: STRIPE_CURRENCY=usd
400 about idempotency a key reused with other parameters
webhooks 400 bad signature STRIPE_WEBHOOK_SECRET ≠ listen --print-secret, or payment not restarted
first pay → 503 Stripe beat order's 1 s timeout: pay again

What breaks next

lab 14each checkout charged once, every charge known
→
knowing is not fixingrefunds, 3-D Secure, Pix pending, live keys and PCI DSS
→
class 15 · projectdoes it all hold at 10:00, with 2 M fans?
  • PCI DSS (Payment Card Industry Data Security Standard) stays small because card numbers never touch BoxOffice.

Takeaways

  1. A sandbox is a real provider without real money; a live key is a bug.
  2. Keep the provider behind an interface; order sees only AUTHORIZED / DECLINED.
  3. One idempotency key per order, end to end: no retry anywhere charges twice.
  4. A decline is an answer, not a failure for the retry and the breaker.
  5. Webhooks: verify the signature on the raw body, process each event once, answer fast.
  6. Reconcile against the provider: what webhooks miss, a second check finds.

Chapter 10, second lab: ties classes 3 (a retried buy can charge twice), 10 (the payment provider) and 12 (prove who calls) together. Outline: (1) a sandbox and a test key; (2) the Psp adapter; (3) charge, repeat, decline; (4) signed webhooks, once per event; (5) the lost answer; (6) reconciliation; (7) Pix with Mercado Pago.

The story of the course (2027.1 overview); the 133 come from the idempotent-retry simulator with lab 9's client and the slow provider.