Refund payments
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, so you should monitor the refund order's status.
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 in 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).
- 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)
- Understanding of how you accept payments with your chosen integration:
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)
2. 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.
{
"amount": 10000,
"currency": "GBP"
}
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 you should monitor the refund order until you can confirm that it completed successfully.
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).
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"
}
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 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.
What's next
Explore related topics:
- Authorise a payment to capture later - Use manual capture, so you can cancel uncaptured orders instead of refunding captured payments
API references:
Related resources:
Setup:
Accept payments integrations: