Refund a payment (fully or partially)
create_refundRefund a payment fully or partially by bank transfer, using an idempotency key to prevent duplicate payouts and an optional destination when the original sender is unknown.
Instructions
Refund a payment (fully or partially).
Refund a payment, fully or partially, by bank transfer from your available balance. Idempotency-Key is required.
Without amount, the whole refundable amount is refunded. Only succeeded or partially_refunded payments can be refunded (409 payment_not_refundable).
Destination. When the sender’s full account details are known, the refund always goes back to that account: omit destination (a different one returns 400 refund_destination_mismatch). When the sender isn’t known, pass destination (400 refund_destination_required otherwise); it is verified by name enquiry. In live mode a custom destination also needs outbound transfers enabled (403 transfers_disabled).
The payment becomes partially_refunded or refunded only once the refund has actually been paid out (refund.succeeded). Without a reference, one is derived from the Idempotency-Key, so a retried request can’t create a second refund.
In live mode this sends real money or changes where money is paid, and it cannot be undone. Before calling, confirm the exact amount (in kobo) and the destination with the user.
Choose an idempotency_key and reuse it if you retry this call, so it can never happen twice.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| amount | No | Amount in kobo; defaults to the full refundable amount (partial refunds allowed) | |
| reason | Yes | ||
| payment | Yes | The original payment (pay_…) | |
| metadata | No | ||
| reference | No | Your unique refund reference | |
| destination | No | Where to send the money. Defaults to the original sender when their full account details are known. | |
| idempotency_key | Yes | Required. A unique key you choose for this request (for example a UUID). If you retry, send the SAME key: the API returns the original result instead of acting twice. |