API Console
Help

· Revolut

What's new in 2026-09-22

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 operation now returns the refund order with the failure reason included, so you can handle declines in a single round-trip.

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:

{
  "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 operation and check the decline_reason field of the refund payment. To find the refund order id, use the Retrieve an order list operation, filtered by the merchant_order_data_reference you provided in the refund request or by the creation date.

Adoption guidance

When you adopt version 2026-09-22, update your refund handling: a 200 response from Refund an 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:

Revolut-Api-Version: 2026-09-22

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

Get started