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
- 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: 2023-09-01'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 (Deprecated)deprecated
Create an Order object.
Request
Response
Order created
curl -X POST "https://merchant.revolut.com/api/1.0/orders" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <yourSecretApiKey>" \
-d '{
"amount": 500,
"currency": "GBP",
"email": "example.customer@email.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
{
"amount": 500,
"currency": "GBP",
"email": "example.customer@email.com"
}Response body samples
{
"id": "64a3f721-a5c8-aeee-bfb5-d5a984d32e9c",
"public_id": "54933ff3-9fe5-49cd-8760-7d0e8c3ec198",
"type": "PAYMENT",
"state": "PENDING",
"created_at": "2023-07-04T10:40:33.069624Z",
"updated_at": "2023-07-04T10:40:33.069624Z",
"capture_mode": "AUTOMATIC",
"customer_id": "51918dc4-c02c-49e4-9b8b-3f08c8b01248",
"email": "example.customer@email.com",
"order_amount": {
"value": 500,
"currency": "GBP"
},
"order_outstanding_amount": {
"value": 500,
"currency": "GBP"
},
"metadata": {},
"checkout_url": "https://business.revolut.com/payment-link/h2B9Dow-wZhUkz_zn-VJzQ"
}Retrieve an order list (Deprecated)deprecated
Retrieve all the orders that you've created. 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:
|
The response contains an array of simplified Order objects. To get the full details of an Order object, use the Retrieve an order endpoint.
Request
Response
OK
curl -X GET "https://merchant.revolut.com/api/1.0/orders?limit=100&created_before=2024-01-01T00%3A00%3A00Z&from_created_date=2024-01-01T00%3A00%3A00Z&to_created_date=2024-01-01T00%3A00%3A00Z&customer_id=123e4567-e89b-12d3-a456-426614174000&email=user%40example.com&merchant_order_ext_ref=string&state=%5B%5D" \
-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": "f0d685f4-07ab-4eff-ba80-5811303c607d",
"type": "PAYMENT",
"state": "PENDING",
"created_at": "2021-02-10T18:17:37.959383Z",
"updated_at": "2021-02-10T18:17:37.959383Z",
"order_amount": {
"value": 35000,
"currency": "GBP"
},
"order_outstanding_amount": {
"value": 35000,
"currency": "GBP"
}
},
{
"id": "feca684a-b9ea-4033-9bc4-b9e6ac12ada6",
"type": "PAYMENT",
"state": "COMPLETED",
"created_at": "2021-02-10T16:59:23.642673Z",
"updated_at": "2021-02-10T16:59:50.886826Z",
"completed_at": "2021-02-10T16:59:50.886826Z",
"settlement_currency": "USD",
"email": "sally.gibson@lloydsbank.co.uk",
"order_amount": {
"value": 1000,
"currency": "GBP"
},
"order_outstanding_amount": {
"value": 0,
"currency": "GBP"
}
},
{
"id": "f3c5e3f1-f73a-4853-a9e3-b0261301c66a",
"type": "PAYMENT",
"state": "COMPLETED",
"created_at": "2021-02-10T16:58:47.507560Z",
"updated_at": "2021-02-10T16:59:52.847017Z",
"completed_at": "2021-02-10T16:59:52.847017Z",
"description": "URBAN 'Panther' Watch by José Almeida",
"capture_mode": "AUTOMATIC",
"merchant_order_ext_ref": "testorder123",
"customer_id": "31345442-3d03-4c4b-8354-3bdaf0ca9600",
"email": "someothermail@gmail.com",
"order_amount": {
"value": 777,
"currency": "GBP"
},
"order_outstanding_amount": {
"value": 0,
"currency": "GBP"
}
}
]Retrieve an order (Deprecated)deprecated
Retrieve the details of an order that has been created. Provide the unique order ID, and the corresponding order information is returned.
Request
Response
OK
curl -X GET "https://merchant.revolut.com/api/1.0/orders/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": "7c97ce7e-a7e4-4ff9-b3ca-9f988b0ba5e0",
"public_id": "fecaafa0-c230-44e9-a24e-7005e82e03f8",
"type": "PAYMENT",
"state": "COMPLETED",
"created_at": "2021-01-14T18:37:06.055371Z",
"updated_at": "2021-01-14T18:38:04.115204Z",
"completed_at": "2021-01-14T18:38:39.476986Z",
"description": "Testing Orders",
"capture_mode": "MANUAL",
"settlement_currency": "EUR",
"merchant_order_ext_ref": "testorder123",
"customer_id": "56db1367-2494-4a35-8254-c23929f8e5e1",
"email": "test@revolut.com",
"phone": "+447123456789",
"order_amount": {
"value": 50,
"currency": "GBP"
},
"order_outstanding_amount": {
"value": 0,
"currency": "GBP"
},
"refunded_amount": {
"value": 30,
"currency": "GBP"
},
"shipping_address": {
"street_line_1": "7 Westferry Circus",
"street_line_2": "Revolut",
"city": "London",
"country_code": "GB",
"postcode": "E14 4HD"
},
"payments": [
{
"id": "7c97ce7e-a7e4-4ff9-b3ca-absgdjwuio12",
"state": "COMPLETED",
"created_at": "2021-01-14T18:37:48.069092Z",
"updated_at": "2021-01-14T18:38:39.476986Z",
"token": "3cba558e-f465-4688-b5c4-94673508ece5",
"amount": {
"value": 50,
"currency": "GBP"
},
"settled_amount": {
"value": 67,
"currency": "EUR"
},
"payment_method": {
"type": "CARD",
"card": {
"card_brand": "VISA",
"funding": "CREDIT",
"card_country": "GB",
"card_bin": "459664",
"card_last_four": "6376",
"card_expiry": "03/2025",
"cardholder_name": "John Doe",
"checks": {
"three_ds": {
"state": "VERIFIED",
"version": 2
},
"cvv_verification": "MATCH",
"address": "NOT_MATCH",
"postcode": "MATCH",
"cardholder": "N_A"
}
}
},
"billing_address": {
"street_line_1": "7 Westferry Circus",
"street_line_2": "Revolut",
"city": "London",
"country_code": "GB",
"postcode": "E14 4HD"
},
"risk_level": "LOW",
"fees": [
{
"type": "ACQUIRING",
"amount": {
"value": 5,
"currency": "GBP"
}
}
]
}
],
"related": [
{
"id": "8af43efa-0d0c-4267-9abc-72679bc56859",
"type": "REFUND",
"state": "COMPLETED",
"amount": {
"value": 30,
"currency": "GBP"
}
}
]
}Update an order (Deprecated)deprecated
Update the details of an order.
You can update the details of an order based on the state of the order:
PENDINGstate: You can use all the following parameters to update the order.AUTHORISEDorCOMPLETEDstate: You can update only themerchant_order_ext_ref,description,metadataandshipping_addressparameters.PROCESSINGstate: You cannot update the order.
Request
Response
OK
curl -X PATCH "https://merchant.revolut.com/api/1.0/orders/123e4567-e89b-12d3-a456-426614174000" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <yourSecretApiKey>" \
-d '{
"amount": 100,
"currency": "EUR",
"merchant_order_ext_ref": "#2234"
}'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": "EUR",
"merchant_order_ext_ref": "#2234"
}Response body samples
{
"id": "5fd927ba-6f73-4a01-8e2b-fcd37fb629c5",
"public_id": "94a11217-6319-4d34-8dae-a2b80b953adb",
"type": "PAYMENT",
"state": "PENDING",
"created_at": "2020-10-15T07:46:40.648108Z",
"updated_at": "2020-10-15T07:46:40.648108Z",
"order_amount": {
"value": 100,
"currency": "EUR"
},
"merchant_order_ext_ref": "#2234",
"email": "johndoe001@gmail.com",
"checkout_url": "https://business.revolut.com/payment-link/uLHGQVGNx_ZRDV14z5VFIA"
}Capture an order (Deprecated)
Capture the funds of an existing, uncaptured order. When the payment for an order is authorised, the order is captured and sent to the processing stage.
When you create an order, you can choose one of the following capture modes:
AUTOMATIC: The order is captured automatically after payment authorisation, so you don't need to take any action then.MANUAL: The order is not captured automatically and stays inAUTHORISEDstate. You must manually capture the order later using one of the following methods:- Web UI: Complete the following steps:
- Log in to your Revolut Business portal.
- Navigate to the Merchant tab on the dashboard, and click the See all button in the Transactions section.
- Select an uncaptured payment, and click Capture.
- Endpoint: Use the
/captureendpoint.
- Web UI: Complete the following steps:
Optionally, you can send a fraction of the full amount in the capture request to do a partial capture. You can only capture an order once. The amount that isn't captured will be voided.
Orders stay uncaptured for 7 days. After this period, the funds are returned to the customer's original payment method.
Request
Response
OK
curl -X POST "https://merchant.revolut.com/api/1.0/orders/123e4567-e89b-12d3-a456-426614174000/capture" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <yourSecretApiKey>" \
-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": "7c97ce7e-a7e4-4ff9-b3ca-9f988b0ba5e0",
"public_id": "fecaafa0-c230-44e9-a24e-7005e82e03f8",
"type": "PAYMENT",
"state": "COMPLETED",
"created_at": "2021-01-14T18:37:06.055371Z",
"updated_at": "2021-01-14T18:38:04.115204Z",
"completed_at": "2021-01-14T18:38:39.476986Z",
"description": "Testing Orders",
"capture_mode": "MANUAL",
"settlement_currency": "EUR",
"merchant_order_ext_ref": "testorder123",
"customer_id": "56db1367-2494-4a35-8254-c23929f8e5e1",
"email": "test@revolut.com",
"phone": "+447123456789",
"order_amount": {
"value": 50,
"currency": "GBP"
},
"order_outstanding_amount": {
"value": 0,
"currency": "GBP"
},
"shipping_address": {
"street_line_1": "7 Westferry Circus",
"street_line_2": "Revolut",
"city": "London",
"country_code": "GB",
"postcode": "E14 4HD"
},
"payments": [
{
"id": "7c97ce7e-a7e4-4ff9-b3ca-absgdjwuio12",
"state": "COMPLETED",
"created_at": "2021-01-14T18:37:48.069092Z",
"updated_at": "2021-01-14T18:38:39.476986Z",
"amount": {
"value": 50,
"currency": "GBP"
},
"settled_amount": {
"value": 67,
"currency": "EUR"
},
"payment_method": {
"type": "CARD",
"card": {
"card_brand": "VISA",
"funding": "CREDIT",
"card_country": "GB",
"card_bin": "459664",
"card_last_four": "6376",
"card_expiry": "03/2025",
"cardholder_name": "John Doe",
"checks": {
"cvv_verification": "MATCH",
"address": "NOT_MATCH",
"postcode": "MATCH",
"cardholder": "N_A"
}
}
},
"billing_address": {
"street_line_1": "7 Westferry Circus",
"street_line_2": "Revolut",
"city": "London",
"country_code": "GB",
"postcode": "E14 4HD"
},
"risk_level": "LOW",
"fees": [
{
"type": "ACQUIRING",
"amount": {
"value": 5,
"currency": "GBP"
}
}
]
}
]
}Cancel an order (Deprecated)
Cancel an existing uncaptured order.
You can only cancel an order that is in one of the following states:
- In the
AUTHORISEDstate, which means that thecapture_modeof an order is set toMANUALand the customer has made a successful payment. - In the
PENDINGstate, which means that it doesn't have any successful payment associated with it.
For more information about the order lifecycle, see: Order and payment lifecycle.
Request
Response
OK
curl -X POST "https://merchant.revolut.com/api/1.0/orders/123e4567-e89b-12d3-a456-426614174000/cancel" \
-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": "7c97ce7e-a7e4-4ff9-b3ca-9f988b0ba5e0",
"public_id": "fecaafa0-c230-44e9-a24e-7005e82e03f8",
"type": "PAYMENT",
"state": "CANCELLED",
"created_at": "2021-01-14T18:37:06.055371Z",
"updated_at": "2021-01-14T18:38:04.115204Z",
"completed_at": "2021-01-14T18:38:39.476986Z",
"description": "Testing Orders",
"capture_mode": "MANUAL",
"settlement_currency": "EUR",
"merchant_order_ext_ref": "testorder123",
"customer_id": "56db1367-2494-4a35-8254-c23929f8e5e1",
"email": "test@revolut.com",
"phone": "+447123456789",
"order_amount": {
"value": 50,
"currency": "GBP"
},
"order_outstanding_amount": {
"value": 0,
"currency": "GBP"
},
"shipping_address": {
"street_line_1": "7 Westferry Circus",
"street_line_2": "Revolut",
"city": "London",
"country_code": "GB",
"postcode": "E14 4HD"
},
"payments": [
{
"id": "7c97ce7e-a7e4-4ff9-b3ca-absgdjwuio12",
"state": "CANCELLED",
"created_at": "2021-01-14T18:37:48.069092Z",
"updated_at": "2021-01-14T18:38:39.476986Z",
"amount": {
"value": 50,
"currency": "GBP"
},
"payment_method": {
"type": "CARD",
"card": {
"card_brand": "VISA",
"funding": "CREDIT",
"card_country": "GB",
"card_bin": "459664",
"card_last_four": "6376",
"card_expiry": "03/2025",
"cardholder_name": "John Doe",
"checks": {
"cvv_verification": "MATCH",
"address": "NOT_MATCH",
"postcode": "MATCH",
"cardholder": "N_A"
}
}
},
"billing_address": {
"street_line_1": "7 Westferry Circus",
"street_line_2": "Revolut",
"city": "London",
"country_code": "GB",
"postcode": "E14 4HD"
},
"risk_level": "LOW"
}
]
}Refund an order (Deprecated)
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.
Operation details
- The refund operation generates a new order with
type: REFUND. This new order represents a full or partial refund of the original amount paid. - Refunds can only be initiated for orders that are in the
COMPLETEDstate. Orders in any other state are not eligible for refunds to ensure transaction integrity and to prevent errors.
- Ensure that the order to be refunded is confirmed as
COMPLETEDbefore attempting a refund operation. - Consider using the
Idempotency-Keyheader to make the refund operation idempotent, preventing duplicate refund processing in cases of multiple submissions.
Request
Response
OK
curl -X POST "https://merchant.revolut.com/api/1.0/orders/123e4567-e89b-12d3-a456-426614174000/refund" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <yourSecretApiKey>" \
-H "Idempotency-Key: string" \
-d '{
"amount": 40,
"description": "Refund for damaged goods"
}'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": 40,
"description": "Refund for damaged goods"
}Response body samples
{
"id": "6a1353a8-3054-40ee-ab39-97a11e4c5f2a",
"type": "REFUND",
"state": "COMPLETED",
"created_at": "2020-05-12T14:23:11.046526Z",
"updated_at": "2020-05-12T14:23:11.046526Z",
"completed_at": "2020-05-12T14:23:11.046526Z",
"order_amount": {
"value": 40,
"currency": "GBP"
},
"email": "customer@gmail.com",
"full_name": "Example Customer",
"related": [
{
"id": "4695b666-45d0-4f15-ad10-e66a84c914bf",
"type": "PAYMENT",
"amount": {
"value": 100,
"currency": "GBP"
}
}
]
}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 (Deprecated)deprecated
Create a customer that has the information in the body of the request.
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.
Request
Response
Created
curl -X POST "https://merchant.revolut.com/api/1.0/customers" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <yourSecretApiKey>" \
-d '{
"full_name": "Example Customer",
"business_name": "Example Business",
"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",
"business_name": "Example Business",
"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",
"business_name": "Example Business",
"email": "example.customer@example.com",
"phone": "+441234567890",
"date_of_birth": "1990-01-01",
"created_at": "2020-06-24T12:03:39.979397Z",
"updated_at": "2020-06-24T12:03:39.979397Z"
}Retrieve a customer list (Deprecated)deprecated
Get a list of all your customers.
Request
Response
OK
curl -X GET "https://merchant.revolut.com/api/1.0/customers?limit=100&page=0" \
-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": "9dfb8491-bfb0-4420-ad63-0fa7bdd3dffb",
"full_name": "First Customer",
"email": "first.customer@example.com",
"date_of_birth": "1990-01-01",
"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",
"business_name": "Second Business",
"email": "second.customer@example.com",
"phone": "+441234567890",
"created_at": "2020-06-24T12:03:39.979397Z",
"updated_at": "2020-06-25T10:03:39.134417Z"
},
{
"id": "014f0ad6-c45b-4d7d-83c6-80eea94fceac",
"full_name": "Third Customer",
"email": "third.customer@example.com",
"phone": "+441234567890",
"created_at": "2020-06-23T14:13:08.262336Z",
"updated_at": "2020-06-24T10:47:11.173027Z"
}
]Retrieve a customer (Deprecated)deprecated
Get the information about a specific customer, based on its ID.
Request
Response
OK
curl -X GET "https://merchant.revolut.com/api/1.0/customers/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": "6c7c97a8-cfc1-4cf3-8b38-26a74fdf1fae",
"full_name": "Example Customer",
"business_name": "Example Business",
"email": "example.customer@example.com",
"phone": "+441234567890",
"date_of_birth": "1990-01-01",
"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",
"method_details": {
"created_at": "2023-06-09T14:18:16.577888Z"
}
},
{
"id": "edef3ba4-60a0-4df3-8f12-e5fc858c2420",
"type": "CARD",
"saved_for": "CUSTOMER",
"method_details": {
"bin": "459765",
"last4": "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"
},
"created_at": "2023-03-24T14:15:22Z"
}
}
]
}Update a customer (Deprecated)deprecated
Update the attributes of a specific customer.
Request
Response
OK
curl -X PATCH "https://merchant.revolut.com/api/1.0/customers/123e4567-e89b-12d3-a456-426614174000" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <yourSecretApiKey>" \
-d '{
"email": "example.business@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": "example.business@example.com"
}Response body samples
{
"id": "6c7c97a8-cfc1-4cf3-8b38-26a74fdf1fae",
"full_name": "Example Customer",
"business_name": "Example Business",
"email": "example.business@example.com",
"phone": "+441234567890",
"date_of_birth": "1990-01-01",
"created_at": "2020-06-24T12:03:39.979397Z",
"updated_at": "2020-06-25T10:03:39.134417Z"
}Delete a customer (Deprecated)deprecated
Delete the profile of a specific customer.
Request
Response
No Content
curl -X DELETE "https://merchant.revolut.com/api/1.0/customers/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
Retrieve all payment methods of a customer (Deprecated)deprecated
Retrieve all the payment methods for a specific customer.
This can be useful in the following example cases:
- To show what 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/1.0/customers/123e4567-e89b-12d3-a456-426614174000/payment-methods?only_merchant=false" \
-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": "648334a8-9546-a983-a81a-efc6d5bdd0be",
"type": "REVOLUT_PAY",
"saved_for": "MERCHANT",
"method_details": {
"created_at": "2023-06-09T14:18:16.577888Z"
}
},
{
"id": "edef3ba4-60a0-4df3-8f12-e5fc858c2420",
"type": "CARD",
"saved_for": "CUSTOMER",
"method_details": {
"bin": "459678",
"last4": "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"
},
"created_at": "2023-03-24T14:15:22Z"
}
},
{
"id": "a04406c4-05be-498b-8207-cc1e02a9b3ca",
"type": "CARD",
"saved_for": "MERCHANT",
"method_details": {
"bin": "459885",
"last4": "7653",
"expiry_month": 12,
"expiry_year": 2021,
"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"
},
"created_at": "2023-03-24T14:15:22Z"
}
}
]Retrieve a customer's payment method (Deprecated)deprecated
Retrieve the information of a specific payment method that is saved.
Request
Response
OK
curl -X GET "https://merchant.revolut.com/api/1.0/customers/123e4567-e89b-12d3-a456-426614174000/payment-methods/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": "edef3ba4-60a0-4df3-8f12-e5fc858c2420",
"type": "CARD",
"saved_for": "CUSTOMER",
"method_details": {
"bin": "459678",
"last4": "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"
},
"created_at": "2023-03-24T14:15:22Z"
}
}Update a customer's payment method (Deprecated)deprecated
When you use this request to update a customer's payment method, the payment method can't be used for merchant initiated transactions (MIT) any more. This payment method can be used only when the customer is on the checkout page.
For more information about the limitations introduced by this parameter, see:
Request
Response
OK
curl -X PATCH "https://merchant.revolut.com/api/1.0/customers/123e4567-e89b-12d3-a456-426614174000/payment-methods/123e4567-e89b-12d3-a456-426614174000" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <yourSecretApiKey>" \
-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": "edef3ba4-60a0-4df3-8f12-e5fc858c2420",
"type": "CARD",
"saved_for": "CUSTOMER",
"method_details": {
"bin": "459678",
"last4": "6896",
"expiry_month": 3,
"expiry_year": 2025,
"cardholder_name": "John Doe",
"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"
},
"created_at": "2023-03-24T14:15:22Z"
}
}Delete a customer's payment method (Deprecated)deprecated
Delete a specific payment method. The payment method is completely deleted from the customer payment methods.
To reuse the payment method that is deleted, direct your customer to the checkout page and save the card details again.
Request
Response
No Content
curl -X DELETE "https://merchant.revolut.com/api/1.0/customers/123e4567-e89b-12d3-a456-426614174000/payment-methods/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
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>"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": "64905d4b-a205-aac3-a5ef-dab978b1b7ee",
"order_id": "64905d0f-3f95-a2ac-91ea-57c77f9dbe69",
"state": "completed",
"payment_method": {
"type": "revolut_pay",
"subtype": "revolut_account",
"id": "648334a8-9546-a983-a81a-efc6d5bdd0be"
}
}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 (Deprecated)deprecated
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/1.0/webhooks" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <yourSecretApiKey>" \
-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 (Deprecated)deprecated
Get a list of webhooks that you are currently subscribed to.
Request
Response
OK
curl -X GET "https://merchant.revolut.com/api/1.0/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": "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": "4a31c8a3-8037-4260-a09e-090475d37025",
"url": "https://developer.revolut.com/webhooks",
"events": [
"ORDER_AUTHORISED"
]
},
{
"id": "5d815041-5753-46bc-aebc-315fe99f30aa",
"url": "https://example.com/webhooks",
"events": [
"ORDER_COMPLETED",
"ORDER_AUTHORISED"
]
}
]Retrieve a webhook (Deprecated)deprecated
Get the details of a specific webhook.
Request
Response
OK
curl -X GET "https://merchant.revolut.com/api/1.0/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.
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 (Deprecated)deprecated
Update the details of a specific webhook.
Request
Response
OK
curl -X PUT "https://merchant.revolut.com/api/1.0/webhooks/123e4567-e89b-12d3-a456-426614174000" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <yourSecretApiKey>" \
-d '{
"url": "http://business.revolut.com",
"events": [
"ORDER_COMPLETED"
]
}'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": "http://business.revolut.com",
"events": [
"ORDER_COMPLETED"
]
}Response body samples
{
"id": "c6b981f4-53b3-47d5-9b24-4f87af1160eb",
"url": "http://business.revolut.com",
"events": [
"ORDER_COMPLETED"
]
}Delete a webhook (Deprecated)deprecated
Delete a webhook so that events are not sent to the specified URL any more.
Request
Response
No Content
curl -X DELETE "https://merchant.revolut.com/api/1.0/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.
Response body samples
Rotate a webhook signing secret (Deprecated)deprecated
Rotate the signing secret for a specific webhook.
For more information, see Tutorials: Verify the payload signature.
Request
Response
OK
curl -X POST "https://merchant.revolut.com/api/1.0/webhooks/123e4567-e89b-12d3-a456-426614174000/rotate-signing-secret" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <yourSecretApiKey>" \
-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": "http://business.revolut.com",
"events": [
"ORDER_COMPLETED"
],
"signing_secret": "wsk_4jETWMz1g1b37gCONjNp84t2KSSIT6aG"
}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
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.