Audience: Developers, Architects, SRE
Outcomes: Clear mental model; predictable control/data planes
Roles
Your backend: issues commands via REST (create orders, payment intents, releases).
Providers: push webhooks (payments settled, refunds, chargebacks).
Clients: subscribe to SSE for live updates.
Message flow (sequence)
sequenceDiagram participant UI as Client (Browser/App) participant API as TradeOS API participant STR as Stripe/Bank/Crypto participant DB as DB/Store UI->>API: POST /api/orders (create) API->>DB: persist order + emit order.created UI-->>API: POST /api/payments/... (initiate) API->>STR: create intent/link/tx STR-->>API: Webhook (succeeded/refunded/chargeback) (signed) API->>DB: upsert payment + order.status.changed API-->>UI: SSE (payment.succeeded, order.status.changed)
Principles
Webhook > redirect: webhook is authoritative for settlement.
Idempotency everywhere: clients, webhooks, releases.
Observability: correlation IDs tie logs, metrics, traces, tickets.
Do heavy work async: acknowledge webhooks fast, queue the rest.
QA checklist
Orders only advance to DepositPaid on verified webhook.
Duplicate webhook events do not duplicate side-effects.
Runbook: “Payment stuck in Pending”
Check provider delivery logs → replay.
Verify signature (Stripe/HMAC).
Inspect handler logs via
x-correlation-id; repair and reprocess.