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 FieldRequirementDescription
amountMThe amount to be refunded in the smallest currency unit. This must not exceed the captured amount.
merchantRefundReferenceOMerchant reference for the refund.
refundDescriptorODescription 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

typeReason
PAYMENT_CHARGE_NOT_FOUNDThe payment charge does not exist.
PAYMENT_CHARGE_INSUFFICIENT_FUNDSThe refund exceeds the total amount captured.
PAYMENT_CHARGE_INVALID_STATEThe payment charge has already been refunded.