Create a full or partial refund through the API

Use `POST https://api.payerone.com/checkout/v1/refunds` from your server with the Merchant Token. Refunds are merchant-initiated; your application chooses the amount and reason. The currently supported gateway types are **Stripe, Razorpay, PayPal and Cashfree**.

Check eligibility

The order must be **Paid**, processed through a supported payment gateway, and have a recorded captured amount and provider payment reference. Refund only the available refundable amount. Pending or partially paid orders, unsupported payment methods and ordinary crypto transfers do not use this gateway refund API.

Before submitting, use `GET /checkout/v1/refunds?order_id=PAYERONE_ORDER_ID` to inspect `info.order_refund_details.refund_summary`. Check `refund_supported`, `refundable_amount`, `pending_refund_amount` and `currency_code`. The refund currency follows the captured payment currency and may differ from the original order currency.

Submit the request

| Field | Requirement |

| --- | --- |

| `order_id` | PayerOne display order ID, or supply `transaction_id` instead. |

| `transaction_id` | Alternative PayerOne payment transaction UUID; not a provider payment ID or blockchain hash. |

| `amount` | Positive amount no greater than the available refundable amount, in the captured payment currency. |

| `reason` | Optional explanation for the refund. |

| `note` | Optional refund note. |

| `idempotency_key` | Stable unique reference for this intended refund; strongly recommended even though the field is optional. |

{
  "order_id": "PAYERONE_ORDER_ID",
  "amount": 10.00,
  "reason": "Customer requested cancellation",
  "idempotency_key": "shop-1001-refund-01"
}

Save and track the result

The response includes a `refund` object with its `refund_id`, order reference, amount, currency and status. Store the refund ID and idempotency key. A recorded request, a successful HTTP response or a pending provider result does not mean the customer has received a completed refund.

Use the same idempotency key when retrying the same intended request after an uncertain response. Do not reuse the key for a different amount or refund. Do not generate a new key just because a request timed out; look up the original refund first.

Platform fees are not automatically reversed by this refund flow. Refunds created directly in a provider dashboard are outside the automatic request history described here; reconcile them separately before requesting another refund in PayerOne.