Refund
Once a payment has been successfully captured (either fully or partially), funds can be refunded to the consumer through a refund request.
Refunds can be processed in full or in multiple partial amounts, as long as the total refunded amount does not exceed the original captured amount.
Important
Not all payment methods support refunds. The support for refunds and their validity periods are detailed in the properties of each payment method.
Types of Refund
Full: The payment charge can be refunded in full.
Partial: The payment charge can be refunded in full.
Multiple: More than one refund can be performed on a single payment charge, the total amount cannot exceed the original authorized amount.
Refunding a Payment Charge
In your v1/payment-charges/{paymentChargeId}/refunds request, include:
Data Field | Requirement | Description |
---|---|---|
amount | M | The amount to be refunded in the smallest currency unit. This must not exceed the captured amount. |
merchantRefundReference | O | Merchant reference for the refund. |
refundDescriptor | O | Description of the refund. |
Request
POST
/v1/payment-charges/charge_ViwZ6ObcA6GO2V5dS6ssH/refunds
{
"amount": 900,
"merchantRefundReference": "your_refund_reference",
"refundDescriptor": "your_refund_descriptor"
}
Response
{
"id": "refund_NrDVHpi7FZ9PhMXWkwFcu",
"amount": 900,
"status": "REFUNDED",
"merchantRefundReference": "your_refund_reference",
"refundDescriptor": "your_refund_descriptor",
"createdAt": "2025-03-24T12:13:55.114Z",
"updatedAt": "2025-03-24T12:13:55.114Z",
"_links": {
"payment_charge": {
"href": "/v1/payment-charges/charge_mev5QxOzVXSbXoRogFpsC"
}
}
}
Whilst the refund is processing the payment charge status will temporarily show as REFUND_PROCESSING
. Once the full captured amount has been refunded the payment charge status will update to REFUNDED
.
Failed reasons
type | Reason |
---|---|
PAYMENT_CHARGE_NOT_FOUND | The payment charge does not exist. |
PAYMENT_CHARGE_INSUFFICIENT_FUNDS | The refund exceeds the total amount captured. |
PAYMENT_CHARGE_INVALID_STATE | The payment charge has already been refunded. |
Updated 23 days ago