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.

Refund a payment charge

In your v1/payment-charges/{paymentChargeId}/refunds request, include:

Request

POST /v1/payment-charges/charge_mev5QxOzVXSbXoRogFpsC/refunds

{
  "amount": 900,
  "merchantRefundReference": "your_refund_reference",
  "refundDescriptor": "your_refund_descriptor",
  "refundReason": "CUSTOMER_REQUEST"
}

Response

{
  "id": "refund_NrDVHpi7FZ9PhMXWkwFcu",
  "amount": 900,
  "status": "REFUNDED",
  "merchantRefundReference": "your_refund_reference",
  "refundDescriptor": "your_refund_descriptor",
  "refundReason": "CUSTOMER_REQUEST",
  "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.

The payment charge status will update to REFUNDED only after the full captured amount has been refunded.

Refund status

A refund can be issued for any amount up to the total captured amount. Attempting to refund more than the captured amount will result in an error.

If the refund cannot be processed synchronously, its status will initially be set to PENDING, and will later transition to either REFUNDED or FAILED.

Example failure

{
    "id": "refund_NrDVHpi7FZ9PhMXWkwFcu",
    "amount": 10,
    "status": "FAILED",
    "merchantRefundReference": "your_refund_reference",
    "refundReason": "CUSTOMER_REQUEST",
    "refundDescriptor": "your_refund_descriptor",
    "failure": {
        "failureType": "INTERNAL_DECLINE",
        "failureCode": "EXCEEDS_CAPTURED_AMOUNT",
        "failureMessage": "Insufficient captured funds to process the refund request"
    },
    "createdAt": "2025-06-09T16:40:49.712Z",
    "updatedAt": "2025-06-09T16:40:49.712Z",
    "_links": {
        "payment_charge": {
            "href": "/v1/payment-charges/charge_mev5QxOzVXSbXoRogFpsC"
        }
    }
}