Skip to main content

Refunds API

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

Create a refund​

Creates a new refund object for a 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 payment intent amount.

Parameters​

payment_intent_secretinteger

The id of the payment intent that is (partially) refunded.

amountinteger

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

currencystring

A 3 letter ISO currency that governs this payment intent, i.e. EUR, EGP, NGN, etc.

webhook_urlsoptional, array

An array of URLs that will receive a POST Webhook once the refund status changes. All these webhooks will be called whenever the status of this ressource change.

webhook_secretoptional, string

Secret that's passed back to the webhooks we call when the status of a refund changes.

refund_sla_timeoutoptional, integer

The point after which an outstanding refund that has a mutable status (e.g. not finished / canceled) becomes automatically canceled. This number is in seconds. Default is 3 days.

checkout_intent_idempotency_keyoptional, string

An idempotency key provided by you to ensure resources are not created multiple times.

Status Codes​

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

Error Codes​

  • REFUND_TX_MUST_BE_SUCCESSFUL: Payment intent must be in success status
  • REFUND_CCY_MISMATCH: Currency must match the payment intent currency
  • REFUND_RQST_AMT_GREATER_THAN_TX_AMT: Refund amount exceeds available balance
POST /refunds
curl -X POST https://api.orchestrapay.com/refunds \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_intent_secret": 19302,
    "amount": 20000,
    "currency": "EGP",
    "webhook_urls": ["https://excited-candied-measure.glitch.me/"],
    "webhook_secret": "My-Secret-123",
    "refund_sla_timeout": 259200,
    "checkout_intent_idempotency_key": "refund-tx-2038489201"
  }'

Response Parameters​

refund_idinteger

The id of the refund that was created.

refundable_amount_leftinteger

Amount left that can be requested for further refund (in cents) for the specified payment intent.

resource_createdboolean

Whether the resource was created or already existing (through its idempotency key).

RESPONSE
{
  "refund_id": 1728,
  "refundable_amount_left": 2700,
  "resource_created": true
}

Query refunds​

Retrieves a paginated list of refunds that match your query criteria.

Query Parameters​

limitoptional, integer, default is 50

Number of entities per page (max 1000)

pageoptional, integer

Page number to query

sortByoptional, string

Sort by property:ASC|DESC (e.g., "amount:DESC"). Available columns: id, amount

filteroptional, object

Filter parameters for querying refunds

Filter Operators​

$eqEqual to
$notNot equal to
$nullIs null
$inIn array
$gtGreater than
$gteGreater than or equal to
$ltLess than
$lteLess than or equal to
$btwBetween
$ilikeCase-insensitive like
$swStarts with
$containsContains
GET /refunds
curl https://api.orchestrapay.com/refunds \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d "limit=50" \
  -d "page=1" \
  -d "sortBy=amount:DESC" \
  -d "filter.currency=$eq:EGP" \
  -d "filter.status=$in:success,canceled"

Response Parameters​

data[]array

Array of refund objects

metaobject

Pagination metadata

linksobject

Pagination links

Notes​

  • The response follows JSON:API pagination specifications
  • You can sort by the following columns: id, amount
  • Filterable properties include: currency, created_at, updated_at, status, amount, id, checkout_intent_idempotency_key, checkout_intent_secret, gateway, gateway_transaction_id, gateway_transaction_human_readable, uuid
  • To fetch a single record by ID, use ?filter.id=$eq:...
  • Status values in the response are simplified to their base form (e.g., pending_created becomes pending)
RESPONSE
{
  "data": [
    {
      "id": 5678,
      "amount": 1000,
      "currency": "EGP",
      "status": "success",
      "sub_status": "success",
      "created_at": "2023-07-01T12:00:00Z",
      "updated_at": "2023-07-01T12:00:00Z",
      "checkout_intent_idempotency_key": "550e8400-e29b-41d4-a716-446655440000",
      "gateway_transaction_id": "ref_1J5JGz2eZvKYlo2C7X2Q8Q",
      "gateway_transaction_human_readable": "MyBnpl*Ref*Tx920 he.lp/20s",
      "gateway": "stripe",
      "succeeded_at": "2023-07-01T12:00:00Z"
    }
  ],
  "meta": {
    "itemsPerPage": 50,
    "totalItems": 95,
    "currentPage": 2,
    "totalPages": 4,
    "sortBy": [["amount", "DESC"]]
  },
  "links": {
    "first": "https://api-staging.orchestrapay.com/refunds?page=1&limit=50&sortBy=amount:DESC",
    "previous": "https://api-staging.orchestrapay.com/refunds?page=1&limit=50&sortBy=amount:DESC",
    "current": "https://api-staging.orchestrapay.com/refunds?page=2&limit=50&sortBy=amount:DESC",
    "next": "https://api-staging.orchestrapay.com/refunds?page=3&limit=50&sortBy=amount:DESC",
    "last": "https://api-staging.orchestrapay.com/refunds?page=4&limit=50&sortBy=amount:DESC"
  }
}

Refund Statuses​

Refunds have three main statuses:

  • pending: The refund is being processed
  • success: The refund has been successfully processed
  • canceled: The refund has been canceled

Each status has sub-statuses that provide more detailed information:

Sub-statuses​

  • pending_created: Initial state when refund is created
  • pending_promise: Refund is being processed by the gateway
  • success: Refund has been successfully processed
  • canceled_timeout_potential_ghost: Refund timed out and may be a ghost payment intent
  • canceled_timeout_e2e_manual: Refund timed out and requires manual intervention