Audience: Finance, PMs, Developers, Admins
Outcomes: Choose the right rail; understand states/events and escrow hand-offs
What payments do
Collect via cards, bank/open banking, or crypto
Hold funds in escrow until milestones are accepted
Drive order status, invoice generation, and payouts
Rails (quick reference)
Rail | Best for | Notes |
Cards (Stripe) | Fast deposits, global | SCA/3DS handled; instant auth |
Bank link | Larger amounts, domestic | Lower fees; settlement via webhook; slower |
Crypto | Web3 clients, FX avoidance | On-chain escrow; gas & network risk |
Guidance: Use Hosted Checkout for fastest PCI-light card flow; Payment Intents for server-controlled flows/saved methods; bank for high-value; crypto where wallets/USDC/ETH preferred.
Canonical state machine
stateDiagram-v2 [*] --> Initiated Initiated --> Pending: provider created (PI/link/tx) Pending --> Succeeded: webhook verified Pending --> Failed: declined/expired/canceled Succeeded --> Refunded: refund webhook Succeeded --> ChargedBack: chargeback/dispute Refunded --> [*] Failed --> [*] ChargedBack --> [*]
Events
payment.intent.created, payment.checkout.created, payment.succeeded, payment.failed, payment.refunded, payment.chargeback.
QA checklist
Pending → Succeeded only via verified webhook
Order moves to DepositPaid on
payment.succeeded
Runbook: “Payment stuck in Pending”
Replay provider webhook
Verify signature (Stripe/HMAC)
Check handler logs with
x-correlation-id