Refunds

A refund can only be created against a completed payment intent. Partial refunds are allowed; multiple refunds may be issued against the same intent as long as the refundable amount permits it.

Create a refund

POST /payment/intents/{intentId}/refunds

number

required

Amount to refund in major units (e.g. 25 = 25.00). Minimum 1. Must not exceed the refundable_amount returned by refund availability. Decimals are accepted and rounded to the scale the currency supports.

string

required

Reason for the refund. Must be one of the following values:

Value	Description
`requested_by_customer`	The customer requested the refund
`duplicate`	The payment was a duplicate charge
`fraudulent`	The payment is suspected fraud
`product_not_received`	The customer did not receive the product or service
`product_unsatisfactory`	The product or service did not meet expectations
`order_cancelled`	The order was cancelled
`other`	Any other reason — use `note` to add details

string

Free-text explanation. Maximum 500 characters.

object

Up to 10 key/value pairs stored on the refund.

boolean

When true, Orchestrate may process the refund as an outbound payout to the original payer if the payment gateway does not support a direct reversal. Requires the corresponding project setting to be enabled. When this path is taken, the execution_method on the refund will be payout and the payout block will be populated.

A rejected refund returns 422 with the service’s error message — for example, if the amount exceeds what is refundable or the payment is not in a refundable state.

Refundable amount

Call refund availability before submitting a refund:

GET /payment/intents/{intentId}/refunds/availability

It returns refundable_amount — authoritative, already reserving in-flight refunds — along with whether a refund is possible at all and whether the remaining balance allows a partial one. Use it rather than your own arithmetic.

Refund resource

string

Refund identifier.

Amount

{ value, formatted, short, currency } — the refunded amount.

Amount | null

Amount sent to the payment gateway. It differs from amount when the payment was processed in another currency.

ExchangeRate | null

Effective conversion between amount and processed_amount. Contains value, from_currency, to_currency, and a display-ready expression. null when both amounts use the same currency.

string

full when the refund covers the full intent amount; partial otherwise.

string

How the refund was processed: gateway (reversed through the original payment gateway) or payout (sent as an outbound payout to the original payer).

string

One of pending, processing, completed, failed.

object

{ value, label } — the reason enum value and its human-readable label.

string

The note supplied at creation, if any.

string | null

Machine-readable failure code when status is failed.

string | null

Human-readable failure message when status is failed.

object

The metadata supplied at creation.

object | null

Populated when execution_method is payout. Contains:

Field	Description
`id`	Payout identifier
`amount`	Requested payout amount as an Amount object
`settlement_amount`	Amount processed by the payout gateway, or `null`
`exchange_rate`	Effective ExchangeRate object, or `null`
`gateway_code`	The gateway used to send the payout
`method`	Payout method identifier
`recipient`	Payout instrument object describing where funds were sent
`gateway_transaction_id`	Provider transaction identifier
`fee_amount`	Fee charged for the payout as an Amount object, or `null`
`status`	Payout status
`initiated_at`	ISO 8601 timestamp
`completed_at`	ISO 8601 timestamp

string | null

ISO 8601 timestamp when the refund completed.

string | null

ISO 8601 timestamp when the refund failed.

string

ISO 8601 timestamp when the refund was created.

List and retrieve

List all refunds for an intent:

GET /payment/intents/{intentId}/refunds

Returns a paginated collection. See API conventions for the pagination shape. Retrieve a single refund:

GET /payment/intents/{intentId}/refunds/{refundId}

Example

curl -X POST https://api.orqex.com/v1/payment/intents/pi_.../refunds \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 25,
    "reason": "requested_by_customer",
    "note": "Customer changed their mind before delivery."
  }'

use Orqex\Client;

$client = new Client('sk_live_...');

// Check what can still be refunded first
$availability = $client->refunds->availability('pi_...');

if ($availability->data->is_refundable && $availability->data->refundable_amount->value >= 25) {
    $refund = $client->refunds->create('pi_...', [
        'amount' => 25,
        'reason' => 'requested_by_customer',
        'note'   => 'Customer changed their mind before delivery.',
    ]);
}

Get started

Payments

Payouts

Events

Utilities

MCP

Create a refund

Refundable amount

Refund resource

List and retrieve

Example

​Create a refund

​Refundable amount

​Refund resource

​List and retrieve

​Example

Create a refund

Refundable amount

Refund resource

List and retrieve

Example