Skip to main content

Refunds API

The Refunds API allows you to create and query refund objects. Refunds can be created against a successful payment intent, either as full or partial refunds.

Create a refund​

Creates a new refund object against a successful payment intent. You can create multiple refunds for a given payment intent as long as the total amount of all refunds does not exceed the amount that was paid.

Parameters​

payment_intentstring

The payment intent being (partially) refunded (pi_...). This is the same id returned when you created the payment intent; we resolve it to the underlying successful payment on our end.

amountinteger

The amount refunded to the customer in cents, as an integer. E.g. a $100.25 payment will use 10025 as its amount, a $27 payment will use 2700 as its amount, etc.

currencystring

A 3 letter ISO currency that governs this transaction, e.g. USD, EUR, GBP, etc. Must match the currency that was paid.

webhooksoptional, array

Webhook endpoints to notify about this refund's events. Each endpoint is configured independently.

refund_sla_timeoutoptional, integer

The point after which an outstanding refund that still has a mutable status becomes automatically canceled, in seconds. Default is 3 days.

idempotency_keyoptional, string

An idempotency key provided by you to ensure the refund is not created multiple times.

Status Codes​

  • 201 Created: A new refund was successfully created
  • 200 OK: An existing refund was found (when using idempotency_key)
  • 400 Bad Request: Invalid request (see Error Codes below)
  • 404 Not Found: No payment intent with the given reference exists

Error Codes​

  • REFUND_TX_MUST_BE_SUCCESSFUL: The payment intent must have a successful payment
  • REFUND_CCY_MISMATCH: Currency must match the payment currency
  • REFUND_RQST_AMT_GREATER_THAN_TX_AMT: Refund amount exceeds available balance
POST /v202607/refunds
const response = await fetch('https://api-{region}.orchestrapay.com/v202607/refunds', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer orch_sk_live_eu1_...',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    payment_intent: 'pi_eu1_b8b5be0f481f42b4b7f5972118777c5f',
    amount: 20000,
    currency: 'usd',
    webhooks: [
      {
        url: 'https://yoursite.com/webhooks/orchestrapay',
        secret: 'your_webhook_secret',
        events: ['refund.success', 'refund.canceled']
      }
    ],
    refund_sla_timeout: 259200,
    idempotency_key: 'refund-order-123'
  })
});

Response Parameters​

refundstring

The typed, region-coded identifier of the refund that was created (re_...).

payment_intentstring

The payment intent that was refunded (pi_...).

statusstring

The refund status. Typically pending on creation.

amountinteger

The refunded amount, in cents, echoed back.

currencystring

The 3-letter ISO currency, echoed back.

refundable_amount_leftinteger

Amount left (in cents) that can still be requested for further refunds on this payment intent.

resource_createdboolean

Whether the resource was created, or already existed (matched via its idempotency key).

RESPONSE
{
  "refund": "re_eu1_582f94c6856c447b9b2cfbbd9a528c9d",
  "payment_intent": "pi_eu1_b8b5be0f481f42b4b7f5972118777c5f",
  "status": "pending",
  "amount": 20000,
  "currency": "usd",
  "refundable_amount_left": 2700,
  "resource_created": true
}

Query refunds​

Returns a list of refunds, most recent first. Results are cursor-paginated and can be narrowed with a fixed set of filters.

Query Parameters​

limitoptional, integer, default is 25

How many refunds to return, 1 to 100.

starting_afteroptional, string

A cursor for pagination: a refund id (re_...). Returns the page of results immediately after this object.

ending_beforeoptional, string

A cursor for pagination: a refund id (re_...). Returns the page of results immediately before this object.

payment_intentoptional, string

Only return refunds for this payment intent (pi_...).

statusoptional, string

Only return refunds with this status: pending, success, or canceled.

createdoptional, object

Filter by creation time. Pass a Unix timestamp (or ISO 8601) for an exact match, or a range object.

currencyoptional, string

Only return refunds in this 3-letter ISO currency.

Notes​

  • Results are ordered by creation time, most recent first.
  • Pagination is cursor-based: pass the last item's re_ id as starting_after to get the next page.
GET /v202607/refunds
const params = new URLSearchParams({
limit: '25',
status: 'success',
payment_intent: 'pi_eu1_b8b5be0f481f42b4b7f5972118777c5f'
});
const response = await fetch(
'https://api-{region}.orchestrapay.com/v202607/refunds?' + params,
{ headers: { 'Authorization': 'Bearer orch_sk_live_eu1_...' } }
);

Response Parameters​

dataarray

The list of refunds, most recent first.

has_moreboolean

true if there are more results after this page.

RESPONSE
{
  "data": [
    {
      "refund": "re_eu1_582f94c6856c447b9b2cfbbd9a528c9d",
      "payment_intent": "pi_eu1_b8b5be0f481f42b4b7f5972118777c5f",
      "status": "success",
      "amount": 20000,
      "currency": "USD",
      "created_at": "2026-07-01T12:00:00Z"
    }
  ],
  "has_more": false
}

Get a refund​

Retrieves a single refund by its reference.

Parameters​

refundstring

The refund reference to retrieve (re_...).

GET /v202607/refunds/{refund}
const response = await fetch('https://api-{region}.orchestrapay.com/v202607/refunds/re_eu1_582f94c6856c447b9b2cfbbd9a528c9d', {
  headers: { 'Authorization': 'Bearer orch_sk_live_eu1_...' }
});

Response Parameters​

refundstring

The refund reference (re_...).

payment_intentstring

The payment intent that was refunded (pi_...).

statusstring

pending, success, or canceled.

amountinteger

Amount in cents.

currencystring

Three-letter ISO currency code.

created_atstring

ISO 8601 creation timestamp.

gateway_transaction_idstring

The gateway's own reference for this refund, for reconciliation.

RESPONSE
{
  "refund": "re_eu1_582f94c6856c447b9b2cfbbd9a528c9d",
  "payment_intent": "pi_eu1_b8b5be0f481f42b4b7f5972118777c5f",
  "status": "success",
  "amount": 20000,
  "currency": "USD",
  "created_at": "2026-07-01T12:00:00Z",
  "gateway_transaction_id": "a1e8c3f60d2b95743f0e"
}