Implement a correct refund state machine handling async refunds, failed refunds, and partial refunds

Steps

1. Model refund states explicitly in your database: PENDING, PROCESSING, SUCCEEDED, FAILED, and CANCELLED; the initial state on API submission is PENDING, not SUCCEEDED — most PSPs process refunds asynchronously.
2. Submit the refund via the PSP API with the original charge/payment ID and the refund amount in minor units; for partial refunds, submit an amount less than the original charge — confirm the PSP supports partial refunds on the original payment method (some wallets and BNPL methods do not).
3. Store the PSP-assigned refund ID alongside your internal refund record; use this ID for all subsequent status lookups and to correlate webhook events.
4. Listen for refund webhooks: Stripe emits 'charge.refund.updated', PayPal emits 'PAYMENT.CAPTURE.REFUNDED', etc.; update your local state on each event rather than assuming the refund succeeded immediately after the API call.
5. Handle FAILED refunds: failures occur when the original card has been cancelled, the account closed, or the refund window has expired; in these cases, issue the refund via alternative means (bank transfer, store credit) and update your refund record with 'FAILED' status and reason.
6. For partial refund tracking, store each partial refund as a separate record linked to the original payment; sum refunded amounts and compare to the original charge amount to determine remaining refundable balance before allowing further partial refunds.