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.
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-22API versions before 2026-09-22 continue to work unchanged.
Get started
- Refund payments guide - how to issue refunds and monitor their status, including declined refunds
- Refund decline reasons - the full list of
decline_reasonvalues for refunds - Refund an order - updated operation reference for version
2026-09-22 - API changelog - all changes in version
2026-09-22