Audience: Finance, Support, Developers, PMs
Outcomes: Clean refunds; correct expectations; resilient client code
Refunds & reversals
Initiation:
Cards: Stripe Dashboard/API
Bank: provider API/dashboard
Crypto: on-chain or provider flow
Reconciliation: refund webhook → mark Refunded; update invoices
Partial refunds: supported; appear as credit notes; reduce released totals
Edge case: active platform dispute + refund → follow provider rules; record both
Chargebacks vs platform disputes
Chargeback (card): initiated by cardholder/bank via Stripe; you submit evidence to network
TradeOS dispute: about deliverables; resolved by admins; controls escrow release/refunds
Status, idempotency & retries
Statuses:
Initiated,Pending,Succeeded,Failed,Refunded,ChargedBackIdempotency: stable reference per attempt; webhooks dedupe by event.id; releases dedupe by release reference
Retries:
5xx/network ⇒ exponential backoff with jitter
4xx ⇒ fix payload/permissions (don’t blind-retry)
QA checklist
Duplicate webhook doesn’t double-apply refund
Dispute freeze prevents releases per policy
Runbook: “Duplicate charge concern”
Show invoice & provider reference; confirm with provider report; highlight idempotency protections