Orchestrate partial refunds on Stripe charges and select the correct refund reason for downstream reporting and dispute handling

In-depth guide

Steps

1. Issue a partial refund via POST /v1/refunds with charge or payment_intent, the amount to refund in the smallest currency unit, and an optional reason (duplicate, fraudulent, or requested_by_customer)
2. Multiple partial refunds can be issued against the same charge up to the full original amount; retrieve all refunds for a charge via GET /v1/charges/{id} and inspect the refunds list object
3. Set reason=fraudulent only when the original charge was unauthorized fraud — this triggers Stripe Radar signals and affects dispute metrics; use requested_by_customer for standard returns
4. Retrieve the Refund object to verify status; async refund methods (e.g., ACH-funded charges) may show status=pending before transitioning to succeeded or failed
5. Handle refund.failed events via webhook — Stripe may fail to reverse funds if the original payment method is no longer valid (e.g., closed card account); implement a fallback (check, bank transfer) for failed refunds
6. Include metadata on the refund object for order management correlation — use metadata.order_id or similar to enable efficient reconciliation against your internal order system