Welcome to the Revolut Merchant API - your solution to managing the core aspects of e-commerce and accepting online payments. Whether you're a startup, a growing business, or an established enterprise in the e-commerce industry, our API helps you streamline your operations.
As a Revolut Business customer with a Merchant Account, you can use the Merchant API to leverage the following features:
- Order management
- Customer management
- Payment management
- Subscription management
- Payout management
- Dispute management
- Reporting analytics
- Webhook management
- Location management
... and more.
API versions
We highly recommend using versioning in your API calls. If you don't provide a version header on the operations where it's required, you will receive an error response.
The Merchant API uses request header versioning. Where it is required you need to use the Revolut-Api-Version header parameter to specify an API version. Each request, where it is indicated in the API specification, must contain a version header in the following format:
'Revolut-Api-Version: 2026-04-20'For more information, see: API versions
Test the Merchant API
You can test the Merchant API in Postman by forking this collection:
Authentication
apiKeyAuthorizationEach Merchant API request must contain an authorization header in the following format:
'Authorization: Bearer <yourSecretApiKey>'To use this API, you need to generate API keys from your Revolut Business account. The Secret key is used in the authorization header for all server calls, while the Public key is provided with payment methods at checkout.
For detailed instructions on generating your API keys, see: Generate API keys.
Orders
The Orders resource in the Merchant API offers a comprehensive solution for managing the lifecycle of orders within your e-commerce or retail platform. Designed to streamline order processing, this resource encapsulates a suite of operations that allow for efficiently handling order management-related tasks. For more information about the order lifecycle, see: Order and payment lifecycle.
These operations are equipped to handle various order management scenarios, providing a robust interface for businesses to interact with their order data.
To process a payment related to your customers' purchases, you need to create an Order object. Then you can use an order's unique token to process and accept payments via the Revolut Checkout Widget.
The Create an order endpoint was updated to a new version and now returns token as the public identifier for the order. Previous integrations might still use the deprecated endpoint returning public_id.
We strongly advise upgrading to the new Create an order endpoint.
Create an order
Create an Order object.
Creating orders is one of the basic operations of the Merchant API. Most of the other operations are related to creating orders. Furthermore, the payment methods merchants can use to take payments for their orders are also built on order creation.
To learn more about how you can accept payments, see:
- Revolut Pay
- Card payments
- Apple Pay and Google Pay
- Pay by Bank
- Revolut Checkout
- Hosted Checkout Page
Pre-authorisation and incremental authorisation
Orders can be created with authorisation_type: pre_authorisation to enable incremental authorisation. This allows you to increase the authorised amount after the initial authorisation.
Requirements:
capture_modemust be set tomanualauthorisation_typemust be set topre_authorisation
Payment method support:
Pre-authorisation orders support card, Apple Pay, and Google Pay only — enforced at the API level and on the hosted checkout page. Revolut Pay account-to-account (A2A) payments, Pay by Bank, and SEPA Direct Debit are not supported for pre-authorisation orders.
cancel_authorised_after:
For pre-authorisation orders, cancel_authorised_after can be set to a maximum of 30 days (P30D). For final authorisation orders, the 7-day maximum (P7D) still applies. If omitted, only capture_deadline governs expiry.
Example use cases:
- Hotels: authorise deposit, then increment for room service and minibar
- Car rentals: authorise deposit, then increment for damages or fuel
For more information, see:
Industry-specific requirements
If you operate in any of the industries listed below, sharing industry-specific data is mandatory. Not providing the necessary information will result in further scrutiny from Revolut and/or the imposition of risk mitigation actions.
| Industry | Related fields |
|---|---|
| Retail merchants | line_items, shipping |
| Airlines | industry_data with type: airline |
| Car rentals | industry_data with type: car_rental |
| Hotels & accommodation | industry_data with type: lodging |
| Travel agencies (OTAs) | industry_data with type: airline and industry_data with type: lodging |
| Crypto merchants | industry_data with type: crypto |
| Event ticket sellers | industry_data with type: event |
| Marketplace merchants | industry_data with type: marketplace |
Request
Response
Order created
curl -X POST "https://merchant.revolut.com/api/orders" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <yourSecretApiKey>" \
-H "Revolut-Api-Version: 2026-04-20" \
-d '{
"amount": 500,
"currency": "GBP"
}'Authorization
apiKeyAuthorizationEach Merchant API request must contain an authorization header in the following format:
'Authorization: Bearer <yourSecretApiKey>'To use this API, you need to generate API keys from your Revolut Business account. The Secret key is used in the authorization header for all server calls, while the Public key is provided with payment methods at checkout.
For detailed instructions on generating your API keys, see: Generate API keys.
Request body samples
{
"amount": 500,
"currency": "GBP"
}Response body samples
{
"id": "6516e61c-d279-a454-a837-bc52ce55ed49",
"token": "0adc0e3c-ab44-4f33-bcc0-534ded7354ce",
"type": "payment",
"state": "pending",
"created_at": "2023-09-29T14:58:36.079398Z",
"updated_at": "2023-09-29T14:58:36.079398Z",
"amount": 500,
"currency": "GBP",
"outstanding_amount": 500,
"capture_mode": "automatic",
"authorisation_type": "final",
"checkout_url": "https://checkout.revolut.com/payment-link/0adc0e3c-ab44-4f33-bcc0-534ded7354ce",
"enforce_challenge": "automatic"
}Retrieve an order list
Get a paginated list of your orders, returned as a wrapped orders array.
The response contains simplified Order objects. To get the full details of a specific order, use the Retrieve an order endpoint.
Request
Response
OK
curl -X GET "https://merchant.revolut.com/api/orders?limit=100&from=2024-01-01T00%3A00%3A00Z&to=2024-01-01T00%3A00%3A00Z&customer_id=123e4567-e89b-12d3-a456-426614174000&merchant_order_data_reference=string&state=%5B%5D&location_id=123e4567-e89b-12d3-a456-426614174000" \
-H "Authorization: Bearer <yourSecretApiKey>" \
-H "Revolut-Api-Version: 2026-04-20"Authorization
apiKeyAuthorizationEach Merchant API request must contain an authorization header in the following format:
'Authorization: Bearer <yourSecretApiKey>'To use this API, you need to generate API keys from your Revolut Business account. The Secret key is used in the authorization header for all server calls, while the Public key is provided with payment methods at checkout.
For detailed instructions on generating your API keys, see: Generate API keys.
Response body samples
{
"orders": [
{
"id": "a1b2c3d4-0001-0000-0000-000000000001",
"token": "b2c3d4e5-0001-0000-0000-000000000001",
"type": "payment",
"state": "completed",
"created_at": "2025-03-10T08:30:00Z",
"updated_at": "2025-03-10T08:32:15Z",
"amount": 4999,
"currency": "GBP",
"outstanding_amount": 0,
"capture_mode": "automatic",
"enforce_challenge": "automatic",
"description": "Premium subscription",
"customer": {
"id": "c3d4e5f6-0001-0000-0000-000000000001",
"email": "jane.doe@example.com",
"full_name": "Jane Doe",
"phone": "+441234567890"
}
},
{
"id": "a1b2c3d4-0002-0000-0000-000000000002",
"token": "b2c3d4e5-0002-0000-0000-000000000002",
"type": "payment",
"state": "completed",
"created_at": "2025-03-11T09:00:00Z",
"updated_at": "2025-03-11T09:01:45Z",
"amount": 12500,
"currency": "EUR",
"outstanding_amount": 0,
"capture_mode": "automatic",
"enforce_challenge": "automatic",
"description": "Shopping cart",
"customer": {
"id": "c3d4e5f6-0002-0000-0000-000000000002",
"email": "john.smith@example.com",
"full_name": "John Smith"
},
"line_items": [
{
"name": "Wireless headphones",
"quantity": 1,
"unit_price": 9900,
"total_amount": 9900
},
{
"name": "Phone case",
"quantity": 2,
"unit_price": 1300,
"total_amount": 2600
}
]
},
{
"id": "a1b2c3d4-0003-0000-0000-000000000003",
"type": "refund",
"state": "completed",
"created_at": "2025-03-12T11:15:00Z",
"updated_at": "2025-03-12T11:16:30Z",
"amount": 4999,
"currency": "GBP",
"outstanding_amount": 0,
"capture_mode": "automatic",
"enforce_challenge": "automatic",
"related_order_id": "a1b2c3d4-0001-0000-0000-000000000001",
"merchant_order_data": {
"order_id": "ORD-2025-001",
"description": "Customer-requested refund"
}
},
{
"id": "a1b2c3d4-0004-0000-0000-000000000004",
"token": "b2c3d4e5-0004-0000-0000-000000000004",
"type": "payment",
"state": "authorised",
"created_at": "2025-03-13T14:00:00Z",
"updated_at": "2025-03-13T14:00:30Z",
"amount": 35000,
"currency": "USD",
"outstanding_amount": 35000,
"capture_mode": "manual",
"enforce_challenge": "automatic",
"description": "Enterprise software licence",
"cancel_authorised_after": "2025-03-20T14:00:00Z",
"customer": {
"id": "c3d4e5f6-0003-0000-0000-000000000003",
"email": "alex.johnson@example.com",
"full_name": "Alex Johnson"
}
},
{
"id": "a1b2c3d4-0005-0000-0000-000000000005",
"token": "b2c3d4e5-0005-0000-0000-000000000005",
"type": "payment",
"state": "completed",
"created_at": "2025-03-14T16:45:00Z",
"updated_at": "2025-03-14T16:46:00Z",
"amount": 799,
"currency": "GBP",
"outstanding_amount": 0,
"capture_mode": "automatic",
"enforce_challenge": "automatic",
"description": "Coffee and pastry",
"location_id": "d4e5f6a7-0001-0000-0000-000000000001"
}
]
}Retrieve an order
Retrieve the details of an order that has been created. Provide the unique order ID, and the corresponding order information is returned.
Request
Response
Order retrieved
curl -X GET "https://merchant.revolut.com/api/orders/123e4567-e89b-12d3-a456-426614174000" \
-H "Authorization: Bearer <yourSecretApiKey>" \
-H "Revolut-Api-Version: 2026-04-20"Authorization
apiKeyAuthorizationEach Merchant API request must contain an authorization header in the following format:
'Authorization: Bearer <yourSecretApiKey>'To use this API, you need to generate API keys from your Revolut Business account. The Secret key is used in the authorization header for all server calls, while the Public key is provided with payment methods at checkout.
For detailed instructions on generating your API keys, see: Generate API keys.
Response body samples
{
"id": "6516e61c-d279-a454-a837-bc52ce55ed49",
"token": "0adc0e3c-ab44-4f33-bcc0-534ded7354ce",
"type": "payment",
"state": "pending",
"created_at": "2023-09-29T14:58:36.079398Z",
"updated_at": "2023-09-29T14:58:36.079398Z",
"amount": 500,
"currency": "GBP",
"outstanding_amount": 500,
"capture_mode": "automatic",
"authorisation_type": "final",
"checkout_url": "https://checkout.revolut.com/payment-link/0adc0e3c-ab44-4f33-bcc0-534ded7354ce",
"enforce_challenge": "automatic"
}Update an order
Update the details of an order.
You can update an order and specific parameters based on the value of the state parameter:
| State parameter value | Modifiable parameters |
|---|---|
pending | You can modify all listed parameters. |
authorised | You can modify the following parameters:
|
completed | You can modify the following parameters:
|
processing | You cannot modify parameters. |
For more information about the order lifecycle, see: Order and payment lifecycle.
Request
Response
Order updated
curl -X PATCH "https://merchant.revolut.com/api/orders/123e4567-e89b-12d3-a456-426614174000" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <yourSecretApiKey>" \
-H "Revolut-Api-Version: 2026-04-20" \
-d '{
"amount": 1000,
"currency": "EUR",
"settlement_currency": "GBP",
"capture_mode": "manual",
"cancel_authorised_after": "P3D",
"metadata": {
"example_key": "example_value"
},
"merchant_order_data": {
"url": "https://example.com/orders/12345"
},
"statement_descriptor_suffix": "12345"
}'Authorization
apiKeyAuthorizationEach Merchant API request must contain an authorization header in the following format:
'Authorization: Bearer <yourSecretApiKey>'To use this API, you need to generate API keys from your Revolut Business account. The Secret key is used in the authorization header for all server calls, while the Public key is provided with payment methods at checkout.
For detailed instructions on generating your API keys, see: Generate API keys.
Request body samples
{
"amount": 1000,
"currency": "EUR",
"settlement_currency": "GBP",
"capture_mode": "manual",
"cancel_authorised_after": "P3D",
"metadata": {
"example_key": "example_value"
},
"merchant_order_data": {
"url": "https://example.com/orders/12345"
},
"statement_descriptor_suffix": "12345"
}Response body samples
{
"id": "651a941a-02ef-af6f-9b6c-458c652e2c6a",
"token": "0aa685ee-8d86-441d-bedd-3f7fbf41731b",
"type": "payment",
"state": "pending",
"created_at": "2023-10-02T09:57:46.498026Z",
"updated_at": "2023-10-02T11:54:46.648414Z",
"amount": 1000,
"currency": "EUR",
"outstanding_amount": 1000,
"settlement_currency": "GBP",
"capture_mode": "manual",
"cancel_authorised_after": "P3D",
"checkout_url": "https://checkout.revolut.com/payment-link/0aa685ee-8d86-441d-bedd-3f7fbf41731b",
"metadata": {
"example_key": "example_value"
},
"enforce_challenge": "automatic",
"merchant_order_data": {
"url": "https://example.com/orders/12345"
},
"statement_descriptor_suffix": "12345"
}Increment authorisation
Increase the authorised amount on a pre-authorised order.
This operation allows you to increment the authorised amount for orders created with authorisation_type: pre_authorisation and capture_mode: manual.
Currently, only card payments are supported.
Common use-cases
- Hotel additional charges (e.g., minibar, room service)
- Car rental damage or fuel charges
- Equipment rental extensions
How it works
- Create an order with
capture_mode: manualandauthorisation_type: pre_authorisation - Take payment using one of our card payment solutions
- When payment/order reaches
authorisedstate, you can increment authorised amount - When no more increments are expected, capture the order to complete the transaction
- Can only increment orders in
authorisedstate - Must have
authorisation_type: pre_authorisationandcapture_mode: manual - Sum of all increment amounts cannot exceed 5x the initial amount
- Maximum 10 increments per order
- Process increments sequentially to avoid declines
- Currently only supported for card payments
For more information, see: Incremental authorisation guide
Request
Response
Authorization increment initiated successfully
curl -X POST "https://merchant.revolut.com/api/orders/123e4567-e89b-12d3-a456-426614174000/increment-authorisation" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <yourSecretApiKey>" \
-H "Revolut-Api-Version: 2026-04-20" \
-d '{
"amount": 600
}'Authorization
apiKeyAuthorizationEach Merchant API request must contain an authorization header in the following format:
'Authorization: Bearer <yourSecretApiKey>'To use this API, you need to generate API keys from your Revolut Business account. The Secret key is used in the authorization header for all server calls, while the Public key is provided with payment methods at checkout.
For detailed instructions on generating your API keys, see: Generate API keys.
Request body samples
{
"amount": 600
}Response body samples
{
"id": "6920869a-8d8d-aefd-a3c3-8fe4690e4323",
"token": "0823794d-28e9-4fdd-a130-3293ff9dd57b",
"type": "payment",
"state": "processing",
"created_at": "2025-11-21T15:34:50.351537Z",
"updated_at": "2025-11-21T15:35:12.123456Z",
"amount": 500,
"currency": "EUR",
"outstanding_amount": 500,
"capture_mode": "manual",
"authorisation_type": "pre_authorisation",
"incremental_authorisations": [
{
"new_amount": 600,
"old_amount": 500,
"state": "processing",
"reference": "1263738"
}
],
"payments": [
{
"id": "696a4ce4-2aaf-a008-9f26-f47cf8ab1678",
"state": "authorisation_started",
"created_at": "2025-11-21T15:34:50.474085Z",
"updated_at": "2025-11-21T15:35:12.300608Z",
"token": "928f25b1-121c-4669-ab9f-d0b7a5804576",
"amount": 600,
"authorised_amount": 500,
"currency": "EUR",
"settled_amount": 500,
"settled_currency": "EUR",
"billing_address": {
"country_code": "US",
"postcode": "94102"
},
"risk_level": "low",
"fees": [],
"payer": {
"email": "example.payer@example.com",
"phone": "+447911123456"
},
"payment_method": {
"type": "card",
"card_brand": "visa",
"funding": "debit",
"card_country_code": "US",
"card_bin": "424242",
"card_last_four": "4242",
"card_expiry": "12/35",
"cardholder_name": "Example Customer",
"checks": {
"three_ds": {
"eci": "05",
"state": "verified",
"version": 2
},
"cvv_verification": "not_processed",
"address": "n_a",
"postcode": "n_a",
"cardholder": "n_a"
},
"fingerprint": "aadDmPDArelhtk5QK3zqccaPi39zEDp6/uKuUsA9LHE=",
"network_transaction_id": "1234567890123456",
"authorisation_code": "100000",
"arn": "12345678912345678912345",
"capture_deadline": "2025-11-28T15:34:50.513Z"
}
}
],
"checkout_url": "https://checkout.revolut.com/payment-link/0823794d-28e9-4fdd-a130-3293ff9dd57b",
"enforce_challenge": "automatic"
}Capture an order
This endpoint is used to capture the funds of an existing, uncaptured order. When the payment for an order is authorised, you can capture the order to send it to the processing stage.
For more information about the order and payment lifecycle, see: Order and payment lifecycle.
Capture modes
When you create an order, you can choose one of the following capture modes:
| Capture mode | Description |
|---|---|
automatic | The order is captured automatically after payment authorisation. No further actions are needed. |
manual | The order is not captured automatically and stays in authorised state. You must manually capture the order using the steps outlined below. |
By default, uncaptured orders with final authorisation (authorisation_type: final) remain in authorised state for 7 days. If not captured within this period, the funds are returned to the customer's original payment method.
The capture deadline can be customised:
- Use
cancel_authorised_afterparameter when creating an order to set a custom expiry period - The effective deadline is the earlier of
cancel_authorised_afterand the card/network clearing window capture_deadlineis set when the order becomesauthorisedand doesn't change afterwards- Use pre-authorisation (
authorisation_type: pre_authorisation) for extended clearing windows (up to 30 days) and incremental authorisation support (see tip below)
If your business requires longer authorisation hold periods (up to 30 days depending on card scheme and MCC), use pre-authorisation instead of standard authorisation. Pre-authorisation also supports incremental authorisation for variable-amount scenarios.
Manual capture
To capture an order manually, use one of the following methods:
| Web UI | Merchant API |
|---|---|
| Use the /capture endpoint. |
For more information about manually capturing an order, see: Authorise an amount to capture later.
Partial capture
You have the option to capture only a fraction of the full amount. In such cases, the uncaptured portion of the amount will be voided.
The following limitations apply to manual captures:
- An order can only be captured once
- Captured amount can't exceed the authorised amount
- On Web UI, only capturing full amount is possible
0amount captures are not allowed- For partial captures, you can only resend the request with the initial amount
Updating line items at capture
You can optionally provide line_items when capturing an order. This allows you to adjust the final order details at the time of capture, which is useful for scenarios such as:
- Partial captures: Specify which items are being captured when capturing less than the full amount. Line items help accurately reflect which items were captured versus voided (see Partial capture above).
- Final adjustments: Update order details when the delivered items differ from the initial authorisation (e.g., out-of-stock items, substitutions, quantity changes).
If you provide line_items when capturing, they will overwrite the original line items provided during order creation or update. Ensure you include all items you want associated with the captured order.
For a comprehensive guide including use cases and examples, see: Authorise a payment to capture later.
Idempotency and repeated requests
The capture operation is idempotent. This means that an order can only be captured once. If you send a capture request more than once:
- The first valid request captures the order and moves it to the processing stage.
- Any subsequent request with the same capture amount will not recapture funds and behaves like a Retrieve an order request, returning the current order state.
- A subsequent request with a different capture amount returns an error.
Utilising the idempotent nature of this endpoint helps maintain data consistency and prevents duplicate processing of the same order.
Request
Response
Order captured
curl -X POST "https://merchant.revolut.com/api/orders/123e4567-e89b-12d3-a456-426614174000/capture" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <yourSecretApiKey>" \
-H "Revolut-Api-Version: 2026-04-20" \
-d '{
"amount": 100
}'Authorization
apiKeyAuthorizationEach Merchant API request must contain an authorization header in the following format:
'Authorization: Bearer <yourSecretApiKey>'To use this API, you need to generate API keys from your Revolut Business account. The Secret key is used in the authorization header for all server calls, while the Public key is provided with payment methods at checkout.
For detailed instructions on generating your API keys, see: Generate API keys.
Request body samples
{
"amount": 100
}Response body samples
{
"id": "65c4c739-113d-a608-9128-47c7ca90cbe3",
"token": "ebc06202-061e-4d0f-8063-99195fad31fb",
"type": "payment",
"state": "completed",
"created_at": "2024-02-08T12:21:13.022871Z",
"updated_at": "2024-02-08T12:21:52.194601Z",
"amount": 100,
"currency": "GBP",
"refunded_amount": 0,
"outstanding_amount": 0,
"capture_mode": "manual",
"payments": [
{
"id": "65c4c748-bf0d-af8a-9d69-0fc92bc0ff94",
"state": "captured",
"created_at": "2024-02-08T12:21:28.803165Z",
"updated_at": "2024-02-08T12:21:52.191352Z",
"token": "74af5a2b-6722-4353-aaf1-cd5926883b60",
"amount": 100,
"currency": "GBP",
"settled_amount": 100,
"settled_currency": "GBP",
"billing_address": {
"country_code": "US",
"postcode": "12345"
},
"risk_level": "low",
"fees": [],
"payer": {
"email": "example.payer@example.com",
"phone": "+447911123456"
},
"payment_method": {
"type": "revolut_pay_card",
"card_brand": "visa",
"funding": "debit",
"card_country_code": "US",
"card_bin": "529999",
"card_last_four": "0368",
"card_expiry": "12/28",
"cardholder_name": "Test Holder",
"checks": {
"three_ds": {
"state": "verified",
"version": 2
}
},
"enforce_challenge": "automatic",
"fingerprint": "1JAllfQY4POhBV8DaddAQ4LC5RbMP8LMLvUdJW4s5JY=",
"network_transaction_id": "1234567890123456"
}
}
]
}Cancel an order
Cancel an existing uncaptured order.
You can only cancel an order that is in one of the following states:
| Order state | Description |
|---|---|
pending | The order does not have any successful payment. |
authorised | The capture_mode of an order is set to manual and the customer has made a successful payment. |
For more information about the order lifecycle, see: Order and payment lifecycle.
Request
Response
OK
curl -X POST "https://merchant.revolut.com/api/orders/123e4567-e89b-12d3-a456-426614174000/cancel" \
-H "Authorization: Bearer <yourSecretApiKey>" \
-H "Revolut-Api-Version: 2023-09-01"Authorization
apiKeyAuthorizationEach Merchant API request must contain an authorization header in the following format:
'Authorization: Bearer <yourSecretApiKey>'To use this API, you need to generate API keys from your Revolut Business account. The Secret key is used in the authorization header for all server calls, while the Public key is provided with payment methods at checkout.
For detailed instructions on generating your API keys, see: Generate API keys.
Response body samples
{
"id": "6516f565-c903-ae7d-8582-0bc70468ec29",
"token": "579462b3-da89-4a46-8690-572d3968573f",
"type": "payment",
"state": "cancelled",
"created_at": "2023-09-29T16:03:49.569437Z",
"updated_at": "2023-09-29T16:04:30.727004Z",
"amount": 500,
"currency": "GBP",
"refunded_amount": 0,
"outstanding_amount": 0,
"capture_mode": "automatic",
"authorisation_type": "final",
"enforce_challenge": "automatic"
}Refund an order
Issue a refund for a completed order. This operation allows for either a full or partial refund, which will be processed back to the customer's original payment method.
- The refund operation generates a new order with
type: refund. This new order represents a full or partial refund of the original amount paid. - Multiple partial refunds can be issued for a single order, given the total refunded amount does not exceed the original order amount.
- Refund orders will contain
related_order_idwhich links to the original order that was refunded. - Refunds can only be initiated for orders that are in a
completedstate. Orders in any other state are not eligible for refunds to ensure transaction integrity and to prevent errors.
Consider using the Idempotency-Key header to make the refund operation idempotent, preventing duplicate refund processing in cases of multiple submissions.
For more information see our Refund payments guide.
Request
Response
Refund order successfully created
curl -X POST "https://merchant.revolut.com/api/orders/123e4567-e89b-12d3-a456-426614174000/refund" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <yourSecretApiKey>" \
-H "Revolut-Api-Version: 2026-04-20" \
-H "Idempotency-Key: string" \
-d '{
"amount": 100,
"currency": "GBP"
}'Authorization
apiKeyAuthorizationEach Merchant API request must contain an authorization header in the following format:
'Authorization: Bearer <yourSecretApiKey>'To use this API, you need to generate API keys from your Revolut Business account. The Secret key is used in the authorization header for all server calls, while the Public key is provided with payment methods at checkout.
For detailed instructions on generating your API keys, see: Generate API keys.
Request body samples
{
"amount": 100,
"currency": "GBP"
}Response body samples
{
"id": "6852e9a6-5cf0-ac65-8182-6a9c251011ce",
"type": "refund",
"state": "processing",
"created_at": "2025-06-18T16:30:30.792962Z",
"updated_at": "2025-06-18T16:30:30.954966Z",
"amount": 100,
"currency": "GBP",
"outstanding_amount": 100,
"capture_mode": "automatic",
"authorisation_type": "final",
"payments": [
{
"id": "6852e9a6-ca77-a25d-b0be-83191db96e68",
"state": "refund_validated",
"created_at": "2025-06-18T16:30:30.821411Z",
"updated_at": "2025-06-18T16:30:31.391153Z",
"amount": 100,
"currency": "GBP",
"settled_amount": -100,
"settled_currency": "GBP",
"billing_address": {
"country_code": "GB",
"postcode": "E14 4HD"
},
"risk_level": "low",
"fees": [],
"payer": {
"email": "example.payer@example.com",
"phone": "+447911123456"
},
"payment_method": {
"type": "card",
"fingerprint": "1JAllfQY4POhBV8DaddAQ4LC5RbMP8LMLvUdJW4s5JY=",
"network_transaction_id": "1234567890123456",
"card_brand": "visa",
"funding": "credit",
"card_country_code": "GB",
"card_bin": "123456",
"card_last_four": "1234",
"card_expiry": "12/33",
"cardholder_name": "Example Holder"
}
}
],
"enforce_challenge": "automatic",
"related_order_id": "6852e963-d6a9-a5a4-9609-50b3addc5425"
}Pay for an order
Initiate a payment to pay full amount for an order using a customer's saved payment method.
The /orders/{order_id}/confirm endpoint has been deprecated. It will be only supported for already existing implementations.
This endpoint is part of a new API, pay attention to the different endpoint URL.
For more information about how to save and charge payment methods, see: Charge a customer's saved payment method.
The following table shows who can initiate payments on saved payment methods (initiator parameter), depending on if the payment method was saved for the customer or the merchant (savedPaymentMethodFor parameter):
savePaymentMethodFor: customer | savePaymentMethodFor: merchant | |
|---|---|---|
initiator: customer | Allowed | Allowed |
initiator: merchant | Not allowed | Allowed |
Using this endpoint, only merchant initiated payments are supported with Revolut Pay.
For more information about customers' payment methods, see the Retrieve payment method list of a customer operation.
Request
Response
Payment initiated
curl -X POST "https://merchant.revolut.com/api/orders/123e4567-e89b-12d3-a456-426614174000/payments" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <yourSecretApiKey>" \
-d '{
"saved_payment_method": {
"type": "card",
"id": "2b83c23a-650e-40c3-8989-00ee24478738",
"initiator": "customer",
"environment": {
"type": "browser",
"time_zone_utc_offset": 180,
"color_depth": 48,
"screen_width": 1920,
"screen_height": 1080,
"java_enabled": true,
"challenge_window_width": 640,
"browser_url": "https://business.revolut.com"
}
}
}'Authorization
apiKeyAuthorizationEach Merchant API request must contain an authorization header in the following format:
'Authorization: Bearer <yourSecretApiKey>'To use this API, you need to generate API keys from your Revolut Business account. The Secret key is used in the authorization header for all server calls, while the Public key is provided with payment methods at checkout.
For detailed instructions on generating your API keys, see: Generate API keys.
Request body samples
{
"saved_payment_method": {
"type": "card",
"id": "2b83c23a-650e-40c3-8989-00ee24478738",
"initiator": "customer",
"environment": {
"type": "browser",
"time_zone_utc_offset": 180,
"color_depth": 48,
"screen_width": 1920,
"screen_height": 1080,
"java_enabled": true,
"challenge_window_width": 640,
"browser_url": "https://business.revolut.com"
}
}
}Response body samples
{
"id": "63c55e04-4208-a43d-9c96-eaee848ffbaf",
"order_id": "63c55df6-1461-a886-b90f-f49d3c370253",
"payment_method": {
"type": "card",
"id": "2b83c23a-650e-40c3-8989-00ee24478738",
"brand": "mastercard_credit",
"last_four": "1234"
},
"state": "authorisation_passed"
}Retrieve payment list of an order
Retrieve a list of payments for a specific order, based on the order's ID.
This endpoint is part of a new API, pay attention to the different endpoint URL.
Use this endpoint to retrieve payment details for saved payment methods to make merchant and customer initiated transactions. For more information, see:
Request
Response
List of payments
curl -X GET "https://merchant.revolut.com/api/orders/123e4567-e89b-12d3-a456-426614174000/payments" \
-H "Authorization: Bearer <yourSecretApiKey>"Authorization
apiKeyAuthorizationEach Merchant API request must contain an authorization header in the following format:
'Authorization: Bearer <yourSecretApiKey>'To use this API, you need to generate API keys from your Revolut Business account. The Secret key is used in the authorization header for all server calls, while the Public key is provided with payment methods at checkout.
For detailed instructions on generating your API keys, see: Generate API keys.
Response body samples
[
{
"id": "63dd0e4a-42c4-a1a6-ab2c-6ac9d255ca4b",
"token": "294358bf-3818-49b2-aacc-7ca971f52695",
"order_id": "63dd0e3f-7b84-ab5c-927c-1a06f7c9583a",
"state": "declined",
"amount": 100,
"currency": "EUR",
"payment_method": {
"type": "card",
"card_brand": "visa",
"funding": "credit",
"card_last_four": "1234"
}
},
{
"id": "649adc44-3e86-a832-879c-2f6d0255dd4c",
"token": "8061e645-35e0-42bb-8318-603abaeab7b7",
"order_id": "63dd0e3f-7b84-ab5c-927c-1a06f7c9583a",
"state": "declined",
"amount": 100,
"currency": "EUR",
"decline_reason": "insufficient_funds",
"payment_method": {
"type": "revolut_pay",
"subtype": "revolut_account"
}
},
{
"id": "663387f1-1c2e-a295-b143-9f1fb1eec175",
"token": "663387f1-c91e-a464-908a-1cc4548ebc6a",
"order_id": "63dd0e3f-7b84-ab5c-927c-1a06f7c9583a",
"state": "pending",
"amount": 100,
"currency": "EUR",
"payment_method": {
"type": "sepa_direct_debit",
"debtor_iban_last_four": "1234",
"debtor_name": "John Doe",
"mandate_reference": "A1B2C3D4E5F6A1B2C3D4E5F6A1B2C3D4"
}
}
]Customers
The Customers resource in the Merchant API is a pivotal tool for tracking and managing customer-related transactions within your e-commerce or retail platform. This resource provides a structured approach to customer management, enabling you to maintain a consistent record of customer transactions.
A Customer object can be created using the Create a customer endpoint and you can then retrieve, update and delete a customer using its id. Customer objects enable you to track multiple transactions in your system associated with the same customer in the Merchant API.
You can save and store payment methods of a customer in the payment_method object, for more information, see: Charge a customer's saved payment method. A merchant can store the details of the payment securely and group transactions from the same payment method in their system.
A payment method is unique for each customer. For example, if the same card is used for a transaction by two different customers, two payment method objects are created linked to each customer.
Similar principle applies when saving payment methods via Revolut Pay for merchant initiated transaction (MIT - useful for recurring payments). If a customer saves their details through Revolut Pay for MIT in separate sessions, each session will create a new payment method object linked to the customer.
You cannot create a payment method explicitly because they are generated as part of a payment. You can only retrieve, update or delete a payment method, or you can retrieve all payment methods of a customer.
Create a customer
Create a customer object.
The API does not prevent creating multiple customers with the same email address or phone number.
This can be intentional, for example, to maintain separate customer records per storefront or brand under the same account.
To avoid unintentional duplicates, search for existing customers by email or phone using the List customers endpoint before creating a new one.
Save payment methods
If you wish to save a customer's payment details using any of the available payment methods on the Revolut Checkout Widget (Revolut Pay, Card payments), you need to meet one of the following requirements:
- Have a customer object with
emailand assign it to the order by providingcustomer.id - Create a new customer with, at least,
customer.emailduring order creation
For more information, see: Charge a customer's saved payment method.
AFT processing requirements
For merchants in the following industries, full_name and date_of_birth are required for Account Funding Transaction (AFT) processing:
| Industry | Required fields |
|---|---|
| Crypto | full_name, date_of_birth |
| Financial Institutions | full_name, date_of_birth |
| Stored Value / Wallets | full_name, date_of_birth |
Request
Response
Created
curl -X POST "https://merchant.revolut.com/api/customers" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <yourSecretApiKey>" \
-H "Revolut-Api-Version: 2026-04-20" \
-d '{
"full_name": "Example Customer",
"email": "example.customer@example.com",
"phone": "+441234567890",
"date_of_birth": "1990-01-01"
}'Authorization
apiKeyAuthorizationEach Merchant API request must contain an authorization header in the following format:
'Authorization: Bearer <yourSecretApiKey>'To use this API, you need to generate API keys from your Revolut Business account. The Secret key is used in the authorization header for all server calls, while the Public key is provided with payment methods at checkout.
For detailed instructions on generating your API keys, see: Generate API keys.
Request body samples
{
"full_name": "Example Customer",
"email": "example.customer@example.com",
"phone": "+441234567890",
"date_of_birth": "1990-01-01"
}Response body samples
{
"id": "6c7c97a8-cfc1-4cf3-8b38-26a74fdf1fae",
"full_name": "Example Customer",
"email": "example.customer@example.com",
"phone": "+441234567890",
"created_at": "2020-06-24T12:03:39.979397Z",
"updated_at": "2020-06-24T12:03:39.979397Z"
}Retrieve a customer list
Get a paginated list of your customer profiles.
| Filtering | Pagination |
|---|---|
| Filter the customers that you want to retrieve, for example, only retrieve customers created within a specific date range. Parameters used for filtering:
| View customers without loading all of them at once, for example, return a specified number of customers per page. Parameters used for pagination:
|
To paginate through all results:
- Make an initial request with the desired
limitand any filter parameters. - If more results are available, the response includes a
next_page_token. - Pass
next_page_tokenaspage_tokenin your next request, keeping all other parameters unchanged. - Repeat until
next_page_tokenis no longer present in the response.
Request
Response
OK
curl -X GET "https://merchant.revolut.com/api/customers?limit=100&page_token=string&from=2024-01-01T00%3A00%3A00Z&to=2024-01-01T00%3A00%3A00Z" \
-H "Authorization: Bearer <yourSecretApiKey>" \
-H "Revolut-Api-Version: 2026-04-20"Authorization
apiKeyAuthorizationEach Merchant API request must contain an authorization header in the following format:
'Authorization: Bearer <yourSecretApiKey>'To use this API, you need to generate API keys from your Revolut Business account. The Secret key is used in the authorization header for all server calls, while the Public key is provided with payment methods at checkout.
For detailed instructions on generating your API keys, see: Generate API keys.
Response body samples
{
"next_page_token": "9e5d2caa-bb60-4b5b-b7cf-6345bbdff67e",
"customers": [
{
"id": "9dfb8491-bfb0-4420-ad63-0fa7bdd3dffb",
"full_name": "First Customer",
"email": "first.customer@example.com",
"created_at": "2020-06-24T12:12:56.596703Z",
"updated_at": "2020-06-24T12:12:56.737082Z"
},
{
"id": "6c7c97a8-cfc1-4cf3-8b38-26a74fdf1fae",
"full_name": "Second Customer",
"email": "second.customer@example.com",
"phone": "+441234567890",
"created_at": "2020-06-24T12:03:39.979397Z",
"updated_at": "2020-06-25T10:03:39.134417Z"
}
]
}Retrieve a customer
Get the information about a specific customer, including their saved payment methods.
Request
Response
OK
curl -X GET "https://merchant.revolut.com/api/customers/123e4567-e89b-12d3-a456-426614174000" \
-H "Authorization: Bearer <yourSecretApiKey>" \
-H "Revolut-Api-Version: 2026-04-20"Authorization
apiKeyAuthorizationEach Merchant API request must contain an authorization header in the following format:
'Authorization: Bearer <yourSecretApiKey>'To use this API, you need to generate API keys from your Revolut Business account. The Secret key is used in the authorization header for all server calls, while the Public key is provided with payment methods at checkout.
For detailed instructions on generating your API keys, see: Generate API keys.
Response body samples
{
"id": "6c7c97a8-cfc1-4cf3-8b38-26a74fdf1fae",
"full_name": "Example Customer",
"email": "example.customer@example.com",
"phone": "+441234567890",
"created_at": "2020-06-24T12:03:39.979397Z",
"updated_at": "2020-06-25T10:03:39.134417Z",
"payment_methods": [
{
"id": "648334a8-9546-a983-a81a-efc6d5bdd0be",
"type": "revolut_pay",
"saved_for": "merchant",
"created_at": "2023-06-09T14:18:16.577888Z"
},
{
"id": "edef3ba4-60a0-4df3-8f12-e5fc858c2420",
"type": "card",
"saved_for": "customer",
"created_at": "2023-03-24T14:15:22Z",
"bin": "459765",
"last_four": "6578",
"expiry_month": 2,
"expiry_year": 2025,
"cardholder_name": "Example Customer",
"brand": "visa",
"funding": "debit",
"issuer": "EXAMPLE ISSUER",
"issuer_country": "GB",
"billing_address": {
"street_line_1": "7 Westferry Circus",
"street_line_2": "Columbus Building",
"postcode": "E144HD",
"city": "London",
"region": "Greater London",
"country_code": "GB"
}
},
{
"id": "6a0fe961-a961-a8b6-ad17-ab2779165a82",
"type": "sepa_direct_debit",
"saved_for": "merchant",
"created_at": "2026-05-22T05:28:01.887482Z",
"debtor_iban_last_four": "3273",
"debtor_name": "John Doe",
"mandate_reference": "69F1CB61BD99A32C8E20D7FB9E21E146",
"billing_address": {
"street_line_1": "Bank of England",
"street_line_2": "Threadneedle St",
"postcode": "EC2R 8AH",
"city": "London",
"region": "Greater London",
"country_code": "GB"
}
}
]
}Update a customer
Update the attributes of a specific customer.
All request body fields are optional. Only the fields provided will be updated.
AFT processing requirements
For merchants in the following industries, full_name and date_of_birth are required for Account Funding Transaction (AFT) processing:
| Industry | Required fields |
|---|---|
| Crypto | full_name, date_of_birth |
| Financial Institutions | full_name, date_of_birth |
| Stored Value / Wallets | full_name, date_of_birth |
Request
Response
OK
curl -X PATCH "https://merchant.revolut.com/api/customers/123e4567-e89b-12d3-a456-426614174000" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <yourSecretApiKey>" \
-H "Revolut-Api-Version: 2026-04-20" \
-d '{
"email": "updated.customer@example.com"
}'Authorization
apiKeyAuthorizationEach Merchant API request must contain an authorization header in the following format:
'Authorization: Bearer <yourSecretApiKey>'To use this API, you need to generate API keys from your Revolut Business account. The Secret key is used in the authorization header for all server calls, while the Public key is provided with payment methods at checkout.
For detailed instructions on generating your API keys, see: Generate API keys.
Request body samples
{
"email": "updated.customer@example.com"
}Response body samples
{
"id": "6c7c97a8-cfc1-4cf3-8b38-26a74fdf1fae",
"full_name": "Example Customer",
"email": "example.customer@example.com",
"phone": "+441234567890",
"created_at": "2020-06-24T12:03:39.979397Z",
"updated_at": "2020-06-25T10:03:39.134417Z",
"payment_methods": [
{
"id": "648334a8-9546-a983-a81a-efc6d5bdd0be",
"type": "revolut_pay",
"saved_for": "merchant",
"created_at": "2023-06-09T14:18:16.577888Z"
},
{
"id": "edef3ba4-60a0-4df3-8f12-e5fc858c2420",
"type": "card",
"saved_for": "customer",
"created_at": "2023-03-24T14:15:22Z",
"bin": "459765",
"last_four": "6578",
"expiry_month": 2,
"expiry_year": 2025,
"cardholder_name": "Example Customer",
"brand": "visa",
"funding": "debit",
"issuer": "EXAMPLE ISSUER",
"issuer_country": "GB",
"billing_address": {
"street_line_1": "7 Westferry Circus",
"street_line_2": "Columbus Building",
"postcode": "E144HD",
"city": "London",
"region": "Greater London",
"country_code": "GB"
}
},
{
"id": "6a0fe961-a961-a8b6-ad17-ab2779165a82",
"type": "sepa_direct_debit",
"saved_for": "merchant",
"created_at": "2026-05-22T05:28:01.887482Z",
"debtor_iban_last_four": "3273",
"debtor_name": "John Doe",
"mandate_reference": "69F1CB61BD99A32C8E20D7FB9E21E146",
"billing_address": {
"street_line_1": "Bank of England",
"street_line_2": "Threadneedle St",
"postcode": "EC2R 8AH",
"city": "London",
"region": "Greater London",
"country_code": "GB"
}
}
]
}Delete a customer
Delete the profile of a specific customer.
Request
Response
No Content
curl -X DELETE "https://merchant.revolut.com/api/customers/123e4567-e89b-12d3-a456-426614174000" \
-H "Authorization: Bearer <yourSecretApiKey>" \
-H "Revolut-Api-Version: 2026-04-20"Authorization
apiKeyAuthorizationEach Merchant API request must contain an authorization header in the following format:
'Authorization: Bearer <yourSecretApiKey>'To use this API, you need to generate API keys from your Revolut Business account. The Secret key is used in the authorization header for all server calls, while the Public key is provided with payment methods at checkout.
For detailed instructions on generating your API keys, see: Generate API keys.
Response body samples
Retrieve payment method list of a customer
Retrieve all the saved payment methods for a specific customer. This can be useful in the following example cases:
- To show what payment information is stored for the customer.
- To try a different payment method if the first payment method fails when a recurring transaction occurs.
Request
Response
OK
curl -X GET "https://merchant.revolut.com/api/customers/123e4567-e89b-12d3-a456-426614174000/payment-methods?only_merchant=true" \
-H "Authorization: Bearer <yourSecretApiKey>" \
-H "Revolut-Api-Version: 2026-04-20"Authorization
apiKeyAuthorizationEach Merchant API request must contain an authorization header in the following format:
'Authorization: Bearer <yourSecretApiKey>'To use this API, you need to generate API keys from your Revolut Business account. The Secret key is used in the authorization header for all server calls, while the Public key is provided with payment methods at checkout.
For detailed instructions on generating your API keys, see: Generate API keys.
Response body samples
{
"payment_methods": [
{
"id": "648334a8-9546-a983-a81a-efc6d5bdd0be",
"type": "revolut_pay",
"saved_for": "merchant",
"created_at": "2023-06-09T14:18:16.577888Z"
},
{
"id": "edef3ba4-60a0-4df3-8f12-e5fc858c2420",
"type": "card",
"saved_for": "customer",
"created_at": "2023-03-24T14:15:22Z",
"bin": "459678",
"last_four": "6896",
"expiry_month": 3,
"expiry_year": 2025,
"cardholder_name": "Example Customer",
"brand": "visa",
"funding": "debit",
"issuer": "EXAMPLE ISSUER",
"issuer_country": "GB",
"billing_address": {
"street_line_1": "7",
"street_line_2": "Westferry Circus",
"postcode": "E144HD",
"city": "London",
"region": "Greater London",
"country_code": "GB"
}
},
{
"id": "a04406c4-05be-498b-8207-cc1e02a9b3ca",
"type": "card",
"saved_for": "merchant",
"created_at": "2023-03-24T14:15:22Z",
"bin": "459885",
"last_four": "7653",
"expiry_month": 12,
"expiry_year": 2026,
"cardholder_name": "Example Holder",
"brand": "mastercard",
"funding": "credit",
"issuer": "EXAMPLE ISSUER",
"issuer_country": "GB",
"billing_address": {
"street_line_1": "Revolut",
"street_line_2": "1 Canada Square",
"postcode": "EC2V 6DN",
"city": "London",
"region": "Greater London",
"country_code": "GB"
}
},
{
"id": "6a0fe961-a961-a8b6-ad17-ab2779165a82",
"type": "sepa_direct_debit",
"saved_for": "merchant",
"created_at": "2026-05-22T05:28:01.887482Z",
"debtor_iban_last_four": "3273",
"debtor_name": "John Doe",
"mandate_reference": "69F1CB61BD99A32C8E20D7FB9E21E146",
"billing_address": {
"street_line_1": "Bank of England",
"street_line_2": "Threadneedle St",
"postcode": "EC2R 8AH",
"city": "London",
"region": "Greater London",
"country_code": "GB"
}
}
]
}Retrieve a customer's payment method
Retrieve the information of a specific saved payment method for a customer.
Request
Response
OK
curl -X GET "https://merchant.revolut.com/api/customers/123e4567-e89b-12d3-a456-426614174000/payment-methods/123e4567-e89b-12d3-a456-426614174000" \
-H "Authorization: Bearer <yourSecretApiKey>" \
-H "Revolut-Api-Version: 2026-04-20"Authorization
apiKeyAuthorizationEach Merchant API request must contain an authorization header in the following format:
'Authorization: Bearer <yourSecretApiKey>'To use this API, you need to generate API keys from your Revolut Business account. The Secret key is used in the authorization header for all server calls, while the Public key is provided with payment methods at checkout.
For detailed instructions on generating your API keys, see: Generate API keys.
Response body samples
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"type": "card",
"saved_for": "customer",
"created_at": "2024-01-01T00:00:00Z",
"bin": "string",
"last_four": "aaaa",
"expiry_month": 123,
"expiry_year": 123,
"cardholder_name": "string",
"brand": "visa",
"funding": "debit",
"issuer": "string",
"issuer_country": "aa",
"billing_address": {
"street_line_1": "string",
"street_line_2": "string",
"region": "string",
"city": "string",
"country_code": "aa",
"postcode": "string"
}
}Update a customer's payment method
Update the attributes of a specific saved payment method for a customer.
Updating saved_for to customer is a one-way operation — you can't change it back to merchant.
Once updated, this payment method can no longer be used for merchant-initiated transactions (MIT), for example, to charge recurring payments. It can only be used when the customer is on the checkout page.
For more information, see:
Request
Response
OK
curl -X PATCH "https://merchant.revolut.com/api/customers/123e4567-e89b-12d3-a456-426614174000/payment-methods/123e4567-e89b-12d3-a456-426614174000" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <yourSecretApiKey>" \
-H "Revolut-Api-Version: 2026-04-20" \
-d '{
"saved_for": "customer"
}'Authorization
apiKeyAuthorizationEach Merchant API request must contain an authorization header in the following format:
'Authorization: Bearer <yourSecretApiKey>'To use this API, you need to generate API keys from your Revolut Business account. The Secret key is used in the authorization header for all server calls, while the Public key is provided with payment methods at checkout.
For detailed instructions on generating your API keys, see: Generate API keys.
Request body samples
{
"saved_for": "customer"
}Response body samples
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"type": "card",
"saved_for": "customer",
"created_at": "2024-01-01T00:00:00Z",
"bin": "string",
"last_four": "aaaa",
"expiry_month": 123,
"expiry_year": 123,
"cardholder_name": "string",
"brand": "visa",
"funding": "debit",
"issuer": "string",
"issuer_country": "aa",
"billing_address": {
"street_line_1": "string",
"street_line_2": "string",
"region": "string",
"city": "string",
"country_code": "aa",
"postcode": "string"
}
}Delete a customer's payment method
Delete a specific saved payment method. The payment method is completely removed from the customer's saved payment methods.
To reuse a deleted payment method, direct your customer to the checkout page to save their card details again.
Request
Response
No Content
curl -X DELETE "https://merchant.revolut.com/api/customers/123e4567-e89b-12d3-a456-426614174000/payment-methods/123e4567-e89b-12d3-a456-426614174000" \
-H "Authorization: Bearer <yourSecretApiKey>" \
-H "Revolut-Api-Version: 2026-04-20"Authorization
apiKeyAuthorizationEach Merchant API request must contain an authorization header in the following format:
'Authorization: Bearer <yourSecretApiKey>'To use this API, you need to generate API keys from your Revolut Business account. The Secret key is used in the authorization header for all server calls, while the Public key is provided with payment methods at checkout.
For detailed instructions on generating your API keys, see: Generate API keys.
Response body samples
Payments
Payment operations enable you to initiate payments, or track payment status transitions. You can use the ID of the payment to retrieve information about a specific payment.
For more information about the payment lifecycle, see: Order and payment lifecycle.
Retrieve payment details
Retrieve information about a specific payment, based on the payment's ID.
Use this endpoint to track a payment's lifecycle, for example:
- When you develop a 1-click checkout process
- When you build a subscription management system
Request
Response
Payment details
curl -X GET "https://merchant.revolut.com/api/payments/123e4567-e89b-12d3-a456-426614174000" \
-H "Authorization: Bearer <yourSecretApiKey>" \
-H "Revolut-Api-Version: 2023-09-01"Authorization
apiKeyAuthorizationEach Merchant API request must contain an authorization header in the following format:
'Authorization: Bearer <yourSecretApiKey>'To use this API, you need to generate API keys from your Revolut Business account. The Secret key is used in the authorization header for all server calls, while the Public key is provided with payment methods at checkout.
For detailed instructions on generating your API keys, see: Generate API keys.
Response body samples
{
"id": "6633855a-0e4f-a768-8b2c-e765d8872505",
"state": "captured",
"created_at": "2024-05-02T12:21:46.638369Z",
"updated_at": "2024-05-02T12:21:55.198089Z",
"token": "0b277730-8b3c-48d4-ab63-8903f40ee520",
"amount": 100,
"currency": "GBP",
"settled_amount": 77,
"settled_currency": "GBP",
"risk_level": "low",
"fees": [
{
"type": "acquiring",
"amount": 23,
"currency": "GBP"
}
],
"payment_method": {
"id": "6633855a-3b39-ad95-9782-cd1327ffa0e7",
"type": "revolut_pay_card",
"fingerprint": "1JAllfQY4POhBV8DaddAQ4LC5RbMP8LMLvUdJW4s5JY=",
"card_brand": "visa",
"funding": "credit",
"card_country_code": "MT",
"card_bin": "123456",
"card_last_four": "1234",
"card_expiry": "12/28",
"cardholder_name": "Example Holder",
"checks": {
"three_ds": {
"eci": "06",
"state": "verified",
"version": 2
}
}
},
"order_id": "66338534-28a7-a68e-b312-43722430df1b"
}Subscriptions
The Subscriptions API provides a complete solution for creating and managing recurring billing for your customers.
You can automatically charge customers on flexible billing cycles, manage sophisticated subscription plans, and track the entire billing history for every subscriber.
How it works?
A subscription's billing structure is defined by a Subscription plan. This model gives you granular control:
- Plans contain one or more variations (e.g., a "Gold" plan could have "Monthly" and "Yearly" variations).
- Variations can have multiple phases (e.g., a 7-day free trial followed by a regular billing phase).
This powerful structure allows you to build complex pricing models, including free trials, introductory offers, and tiered pricing.
Key features
- Flexible pricing models: Create plans with multiple variations and phases to support any billing scenario.
- Automated charging: Automatically charge a customer's saved payment method at the start of each billing cycle.
- Hosted onboarding: For new customers, generate a setup order with a redirect URL to Revolut's Hosted Payment Page, allowing them to securely add a payment method.
- Lifecycle tracking: Monitor each billing cycle's state, view all associated orders, and access complete payment histories.
- Full subscription management: Easily update customer payment methods, cancel subscriptions, and view a complete billing history.
Create a subscription plan
Create a new subscription plan with one or more pricing variations.
A subscription plan defines the billing structure for subscriptions. Each plan can have multiple variations (e.g., monthly vs. yearly), and each variation can have multiple billing phases (e.g., trial period followed by regular billing). These plans are designed for flexibility, allowing you to combine fixed recurring fees with unit-based or usage-based charges into a single, unified subscription.
How subscription plans work
A subscription plan consists of four hierarchical levels:
- Plan: The top-level container (e.g., "Standard Plan")
- Variations: Different pricing options (e.g., monthly vs. yearly)
- Phases: Sequential billing stages within each variation
- Subscription items: Individual line items within a phase that define how to charge (e.g., a base fee plus per-unit charges)
Phases and billing items
If a trial_duration is defined at the variation level, billing phases begin immediately after the trial ends. Phases execute in sequence based on their ordinal value (1, 2, 3, etc.):
| Concept | Behaviour |
|---|---|
| Cycle control | Each phase has a cycle_duration (e.g., P1M for monthly). Use cycle_count to limit how many cycles occur; if null or omitted, the phase runs indefinitely. |
| Sequential transition | When a phase completes its cycles, the subscription advances to the next ordinal. If no next phase exists, the subscription stops automatically. |
| Item composition | Each phase contains one or more subscription_items defining how charges are calculated: flat items apply a fixed cost multiplied by quantity; usage items are metered at the end of the cycle based on reported consumption. |
A plan combining a base platform fee and monthly user licenses:
Variation: Monthly Team
Phase 1 — ordinal: 1, cycle_duration: P1M
| Item | Type | amount | quantity |
|---|---|---|---|
| Base platform fee | flat | 4900 (£49.00) | 1 |
| User licenses | flat | 1000 (£10.00 per unit) | 5 |
The customer is billed a fixed platform fee plus £10.00 for each of their 5 active licenses every month.
Request
Response
Subscription plan created successfully
curl -X POST "https://merchant.revolut.com/api/subscription-plans" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <yourSecretApiKey>" \
-H "Revolut-Api-Version: 2026-04-20" \
-d '{
"name": "Enterprise Pro Plan",
"variations": [
{
"phases": [
{
"ordinal": 1,
"cycle_duration": "P1Y",
"amount": 99900,
"currency": "GBP"
}
]
},
{
"phases": [
{
"ordinal": 1,
"cycle_duration": "P1M",
"amount": 9900,
"currency": "GBP"
}
]
}
]
}'Authorization
apiKeyAuthorizationEach Merchant API request must contain an authorization header in the following format:
'Authorization: Bearer <yourSecretApiKey>'To use this API, you need to generate API keys from your Revolut Business account. The Secret key is used in the authorization header for all server calls, while the Public key is provided with payment methods at checkout.
For detailed instructions on generating your API keys, see: Generate API keys.
Request body samples
{
"name": "Enterprise Pro Plan",
"variations": [
{
"phases": [
{
"ordinal": 1,
"cycle_duration": "P1Y",
"amount": 99900,
"currency": "GBP"
}
]
},
{
"phases": [
{
"ordinal": 1,
"cycle_duration": "P1M",
"amount": 9900,
"currency": "GBP"
}
]
}
]
}Response body samples
{
"id": "f757b068-f287-43c8-8d05-9c073fecbe73",
"name": "Enterprise Pro Plan",
"state": "active",
"created_at": "2026-01-26T08:59:09.433527Z",
"updated_at": "2026-01-26T08:59:09.433527Z",
"variations": [
{
"id": "f4e0a171-4f4e-484b-b0a2-22085059af65",
"phases": [
{
"id": "23319d04-4b23-4ae7-ba54-82112c752683",
"ordinal": 1,
"cycle_duration": "P1M",
"amount": 990,
"currency": "GBP"
}
]
},
{
"id": "7cf47b0d-3da9-496b-a4e9-fbbe43c33ee3",
"phases": [
{
"id": "feed2491-c895-4bfa-ba05-a3a088842d5c",
"ordinal": 1,
"cycle_duration": "P1Y",
"amount": 9990,
"currency": "GBP"
}
]
}
]
}Retrieve a subscription plan list
Retrieve all subscription plans configured for your merchant account. You can use the query parameters for:
| Filtering | Pagination |
|---|---|
| Filter the subscription plans that you want to retrieve, for example, only retrieve plans created within a specific date range. Parameters used for filtering:
| View the subscription plans without loading all of them at once, for example, return a specified number of plans per page. Parameters used for pagination:
|
Request
Response
List of subscription plans retrieved successfully
curl -X GET "https://merchant.revolut.com/api/subscription-plans?limit=100&from=2024-01-01T00%3A00%3A00Z&to=2024-01-01T00%3A00%3A00Z&page_token=string" \
-H "Authorization: Bearer <yourSecretApiKey>" \
-H "Revolut-Api-Version: 2026-04-20"Authorization
apiKeyAuthorizationEach Merchant API request must contain an authorization header in the following format:
'Authorization: Bearer <yourSecretApiKey>'To use this API, you need to generate API keys from your Revolut Business account. The Secret key is used in the authorization header for all server calls, while the Public key is provided with payment methods at checkout.
For detailed instructions on generating your API keys, see: Generate API keys.
Response body samples
{
"next_page_token": "9e5d2caa-bb60-4b5b-b7cf-6345bbdff67e",
"subscription_plans": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Premium Plan with 14-days Trial",
"state": "active",
"trial_duration": "P14D",
"created_at": "2025-06-05T21:00:00.036001Z",
"updated_at": "2025-06-05T21:00:00.036001Z",
"variations": [
{
"id": "550e8400-e29b-41d4-a716-446655440001",
"phases": [
{
"id": "550e8400-e29b-41d4-a716-446655440002",
"ordinal": 1,
"cycle_duration": "P1Y",
"amount": 99900,
"currency": "GBP"
}
]
}
]
},
{
"id": "f757b068-f287-43c8-8d05-9c073fecbe73",
"name": "Enterprise Pro Plan",
"state": "active",
"created_at": "2026-01-26T08:59:09.433527Z",
"updated_at": "2026-01-26T08:59:09.433527Z",
"variations": [
{
"id": "f4e0a171-4f4e-484b-b0a2-22085059af65",
"phases": [
{
"id": "23319d04-4b23-4ae7-ba54-82112c752683",
"ordinal": 1,
"cycle_duration": "P1M",
"amount": 990,
"currency": "GBP"
}
]
},
{
"id": "7cf47b0d-3da9-496b-a4e9-fbbe43c33ee3",
"phases": [
{
"id": "feed2491-c895-4bfa-ba05-a3a088842d5c",
"ordinal": 1,
"cycle_duration": "P1Y",
"amount": 9990,
"currency": "GBP"
}
]
}
]
}
]
}Retrieve a subscription plan
Retrieve a specific subscription plan by its unique identifier.
A subscription plan contains variations (different pricing options like monthly vs. yearly), and each variation contains phases (sequential billing stages).
Phases execute based on their ordinal value. When a phase completes its cycle_count, the subscription moves to the next phase. If cycle_count is null or omitted, the phase continues indefinitely.
If a trial_duration is defined, phases begin immediately after the trial ends.
Request
Response
Subscription plan retrieved successfully
curl -X GET "https://merchant.revolut.com/api/subscription-plans/123e4567-e89b-12d3-a456-426614174000" \
-H "Authorization: Bearer <yourSecretApiKey>" \
-H "Revolut-Api-Version: 2026-04-20"Authorization
apiKeyAuthorizationEach Merchant API request must contain an authorization header in the following format:
'Authorization: Bearer <yourSecretApiKey>'To use this API, you need to generate API keys from your Revolut Business account. The Secret key is used in the authorization header for all server calls, while the Public key is provided with payment methods at checkout.
For detailed instructions on generating your API keys, see: Generate API keys.
Response body samples
{
"id": "f757b068-f287-43c8-8d05-9c073fecbe73",
"name": "Enterprise Pro Plan",
"state": "active",
"created_at": "2026-01-26T08:59:09.433527Z",
"updated_at": "2026-01-26T08:59:09.433527Z",
"variations": [
{
"id": "f4e0a171-4f4e-484b-b0a2-22085059af65",
"phases": [
{
"id": "23319d04-4b23-4ae7-ba54-82112c752683",
"ordinal": 1,
"cycle_duration": "P1M",
"amount": 990,
"currency": "GBP"
}
]
},
{
"id": "7cf47b0d-3da9-496b-a4e9-fbbe43c33ee3",
"phases": [
{
"id": "feed2491-c895-4bfa-ba05-a3a088842d5c",
"ordinal": 1,
"cycle_duration": "P1Y",
"amount": 9990,
"currency": "GBP"
}
]
}
]
}Create a subscription
Create a new subscription for a customer using a subscription plan variation.
There are several supported flows for creating and activating subscriptions, depending on your integration needs.
The customer must already exist in the API. The customer_id is required for all subscription flows.
Flow 1: Hosted Payment Page (HPP)
Use this flow to redirect the customer to Revolut's Hosted Payment Page to complete the first payment and save their payment method.
Backend flow:
-
Create a subscription with optional
setup_order_redirect_url:setup_order_redirect_urlBehaviour Provided The setup order's redirect_urlfield is set to this value.Omitted The setup order uses Revolut's default redirect behaviour. -
The subscription is created in a
pendingstate with asetup_order_idin the response. -
Retrieve the order using
setup_order_idas theorder_idin the path to get thecheckout_url. -
Redirect the customer to the
checkout_urlfor the Hosted Payment Page.
Customer flow:
-
Customer is redirected to Revolut's Hosted Payment Page.
-
Customer completes payment on the HPP, and their payment method is saved.
-
Customer redirect after payment depends on your setup:
setup_order_redirect_urlCustomer redirect Provided Customer is redirected to your custom URL. Omitted Customer sees the default Revolut completion screen.
Key characteristics:
- Customer completes payment on Revolut's hosted page
- Payment method is automatically saved for future billing cycles
- Optional custom redirect after payment
- Best for web-based integrations
Flow 2: Widget or card-not-present (CNP) payment
Use this flow when you want to embed the payment experience directly on your website using one of Revolut's payment widgets or handle card-not-present payments.
Backend flow:
- Create a subscription with minimal required parameters.
- The subscription is created in a
pendingstate with asetup_order_idin the response. - Retrieve the order using
setup_order_idas theorder_idin the path to get order details for your integration. - Integrate your payment solution (widget, SDK, or CNP method) on your frontend, ensuring it's configured to save the customer's payment method for recurring billing.
Customer flow:
- Customer stays on your website/application.
- Customer completes payment, and their payment method is saved for future billing cycles.
Key characteristics:
- Payment experience embedded directly in your application
- Customer never leaves your website
- Payment method is saved for future billing cycles
- Best for native mobile apps or fully custom web experiences
Request
Response
Subscription created successfully
curl -X POST "https://merchant.revolut.com/api/subscriptions" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <yourSecretApiKey>" \
-H "Revolut-Api-Version: 2026-04-20" \
-H "Idempotency-Key: string" \
-d '{
"plan_variation_id": "550e8400-e29b-41d4-a716-446655440000",
"customer_id": "650e8400-e29b-41d4-a716-446655440001",
"setup_order_redirect_url": "https://example.com/subscription/setup/complete",
"external_reference": "ext-ref-12345"
}'Authorization
apiKeyAuthorizationEach Merchant API request must contain an authorization header in the following format:
'Authorization: Bearer <yourSecretApiKey>'To use this API, you need to generate API keys from your Revolut Business account. The Secret key is used in the authorization header for all server calls, while the Public key is provided with payment methods at checkout.
For detailed instructions on generating your API keys, see: Generate API keys.
Request body samples
{
"plan_variation_id": "550e8400-e29b-41d4-a716-446655440000",
"customer_id": "650e8400-e29b-41d4-a716-446655440001",
"setup_order_redirect_url": "https://example.com/subscription/setup/complete",
"external_reference": "ext-ref-12345"
}Response body samples
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"external_reference": "ext-ref-12345",
"state": "pending",
"customer_id": "650e8400-e29b-41d4-a716-446655440001",
"plan_id": "750e8400-e29b-41d4-a716-446655440002",
"plan_variation_id": "850e8400-e29b-41d4-a716-446655440003",
"payment_method_type": "automatic",
"created_at": "2025-06-05T21:00:00.036001Z",
"updated_at": "2025-06-05T21:00:00.036001Z",
"setup_order_id": "a50e8400-e29b-41d4-a716-446655440005",
"current_cycle_id": "a31627fb-b037-4566-8d7b-f380c1f44653"
}Retrieve a subscription list
Retrieve all subscriptions for the merchant account. You can use the query parameters for:
| Filtering | Pagination |
|---|---|
| Filter the subscriptions that you want to retrieve, for example, only retrieve subscriptions created within a specific date range or with a specific external reference. Parameters used for filtering:
| View the subscriptions without loading all of them at once, for example, return a specified number of subscriptions per page. Parameters used for pagination:
|
Request
Response
List of subscriptions retrieved successfully
curl -X GET "https://merchant.revolut.com/api/subscriptions?limit=100&from=2024-01-01T00%3A00%3A00Z&to=2024-01-01T00%3A00%3A00Z&external_reference=string&page_token=string" \
-H "Authorization: Bearer <yourSecretApiKey>" \
-H "Revolut-Api-Version: 2026-04-20"Authorization
apiKeyAuthorizationEach Merchant API request must contain an authorization header in the following format:
'Authorization: Bearer <yourSecretApiKey>'To use this API, you need to generate API keys from your Revolut Business account. The Secret key is used in the authorization header for all server calls, while the Public key is provided with payment methods at checkout.
For detailed instructions on generating your API keys, see: Generate API keys.
Response body samples
{
"next_page_token": "9e5d2caa-bb60-4b5b-b7cf-6345bbdff67e",
"subscriptions": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"external_reference": "ext-ref-12345",
"state": "active",
"customer_id": "650e8400-e29b-41d4-a716-446655440001",
"plan_id": "750e8400-e29b-41d4-a716-446655440002",
"plan_variation_id": "850e8400-e29b-41d4-a716-446655440003",
"payment_method_type": "automatic",
"payment_method_id": "6689e244-8af7-4ada-9448-a91f02d4f192",
"created_at": "2025-06-05T21:00:00.036001Z",
"updated_at": "2025-06-05T21:00:00.036001Z",
"start_date": "2025-06-05T21:00:00.036001Z",
"current_cycle_id": "950e8400-e29b-41d4-a716-446655440004"
},
{
"id": "550e8400-e29b-41d4-a716-446655440010",
"state": "pending",
"customer_id": "650e8400-e29b-41d4-a716-446655440011",
"plan_id": "750e8400-e29b-41d4-a716-446655440012",
"plan_variation_id": "850e8400-e29b-41d4-a716-446655440013",
"payment_method_type": "automatic",
"created_at": "2025-06-04T21:00:00.036001Z",
"updated_at": "2025-06-04T21:00:00.036001Z",
"current_cycle_id": "a31627fb-b037-4566-8d7b-f380c1f44653"
}
]
}Retrieve a subscription
Retrieve a subscription by its unique identifier.
Use this endpoint to get the current state and details of a specific subscription.
Request
Response
Subscription retrieved successfully
curl -X GET "https://merchant.revolut.com/api/subscriptions/123e4567-e89b-12d3-a456-426614174000" \
-H "Authorization: Bearer <yourSecretApiKey>" \
-H "Revolut-Api-Version: 2026-04-20"Authorization
apiKeyAuthorizationEach Merchant API request must contain an authorization header in the following format:
'Authorization: Bearer <yourSecretApiKey>'To use this API, you need to generate API keys from your Revolut Business account. The Secret key is used in the authorization header for all server calls, while the Public key is provided with payment methods at checkout.
For detailed instructions on generating your API keys, see: Generate API keys.
Response body samples
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"external_reference": "ext-ref-12345",
"state": "active",
"customer_id": "650e8400-e29b-41d4-a716-446655440001",
"plan_id": "750e8400-e29b-41d4-a716-446655440002",
"plan_variation_id": "850e8400-e29b-41d4-a716-446655440003",
"payment_method_type": "automatic",
"payment_method_id": "6689e244-8af7-4ada-9448-a91f02d4f192",
"created_at": "2025-06-05T21:00:00.036001Z",
"updated_at": "2025-06-05T21:00:00.036001Z",
"start_date": "2025-06-05T21:00:00.036001Z",
"current_cycle_id": "950e8400-e29b-41d4-a716-446655440004",
"trial_duration": "P14D",
"trial_end_date": "2025-06-19T21:00:00.036001Z"
}Update a subscription
Update a subscription's details.
You can update a subscription and specific parameters based on the value of the state parameter:
| State parameter value | Modifiable parameters |
|---|---|
pending, active, overdue, paused | You can modify all listed parameters. |
cancelled, finished | You cannot modify parameters. These are final states. |
Common use cases:
- Update external reference: When you need to sync with updated customer records in your system, correct an initial reference value, or re-map the subscription to a different internal tracking ID to maintain consistency with your database.
Request
Response
Subscription updated successfully
curl -X PATCH "https://merchant.revolut.com/api/subscriptions/123e4567-e89b-12d3-a456-426614174000" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <yourSecretApiKey>" \
-H "Revolut-Api-Version: 2026-04-20" \
-d '{
"external_reference": "ext-ref-12345"
}'Authorization
apiKeyAuthorizationEach Merchant API request must contain an authorization header in the following format:
'Authorization: Bearer <yourSecretApiKey>'To use this API, you need to generate API keys from your Revolut Business account. The Secret key is used in the authorization header for all server calls, while the Public key is provided with payment methods at checkout.
For detailed instructions on generating your API keys, see: Generate API keys.
Request body samples
{
"external_reference": "ext-ref-12345"
}Response body samples
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"external_reference": "ext-ref-12345",
"state": "active",
"customer_id": "650e8400-e29b-41d4-a716-446655440001",
"plan_id": "750e8400-e29b-41d4-a716-446655440002",
"plan_variation_id": "850e8400-e29b-41d4-a716-446655440003",
"payment_method_type": "automatic",
"payment_method_id": "6689e244-8af7-4ada-9448-a91f02d4f192",
"created_at": "2025-06-05T21:00:00.036001Z",
"updated_at": "2025-06-05T21:00:00.036001Z",
"start_date": "2025-06-05T21:00:00.036001Z",
"current_cycle_id": "950e8400-e29b-41d4-a716-446655440004",
"trial_duration": "P14D",
"trial_end_date": "2025-06-19T21:00:00.036001Z"
}Change a subscription plan
Schedule a plan change for a subscription. The change is applied at the end of the current billing cycle.
Use cases
- Plan upgrades: Moving a customer to a higher-tier plan with more features or capacity.
- Plan downgrades: Moving a customer to a lower-tier plan that better fits their usage and budget.
- Customer requests: Accommodating a customer's request to switch to a different plan variation.
How it works
When you schedule a plan change, the subscription continues operating under its current plan variation until the current billing cycle ends. At that point, the next cycle is created under the new plan variation.
- Scheduled change: The plan change is scheduled to take effect
at_cycle_end. The current cycle completes normally, and the new plan variation applies starting from the next cycle. - Plan variation phases: Some plan variations are divided into phases - distinct pricing or duration periods within a single variation. If the target plan variation has multiple phases, use
plan_variation_phase_idto specify which phase to start from. If omitted, the change starts from the first phase. - Trial periods: If the target plan variation includes a trial period, it is skipped when changing plans. Trial periods only apply when a subscription is first created.
- Subsequent cycles: After the transition, future cycles follow the cadence and pricing defined by the new plan variation.
Request
Response
Plan change scheduled successfully
curl -X POST "https://merchant.revolut.com/api/subscriptions/123e4567-e89b-12d3-a456-426614174000/change-plan" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <yourSecretApiKey>" \
-H "Revolut-Api-Version: 2026-04-20" \
-d '{
"plan_variation_id": "850e8400-e29b-41d4-a716-446655440003",
"scheduled": "at_cycle_end"
}'Authorization
apiKeyAuthorizationEach Merchant API request must contain an authorization header in the following format:
'Authorization: Bearer <yourSecretApiKey>'To use this API, you need to generate API keys from your Revolut Business account. The Secret key is used in the authorization header for all server calls, while the Public key is provided with payment methods at checkout.
For detailed instructions on generating your API keys, see: Generate API keys.
Request body samples
{
"plan_variation_id": "850e8400-e29b-41d4-a716-446655440003",
"scheduled": "at_cycle_end"
}Response body samples
Update a subscription renewal date
Reschedule the upcoming payment date for an active subscription cycle. This is a command endpoint — the renewal date is not a direct field on the Subscription resource, but is derived from the current active cycle's end_date.
Use cases
- Payment extensions: Granting a customer more time to pay.
- Service delays: Adjusting the billing date if service delivery is delayed.
- Billing alignment: Moving a payment date to better suit a customer's financial schedule.
How it works
Extending the current cycle's end_date naturally postpones the start of the next cycle and its associated payment trigger, providing flexibility for both the merchant and the customer.
The relationship between the cycle end and the billing execution depends on the plan type:
- Non-usage plans: The next cycle's start date is the same as the billing date. The moment the current cycle ends, the next cycle begins and the payment is attempted.
- Usage-based plans (buffer & overlap): To allow merchants time to finalize usage data, the billing date is scheduled after the cycle
end_date.- Usage continues to be aggregated until the updated
end_date. - When the current cycle (Cycle 1) reaches its updated
end_date, Cycle 2 starts immediately to ensure no service interruption. - The billing for Cycle 1 occurs a few hours later (12-hour buffer). This window allows you to upload or edit usages for the period that just ended while the customer is already technically in their next cycle.
- Rescheduling the
renewal_datepushes this entire sequence—the end of Cycle 1, the start of Cycle 2, and the delayed billing trigger—further into the future.
- Usage continues to be aggregated until the updated
Subsequent cycles resume the original plan cadence (e.g., monthly) from the new date.
Request
Response
Renewal date updated successfully
curl -X POST "https://merchant.revolut.com/api/subscriptions/123e4567-e89b-12d3-a456-426614174000/change-renewal-date" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <yourSecretApiKey>" \
-H "Revolut-Api-Version: 2026-04-20" \
-d '{
"renewal_date": "2026-07-01T00:00:00Z"
}'Authorization
apiKeyAuthorizationEach Merchant API request must contain an authorization header in the following format:
'Authorization: Bearer <yourSecretApiKey>'To use this API, you need to generate API keys from your Revolut Business account. The Secret key is used in the authorization header for all server calls, while the Public key is provided with payment methods at checkout.
For detailed instructions on generating your API keys, see: Generate API keys.
Request body samples
{
"renewal_date": "2026-07-01T00:00:00Z"
}Response body samples
Cancel a subscription
Cancel a subscription.
You can cancel a subscription in any state except cancelled or finished. When you cancel a subscription, it will be marked as cancelled and no further billing cycles will be created. Any pending orders will be cancelled.
Request
Response
Subscription cancelled successfully
curl -X POST "https://merchant.revolut.com/api/subscriptions/123e4567-e89b-12d3-a456-426614174000/cancel" \
-H "Authorization: Bearer <yourSecretApiKey>" \
-H "Revolut-Api-Version: 2026-04-20"Authorization
apiKeyAuthorizationEach Merchant API request must contain an authorization header in the following format:
'Authorization: Bearer <yourSecretApiKey>'To use this API, you need to generate API keys from your Revolut Business account. The Secret key is used in the authorization header for all server calls, while the Public key is provided with payment methods at checkout.
For detailed instructions on generating your API keys, see: Generate API keys.
Response body samples
Retrieve a subscription cycle list
Retrieve all billing cycles for a specific subscription.
You can use the query parameters for:
| Filtering | Pagination |
|---|---|
| Filter the subscription cycles that you want to retrieve, for example, only retrieve cycles that started within a specific date range. Parameters used for filtering:
| View the subscription cycles without loading all of them at once, for example, return a specified number of cycles per page. Parameters used for pagination:
|
Request
Response
List of subscription cycles retrieved successfully
curl -X GET "https://merchant.revolut.com/api/subscriptions/123e4567-e89b-12d3-a456-426614174000/cycles?limit=100&from=2024-01-01T00%3A00%3A00Z&to=2024-01-01T00%3A00%3A00Z&page_token=string" \
-H "Authorization: Bearer <yourSecretApiKey>" \
-H "Revolut-Api-Version: 2026-04-20"Authorization
apiKeyAuthorizationEach Merchant API request must contain an authorization header in the following format:
'Authorization: Bearer <yourSecretApiKey>'To use this API, you need to generate API keys from your Revolut Business account. The Secret key is used in the authorization header for all server calls, while the Public key is provided with payment methods at checkout.
For detailed instructions on generating your API keys, see: Generate API keys.
Response body samples
{
"next_page_token": "9e5d2caa-bb60-4b5b-b7cf-6345bbdff67e",
"cycles": [
{
"id": "550e8400-e29b-41d4-a716-446655440010",
"subscription_id": "650e8400-e29b-41d4-a716-446655440001",
"plan_variation_id": "750e8400-e29b-41d4-a716-446655440002",
"plan_variation_phase_id": "850e8400-e29b-41d4-a716-446655440003",
"number": 2,
"previous_cycle_id": "550e8400-e29b-41d4-a716-446655440000",
"state": "active",
"start_date": "2025-07-05T21:00:00.036001Z",
"end_date": "2025-08-05T21:00:00.036001Z",
"order_id": "a50e8400-e29b-41d4-a716-446655440015",
"trial": false
},
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"subscription_id": "650e8400-e29b-41d4-a716-446655440001",
"plan_variation_id": "750e8400-e29b-41d4-a716-446655440002",
"number": 1,
"state": "finished",
"start_date": "2025-06-05T21:00:00.036001Z",
"end_date": "2025-07-05T21:00:00.036001Z",
"order_id": "a50e8400-e29b-41d4-a716-446655440005",
"trial": true
}
]
}Retrieve a subscription cycle
Retrieve a specific billing cycle for a subscription by its unique identifier.
Use this endpoint to get the details and current state of a particular billing cycle.
Request
Response
Subscription cycle retrieved successfully
curl -X GET "https://merchant.revolut.com/api/subscriptions/123e4567-e89b-12d3-a456-426614174000/cycles/123e4567-e89b-12d3-a456-426614174000" \
-H "Authorization: Bearer <yourSecretApiKey>" \
-H "Revolut-Api-Version: 2026-04-20"Authorization
apiKeyAuthorizationEach Merchant API request must contain an authorization header in the following format:
'Authorization: Bearer <yourSecretApiKey>'To use this API, you need to generate API keys from your Revolut Business account. The Secret key is used in the authorization header for all server calls, while the Public key is provided with payment methods at checkout.
For detailed instructions on generating your API keys, see: Generate API keys.
Response body samples
{
"id": "950e8400-e29b-41d4-a716-446655440004",
"subscription_id": "650e8400-e29b-41d4-a716-446655440001",
"plan_variation_id": "750e8400-e29b-41d4-a716-446655440002",
"plan_variation_phase_id": "850e8400-e29b-41d4-a716-446655440003",
"number": 1,
"state": "finished",
"start_date": "2025-06-05T21:00:00.036001Z",
"end_date": "2025-07-05T21:00:00.036001Z",
"order_id": "b50e8400-e29b-41d4-a716-446655440006",
"trial": true
}Create a subscription usage
Report a unit of consumption against a usage-based subscription item. Revolut accumulates reported records throughout the billing cycle and processes the charge after the cycle's usage_cutoff_date.
Resolve the billing cycle
Revolut automatically identifies the applicable billing cycle from the usage_date you provide. The following submission windows are accepted:
| Window | Rule |
|---|---|
| Active cycle | usage_date falls within the current cycle (start_date ≤ usage_date < end_date). |
| Past cycle correction | usage_date falls within a recently ended cycle, and the request is made before that cycle's usage_cutoff_date (12 hours after end_date by default). |
| Next upcoming cycle | usage_date falls within the one next future cycle. Revolut creates a pending cycle to hold the record until it becomes active. |
Any usage_date outside these windows causes the request to be rejected.
How Revolut calculates the charge
After the usage_cutoff_date passes, all records for each usage item are aggregated using the method defined on the subscription plan:
| Method | Behaviour |
|---|---|
sum | Totals all reported values during the cycle. Use for cumulative metrics (e.g., total GB transferred). |
latest | Uses the most recently reported value at the usage_cutoff_date. If no usages are reported during the cycle, the charge is 0. Use for gauge-style metrics (e.g., active seat count at month-end). |
max | Uses the highest value reported during the cycle. Use for capacity-based billing (e.g., peak concurrent connections). |
The aggregated total is multiplied by the unit price to produce the final charge.
Request
Response
Usage reported successfully
curl -X POST "https://merchant.revolut.com/api/subscription-usages" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <yourSecretApiKey>" \
-H "Revolut-Api-Version: 2026-04-20" \
-d '{
"subscription_id": "550e8400-e29b-41d4-a716-446655440000",
"subscription_item_code": "active_seats",
"usage_date": "2026-03-15T09:30:00Z",
"quantity": 12,
"metadata": {
"department": "engineering",
"update_type": "onboarding"
}
}'Authorization
apiKeyAuthorizationEach Merchant API request must contain an authorization header in the following format:
'Authorization: Bearer <yourSecretApiKey>'To use this API, you need to generate API keys from your Revolut Business account. The Secret key is used in the authorization header for all server calls, while the Public key is provided with payment methods at checkout.
For detailed instructions on generating your API keys, see: Generate API keys.
Request body samples
{
"subscription_id": "550e8400-e29b-41d4-a716-446655440000",
"subscription_item_code": "active_seats",
"usage_date": "2026-03-15T09:30:00Z",
"quantity": 12,
"metadata": {
"department": "engineering",
"update_type": "onboarding"
}
}Response body samples
{
"id": "750e8400-e29b-41d4-a716-446655440000",
"subscription_id": "550e8400-e29b-41d4-a716-446655440000",
"subscription_cycle_id": "850e8400-e29b-41d4-a716-446655440000",
"subscription_item_code": "api_calls",
"usage_date": "2026-03-01T21:00:00Z",
"quantity": 100,
"metadata": {
"user_id": "12345",
"api_version": "v2"
},
"created_at": "2026-03-01T21:05:00Z",
"updated_at": "2026-03-01T21:05:00Z"
}Retrieve a subscription usage list
Retrieve all usage records for the merchant account. Results are ordered by usage_date, unlike other list endpoints which order by created_at. You can use the query parameters for:
| Filtering | Pagination |
|---|---|
| Filter the usage records that you want to retrieve, for example, only retrieve records for a specific subscription or billing cycle. Parameters used for filtering:
| View usage records without loading all of them at once, for example, return a specified number of records per page. Parameters used for pagination:
|
Request
Response
List of subscription usages retrieved successfully
curl -X GET "https://merchant.revolut.com/api/subscription-usages?limit=100&from_usage_date=2024-01-01T00%3A00%3A00Z&to_usage_date=2024-01-01T00%3A00%3A00Z&subscription_id=123e4567-e89b-12d3-a456-426614174000&subscription_cycle_id=123e4567-e89b-12d3-a456-426614174000&page_token=string" \
-H "Authorization: Bearer <yourSecretApiKey>" \
-H "Revolut-Api-Version: 2026-04-20"Authorization
apiKeyAuthorizationEach Merchant API request must contain an authorization header in the following format:
'Authorization: Bearer <yourSecretApiKey>'To use this API, you need to generate API keys from your Revolut Business account. The Secret key is used in the authorization header for all server calls, while the Public key is provided with payment methods at checkout.
For detailed instructions on generating your API keys, see: Generate API keys.
Response body samples
{
"next_page_token": "9e5d2caa-bb60-4b5b-b7cf-6345bbdff67e",
"subscription_usages": [
{
"id": "750e8400-e29b-41d4-a716-446655440000",
"subscription_id": "550e8400-e29b-41d4-a716-446655440000",
"subscription_cycle_id": "850e8400-e29b-41d4-a716-446655440000",
"subscription_item_code": "api_calls",
"usage_date": "2026-03-01T21:00:00Z",
"quantity": 100,
"metadata": {
"user_id": "12345",
"api_version": "v2"
},
"created_at": "2026-03-01T21:05:00Z",
"updated_at": "2026-03-01T21:05:00Z"
},
{
"id": "bc903328-9f37-4d7a-8f56-02e5b7c76891",
"subscription_id": "550e8400-e29b-41d4-a716-446655440000",
"subscription_cycle_id": "850e8400-e29b-41d4-a716-446655440000",
"subscription_item_code": "api_calls",
"usage_date": "2026-03-01T22:15:00Z",
"quantity": 50,
"metadata": {
"user_id": "12345",
"api_version": "v2"
},
"created_at": "2026-03-01T22:20:00Z",
"updated_at": "2026-03-01T22:20:00Z"
}
]
}Retrieve a subscription usage
Retrieve a usage record by its unique identifier.
Use this endpoint to get the details of a specific usage that was reported or updated.
Request
Response
Usage record retrieved successfully
curl -X GET "https://merchant.revolut.com/api/subscription-usages/123e4567-e89b-12d3-a456-426614174000" \
-H "Authorization: Bearer <yourSecretApiKey>" \
-H "Revolut-Api-Version: 2026-04-20"Authorization
apiKeyAuthorizationEach Merchant API request must contain an authorization header in the following format:
'Authorization: Bearer <yourSecretApiKey>'To use this API, you need to generate API keys from your Revolut Business account. The Secret key is used in the authorization header for all server calls, while the Public key is provided with payment methods at checkout.
For detailed instructions on generating your API keys, see: Generate API keys.
Response body samples
{
"id": "750e8400-e29b-41d4-a716-446655440000",
"subscription_id": "550e8400-e29b-41d4-a716-446655440000",
"subscription_cycle_id": "850e8400-e29b-41d4-a716-446655440000",
"subscription_item_code": "api_calls",
"usage_date": "2026-03-01T21:00:00Z",
"quantity": 100,
"metadata": {
"user_id": "12345",
"api_version": "v2"
},
"created_at": "2026-03-01T21:05:00Z",
"updated_at": "2026-03-01T21:05:00Z"
}Update a subscription usage
Update the quantity or metadata of a subscription usage record.
Request
Response
Usage updated successfully
curl -X PATCH "https://merchant.revolut.com/api/subscription-usages/123e4567-e89b-12d3-a456-426614174000" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <yourSecretApiKey>" \
-H "Revolut-Api-Version: 2026-04-20" \
-d '{
"quantity": 150
}'Authorization
apiKeyAuthorizationEach Merchant API request must contain an authorization header in the following format:
'Authorization: Bearer <yourSecretApiKey>'To use this API, you need to generate API keys from your Revolut Business account. The Secret key is used in the authorization header for all server calls, while the Public key is provided with payment methods at checkout.
For detailed instructions on generating your API keys, see: Generate API keys.
Request body samples
{
"quantity": 150
}Response body samples
{
"id": "750e8400-e29b-41d4-a716-446655440000",
"subscription_id": "550e8400-e29b-41d4-a716-446655440000",
"subscription_cycle_id": "850e8400-e29b-41d4-a716-446655440000",
"subscription_item_code": "api_calls",
"usage_date": "2026-03-01T21:00:00Z",
"quantity": 100,
"metadata": {
"user_id": "12345",
"api_version": "v2"
},
"created_at": "2026-03-01T21:05:00Z",
"updated_at": "2026-03-01T21:05:00Z"
}Delete a subscription usage
Delete a subscription usage record. This operation is only permitted while the billing cycle is still open.
Request
Response
Usage deleted successfully
curl -X DELETE "https://merchant.revolut.com/api/subscription-usages/123e4567-e89b-12d3-a456-426614174000" \
-H "Authorization: Bearer <yourSecretApiKey>" \
-H "Revolut-Api-Version: 2026-04-20"Authorization
apiKeyAuthorizationEach Merchant API request must contain an authorization header in the following format:
'Authorization: Bearer <yourSecretApiKey>'To use this API, you need to generate API keys from your Revolut Business account. The Secret key is used in the authorization header for all server calls, while the Public key is provided with payment methods at checkout.
For detailed instructions on generating your API keys, see: Generate API keys.
Response body samples
Payouts
Endpoints for retrieving information about payouts, allowing merchants to access details of funds withdrawn from their Merchant account to external bank accounts.
Merchants can use these endpoints to retrieve a list of payouts and specific payout details. The payout IDs obtained can be used to generate detailed reports that provide comprehensive breakdowns of all transactions contributing to the payout amounts.
Payout information, including IDs, can be retrieved via the Retrieve payout list endpoint or from webhook events related to payouts.
Retrieve a payout list
Retrieve all the payouts you made from your Merchant account. You can also use the query parameters for:
| Filtering | Pagination |
|---|---|
| Filter the orders that you want to retrieve, for example, only retrieve the orders that have a specific email. Parameters used for filtering:
| View the orders without loading all of them at once, for example, return a specified number of orders per page. Parameters used for pagination:
|
Request
Response
Payouts retrieved
curl -X GET "https://merchant.revolut.com/api/payouts?currency=aaa&limit=1&from_created_date=2024-01-01T00%3A00%3A00Z&to_created_date=2024-01-01T00%3A00%3A00Z&state=%5B%5D" \
-H "Authorization: Bearer <yourSecretApiKey>" \
-H "Revolut-Api-Version: 2026-04-20"Authorization
apiKeyAuthorizationEach Merchant API request must contain an authorization header in the following format:
'Authorization: Bearer <yourSecretApiKey>'To use this API, you need to generate API keys from your Revolut Business account. The Secret key is used in the authorization header for all server calls, while the Public key is provided with payment methods at checkout.
For detailed instructions on generating your API keys, see: Generate API keys.
Response body samples
[
{
"id": "a830020e-090c-4717-836d-37941a27ad12",
"state": "completed",
"created_at": "2024-02-27T00:16:39.079285Z",
"destination_type": "current_pocket",
"amount": 50000,
"currency": "GBP"
},
{
"id": "66ffee42-7c4a-a15c-9a47-5dc67150386f",
"state": "processing",
"created_at": "2024-02-26T17:16:39.079285Z",
"destination_type": "external_beneficiary",
"amount": 10000,
"currency": "GBP"
}
]Retrieve a payout
Retrieve the details of a payout. Provide the unique payout ID, and the corresponding payout information is returned.
Request
Response
Payout retrieved
curl -X GET "https://merchant.revolut.com/api/payouts/123e4567-e89b-12d3-a456-426614174000" \
-H "Authorization: Bearer <yourSecretApiKey>" \
-H "Revolut-Api-Version: 2026-04-20"Authorization
apiKeyAuthorizationEach Merchant API request must contain an authorization header in the following format:
'Authorization: Bearer <yourSecretApiKey>'To use this API, you need to generate API keys from your Revolut Business account. The Secret key is used in the authorization header for all server calls, while the Public key is provided with payment methods at checkout.
For detailed instructions on generating your API keys, see: Generate API keys.
Response body samples
{
"id": "a830020e-090c-4717-836d-37941a27ad12",
"state": "completed",
"created_at": "2024-02-27T00:16:39.079285Z",
"destination_type": "current_pocket",
"amount": 50000,
"currency": "GBP"
}Disputes
Endpoints that allow merchants to view customer payment disputes.
It provides a robust framework with high-level states (e.g., won, lost, needs_response, under_review) and detailed substates (e.g., lost_expired, pre_arbitration, won_pre_arbitration, etc.) to accurately track the dispute lifecycle.
Additionally, the API integrates standard dispute reason codes and human-readable descriptions, offering a customisable approach to dispute resolution that facilitates effective dispute management.
Retrieve a dispute list
Retrieve a list of disputes associated with your merchant account.
This endpoint is only available in Production environment.
You can also use the query parameters for:
| Filtering | Pagination |
|---|---|
| Filter the diputes that you want to retrieve, for example, only retrieve the disputes that have a specific state. Parameters used for filtering:
| View the disputes without loading all of them at once, for example, return a specified number of disputes per page. Parameters used for pagination:
|
Request
Response
List of disputes retrieved
An array containing a list of disputes.
curl -X GET "https://merchant.revolut.com/api/disputes?limit=100&from_created_date=2024-01-01T00%3A00%3A00Z&to_created_date=2024-01-01T00%3A00%3A00Z&state=%5B%5D&payment_id=%5B%5D" \
-H "Authorization: Bearer <yourSecretApiKey>" \
-H "Revolut-Api-Version: 2026-04-20"Authorization
apiKeyAuthorizationEach Merchant API request must contain an authorization header in the following format:
'Authorization: Bearer <yourSecretApiKey>'To use this API, you need to generate API keys from your Revolut Business account. The Secret key is used in the authorization header for all server calls, while the Public key is provided with payment methods at checkout.
For detailed instructions on generating your API keys, see: Generate API keys.
Response body samples
[
{
"id": "ab934829-e4ba-4e7f-8a21-365cad85c763",
"state": "under_review",
"substate": "arbitration",
"created_at": "2024-06-13T12:06:18.732706Z",
"updated_at": "2024-09-12T22:27:10.005680Z",
"response_due_date": "2024-10-12T22:27:10.005625Z",
"reason_code": "50",
"reason_description": "Fraud",
"amount": 50,
"currency": "EUR",
"payment": {
"id": "6666f6c7-3898-a094-9c83-dc0152e0185c",
"order_id": "6666f685-46a7-a7b9-9860-a28a4f3495a4",
"created_at": "2024-06-10T12:51:19.960490Z",
"amount": 50,
"currency": "EUR",
"payment_method": {
"type": "revolut_pay_account"
}
}
},
{
"id": "340b85dc-da99-4c5f-9d47-37a45d52a455",
"state": "lost",
"substate": "lost_expired",
"created_at": "2024-09-11T21:20:05.659978Z",
"updated_at": "2024-09-12T22:35:31.721921Z",
"response_due_date": "2024-09-22T22:35:31.721860Z",
"reason_code": "12.4",
"reason_description": "Incorrect Account Number",
"amount": 40,
"currency": "EUR",
"payment": {
"id": "66e1fc66-7606-a7fb-b2e8-b48fb637783a",
"order_id": "66e1fc4d-5cbe-a692-80aa-1cb912291d55",
"created_at": "2024-09-11T20:24:06.271746Z",
"amount": 40,
"currency": "EUR",
"payment_method": {
"type": "card",
"card_brand": "visa",
"card_last_four": "1234"
}
}
},
{
"id": "e9b5472b-7308-4aea-86a0-d4427bc04c24",
"state": "lost",
"substate": "lost_pre_arbitration",
"created_at": "2026-05-22T09:00:00Z",
"updated_at": "2026-05-22T10:15:00Z",
"response_due_date": "2030-12-15T00:00:00Z",
"reason_code": "OTHER",
"reason_description": "merchant_dispute",
"amount": 91700,
"currency": "GBP",
"payment": {
"id": "6a0f2bc4-2137-a1ad-9eb6-b34cf4ca6597",
"order_id": "2bcaf93a-aa87-4d3d-b5c6-62e06051cff2",
"created_at": "2026-05-21T15:59:00.451602Z",
"amount": 1000,
"currency": "GBP",
"payment_method": {
"type": "sepa_direct_debit",
"debtor_iban_last_four": "3273",
"debtor_name": "John Doe",
"mandate_reference": "69F1CB61BD99A32C8E20D7FB9E21E146"
}
}
}
]Retrieve a dispute
Retrieve the details of a specific dispute by its ID.
This endpoint is only available in Production environment.
Request
Response
Successful response
curl -X GET "https://merchant.revolut.com/api/disputes/123e4567-e89b-12d3-a456-426614174000" \
-H "Authorization: Bearer <yourSecretApiKey>" \
-H "Revolut-Api-Version: 2026-04-20"Authorization
apiKeyAuthorizationEach Merchant API request must contain an authorization header in the following format:
'Authorization: Bearer <yourSecretApiKey>'To use this API, you need to generate API keys from your Revolut Business account. The Secret key is used in the authorization header for all server calls, while the Public key is provided with payment methods at checkout.
For detailed instructions on generating your API keys, see: Generate API keys.
Response body samples
{
"id": "fccc53e9-00e0-4847-9d54-6938e9cdd3ef",
"state": "lost",
"substate": "lost_accepted",
"created_at": "2025-03-12T07:00:00.000000Z",
"updated_at": "2025-03-13T10:00:00.000000Z",
"response_due_date": "2025-03-15T12:00:00.000000Z",
"reason_code": "50",
"reason_description": "Fraud",
"amount": 1500,
"currency": "EUR",
"payment": {
"id": "67810850-4c48-a25d-8765-d03d36ca6719",
"order_id": "38bd1186-a276-4b14-91b4-5da886481f85",
"created_at": "2025-01-02T10:00:00Z",
"arn": "P58PC241502Q7800000000A",
"amount": 3000,
"currency": "EUR",
"payment_method": {
"type": "card",
"card_brand": "visa",
"card_last_four": "1234"
}
}
}Accept a dispute
Marks a specific dispute as accepted.
After accepting a dispute, you cannot challenge it.
This endpoint is only available in Production environment.
Request
Response
Dispute accepted successfully
curl -X POST "https://merchant.revolut.com/api/disputes/123e4567-e89b-12d3-a456-426614174000/accept" \
-H "Authorization: Bearer <yourSecretApiKey>" \
-H "Revolut-Api-Version: 2026-04-20"Authorization
apiKeyAuthorizationEach Merchant API request must contain an authorization header in the following format:
'Authorization: Bearer <yourSecretApiKey>'To use this API, you need to generate API keys from your Revolut Business account. The Secret key is used in the authorization header for all server calls, while the Public key is provided with payment methods at checkout.
For detailed instructions on generating your API keys, see: Generate API keys.
Response body samples
Upload evidence for a dispute
Allows uploading a single evidence file for a specific dispute.
Use these evidences to provide proof for claims when challenging a dispute.
Limitations:
- Maximum
100uploaded files are allowed per dispute. - Maximum file size:
10MB. - Allowed file types:
PDF,PNG,JPEG.
This endpoint is only available in Production environment.
Request
Response
Evidence uploaded successfully
curl -X POST "https://merchant.revolut.com/api/disputes/123e4567-e89b-12d3-a456-426614174000/evidences" \
-H "Authorization: Bearer <yourSecretApiKey>" \
-H "Revolut-Api-Version: 2026-04-20" \
-H "Content-Type: string"Authorization
apiKeyAuthorizationEach Merchant API request must contain an authorization header in the following format:
'Authorization: Bearer <yourSecretApiKey>'To use this API, you need to generate API keys from your Revolut Business account. The Secret key is used in the authorization header for all server calls, while the Public key is provided with payment methods at checkout.
For detailed instructions on generating your API keys, see: Generate API keys.
Request body samples
{
"file": "string"
}Response body samples
{
"id": "121ac27c-b00a-44d0-9120-efeeec7c912d"
}Challenge a dispute
Allows challenging a dispute with a reason, comment and associated evidences.
Use the uploaded evidences to provide proof for the challenge.
A dispute previously accepted, cannot be challenged.
This endpoint is only available in Production environment.
Request
Response
Dispute challenged successfully
curl -X POST "https://merchant.revolut.com/api/disputes/123e4567-e89b-12d3-a456-426614174000/challenge" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <yourSecretApiKey>" \
-H "Revolut-Api-Version: 2026-04-20" \
-d '{
"reason": "refund_already_issued",
"evidences": [
"121ac27c-b00a-44d0-9120-efeeec7c912d"
]
}'Authorization
apiKeyAuthorizationEach Merchant API request must contain an authorization header in the following format:
'Authorization: Bearer <yourSecretApiKey>'To use this API, you need to generate API keys from your Revolut Business account. The Secret key is used in the authorization header for all server calls, while the Public key is provided with payment methods at checkout.
For detailed instructions on generating your API keys, see: Generate API keys.
Request body samples
{
"reason": "refund_already_issued",
"evidences": [
"121ac27c-b00a-44d0-9120-efeeec7c912d"
]
}Response body samples
Report runs
In addition to the CSV statements you can export via the Revolut Business Dashboard, you can generate custom CSV reports using the Report runs operations. Unlike the default statements, creating custom reports offers you more flexibility in determining what data you wish to incorporate. This allows you to have more control over your analytics.
For more information about how to generate custom CSV reports, see: Create CSV reports of transactions.
Create a new report run
Start generating a new report of the relevant transactions, and receive report_run_id.
After generation is done, use the link in file_url to download the report. Use the Retrieve report run details operation to check the status of the report run.
Use the table below to choose the right report type for your use case:
| Report type | What it covers | Required filter |
|---|---|---|
custom_report | Settled and processing transactions with configurable columns | from, to |
settlement_report | Predefined settled transaction view | from, to |
payout_statement_report | All transactions contributing to a specific payout | filter.payout_id |
icpp_fee_breakdown_report | IC++ fees per transaction for a specific IC++ charge | filter.icpp_charge_id |
payments_report | All payments including failed and declined ones | from, to |
Request
Response
Report run created, report started generating
curl -X POST "https://merchant.revolut.com/api/report-runs" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <yourSecretApiKey>" \
-d '{
"filter": {
"from": "2020-01-01T00:00:00Z",
"to": "2020-01-02T00:00:00Z",
"entity_types": [
"payment"
],
"entity_states": [
"completed",
"processing"
]
},
"format": "csv",
"type": "custom_report",
"options": {
"timezone": "Europe/London",
"columns": [
"transaction_id",
"amount",
"currency",
"metadata.custom_attribute"
]
}
}'Authorization
apiKeyAuthorizationEach Merchant API request must contain an authorization header in the following format:
'Authorization: Bearer <yourSecretApiKey>'To use this API, you need to generate API keys from your Revolut Business account. The Secret key is used in the authorization header for all server calls, while the Public key is provided with payment methods at checkout.
For detailed instructions on generating your API keys, see: Generate API keys.
Request body samples
{
"filter": {
"from": "2020-01-01T00:00:00Z",
"to": "2020-01-02T00:00:00Z",
"entity_types": [
"payment"
],
"entity_states": [
"completed",
"processing"
]
},
"format": "csv",
"type": "custom_report",
"options": {
"timezone": "Europe/London",
"columns": [
"transaction_id",
"amount",
"currency",
"metadata.custom_attribute"
]
}
}Response body samples
{
"report_run_id": "d6f6ef64-f668-4e64-8967-1cdf8afb2561",
"status": "processing"
}Retrieve report run details
Retrieve details of a report run, based on the report_run_id.
Use this method to check the status of a report run.
If a report run's status is completed, the report file can be downloaded using the file_url.
Request
Response
Report run found
curl -X GET "https://merchant.revolut.com/api/report-runs/123e4567-e89b-12d3-a456-426614174000" \
-H "Authorization: Bearer <yourSecretApiKey>"Authorization
apiKeyAuthorizationEach Merchant API request must contain an authorization header in the following format:
'Authorization: Bearer <yourSecretApiKey>'To use this API, you need to generate API keys from your Revolut Business account. The Secret key is used in the authorization header for all server calls, while the Public key is provided with payment methods at checkout.
For detailed instructions on generating your API keys, see: Generate API keys.
Response body samples
{
"report_run_id": "d6f6ef64-f668-4e64-8967-1cdf8afb2561",
"status": "processing"
}Download report file
Use this endpoint to download the generated report file.
Request
Response
OK
CSV-formatted text representing the generated report file.
curl -X GET "https://merchant.revolut.com/api/report-runs/123e4567-e89b-12d3-a456-426614174000/file" \
-H "Authorization: Bearer <yourSecretApiKey>"Authorization
apiKeyAuthorizationEach Merchant API request must contain an authorization header in the following format:
'Authorization: Bearer <yourSecretApiKey>'To use this API, you need to generate API keys from your Revolut Business account. The Secret key is used in the authorization header for all server calls, while the Public key is provided with payment methods at checkout.
For detailed instructions on generating your API keys, see: Generate API keys.
Response body samples
"transaction_id,order_id,payment_method,amount,currency,state,updated_date\n\n649ae37f-99ca-a7db-a4fb-5924af14ad7c,649ae35c-2558-adea-bf98-3a7156a764e7,PAY_WITH_REVOLUT,0.05,GBP,COMPLETED,2023-06-28T13:30:46.07498Z\n\n649ae3de-e945-af9f-98c8-1d6172e350b5,649ae3ab-3998-ab2b-ad95-41b48346be69,PAY_WITH_REVOLUT,0.05,GBP,COMPLETED,2023-06-28T13:30:46.075569Z\n\n649ae48b-37f6-a097-9cb0-4fc2a89d9e5a,649ae479-d7e8-a139-993b-bf75865c5059,PAY_WITH_REVOLUT,0.05,GBP,COMPLETED,2023-06-28T13:38:46.084289Z\n\n649af325-0695-ac77-8868-ab421510a964,649af29d-be4a-a854-b872-3ececa585e0a,PAY_WITH_REVOLUT,0.05,GBP,COMPLETED,2023-06-28T14:34:56.894573Z\n\n649af3a5-efbd-af7e-8c95-022bbdb91f1b,649af383-670d-a390-b22c-799a00892645,PAY_WITH_REVOLUT,0.05,GBP,COMPLETED,2023-06-28T14:42:56.903122Z\n\n649ab540-352a-ac19-866f-47189c00d1a2,649ab53e-53ba-a398-88e1-78cf5bd9d348,PAY_WITH_REVOLUT,0.50,GBP,COMPLETED,2023-06-28T10:14:18.000566Z"Webhooks
A webhook (also called a web callback) allows your system to receive an event from a different app immediately after it happens.
For example, you can subscribe to a webhook when an order changes from pending to completed status. When the payment is cleared and the order is completed, Revolut servers send a notification to the URL of your choice. This is a more efficient way to know when an order is paid as opposed to trying to get the status of the order every few seconds.
Many events that happen to a Revolut Merchant account are synchronous, which means they arrive instantly and have immediate results. For example, a successful request to create a customer immediately returns a Customer object. Such requests don't require webhooks.
The Revolut Merchant API supports webhooks for events including ORDER_COMPLETED and ORDER_AUTHORISED.
Because we cannot guarantee the delivery order of the status (events), you might receive the status not in the expected order. Make sure that your implementation does not rely on the order that the events are being received in.
For example, for a completed order, you should receive the ORDER_AUTHORISED status first and then ORDER_COMPLETED. However, if the ORDER_AUTHORISED status isn't sent successfully at first, it's moved to the queue to be resent in the next few minutes. Before then, if the ORDER_COMPLETED status is sent successfully, you get ORDER_COMPLETED first and then ORDER_AUTHORISED.
Check out our tutorial for Using webhooks to keep track of the payment lifecycle.
For more information about the order and payment lifecycle, see: Order and payment lifecycle.
Create a webhook
Set up a webhook URL so that the Merchant API can push event notifications to the specified URL.
Merchants can register a maximum of 10 webhook URLs. If you attempt to register more than 10, the API will return a 422 - Unprocessable Content error.
Ensure your webhook registrations are necessary and within the allowed limit.
Request
Response
OK
curl -X POST "https://merchant.revolut.com/api/webhooks" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <yourSecretApiKey>" \
-H "Revolut-Api-Version: 2026-04-20" \
-d '{
"url": "https://example.com/webhooks",
"events": [
"ORDER_COMPLETED",
"ORDER_AUTHORISED"
]
}'Authorization
apiKeyAuthorizationEach Merchant API request must contain an authorization header in the following format:
'Authorization: Bearer <yourSecretApiKey>'To use this API, you need to generate API keys from your Revolut Business account. The Secret key is used in the authorization header for all server calls, while the Public key is provided with payment methods at checkout.
For detailed instructions on generating your API keys, see: Generate API keys.
Request body samples
{
"url": "https://example.com/webhooks",
"events": [
"ORDER_COMPLETED",
"ORDER_AUTHORISED"
]
}Response body samples
{
"id": "c6b981f4-53b3-47d5-9b24-4f87af1160eb",
"url": "https://example.com/webhooks",
"events": [
"ORDER_AUTHORISED",
"ORDER_COMPLETED"
],
"signing_secret": "wsk_4jETWMz1g1b37gCONjNp84t2KSSIT7dK"
}Retrieve a webhook list
Get a list of webhooks that you are currently subscribed to.
Request
Response
OK
curl -X GET "https://merchant.revolut.com/api/webhooks" \
-H "Authorization: Bearer <yourSecretApiKey>" \
-H "Revolut-Api-Version: 2026-04-20"Authorization
apiKeyAuthorizationEach Merchant API request must contain an authorization header in the following format:
'Authorization: Bearer <yourSecretApiKey>'To use this API, you need to generate API keys from your Revolut Business account. The Secret key is used in the authorization header for all server calls, while the Public key is provided with payment methods at checkout.
For detailed instructions on generating your API keys, see: Generate API keys.
Response body samples
{
"webhooks": [
{
"id": "6fc8db62-6489-4470-a9e0-84b462fe3908",
"url": "https://revolut.com/webhooks",
"events": [
"ORDER_COMPLETED"
]
},
{
"id": "b466ab77-4932-4850-beb0-113bfc1166f8",
"url": "https://business.revolut.com/webhooks",
"events": [
"ORDER_COMPLETED",
"ORDER_AUTHORISED"
]
},
{
"id": "c6b981f4-53b3-47d5-9b24-4f87af1160eb",
"url": "https://example.com/webhooks",
"events": [
"ORDER_AUTHORISED",
"ORDER_COMPLETED"
]
}
]
}Retrieve a webhook
Get the details of a specific webhook, including its signing_secret.
Request
Response
OK
curl -X GET "https://merchant.revolut.com/api/webhooks/123e4567-e89b-12d3-a456-426614174000" \
-H "Authorization: Bearer <yourSecretApiKey>" \
-H "Revolut-Api-Version: 2026-04-20"Authorization
apiKeyAuthorizationEach Merchant API request must contain an authorization header in the following format:
'Authorization: Bearer <yourSecretApiKey>'To use this API, you need to generate API keys from your Revolut Business account. The Secret key is used in the authorization header for all server calls, while the Public key is provided with payment methods at checkout.
For detailed instructions on generating your API keys, see: Generate API keys.
Response body samples
{
"id": "c6b981f4-53b3-47d5-9b24-4f87af1160eb",
"url": "https://example.com/webhooks",
"events": [
"ORDER_AUTHORISED",
"ORDER_COMPLETED"
],
"signing_secret": "wsk_4jETWMz1g1b37gCONjNp84t2KSSIT7dK"
}Update a webhook
Update the URL or events for a specific webhook.
All request body fields are optional. Only the fields provided will be updated.
Request
Response
OK
curl -X PATCH "https://merchant.revolut.com/api/webhooks/123e4567-e89b-12d3-a456-426614174000" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <yourSecretApiKey>" \
-H "Revolut-Api-Version: 2026-04-20" \
-d '{
"url": "https://example.com/webhooks/updated",
"events": [
"ORDER_COMPLETED",
"ORDER_AUTHORISED",
"ORDER_CANCELLED"
]
}'Authorization
apiKeyAuthorizationEach Merchant API request must contain an authorization header in the following format:
'Authorization: Bearer <yourSecretApiKey>'To use this API, you need to generate API keys from your Revolut Business account. The Secret key is used in the authorization header for all server calls, while the Public key is provided with payment methods at checkout.
For detailed instructions on generating your API keys, see: Generate API keys.
Request body samples
{
"url": "https://example.com/webhooks/updated",
"events": [
"ORDER_COMPLETED",
"ORDER_AUTHORISED",
"ORDER_CANCELLED"
]
}Response body samples
{
"id": "c6b981f4-53b3-47d5-9b24-4f87af1160eb",
"url": "https://example.com/webhooks",
"events": [
"ORDER_AUTHORISED",
"ORDER_COMPLETED"
],
"signing_secret": "wsk_4jETWMz1g1b37gCONjNp84t2KSSIT7dK"
}Delete a webhook
Delete a webhook so that events are no longer sent to the specified URL.
Request
Response
No Content
curl -X DELETE "https://merchant.revolut.com/api/webhooks/123e4567-e89b-12d3-a456-426614174000" \
-H "Authorization: Bearer <yourSecretApiKey>" \
-H "Revolut-Api-Version: 2026-04-20"Authorization
apiKeyAuthorizationEach Merchant API request must contain an authorization header in the following format:
'Authorization: Bearer <yourSecretApiKey>'To use this API, you need to generate API keys from your Revolut Business account. The Secret key is used in the authorization header for all server calls, while the Public key is provided with payment methods at checkout.
For detailed instructions on generating your API keys, see: Generate API keys.
Response body samples
Rotate a webhook signing secret
Rotate the signing_secret for a specific webhook.
The updated signing secret is returned in the response as part of the full webhook object.
For more information, see Tutorials: Verify the payload signature.
Request
Response
OK
curl -X POST "https://merchant.revolut.com/api/webhooks/123e4567-e89b-12d3-a456-426614174000/rotate-signing-secret" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <yourSecretApiKey>" \
-H "Revolut-Api-Version: 2026-04-20" \
-d '{
"expiration_period": "PT5H30M"
}'Authorization
apiKeyAuthorizationEach Merchant API request must contain an authorization header in the following format:
'Authorization: Bearer <yourSecretApiKey>'To use this API, you need to generate API keys from your Revolut Business account. The Secret key is used in the authorization header for all server calls, while the Public key is provided with payment methods at checkout.
For detailed instructions on generating your API keys, see: Generate API keys.
Request body samples
{
"expiration_period": "PT5H30M"
}Response body samples
{
"id": "c6b981f4-53b3-47d5-9b24-4f87af1160eb",
"url": "https://example.com/webhooks",
"events": [
"ORDER_AUTHORISED",
"ORDER_COMPLETED"
],
"signing_secret": "wsk_4jETWMz1g1b37gCONjNp84t2KSSIT7dK"
}Locations
The Locations API is designed to help merchants manage multiple points of sale, including both online storefronts and physical stores. Registering locations lets you differentiate and group your orders from different stores. You can also introduce custom business logic for each location, such as different inventory management, pricing, or shipping rules.
To start using locations, follow the relevant use case for your business:
Online locations
- Register an online location using the Create a location endpoint, setting the
typetoonline. - Configure your custom processes on your backend for each registered location (e.g., grouping orders, custom pricing, etc.).
- Send the
location_idparameter in the request body during order creation to assign the order to a specific location.
Physical locations
- Register a physical location using the Create a location endpoint, setting the
typetophysical. - In case of Revolut POS, our system handles order creation including
location_idto associate the order with your location.
Fast checkout for multiple storefronts
Locations are particularly useful for tailoring the user experience on each of your online storefronts, especially when using features like Fast checkout.
For example, if you operate two online stores with different shipping rules, you can register two separate online locations. By then using the location_id to register a distinct address validation endpoint for each one, your backend can apply the correct shipping logic and pricing for the specific storefront a customer is buying from.
Create a location
Create a Location object. Supports online and physical location types.
Request
Response
Location created
curl -X POST "https://merchant.revolut.com/api/locations" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <yourSecretApiKey>" \
-d '{
"name": "Grocery website",
"type": "online",
"details": {
"domain": "groceries.example.com"
}
}'Authorization
apiKeyAuthorizationEach Merchant API request must contain an authorization header in the following format:
'Authorization: Bearer <yourSecretApiKey>'To use this API, you need to generate API keys from your Revolut Business account. The Secret key is used in the authorization header for all server calls, while the Public key is provided with payment methods at checkout.
For detailed instructions on generating your API keys, see: Generate API keys.
Request body samples
{
"name": "Grocery website",
"type": "online",
"details": {
"domain": "groceries.example.com"
}
}Response body samples
{
"id": "8d9a7125-805f-40f3-a405-bc89765db996",
"name": "Grocery website",
"type": "online",
"details": {
"domain": "groceries.example.com"
}
}Retrieve location list
Retrieve a list of locations registered for the merchant.
Without the type query parameter, this endpoint returns only online locations by default. To retrieve physical locations, you must explicitly specify type=physical in the query parameters.
Request
Response
OK
curl -X GET "https://merchant.revolut.com/api/locations?type=online" \
-H "Authorization: Bearer <yourSecretApiKey>"Authorization
apiKeyAuthorizationEach Merchant API request must contain an authorization header in the following format:
'Authorization: Bearer <yourSecretApiKey>'To use this API, you need to generate API keys from your Revolut Business account. The Secret key is used in the authorization header for all server calls, while the Public key is provided with payment methods at checkout.
For detailed instructions on generating your API keys, see: Generate API keys.
Response body samples
[
{
"id": "8d9a7125-805f-40f3-a405-bc89765db996",
"name": "Grocery website",
"type": "online",
"details": {
"domain": "groceries.example.com"
}
},
{
"id": "066223df-d5a8-42f0-b3ce-688c7a76f9a8",
"name": "Cars website",
"type": "online",
"details": {
"domain": "cars.example.com"
}
},
{
"id": "299050a4-cc7a-44b0-8b2b-7cd1e335ef38",
"name": "Example Street Store",
"type": "physical",
"details": {
"address": {
"street_line_1": "123 Example Street",
"city": "Example city",
"postcode": "12345",
"country_code": "GB"
},
"geo_location": {
"lat": 12.3456,
"lon": -12.3456
},
"opening_hours": {
"monday": [
{
"from": "09:00",
"to": "15:00"
},
{
"from": "16:00",
"to": "18:00"
}
],
"tuesday": [
{
"from": "10:00",
"to": "13:00"
},
{
"from": "16:00",
"to": "18:00"
}
]
}
}
}
]Retrieve a location
Retrieve details of a specific location, based on its ID.
Request
Response
OK
curl -X GET "https://merchant.revolut.com/api/locations/123e4567-e89b-12d3-a456-426614174000" \
-H "Authorization: Bearer <yourSecretApiKey>"Authorization
apiKeyAuthorizationEach Merchant API request must contain an authorization header in the following format:
'Authorization: Bearer <yourSecretApiKey>'To use this API, you need to generate API keys from your Revolut Business account. The Secret key is used in the authorization header for all server calls, while the Public key is provided with payment methods at checkout.
For detailed instructions on generating your API keys, see: Generate API keys.
Response body samples
{
"id": "8d9a7125-805f-40f3-a405-bc89765db996",
"name": "Grocery website",
"type": "online",
"details": {
"domain": "groceries.example.com"
}
}Update a location
Update details of a specific location, based on its ID.
Only the fields provided in the request will be updated. Any omitted fields will retain their current values.
The value of the location's type parameter cannot be updated.
Request
Response
Location updated
curl -X PATCH "https://merchant.revolut.com/api/locations/123e4567-e89b-12d3-a456-426614174000" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <yourSecretApiKey>" \
-d '{
"name": "Cars website - Name update",
"details": {
"domain": "cars.example.com"
}
}'Authorization
apiKeyAuthorizationEach Merchant API request must contain an authorization header in the following format:
'Authorization: Bearer <yourSecretApiKey>'To use this API, you need to generate API keys from your Revolut Business account. The Secret key is used in the authorization header for all server calls, while the Public key is provided with payment methods at checkout.
For detailed instructions on generating your API keys, see: Generate API keys.
Request body samples
{
"name": "Cars website - Name update",
"details": {
"domain": "cars.example.com"
}
}Response body samples
{
"id": "8d9a7125-805f-40f3-a405-bc89765db996",
"name": "Cars website - Name update",
"type": "online",
"details": {
"domain": "cars.example.com"
}
}Delete a location
Delete a specific location, based on its ID.
Request
Response
Location deleted
curl -X DELETE "https://merchant.revolut.com/api/locations/123e4567-e89b-12d3-a456-426614174000" \
-H "Authorization: Bearer <yourSecretApiKey>"Authorization
apiKeyAuthorizationEach Merchant API request must contain an authorization header in the following format:
'Authorization: Bearer <yourSecretApiKey>'To use this API, you need to generate API keys from your Revolut Business account. The Secret key is used in the authorization header for all server calls, while the Public key is provided with payment methods at checkout.
For detailed instructions on generating your API keys, see: Generate API keys.
Response body samples
Terminals
Operations for managing Revolut Terminal devices and push payment integrations with Point of Sale (POS) systems.
The Terminals API enables POS software providers to integrate with Revolut Terminal devices for accepting in-person payments through a push payments model. This server-to-server integration allows your POS system to:
- Discover available terminals at specific locations
- Push payment requests to physical terminal devices
- Track payment intent and payment status in real-time
- Cancel pending payment requests when needed
Push payments workflow
- Terminal discovery: Use the Retrieve terminal list endpoint to find available terminals at a location (filtered by
operation_mode=pos) - Payment intent creation: Push a payment request to a specific terminal using Create a payment intent
- Status tracking: Poll the payment intent status until completion using Retrieve a payment intent endpoint
- Payment confirmation: Once the payment intent reaches
completedstate, retrieve the final payment status using the returnedpayment_id
For detailed implementation guidance, see: Push payments to Revolut Terminal.
Retrieve terminal list
Retrieve a list of Revolut Terminal devices available to the merchant.
This endpoint is primarily used for push payments to Revolut Terminal integration, allowing POS systems to discover available terminals at a specific location and in the correct operation mode.
For push payments integration, use the operation_mode=pos query parameter to filter only terminals in Pay at Counter mode that are ready to receive payment intents.
For more information about integration, see: Push payments to Revolut Terminal.
Request
Response
OK
curl -X GET "https://merchant.revolut.com/api/terminals?operation_mode=pos&location_id=123e4567-e89b-12d3-a456-426614174000" \
-H "Authorization: Bearer <yourSecretApiKey>" \
-H "Revolut-Api-Version: 2023-09-01"Authorization
apiKeyAuthorizationEach Merchant API request must contain an authorization header in the following format:
'Authorization: Bearer <yourSecretApiKey>'To use this API, you need to generate API keys from your Revolut Business account. The Secret key is used in the authorization header for all server calls, while the Public key is provided with payment methods at checkout.
For detailed instructions on generating your API keys, see: Generate API keys.
Response body samples
{
"terminals": [
{
"id": "0e53f673-7705-473a-a263-89a3e7647c3d",
"name": "Terminal 1",
"type": "newland_n950",
"serial_number": "RT-00123456",
"battery_level": 85,
"online": true,
"last_online_at": "2025-01-15T14:30:00Z"
},
{
"id": "a7b2c8d1-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
"name": "Terminal 2",
"type": "newland_n950",
"serial_number": "RT-00123457",
"battery_level": 92,
"online": true,
"last_online_at": "2025-01-15T14:32:00Z"
}
]
}Payment intents
Operations for managing payment intents in the push payments to Revolut Terminal flow.
A payment intent represents the intention to complete payment for a specific order on a specific Revolut Terminal device. Payment intents are the mechanism that links orders created via the Merchant API with physical terminal devices in Pay at Counter mode.
What is a payment intent?
When you create a payment intent, you're pushing a payment request from your POS system to a Revolut Terminal. The payment intent:
- Links an order to a specific terminal device
- Triggers the payment request to appear on the terminal screen
- Tracks the customer's interaction with the terminal (pending → processing → completed)
- Provides a
payment_idwhen completed, which you use to retrieve the final payment status
Payment intent lifecycle
- Create: Push a payment intent to a terminal by creating a payment intent
- Track: Poll the payment intent status by retrieving payment intent details until it reaches a final state
- Complete: When state is
completed, extract thepayment_idand retrieve the final payment status - Cancel (optional): Cancel pending payment intents using Cancel a payment intent
Important notes
- A payment intent reaching
completedstate means the checkout process finished on the terminal, but it does not guarantee the payment succeeded - You must check the actual payment status using the
payment_idreturned in the completed payment intent - Payment status can be
captured/completed(successful),declined(card rejected),failed(technical error), orcancelled
For the complete push payments integration guide, see: Push payments to Revolut Terminal.
Create a payment intent
Create a payment intent to push a payment request to a specific Revolut Terminal device.
This endpoint is used in push payments to Revolut Terminal integration, where a POS system sends payment requests to physical terminal devices. The terminal must be in Pay at Counter mode and assigned to the same location as the order.
Requirements:
- Order must be created with
channel: "pos"and include alocation_id - Terminal must be online, in
posoperation mode, and assigned to the same location - Amount must match the order amount
What happens next:
- The payment request appears on the Revolut Terminal screen
- Customer presents their card or device to complete payment
- You should poll the payment intent status until it reaches a final state (
completed,cancelled, orfailed) - When the payment intent reaches
completedstate, use the returnedpayment_idto retrieve the final payment status
For the complete push payments flow, see: Push payments to Revolut Terminal.
Request
Response
Payment intent created
curl -X POST "https://merchant.revolut.com/api/orders/123e4567-e89b-12d3-a456-426614174000/payment-intents" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <yourSecretApiKey>" \
-H "Revolut-Api-Version: 2023-09-01" \
-d '{
"amount": 2500,
"terminal_id": "0e53f673-7705-473a-a263-89a3e7647c3d"
}'Authorization
apiKeyAuthorizationEach Merchant API request must contain an authorization header in the following format:
'Authorization: Bearer <yourSecretApiKey>'To use this API, you need to generate API keys from your Revolut Business account. The Secret key is used in the authorization header for all server calls, while the Public key is provided with payment methods at checkout.
For detailed instructions on generating your API keys, see: Generate API keys.
Request body samples
{
"amount": 2500,
"terminal_id": "0e53f673-7705-473a-a263-89a3e7647c3d"
}Response body samples
{
"id": "b4d58add-b3fe-40e4-a70a-8c78df977888",
"state": "pending",
"order_id": "5c9fc54e-11b4-4f7f-8686-4a64d4d20db4",
"amount": 2500,
"currency": "GBP"
}Retrieve a payment intent
Retrieve the current state and details of a payment intent.
This endpoint is used to poll the payment intent status after pushing a payment request to a Revolut Terminal. You should poll this endpoint repeatedly until the payment intent reaches a final state.
Payment intent states:
| State | Description |
|---|---|
pending | Payment intent created and sent to terminal, customer has not yet started interacting |
processing | Customer is actively interacting with the terminal (e.g., inserting card, entering PIN) |
completed | Payment authorisation is complete, response includes a payment_id that you should use to retrieve the final payment status |
cancelled | Payment intent was cancelled (by your system or by the customer on the terminal) |
failed | Payment intent failed due to technical issues (e.g., timeout, terminal became unavailable) |
- Poll every second while the state is
pendingorprocessing - Set a reasonable timeout (e.g., 60 seconds) to handle cases where the customer abandons the payment
For the complete push payments flow, see: Push payments to Revolut Terminal.
Request
Response
OK
curl -X GET "https://merchant.revolut.com/api/payment-intents/123e4567-e89b-12d3-a456-426614174000" \
-H "Authorization: Bearer <yourSecretApiKey>" \
-H "Revolut-Api-Version: 2023-09-01"Authorization
apiKeyAuthorizationEach Merchant API request must contain an authorization header in the following format:
'Authorization: Bearer <yourSecretApiKey>'To use this API, you need to generate API keys from your Revolut Business account. The Secret key is used in the authorization header for all server calls, while the Public key is provided with payment methods at checkout.
For detailed instructions on generating your API keys, see: Generate API keys.
Response body samples
{
"id": "b4d58add-b3fe-40e4-a70a-8c78df977888",
"state": "pending",
"order_id": "5c9fc54e-11b4-4f7f-8686-4a64d4d20db4",
"amount": 2500,
"currency": "GBP"
}Cancel a payment intent
Cancel a payment intent while it's still in pending state, before the customer has completed the payment.
This is useful if the customer changes their mind or if there's an issue with the order before payment is completed.
Requirements:
- Payment intent must be in
pendingstate - Cannot cancel payment intents that are already
completed,cancelled, orfailed
For the complete push payments flow, see: Push payments to Revolut Terminal.
Request
Response
Payment intent cancelled
curl -X POST "https://merchant.revolut.com/api/payment-intents/123e4567-e89b-12d3-a456-426614174000/cancel" \
-H "Authorization: Bearer <yourSecretApiKey>" \
-H "Revolut-Api-Version: 2023-09-01"Authorization
apiKeyAuthorizationEach Merchant API request must contain an authorization header in the following format:
'Authorization: Bearer <yourSecretApiKey>'To use this API, you need to generate API keys from your Revolut Business account. The Secret key is used in the authorization header for all server calls, while the Public key is provided with payment methods at checkout.
For detailed instructions on generating your API keys, see: Generate API keys.
Response body samples
{
"id": "b4d58add-b3fe-40e4-a70a-8c78df977888",
"state": "cancelled",
"terminal_id": "0e53f673-7705-473a-a263-89a3e7647c3d",
"order_id": "5c9fc54e-11b4-4f7f-8686-4a64d4d20db4",
"amount": 2500,
"currency": "GBP",
"created_at": "2025-01-15T11:01:00Z",
"updated_at": "2025-01-15T11:01:45Z"
}Apple Pay merchant registration
Operations for managing a merchant's domain registration and configuration with Apple for integration of Apple Pay via Revolut.
This includes initiating domain validation with Apple, a necessary step for merchants to offer Apple Pay as a payment method on their websites or apps.
These endpoints interact with Apple's Apple Pay Web Merchant Registration services.
Register domain for Apple Pay
Register your website's domain to accept payments via Apple Pay.
Before you call this endpoint, make sure that you have completed the following steps:
- Download the latest domain validation file.
- Upload the domain validation file to your website in the following folder
/.well-known/. For example, if your website isexample.com, the file should be available onexample.com/.well-known/apple-developer-merchantid-domain-association, whereapple-developer-merchantid-domain-associationindicates the name of the file.
Request
Response
Domain registered successfully
curl -X POST "https://merchant.revolut.com/api/apple-pay/domains/register" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <yourSecretApiKey>" \
-d '{
"domain": "revolut.com"
}'Authorization
apiKeyAuthorizationEach Merchant API request must contain an authorization header in the following format:
'Authorization: Bearer <yourSecretApiKey>'To use this API, you need to generate API keys from your Revolut Business account. The Secret key is used in the authorization header for all server calls, while the Public key is provided with payment methods at checkout.
For detailed instructions on generating your API keys, see: Generate API keys.
Request body samples
{
"domain": "revolut.com"
}Response body samples
Unregister domain for Apple Pay
Unregister your website from Apple Pay's registered domains.
Request
Response
Domain ungistered successfully
curl -X POST "https://merchant.revolut.com/api/apple-pay/domains/unregister" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <yourSecretApiKey>" \
-H "Revolut-Api-Version: 2023-09-01" \
-d '{
"domain": "revolut.com",
"reason": "Unregister due to domain change."
}'Authorization
apiKeyAuthorizationEach Merchant API request must contain an authorization header in the following format:
'Authorization: Bearer <yourSecretApiKey>'To use this API, you need to generate API keys from your Revolut Business account. The Secret key is used in the authorization header for all server calls, while the Public key is provided with payment methods at checkout.
For detailed instructions on generating your API keys, see: Generate API keys.
Request body samples
{
"domain": "revolut.com",
"reason": "Unregister due to domain change."
}Response body samples
Other
Other operations that can be done with the Merchant API.
Register address validation endpoint for Fast checkout
Use this endpoint to register a URL where Revolut can send shipping address(es) from a Revolut Pay customer for validation during the Fast checkout process.
Revolut Pay can support Fast checkout for delivering goods. Once your customer selects a shipping address, Revolut needs to validate if the merchant (or their shipping partner) delivers to the address provided. This is done by contacting the merchant's backend and asking for such validation and information.
In order for your backend to support Fast checkout, you need to:
- Register an URL to handle address validation
- Validate the shipping address sent to your backend
- Respond with a JSON object containing the result of the validation
Additionally, Revolut Pay can support multiple webhooks if you have multiple stores. For more information, see:
To set up a webhook for tracking order completion, failure, error, etc. events, use the Webhooks endpoints.
Request
Response
OK
curl -X POST "https://merchant.revolut.com/api/synchronous-webhooks" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <yourSecretApiKey>" \
-d '{
"event_type": "fast_checkout.validate_address",
"url": "https://backend.example.com/webhooks/validate-address"
}'Authorization
apiKeyAuthorizationEach Merchant API request must contain an authorization header in the following format:
'Authorization: Bearer <yourSecretApiKey>'To use this API, you need to generate API keys from your Revolut Business account. The Secret key is used in the authorization header for all server calls, while the Public key is provided with payment methods at checkout.
For detailed instructions on generating your API keys, see: Generate API keys.
Request body samples
{
"event_type": "fast_checkout.validate_address",
"url": "https://backend.example.com/webhooks/validate-address"
}Response body samples
{
"id": "f6abc4df-eb48-417c-8e75-f7c6d7ad394f",
"signing_key": "swsk_y5z3LEHYZ9ndote3qegzWD6uL4t1lfp1",
"url": "https://backend.example.com/webhooks/validate-address",
"event_type": "fast_checkout.validate_address"
}Retrieve a synchronous webhook list
Retrieve a list of synchronous webhook objects.
You can use this endpoint to see your different address validation endpoints registered to different locations.
For more information about locations, see: Merchant API: Locations.
Request
Response
Synchronous webhook list returned
curl -X GET "https://merchant.revolut.com/api/synchronous-webhooks" \
-H "Authorization: Bearer <yourSecretApiKey>"Authorization
apiKeyAuthorizationEach Merchant API request must contain an authorization header in the following format:
'Authorization: Bearer <yourSecretApiKey>'To use this API, you need to generate API keys from your Revolut Business account. The Secret key is used in the authorization header for all server calls, while the Public key is provided with payment methods at checkout.
For detailed instructions on generating your API keys, see: Generate API keys.
Response body samples
[
{
"id": "f6abc4df-eb48-417c-8e75-f7c6d7ad394f",
"signing_key": "swsk_y5z3LEHYZ9ndote3qegzWD6uL4t1lfp1",
"url": "https://example.com/webhooks/validate-address",
"event_type": "fast_checkout.validate_address"
},
{
"id": "5c08dcc1-cd60-4b7d-a255-e42d24d7365c",
"signing_key": "swsk_VsuFcq6FIpa9gOWUu0n2WxiCbsDHIJlN",
"url": "https://groceries.example.com/webhooks/validate-address",
"event_type": "fast_checkout.validate_address",
"location_id": "b0ebede4-5cbc-4951-977f-70329faa8769"
},
{
"id": "dbebe6f8-4c47-4176-a94f-576d76e1d0b6",
"signing_key": "swsk_0TKYlzoakBgGGVvojCiRRqInMD1ufLZn",
"url": "https://clothes.example.com/webhooks/validate-address",
"event_type": "fast_checkout.validate_address",
"location_id": "6ebd3d2b-7a51-42e4-84f4-3c513621edd3"
}
]Delete a synchronous webhook
Delete a specific synchronous webhook registration, based on its ID.
Request
Response
Synchronous webhook deleted
curl -X DELETE "https://merchant.revolut.com/api/synchronous-webhooks/123e4567-e89b-12d3-a456-426614174000" \
-H "Authorization: Bearer <yourSecretApiKey>"Authorization
apiKeyAuthorizationEach Merchant API request must contain an authorization header in the following format:
'Authorization: Bearer <yourSecretApiKey>'To use this API, you need to generate API keys from your Revolut Business account. The Secret key is used in the authorization header for all server calls, while the Public key is provided with payment methods at checkout.
For detailed instructions on generating your API keys, see: Generate API keys.