Refund availability

A refund depends on more than the amount left on the payment: the payment must have a completed attempt, the account that took it must still be usable, and the refund has to be executable somewhere. Rather than discover that from a 422, ask first.

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

One call returns the remaining balance, whether a refund is possible at all, and which refund types that balance allows.

Response

boolean

Whether a refund can be created right now. When false, unavailable_reason says why and available_types is empty.

Amount

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

Amount

Total already refunded.

Amount

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

boolean

Whether at least one refund is in flight. A payment carrying one cannot take another until it settles.

string[]

The refund types the remaining balance allows: full, partial, or both.partial is absent when no amount smaller than the balance can be expressed in the currency. With a balance of one whole unit in a currency that has no minor unit, there is nothing between zero and the whole — only full is offered.

string | null

How the reversal would be executed.

Value	Meaning
`gateway`	Reversed directly on the original payment.
`payout`	Sent back to the original payer as an outbound transfer. Requires the project setting and `allow_payout` on the refund request.

null when no refund is available.

string | null

Why no refund can be created, or null when one can. Human-readable; do not branch on the text.

Example

curl https://api.orqex.com/v1/payment/intents/pi_9x2k4m7q1w8e/refunds/availability \
  -H "Authorization: Bearer sk_live_..."

$availability = $orchestrate->refunds()->availability('pi_9x2k4m7q1w8e');

if ($availability->isRefundable) {
    $orchestrate->refunds()->create('pi_9x2k4m7q1w8e', [
        'amount' => $availability->refundableAmount->value,
        'reason' => 'requested_by_customer',
    ]);
}

{
  "data": {
    "is_refundable": true,
    "refundable_amount": { "value": 30, "formatted": "$30.00", "short": "$30", "currency": "USD" },
    "refunded_amount": { "value": 20, "formatted": "$20.00", "short": "$20", "currency": "USD" },
    "pending_amount": { "value": 0, "formatted": "$0.00", "short": "$0", "currency": "USD" },
    "has_pending_refund": false,
    "available_types": ["full", "partial"],
    "execution_method": "gateway",
    "unavailable_reason": null
  }
}

A payment that cannot be refunded answers with the same shape:

{
  "data": {
    "is_refundable": false,
    "refundable_amount": { "value": 0, "formatted": "$0.00", "short": "$0", "currency": "USD" },
    "refunded_amount": { "value": 50, "formatted": "$50.00", "short": "$50", "currency": "USD" },
    "pending_amount": { "value": 0, "formatted": "$0.00", "short": "$0", "currency": "USD" },
    "has_pending_refund": false,
    "available_types": [],
    "execution_method": null,
    "unavailable_reason": "This payment has no refundable balance left."
  }
}

Availability is a snapshot. Two refunds racing on the same payment are still serialised server-side, and the second is rejected on balance. Read availability to build the request, not to skip handling a 422.

Once you have an amount, see Refunds.

Get started

Payments

Payouts

Events

Utilities

MCP

Response

Example

​Response

​Example

Response

Example