Audience: Devs, Support, SRE, Finance
Outcomes: Ship fast; resolve issues calmly
End-to-end recipes
Card deposit → order advance
POST /api/payments/intentswithorderIdUI completes SCA via Elements
Stripe webhook
payment_intent.succeededHandler updates payment; emit
payment.succeeded; set DepositPaidSSE updates UI → start work
Bank link → delayed settlement
POST /api/payments/bank/link→ provider URLBuyer completes auth; returns to app
Provider webhook confirms settlement
Mark DepositPaid; SSE notifies participants
Crypto escrow release
POST /api/escrow/release(orderId,milestoneId,amount)Monitor on-chain tx; emit
escrow.released; update invoice
API quick-reference
SSE
GET /api/events/stream
Webhooks
POST /api/webhooks/stripe POST /api/webhooks/bank
Payments
POST /api/payments/intents POST /api/payments/stripe/checkout-session POST /api/payments/bank/link
Escrow
POST /api/escrow/deploy-contract POST /api/escrow/monitor-deployment POST /api/escrow/release
Error mapping (provider → platform)
Stripe
card_declined→PAYMENT_FAILEDBank
invalid_signature→WEBHOOK_INVALID_SIGNATURECrypto
insufficient_gas→ESCROW_RELEASE_FAILED
UX: translate to human messages; include provider references for support.
Incident runbooks
Payment stuck (Pending)
Check provider logs → replay; verify signature → check handler dedupe; reconcile manually with note if needed.
Webhook flood
Throttle workers; verify DB indexes; ensure idempotency; drain queue, then restore limits.
SSE outage
Disable proxy buffering; confirm CORS + credentials; inspect long-lived response closures.
Escalation ladder
P1 money wrong recipient → on-call engineer + finance lead + exec
P2 delayed confirmations → SRE + support
QA checklist
After incident replay, no duplicate releases (idempotent handlers)
All journal entries tie to
orderId,invoiceId, and provider references
