Audience: Devs, Support, SRE, Finance
Outcomes: Ship fast; resolve issues calmly
End-to-end recipes
Card deposit → order advance
POST /api/payments/intents
withorderId
UI completes SCA via Elements
Stripe webhook
payment_intent.succeeded
Handler 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_FAILED
Bank
invalid_signature
→WEBHOOK_INVALID_SIGNATURE
Crypto
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