Audience: Finance/Ops, Developers, QA, SRE
Outcomes: Accurate ledgers/exports; deterministic tests; early warning on issues
Reconciliation & ledger exports
Store gross, fee, net, currency, FX rate+timestamp, provider ref
Tie every entry to orderId and invoiceId
Export daily CSV/JSON for Payments, Releases, Refunds (timestamps, actor, references, provider IDs)
Bank reconciliation: match by amount/date window/reference; investigate unmatched; re-pull provider reports
Multi-currency & conversion rules
Store amounts in minor units + ISO currency
Display by user locale; never recalc totals on client
Fiat-priced + crypto-settled: store applied FX rate + timestamp
Zero-decimal currencies (e.g., JPY) need special casing in sums/display
Testing & sandbox
Stripe CLI
stripe listen --forward-to localhost:3000/api/webhooks/stripe
Use test cards for success/decline/3DS/insufficient funds
Bank: sandbox flows; simulate settlement/failure webhooks
Crypto: testnet; verify deployment, balances, releases
Confirm order transitions & invoice creation on webhook receipt
Observability (metrics, logs, alerts)
Metrics: API error rate/latency (p95), webhook backlog/latency, success rate by rail, chargeback/refund rates, escrow release throughput
Logs: include
x-correlation-id,orderId, provider refs; redact secrets/PANsAlerts: webhook gap > X min; success rate below threshold; release failures > N/hr
QA checklist
Sandbox runs produce expected events & state
Alerts fire on simulated webhook gap
Runbook: “Unmatched ledger lines”
Expand date window; match on reference; reconcile fees/FX; if still unmatched, re-pull provider exports and diff