Process a partial refund and understand refund vs. reversal semantics

In-depth guide

Steps

1. Determine whether the transaction has settled: if the authorization has not yet been captured or settled, use a cancellation or void (reversal) rather than a refund — reversals return funds instantly and typically incur no fee.
2. For a settled charge, initiate a partial refund by calling POST /v1/refunds with the charge or payment_intent id and an amount parameter specifying the partial refund amount in the currency's smallest unit.
3. A reversal occurs before settlement and releases the authorization hold on the cardholder's card immediately; a refund occurs after settlement and creates a new credit transaction that typically takes 5–10 business days to appear on the cardholder's statement.
4. Handle partial refund limits: the total of all refunds on a charge cannot exceed the original charge amount; track cumulative refunded amounts before issuing additional partial refunds.
5. Listen for the charge.refunded or refund.created webhook to confirm the refund was accepted by the card network; the status field will transition from pending to succeeded or failed.
6. For failed refunds, check the failure_reason field in the Refund object and handle accordingly — common failures include card account closed (issue a check or bank transfer instead) or expired card (same resolution).