Merchant API version `2026-09-22` is now available. It changes how declined refunds are returned for Revolut Pay payments: instead of a `400` error response, the [Refund an order](/docs/api/merchant#refund-order) operation now returns the refund order with the failure reason included, so you can handle declines in a single round-trip.

## What's new in `2026-09-22`

### Declined Revolut Pay refunds return `200` with the failure reason

When a Revolut Pay refund is declined or failed, the operation now returns `200` with the refund order. The refund payment in `payments[]` carries the `decline_reason`, telling you why the refund was unsuccessful - for example `suspected_fraud` or `technical_error`:

```json
{
  "id": "6852ea10-3a1b-4c5d-8e9f-0a1b2c3d4e5f",
  "type": "refund",
  "state": "processing",
  "amount": 100,
  "currency": "GBP",
  "payments": [
    {
      "id": "6852ea10-7d8e-9f0a-1b2c-3d4e5f6a7b8c",
      "state": "declined",
      "decline_reason": "suspected_fraud",
      "amount": 100,
      "currency": "GBP",
      "payment_method": {
        "type": "revolut_pay_card"
      }
    }
  ],
  "related_order_id": "6852e963-d6a9-a5a4-9609-50b3addc4225"
}
```

In API versions before `2026-09-22`, declined refunds return a `400` error response instead, and the error body doesn't include the failure reason.

### Card refunds are unchanged

Declined card refunds (including digital wallets) still return a `400` error response without the failure reason. The declined refund order is still created: to learn why the refund was unsuccessful, retrieve it with the [Retrieve an order](/docs/api/merchant#retrieve-order) operation and check the `decline_reason` field of the refund payment. To find the refund order `id`, use the [Retrieve an order list](/docs/api/merchant#retrieve-order-list) operation, filtered by the `merchant_order_data_reference` you provided in the refund request or by the creation date.

:::warning[Adoption guidance]
When you adopt version `2026-09-22`, update your refund handling: a `200` response from [Refund an order](/docs/api/merchant#refund-order) can now contain a declined or failed refund payment. Don't treat every `2xx` response as a successful refund - check the `state` and `decline_reason` fields of the refund payment in `payments[]`.
:::

## How to adopt the new version

Set the `Revolut-Api-Version` request header to `2026-09-22`:

```http
Revolut-Api-Version: 2026-09-22
```

API versions before `2026-09-22` continue to work unchanged.

## Get started

- [Refund payments guide](/docs/guides/merchant/operations/refunds) - how to issue refunds and monitor their status, including declined refunds
- [Refund decline reasons](/docs/guides/merchant/reference/error-codes/decline-reasons) - the full list of `decline_reason` values for refunds
- [Refund an order](/docs/api/merchant#refund-order) - updated operation reference for version `2026-09-22`
- [API changelog](/docs/guides/merchant/reference/versioning/changelog) - all changes in version `2026-09-22`