Audience: Finance/Ops, Admins, Developers
Outcomes: Correct settlement handling; safe milestone-based payouts
Payments (card & bank)
# Card (Stripe) — create Payment Intent curl -X POST $API_BASE/api/payments/intents -b cookies.txt \ -H 'Content-Type: application/json' \ -d '{"orderId":"ord_123","amount":150000,"currency":"USD"}' # Bank (open banking) — start link curl -X POST $API_BASE/api/payments/bank/link -b cookies.txt \ -H 'Content-Type: application/json' \ -d '{"orderId":"ord_123","amount":150000,"currency":"EUR","returnUrl":"https://app.example.com/return"}'
Reconciliation rule
Order status advances only after a verified webhook.
Persist provider reference (PI ID, bank ref, tx hash).
Webhook security
Stripe:
express.raw()+ signature verification.Bank: HMAC header
X-Hmac-Signature.
Escrow architecture (on-chain)
# Prepare deployment curl -X POST $API_BASE/api/escrow/deploy-contract -b cookies.txt \ -H 'Content-Type: application/json' \ -d '{"orderId":"ord_123","buyerAddress":"0x...","sellerAddress":"0x...","totalAmount":"150000","currency":"USDC"}' # Monitor tx curl -X POST $API_BASE/api/escrow/monitor-deployment -b cookies.txt \ -H 'Content-Type: application/json' -d '{"txHash":"0x...","orderId":"ord_123"}' # Release funds curl -X POST $API_BASE/api/escrow/release -b cookies.txt \ -H 'Content-Type: application/json' -d '{"orderId":"ord_123","milestoneId":"m1","amount":50000}'
Edge cases
Insufficient gas → release fails; retry after funding wallet.
Partial releases allowed; never exceed remaining escrow balance.
Currency, rounding & display
Amounts saved in minor units; currency as ISO-4217.
Display uses org locale; do not recalc totals on the client.
Conversions (if needed) happen at order/invoice time; store the rate used.
Zero-decimal currencies (e.g., JPY) handled accordingly.
Rounding: banker’s or policy-defined scheme.
QA checklist
Webhook with bad signature ⇒ rejected; no order status change.
Escrow release beyond remaining balance ⇒ 400.
EUR order shows EUR everywhere; conversion stored when applicable.