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

integer

required

Amount to refund in major units (e.g. 25 = 25.00). Minimum 1. Must not exceed refunds_summary.refundable_amount.

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

Every payment intent carries a refunds_summary object:

Amount

Total already refunded.

Amount

Total currently in-flight refunds (created but not yet completed).

Amount

The amount you may safely refund right now. This is authoritative — it already accounts for in-flight refunds. A refund up to this value is guaranteed not to be rejected on balance grounds.

boolean

Whether at least one refund is currently in the pending or processing state.

Always use refundable_amount — not your own arithmetic — before submitting a refund.

Refund resource

string

Refund identifier.

Amount

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

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
`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
`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 refundable amount first
$intent = $client->paymentIntents->get('pi_...');
$refundable = $intent->data->refunds_summary->refundable_amount->value;

if ($refundable >= 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