Skip to main content

Recipes, API Quick-Ref & Runbooks

Copy-paste flows, core endpoints, and step-by-step incident handling.

C
Written by Catalin Fetean
Updated over 2 weeks ago

Audience: Devs, Support, SRE, Finance
Outcomes: Ship fast; resolve issues calmly

End-to-end recipes

Card deposit → order advance

  1. POST /api/payments/intents with orderId

  2. UI completes SCA via Elements

  3. Stripe webhook payment_intent.succeeded

  4. Handler updates payment; emit payment.succeeded; set DepositPaid

  5. SSE updates UI → start work

Bank link → delayed settlement

  1. POST /api/payments/bank/link → provider URL

  2. Buyer completes auth; returns to app

  3. Provider webhook confirms settlement

  4. Mark DepositPaid; SSE notifies participants

Crypto escrow release

  1. POST /api/escrow/release (orderId, milestoneId, amount)

  2. 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_declinedPAYMENT_FAILED

  • Bank invalid_signatureWEBHOOK_INVALID_SIGNATURE

  • Crypto insufficient_gasESCROW_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

Did this answer your question?