Audience: Developers, Finance, Crypto-enabled teams
Outcomes: High-value bank flow with webhook confirmation; USDC/ETH escrow
Bank link (create & settle)
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", "reference":"ORD123-DEP" }'Returns provider URL; settlement is asynchronous (hours/days)
Order → DepositPaid when webhook confirms receipt
Always store provider reference for reconciliation
Crypto escrow (USDC/ETH)
Prepare deployment
curl -X POST $API_BASE/api/escrow/deploy-contract -b cookies.txt \ -H 'Content-Type: application/json' \ -d '{ "orderId":"ord_123", "buyerAddress":"0xBuyer...", "sellerAddress":"0xSeller...", "totalAmount":"150000", "currency":"USDC" }'Monitor deployment
curl -X POST $API_BASE/api/escrow/monitor-deployment -b cookies.txt \ -H 'Content-Type: application/json' \ -d '{"txHash":"0xHASH","orderId":"ord_123"}'Release milestone
curl -X POST $API_BASE/api/escrow/release -b cookies.txt \ -H 'Content-Type: application/json' \ -d '{"orderId":"ord_123","milestoneId":"m1","amount":50000}'Best practices
Keep contract address and tx hash on the order
Factor gas; never exceed remaining escrow
Edge cases
Insufficient gas ⇒ release fails; retry after funding
Network congestion ⇒ backoff with jitter
QA checklist
Partial releases allowed; totals guarded
On-chain events reconcile to internal state