Return money from a completed payment - in full or in part - and track every refund to a final state.
Refunds return money from a completed payment back to your customer's original payment method. This tutorial shows you how to create full and partial refunds using the Merchant API, and how to monitor refund status until you can confirm the outcome in your system.
What is a refund
A refund is a server-to-server operation where your backend asks Revolut to return funds to the customer. When you refund a payment:
- Revolut creates a new order of type
refund. - The refund order contains
related_order_id, which links to the original order you refunded. - The refund is processed asynchronously - it can take up to 2 days to complete - so monitor the refund order's status until it reaches a final state.
If you use manual capture, cancelling an uncaptured order (or letting an authorisation expire) is typically faster and less costly than capturing and then refunding.
For more details, see:
How it works
Refunds are a server-to-server integration between the Merchant API and your backend server:
- Your system identifies the original order you want to refund (must be in state
completed). - Your server calls the Refund an order endpoint with the refund amount and currency.
- Revolut returns a new refund order. Store the
idof the refund order in your system. - Your system monitors the refund order's lifecycle.
To monitor refund processing in real time, use webhooks. For setup steps, see: Use webhooks to track order and payment lifecycle.
How refunds fit your operations
In most merchant setups, refunds are triggered from a customer support tool or an order management system (OMS). Typical steps are:
- Validate the request (e.g., returns policy, delivery status, fraud checks).
- Calculate the refund amount (full vs. partial, shipping, taxes, discounts).
- Create the refund through your backend (Merchant API).
- Once the refund order reaches a final state - this can take up to 2 days - update internal systems (OMS, accounting, inventory) and notify the customer.
Full vs partial refunds
| Full refund | Partial refund | |
|---|---|---|
| When to use | You return the entire captured amount | You return only part of the captured amount |
| API request | amount equals the original order amount | amount is less than the original order amount |
| Multiple refunds | Not applicable | You can issue multiple partial refunds, as long as the total refunded amount does not exceed the original paid amount |
Before you begin
Ensure you have:
- Active Revolut Business account with Merchant capabilities
- API credentials for the Merchant API
- A
completedpayment order to refund (you know its orderid) - Server-side integration capability (server-to-server API flow)
- An understanding of how you accept payments with your chosen integration - see Introduction to online payments
Refunds are not supported with Pay by Bank payments.
Implement refund processing
1. Retrieve the original order details
Use the Retrieve an order endpoint to confirm:
- the order is in state
completed - the
amountandcurrencyyou will use for the refund - how much you have already refunded (if you support multiple partial refunds)
Send a GET request to the Retrieve an order endpoint with the original order id:
GET /api/orders/{order_id} HTTP/1.1
Host: merchant.revolut.com
Authorization: Bearer sk_abcdef12347890_...
Revolut-Api-Version: 2026-08-172. Create a refund order
Create a refund by calling Refund an order from your backend server, using the original order id you want to refund.
Required parameters:
| Parameter | Description |
|---|---|
amount | Specified in the smallest currency unit (for example, 10000 = £100.00). |
currency | Must match the original order currency. |
Optional parameters:
| Parameter | Description |
|---|---|
description | Optional, user-facing description for the refund. |
merchant_order_data.reference | Your internal refund reference/ID for correlating Revolut refund orders with your system. This value is included in webhook callbacks as merchant_order_ext_ref. |
metadata | Optional key-value pairs for internal tracking. |
Set amount to the full captured amount of the original order (£100.00 → 10000). The example also passes the optional description, merchant_order_data.reference, and metadata parameters.
POST /api/orders/{order_id}/refund HTTP/1.1
Host: merchant.revolut.com
Authorization: Bearer sk_abcdef12347890_...
Revolut-Api-Version: 2026-08-17
Content-Type: application/json
{
"amount": 10000,
"currency": "GBP",
"description": "Example refund description",
"merchant_order_data": {
"reference": "example_order_reference_123456"
},
"metadata": {
"example_metadata_1": "Example metadata value 1",
"example_metadata_2": "Example metadata value 2"
}
}When the operation succeeds, store the refund order id from the response. You'll use it to monitor the refund status.
3. Monitor refund status
Refunds are processed asynchronously, so monitor the refund order until you can confirm it completed successfully.
A refund can take up to 2 days to complete. Keep your refund process open and keep handling refund events (or polling the refund order) for at least that window before you finalise the refund on your side - the absence of a webhook right after creating the refund doesn't mean the refund failed.
For refunds to SEPA Direct Debit payment methods, the window is longer: processing typically takes 3-4 business days, and funds can take up to 5 business days to appear on the customer's account. For more details, see: SEPA Direct Debit refunds.
What to expect for a typical refund order:
| Stage | Refund order | When |
|---|---|---|
| Refund created | processing (payment: refund_validated) | Immediately, in the refund response |
| Refund processing | processing | Can take up to 2 days |
| Refund final | completed, or declined/failed | Final webhook event, or a polled final state |
Listen to webhooks to receive asynchronous notifications when the refund order changes state. This is the recommended way to get notified about refund outcomes.
To set up webhooks, follow: Use webhooks to track order and payment lifecycle.
When you create the refund, you receive a refund order id. Use that value to correlate webhook callbacks (it will appear as order_id in the webhook payload). If you set merchant_order_data.reference on the refund, it also appears in the payload as merchant_order_ext_ref.
Subscribe to these events and handle them for the refund order:
| Event | Description |
|---|---|
ORDER_COMPLETED | Refund finished successfully |
ORDER_PAYMENT_DECLINED | Refund could not be processed (declined) |
ORDER_PAYMENT_FAILED | Refund could not be processed (technical failure) |
{
"event": "ORDER_COMPLETED",
"order_id": "6852e9a6-5cf0-ac65-8182-6a9c251011ce",
"merchant_order_ext_ref": "example_order_reference_123456"
}For refunds to card-based payment methods (including digital wallets), your system may receive confirmation (for example, ORDER_COMPLETED) before the customer sees the funds on their account.
If the customer contacts you, retrieve the refund order with Retrieve an order and check payments[].payment_method.arn. The ARN (Acquirer Reference Number) is a 23-digit reference that the customer's bank can use to trace the refund and potentially speed up support on their side.
The arn is only returned for refund payments made by a card.