Payments API

Refund a payment

Issue a full or partial refund for a previously settled payment. By default, the full amount will be refunded unless a specific amount is provided for a partial refund. If the payment was partially captured multiple times, you can specify which capture to refund by using the transaction event ID. Refer to the `transactions.events` array in the payment object to find available transaction event IDs (when the appropriate `expand` parameter is passed). When specifying a transaction event ID, the refund amount should not exceed the amount captured in that event. If no refund amount is provided, it defaults to the amount captured in that specific event.

post/payments/{id}/refund

Path parameters

idstring required

ID of payment to refund.

Headers

X-Idempotency-Keystring

Optional key to make the request idempotent. Enables a safe retry of a request without risking the user being charged or refunded multiple times. The idempotency key must be generated by the client and needs to be unique for every new request.

X-API-VERSIONstring required

Example:2.4

Specifies the version of the API to use. This must be set to 2.4.

Request body

amountinteger

The amount you would like to refund the customer, in minor units. e.g. for $7, use 700.

Defaults to remaining non-refunded amount.

orderIdstring

Optionally you can pass a specific order ID for the refund.

By default this will be set to the original orderId given on payment creation.

reasonstring

You can optionally specify a reason for the refund, for your own records. This will be returned in the refund transaction of payment responses.

transactionEventIdstring uuid

Specific capture ID to target for the refund. Use this to specify which transaction event the refund should apply to.

expandstring[] nullable

A list of fields to expand, such as transactions.events.

Example request

{
  "amount": 42,
  "orderId": "order-1234-refund",
  "reason": "Customer returned order #1234."
}

Response

Successful Response

idstring required

The unique payment ID.

You can use this ID to retrieve the payment details, or perform downstream operations.

datestring date-time required

The date and time at which the payment was created in UTC format.

dateUpdatedstring date-time required

The date and time of the last payment update in UTC format.

An enumeration.

cardTokenType'CARD_PAN' | 'NETWORK_TOKEN' | 'PROCESSOR_TOKEN'

An enumeration.

orderIdstring required

Your reference for the payment.

currencyCode'AED' | 'AFN' | 'ALL' | 'AMD' | 'ANG' | 'AOA' | 'ARS' | 'AUD' | 'AWG' | 'AZN' | 'BAM' | 'BBD' | 'BDT' | 'BGN' | 'BHD' | 'BIF' | 'BMD' | 'BND' | 'BOB' | 'BOV' | 'BRL' | 'BSD' | 'BTN' | 'BWP' | 'BYR' | 'BYN' | 'BZD' | 'CAD' | 'CDF' | 'CHE' | 'CHF' | 'CHW' | 'CLP' | 'CNY' | 'COP' | 'COU' | 'CRC' | 'CUC' | 'CUP' | 'CVE' | 'CZK' | 'DJF' | 'DKK' | 'DOP' | 'DZD' | 'EGP' | 'ERN' | 'ETB' | 'EUR' | 'FJD' | 'FKP' | 'GBP' | 'GEL' | 'GHS' | 'GIP' | 'GMD' | 'GNF' | 'GTQ' | 'GYD' | 'HKD' | 'HNL' | 'HRK' | 'HTG' | 'HUF' | 'IDR' | 'ILS' | 'INR' | 'IQD' | 'IRR' | 'ISK' | 'JMD' | 'JOD' | 'JPY' | 'KES' | 'KGS' | 'KHR' | 'KMF' | 'KPW' | 'KRW' | 'KWD' | 'KYD' | 'KZT' | 'LAK' | 'LBP' | 'LKR' | 'LRD' | 'LSL' | 'LYD' | 'MAD' | 'MDL' | 'MKD' | 'MMK' | 'MNT' | 'MOP' | 'MRO' | 'MUR' | 'MVR' | 'MWK' | 'MXN' | 'MXV' | 'MYR' | 'MZN' | 'NAD' | 'NGN' | 'NIO' | 'NOK' | 'NPR' | 'NZD' | 'OMR' | 'PAB' | 'PEN' | 'PGK' | 'PHP' | 'PKR' | 'PLN' | 'PYG' | 'QAR' | 'RON' | 'RSD' | 'RUB' | 'RWF' | 'SAR' | 'SBD' | 'SCR' | 'SDG' | 'SEK' | 'SGD' | 'SHP' | 'SOS' | 'SRD' | 'SSP' | 'SVC' | 'SYP' | 'SZL' | 'THB' | 'TJS' | 'TMT' | 'TND' | 'TOP' | 'TRY' | 'TTD' | 'TWD' | 'TZS' | 'UAH' | 'UGX' | 'USD' | 'UYU' | 'UZS' | 'VND' | 'VUV' | 'WST' | 'XAF' | 'XAG' | 'XAU' | 'XBA' | 'XBB' | 'XBC' | 'XBD' | 'XCD' | 'XDR' | 'XFU' | 'XOF' | 'XPD' | 'XPF' | 'XPT' | 'XSU' | 'XTS' | 'XUA' | 'YER' | 'ZAR' | 'ZMW' | 'ZWL' required

3-letter currency code in <a href='https://en.wikipedia.org/wiki/ISO_4217#Active_codes'>ISO 4217</a> format, e.g. <code>USD</code> for US dollars.

amountinteger required

The amount you charged the customer, in minor units.

customerIdstring

The unique identifier for your customer.

metadataobject

Additional data to be used throughout the payment lifecycle.

Example response

{
  "transactions": [
    {
      "reason": "Item returned.",
      "events": [
        {
          "id": "46d25279-9d36-4237-8f45-2dc4e4e262d6",
          "processorEventId": "30B258847H402782C",
          "date": "2025-01-22T13:39:18.992928",
          "type": "CAPTURE_SUCCEEDED",
          "amount": 1234
        }
      ]
    }
  ],
  "riskData": {
    "fraudChecks": {
      "source": "FRAUD_PROVIDER"
    },
    "cvvCheck": {
      "source": "PROCESSOR"
    },
    "avsCheck": {
      "source": "PROCESSOR"
    }
  }
}

Changes

No recorded changes to this endpoint across all 1 revision of this API.