openapi: 3.1.1 info: title: Merchant API version: 2023-09-01 description: |- 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](/docs/api/merchant/2023-09-01#tag-orders) - [Customer management](/docs/api/merchant/2023-09-01#tag-customers) - [Payment management](/docs/api/merchant/2023-09-01#tag-payments) - [Reporting analytics](/docs/api/merchant/2023-09-01#tag-report-runs) - [Webhook management](/docs/api/merchant/2023-09-01#tag-webhooks) - [Location management](/docs/api/merchant/2023-09-01#tag-locations) ... and more. ### API versions :::warning 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' ``` :::info For more information, see: [API versions](/docs/guides/merchant/reference/versioning/api-versions) ::: ### Test the Merchant API You can test the Merchant API in Postman by forking this collection: [![View in Postman](https://run.pstmn.io/button.svg)](https://www.postman.com/revolut-api/workspace/revolut-developers/overview) contact: {} servers: - description: Production server (uses live data) url: https://merchant.revolut.com - description: Sandbox server (uses test data) url: https://sandbox-merchant.revolut.com security: - Api-Key: [] tags: - name: Orders description: >- 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](/docs/guides/merchant/reference/order-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. :::warning The [Create an order endpoint](/docs/api/merchant#create-order) 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](/docs/api/merchant#create-order). ::: - name: Customers description: |- 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](/docs/api/merchant#create-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](/docs/guides/merchant/optimise-checkout/save-payment-methods/charge-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. :::note 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. ::: - name: Payments description: >- 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. :::info For more information about the payment lifecycle, see: [Order and payment lifecycle](/docs/guides/merchant/reference/order-lifecycle). ::: - name: Payouts description: >- 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](/docs/api/merchant#tag-report-runs) that provide comprehensive breakdowns of all transactions contributing to the payout amounts. Payout information, including IDs, can be retrieved via the [Retrieve payout list](/docs/api/merchant#retrieve-payout-list) endpoint or from [webhook events related to payouts](/docs/api/merchant#create-webhook). - name: Report runs description: |- In addition to the CSV statements you can export via the [Revolut Business Dashboard](https://business.revolut.com/merchant/statement), 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](/docs/guides/merchant/monitor-and-observe/reports-reconciliation). - name: Webhooks description: |- 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`. :::note 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](/docs/guides/merchant/monitor-and-observe/webhooks/using-webhooks). :::info For more information about the order and payment lifecycle, see: [Order and payment lifecycle](/docs/guides/merchant/reference/order-lifecycle). ::: - name: Locations description: >- 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 1. Register an online location using the [Create a location](/docs/api/merchant#create-location) endpoint, setting the `type` to `online`. 1. Configure your custom processes on your backend for each registered location (e.g., grouping orders, custom pricing, etc.). 1. Send the `location_id` parameter in the request body during [order creation](/docs/api/merchant#create-order) to assign the order to a specific location. ### Physical locations 1. Register a physical location using the [Create a location](/docs/api/merchant#create-location) endpoint, setting the `type` to `physical`. 1. In case of Revolut POS, our system handles order creation including `location_id` to 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**](/docs/guides/merchant/optimise-checkout/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](/docs/api/merchant#register-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. - name: Terminals description: |- 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 1. **Terminal discovery:** Use the [Retrieve terminal list](/docs/api/merchant#retrieve-terminal-list) endpoint to find available terminals at a location (filtered by `operation_mode=pos`) 1. **Payment intent creation:** Push a payment request to a specific terminal using [Create a payment intent](/docs/api/merchant#create-payment-intent) 1. **Status tracking:** Poll the payment intent status until completion using [Retrieve a payment intent](/docs/api/merchant#retrieve-payment-intent) endpoint 1. **Payment confirmation:** Once the payment intent reaches `completed` state, [retrieve the final payment status](/docs/api/merchant#retrieve-payment-details) using the returned `payment_id` :::info For detailed implementation guidance, see: [Push payments to Revolut Terminal](/docs/guides/merchant/accept-payments/in-person-payments/terminal/push-payments). ::: - name: Payment intents description: |- 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_id` when completed, which you use to retrieve the final payment status ## Payment intent lifecycle 1. **Create:** Push a payment intent to a terminal by [creating a payment intent](/docs/api/merchant#create-payment-intent) 1. **Track:** Poll the payment intent status by [retrieving payment intent details](/docs/api/merchant#retrieve-payment-intent) until it reaches a final state 1. **Complete:** When state is `completed`, extract the `payment_id` and [retrieve the final payment status](/docs/api/merchant#retrieve-payment-details) 1. **Cancel (optional):** Cancel pending payment intents using [Cancel a payment intent](/docs/api/merchant#cancel-payment-intent) ## Important notes - A payment intent reaching `completed` state 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_id` returned in the completed payment intent - Payment status can be `captured`/`completed` (successful), `declined` (card rejected), `failed` (technical error), or `cancelled` :::info For the complete push payments integration guide, see: [Push payments to Revolut Terminal](/docs/guides/merchant/accept-payments/in-person-payments/terminal/push-payments). ::: - name: Apple Pay merchant registration description: |- 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](https://developer.apple.com/documentation/applepaywebmerchantregistrationapi). - name: Other description: Other operations that can be done with the Merchant API. paths: /api/orders: parameters: - $ref: "#/components/parameters/Authorization" - $ref: "#/components/parameters/Revolut-Api-Version" post: summary: Create an order operationId: createOrder description: >- 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 building on order creation. To learn more about how you can accept payments, see: - [Revolut Pay](/docs/guides/merchant/accept-payments/online-payments/revolut-pay/introduction) - [Card payments](/docs/guides/merchant/accept-payments/online-payments/card-payments/introduction) - [Apple Pay and Google Pay](/docs/guides/merchant/accept-payments/online-payments/apple-pay-google-pay/introduction) - [Pay by Bank](/docs/guides/merchant/accept-payments/online-payments/pay-by-bank/introduction) - [Revolut Checkout](/docs/guides/merchant/accept-payments/online-payments/revolut-checkout/introduction) - [Hosted Checkout Page](/docs/guides/merchant/accept-payments/online-payments/hosted-checkout-page/introduction)
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 | | ------- | --------------- | | 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` or `industry_data` with `type: lodging` | | Crypto merchants | `industry_data` with `type: crypto`; `customer.full_name`, `customer.date_of_birth` | | Financial institutions | `customer.full_name`, `customer.date_of_birth` | | Stored value / Wallets | `customer.full_name`, `customer.date_of_birth` | | Event ticket sellers | `industry_data` with `type: event` | | Marketplace merchants | `industry_data` with `type: marketplace` |
requestBody: content: application/json: schema: $ref: "#/components/schemas/Order-Creation-v2" examples: example_order_min: $ref: "#/components/examples/Req-Order-Min" example_order_additional: $ref: "#/components/examples/Req-Order-Additional" example_order_pre_auth: $ref: "#/components/examples/Req-Order-Pre-Auth" example_order_airline: $ref: "#/components/examples/Req-Order-Airline" example_order_car_rental: $ref: "#/components/examples/Req-Order-Car-Rental" example_order_crypto: $ref: "#/components/examples/Req-Order-Crypto" example_order_marketplace: $ref: "#/components/examples/Req-Order-Marketplace" example_order_event: $ref: "#/components/examples/Req-Order-Event" example_order_lodging: $ref: "#/components/examples/Req-Order-Lodging" responses: "201": description: Order created content: application/json: schema: $ref: "#/components/schemas/Order-v2" examples: example_order_min: $ref: "#/components/examples/Res-Order-Min" example_order_additional: $ref: "#/components/examples/Res-Order-Additional" example_order_pre_auth: $ref: "#/components/examples/Res-Order-Pre-Auth" example_order_airline: $ref: "#/components/examples/Res-Order-Airline" example_order_car_rental: $ref: "#/components/examples/Res-Order-Car-Rental" example_order_crypto: $ref: "#/components/examples/Res-Order-Crypto" example_order_marketplace: $ref: "#/components/examples/Res-Order-Marketplace" example_order_event: $ref: "#/components/examples/Res-Order-Event" example_order_lodging: $ref: "#/components/examples/Res-Order-Lodging" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/Error-v2" examples: default: value: code: bad_request message: Could not parse JSON timestamp: 1721049596461 headers: {} "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/Error-v2" examples: default: value: code: unauthenticated message: Authentication failed timestamp: 1721049596461 "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/Error-v2" tags: - Orders security: - Api-Key: [] /api/orders/{order_id}: parameters: - $ref: "#/components/parameters/Authorization" - $ref: "#/components/parameters/Revolut-Api-Version" - $ref: "#/components/parameters/Order-Id" get: summary: Retrieve an order operationId: retrieveOrder description: >- Retrieve the details of an order that has been created. Provide the unique order ID, and the corresponding order information is returned. responses: "200": description: Order retrieved content: application/json: schema: $ref: "#/components/schemas/Order-v2" examples: example_order_min: $ref: "#/components/examples/Res-Order-Min" example_order_additional: $ref: "#/components/examples/Res-Order-Additional" example_order_pre_auth: $ref: "#/components/examples/Res-Order-Pre-Auth" example_order_airline: $ref: "#/components/examples/Res-Order-Airline" example_order_car_rental: $ref: "#/components/examples/Res-Order-Car-Rental" example_order_crypto: $ref: "#/components/examples/Res-Order-Crypto" example_order_marketplace: $ref: "#/components/examples/Res-Order-Marketplace" example_order_event: $ref: "#/components/examples/Res-Order-Event" example_order_lodging: $ref: "#/components/examples/Res-Order-Lodging" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/Error-v2" examples: example-1: value: code: bad_request message: Could not parse JSON timestamp: 1601296792533 "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/Error-v2" examples: default: value: code: unauthenticated message: Authentication failed timestamp: 1721049596461 "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/Error-v2" examples: default: value: code: not_found message: Order with id abfa5bbd-a20c-4a0e-be66-30e733454518 was not found timestamp: 1721050063886 tags: - Orders security: - Api-Key: [] patch: summary: Update an order operationId: updateOrder description: |- 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. | :::info For more information about the order lifecycle, see: [Order and payment lifecycle](/docs/guides/merchant/reference/order-lifecycle). ::: requestBody: content: application/json: schema: $ref: "#/components/schemas/Order-Update-v2" examples: example_update_order: summary: Example order update value: 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" responses: "200": description: Order updated content: application/json: schema: $ref: "#/components/schemas/Order-v2" examples: example_order_updated: summary: Example order update response value: 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" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/Error-v2" examples: default: value: code: bad_request message: Could not parse JSON timestamp: 1721049596461 headers: {} "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/Error-v2" examples: default: value: code: unauthenticated message: Authentication failed timestamp: 1721049596461 "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/Error-v2" examples: default: value: code: not_found message: Order with id abfa5bbd-a20c-4a0e-be66-30e733454518 was not found timestamp: 1721050063886 "422": description: Unprocessable Entity content: application/json: schema: $ref: "#/components/schemas/Error-v2" examples: default: value: code: order_invalid_state message: Operation cannot be performed because order is in completed state and expected is [pending] timestamp: 1721049952145 tags: - Orders security: - Api-Key: [] /api/1.0/orders: parameters: - $ref: "#/components/parameters/Authorization" get: summary: Retrieve an order list operationId: retrieveOrderList description: >- 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](/docs/api/merchant#retrieve-order) endpoint. parameters: - schema: type: integer default: 100 minimum: 1 maximum: 1000 in: query name: limit description: The maximum number of orders returned per page. Used for **pagination**. - schema: type: string format: date-time in: query name: created_before description: >- Retrieve orders with a `created_date` < `created_before`. Used for **pagination**. Use the `created_date` of the last order returned in the previous response to get to the next page. The default value is the current date and time you are calling the endpoint. - schema: type: string format: date-time in: query name: from_created_date description: >- Retrieve all orders with a `created_date` ≥ `from_created_date`. Used for **filtering**. Use the [ISO date format](https://en.wikipedia.org/wiki/ISO_8601): `yyyy-MM-ddTHH:mm:ss[.SSSSSS]Z`. For example, `2021-02-10T16:59:50.886826Z`. - schema: type: string format: date-time in: query name: to_created_date description: >- Retrieve all orders with a `created_date` ≤ `to_created_date`. Used for **filtering**. Use the [ISO date format](https://en.wikipedia.org/wiki/ISO_8601): `yyyy-MM-ddTHH:mm:ss[.SSSSSS]Z`. For example, `2021-02-10T16:59:50.886826Z`. - schema: type: string format: uuid in: query name: customer_id description: Retrieve all orders that have this `customer_id` associated to them. Used for **filtering**. - schema: type: string format: email in: query name: email description: >- Retrieve all orders that have this `email` associated to them. Used for **filtering**. This parameter is case sensitive. - schema: type: string in: query name: merchant_order_ext_ref description: >- Merchant order ID for external reference. Use this field to filter and retrieve all the orders that have this ID. Used for **filtering**. This parameter is case sensitive. - schema: type: array items: type: string enum: - PENDING - PROCESSING - AUTHORISED - COMPLETED - CANCELLED - FAILED style: form explode: true in: query name: state description: |- Retrieve all orders with specific states. You can pass several states. Used for **filtering**. If multiple states are selected, for example `AUTHORISED` and `COMPLETED`, orders with either of the selected values are returned. See this example of such a request URL: ```curl https://merchant.revolut.com/api/1.0/orders?state=AUTHORISED&state=COMPLETED ``` The parameter is case sensitive. responses: "200": description: OK content: application/json: schema: type: array items: $ref: "#/components/schemas/Simplified-Order" examples: list_of_orders: summary: List of orders value: - 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 "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/Error" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/Error" security: - Api-Key: [] tags: - Orders /api/orders/{order_id}/capture: parameters: - $ref: "#/components/parameters/Authorization" - $ref: "#/components/parameters/Revolut-Api-Version" - $ref: "#/components/parameters/Order-Id" post: summary: Capture an order operationId: captureOrder description: |- 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. :::info For more information about the order and payment lifecycle, see: [Order and payment lifecycle](/docs/guides/merchant/reference/order-lifecycle). ::: ## Capture modes When you [create an order](/docs/api/merchant#create-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. | :::warning Uncaptured orders remain in `authorised` state **for 7 days**. If not captured within this period, the funds are returned to the customer's original payment method. ::: ### Manual capture To capture an order manually, use one of the following methods: | **Web UI** | **Merchant API** | | ---------- | ------------ | |
  1. Log in to your [Revolut Business portal](https://business.revolut.com).
  2. Navigate to the **Merchant** tab on the dashboard, and click the **See all** button in the **Transactions** section.
  3. Select an uncaptured payment, and click **Capture**.
| Use the `/capture` endpoint. | :::info For more information about manually capturing an order, see: [Authorise an amount to capture later](/docs/guides/merchant/operations/capture-and-settlement/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. :::warning 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 - `0` amount captures are not allowed - For partial captures, you can only resend the request with the initial amount ::: ## 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](/docs/api/merchant#retrieve-order) request, returning the current order state. - A subsequent request with a different capture amount returns an error. :::info Utilising the idempotent nature of this endpoint helps maintain data consistency and prevents duplicate processing of the same order. ::: requestBody: content: application/json: schema: $ref: "#/components/schemas/Order-Capture" examples: example_minimal: $ref: "#/components/examples/Req-Order-Capture-Min" responses: "200": description: Order captured content: application/json: schema: $ref: "#/components/schemas/Order-v2" examples: captured_order: summary: Captured order value: 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: [] 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 "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/Error-v2" examples: example-1: value: code: bad_request message: Could not parse JSON timestamp: 1601296792533 "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/Error-v2" examples: default: value: code: unauthenticated message: Authentication failed timestamp: 1721049596461 "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/Error-v2" examples: default: value: code: not_found message: Order with id abfa5bbd-a20c-4a0e-be66-30e733454518 was not found timestamp: 1721050063886 security: - Api-Key: [] tags: - Orders /api/orders/{order_id}/cancel: parameters: - $ref: "#/components/parameters/Authorization" - $ref: "#/components/parameters/Revolut-Api-Version-Optional" - $ref: "#/components/parameters/Order-Id" post: summary: Cancel an order operationId: cancelOrder description: >- 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. | :::info For more information about the order lifecycle, see: [Order and payment lifecycle](/docs/guides/merchant/reference/order-lifecycle). ::: responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/Order-v2" examples: example_order_min: $ref: "#/components/examples/Res-Order-Cancel-Min" example_order_additional: $ref: "#/components/examples/Res-Order-Cancel-Additional" example_order_airline: $ref: "#/components/examples/Res-Order-Cancel-Airline" example_order_crypto: $ref: "#/components/examples/Res-Order-Cancel-Crypto" example_order_marketplace: $ref: "#/components/examples/Res-Order-Cancel-Marketplace" example_order_event: $ref: "#/components/examples/Res-Order-Cancel-Event" example_order_lodging: $ref: "#/components/examples/Res-Order-Cancel-Lodging" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/Error-v2" examples: example-1: value: code: bad_request message: Could not parse JSON timestamp: 1601296792533 "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/Error-v2" examples: default: value: code: unauthenticated message: Authentication failed timestamp: 1721049596461 "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/Error-v2" examples: default: value: code: not_found message: Order with id abfa5bbd-a20c-4a0e-be66-30e733454518 was not found timestamp: 1721050063886 security: - Api-Key: [] tags: - Orders /api/1.0/orders/{order_id}/refund: parameters: - $ref: "#/components/parameters/Authorization" - $ref: "#/components/parameters/Idempotency-Key" - $ref: "#/components/parameters/Order-Id" post: summary: Refund an order (Deprecated) operationId: refundOrderDeprecated description: >- 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 `COMPLETED` state. Orders in any other state are not eligible for refunds to ensure transaction integrity and to prevent errors. :::note - Ensure that the order to be refunded is confirmed as `COMPLETED` before attempting a refund operation. - Consider using the `Idempotency-Key` header to make the refund operation idempotent, preventing duplicate refund processing in cases of multiple submissions. ::: requestBody: content: application/json: schema: $ref: "#/components/schemas/Order-Refund" examples: default: value: amount: 40 description: Refund for damaged goods responses: "201": description: OK content: application/json: schema: $ref: "#/components/schemas/Order" examples: refund_example: summary: Refund example value: 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 "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/Error" "401": description: Unauthorized "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/Error" "422": description: Insufficient funds content: application/json: schema: type: object properties: errorId: type: string description: The ID of the error. You can share this ID with Revolut support for troubleshooting. timestamp: type: integer description: The date and time the error happened. code: type: integer examples: example-1: value: errorId: 94b27660-fdda-49ec-8b85-cd46a068ade0 timestamp: 1601296792533 code: 1026 security: - Api-Key: [] tags: - Orders /api/orders/{order_id}/payments: parameters: - $ref: "#/components/parameters/Authorization" - $ref: "#/components/parameters/Order-Id" post: summary: Pay for an order operationId: payOrder description: |- Initiate a payment to pay full amount for an order using a customer's saved payment method. :::note The `/orders/{order_id}/confirm` endpoint has been deprecated. It will be only supported for already existing implementations. ::: :::warning 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](/docs/guides/merchant/optimise-checkout/save-payment-methods/charge-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 | :::note 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](/docs/api/merchant#retrieve-payment-method-list) operation. requestBody: content: application/json: schema: $ref: "#/components/schemas/Saved-Payment-Method" examples: saved_card_customer: summary: Saved card (customer initiator) value: 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 saved_card_merchant: summary: Saved card (merchant initiator) value: saved_payment_method: type: card id: 2b83c23a-650e-40c3-8989-00ee24478738 initiator: merchant revolut_pay: summary: Saved Revolut Pay (merchant initiator) value: saved_payment_method: type: revolut_pay id: 2b83c23a-650e-40c3-8989-00ee24478738 initiator: merchant responses: "200": description: Payment initiated content: application/json: schema: $ref: "#/components/schemas/Payment-Retrieval" examples: successful_payment_card: summary: Payment authorised (card) value: 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 successful_payment_revolut_pay_account: summary: Payment authorised (Revolut Pay - Revolut account) value: id: 63c55e04-4208-a43d-9c96-eaee848ffbaf order_id: 63c55df6-1461-a886-b90f-f49d3c370253 payment_method: type: revolut_pay subtype: revolut_account id: 2b83c23a-650e-40c3-8989-00ee24478738 state: authorisation_passed successful_payment_revolut_pay_card: summary: Payment authorised (Revolut Pay - card) value: id: 63c55e04-4208-a43d-9c96-eaee848ffbaf order_id: 63c55df6-1461-a886-b90f-f49d3c370253 payment_method: type: revolut_pay subtype: card id: 2b83c23a-650e-40c3-8989-00ee24478738 brand: visa last_four: "1234" state: authorisation_passed three_ds: summary: Saved card payment (3DS challenge) value: id: 5e96b328-4054-41ed-b089-595ccc4d0870 order_id: a16718e0-077a-4942-89bc-23ac17a2e14c payment_method: type: card id: 2b83c23a-650e-40c3-8989-00ee24478738 brand: mastercard_credit last_four: "1234" state: authentication_challenge authentication_challenge: type: three_ds acs_url: https://example.com three_ds_fingerprint: summary: Saved card payment (3DS fingerprint challenge) value: id: 5e96b328-4054-41ed-b089-595ccc4d0870 order_id: a16718e0-077a-4942-89bc-23ac17a2e14c payment_method: type: card id: 2b83c23a-650e-40c3-8989-00ee24478738 brand: mastercard_credit last_four: "1234" state: authentication_challenge authentication_challenge: type: three_ds_fingerprint fingerprint_url: https://example.com fingerprint_data: string "400": description: Bad Request content: application/json: schema: type: object properties: errorId: type: string description: |- The ID of the error. You can share this ID with Revolut support for troubleshooting. timestamp: type: integer description: The date and time the error happened. examples: example-1: value: errorId: 94b27660-fdda-49ec-8b85-cd46a068ade0 timestamp: 1601296792533 "401": description: Unauthorized "404": description: Not Found content: application/json: schema: type: object properties: errorId: type: string description: |- The ID of the error. You can share this ID with Revolut support for troubleshooting. timestamp: type: integer description: The date and time the error happened. code: type: integer examples: example-1: value: errorId: 94b27660-fdda-49ec-8b85-cd46a068ade0 timestamp: 1601296792533 code: 1024 security: - Api-Key: [] tags: - Orders - Payments get: summary: Retrieve payment list of an order operationId: retrievePaymentList description: >- Retrieve a list of payments for a specific order, based on the order's ID. :::note 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: - [Speed up customer checkout by using saved card details](/docs/guides/merchant/optimise-checkout/save-payment-methods/checkout-with-saved-card) - [Manage subscriptions](/docs/guides/merchant/optimise-checkout/save-payment-methods/subscription-management) responses: "200": description: List of payments content: application/json: schema: type: array items: $ref: "#/components/schemas/Payment-Retrieval" examples: payment_list: summary: List of payments (failed card attempt, SEPA Direct Debit retry) value: - 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 "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/Error-v2" examples: default: value: code: bad_request message: Could not parse JSON timestamp: 1720528890647 "401": description: Unauthenticated content: application/json: schema: $ref: "#/components/schemas/Error-v2" examples: default: value: code: unauthenticated message: Authentication failed timestamp: 1720528890647 "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/Error-v2" examples: - code: not_found message: Order with id b8883ab5-964a-4329-aa44-4d3c76cf3f54 was not found timestamp: 1720528890647 security: - Api-Key: [] tags: - Orders - Payments /api/1.0/customers: parameters: - $ref: "#/components/parameters/Authorization" post: summary: Create a customer (Deprecated) deprecated: true operationId: createCustomerDeprecated description: |- Create a `customer` that has the information in the body of the request. :::note If you wish to save a customer's payment details using any of the available payment methods on the Revolut Checkout Widget ([Revolut Pay](/docs/guides/merchant/accept-payments/online-payments/revolut-pay/introduction), [Card payments](/docs/guides/merchant/accept-payments/online-payments/card-payments/introduction)), you need to meet one of the following requirements: - Have a customer object with `email` and assign it to the order by providing `customer.id` - Create a new customer with, at least, `customer.email` during [order creation](/docs/api/merchant#create-order) For more information, see: [Charge a customer's saved payment method](/docs/guides/merchant/optimise-checkout/save-payment-methods/charge-saved-payment-method). ::: requestBody: content: application/json: schema: $ref: "#/components/schemas/Customer-Creation" examples: default: value: full_name: Example Customer business_name: Example Business email: example.customer@example.com phone: "+441234567890" date_of_birth: 1990-01-01 responses: "201": description: Created content: application/json: schema: $ref: "#/components/schemas/Customer" examples: created_customer: summary: Created customer value: 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 "400": description: Bad Request content: application/json: schema: description: "" type: object properties: errorId: type: string description: |- The ID of the error. You can share this ID with Revolut support for troubleshooting. timestamp: type: number description: The date and time the error happened. code: type: number description: "`1018` - The customer already exists." required: - errorId - timestamp examples: Error: value: errorId: 5226f800-e9be-4b74-ae61-6c7b71c913b5 timestamp: 1593439990599 code: 1018 "401": description: Unauthorized security: - Api-Key: [] tags: - Customers get: summary: Retrieve a customer list (Deprecated) deprecated: true operationId: retrieveAllCustomersDeprecated description: Get a list of all your `customers`. parameters: - schema: type: integer default: 100 minimum: 1 maximum: 100 in: query name: limit description: The maximum number of customers returned per page. Used for **pagination**. - schema: type: integer default: 0 minimum: 0 in: query name: page description: A zero-based page index for the paginated results, used in conjunction with `limit`. responses: "200": description: OK content: application/json: schema: type: array items: $ref: "#/components/schemas/Customer" examples: list_of_customers: summary: List of customers value: - 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 "401": description: Unauthorized security: - Api-Key: [] tags: - Customers /api/1.0/customers/{customer_id}: parameters: - $ref: "#/components/parameters/Authorization" - $ref: "#/components/parameters/Customer-Id" get: summary: Retrieve a customer (Deprecated) deprecated: true operationId: retrieveCustomerDeprecated description: Get the information about a specific `customer`, based on its ID. responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/Customer-With-Payment-Method" examples: retrieved_customer: summary: Retrieved customer value: 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 "401": description: Unauthorized "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/Error" security: - Api-Key: [] tags: - Customers patch: summary: Update a customer (Deprecated) deprecated: true operationId: updateCustomerDeprecated description: Update the attributes of a specific `customer`. requestBody: content: application/json: schema: $ref: "#/components/schemas/Customer-Update" examples: default: value: email: example.business@example.com responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/Customer" examples: updated_customer: summary: Updated customer value: 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 "400": description: Bad Request content: application/json: schema: type: object properties: errorId: type: string description: |- The ID of the error. You can share this ID with Revolut support for troubleshooting. timestamp: type: integer description: The date and time the error happened. examples: example-1: value: errorId: 94b27660-fdda-49ec-8b85-cd46a068ade0 timestamp: 1601296792533 "401": description: Unauthorized "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/Error" security: - Api-Key: [] tags: - Customers delete: summary: Delete a customer (Deprecated) deprecated: true operationId: deleteCustomerDeprecated description: Delete the profile of a specific `customer`. responses: "204": description: No Content "401": description: Unauthorized "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/Error" security: - Api-Key: [] tags: - Customers /api/1.0/customers/{customer_id}/payment-methods: parameters: - $ref: "#/components/parameters/Authorization" - $ref: "#/components/parameters/Customer-Id" get: summary: Retrieve all payment methods of a customer (Deprecated) deprecated: true operationId: retrieveAllPaymentMethodsDeprecated description: >- 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. parameters: - name: only_merchant in: query schema: type: boolean default: false description: >- If `only_merchant` is set to `true`, you retrieve the payment methods that were saved for the merchant (`saved_for: "MERCHANT"`). To use this parameter insert it at the end of the request URL. See this example for a request URL in Production environment: ```curl https://merchant.revolut.com/api/1.0/customers/{customer_id}/payment-methods?only_merchant=true ``` required: false responses: "200": description: OK content: application/json: schema: type: array items: $ref: "#/components/schemas/Customer-Payment-Method" examples: list_of_payment_methods: summary: List of payment methods value: - 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 list_of_only_merchant_payment_methods: summary: List of payment methods (only_merchant=true) value: - id: 624baa72-0a30-4ee3-9870-d7172912704c type: CARD saved_for: MERCHANT method_details: bin: "492942" last4: "5709" expiry_month: 12 expiry_year: 2025 cardholder_name: Example Customer 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: b92b7413-8764-4f8e-855d-d9b6986af2d9 type: CARD saved_for: MERCHANT method_details: bin: "528143" last4: "7653" expiry_month: 12 expiry_year: 2025 cardholder_name: Example Holder 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 "401": description: Unauthorized "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/Error" security: - Api-Key: [] tags: - Customers /api/1.0/customers/{customer_id}/payment-methods/{payment_method_id}: parameters: - $ref: "#/components/parameters/Authorization" - $ref: "#/components/parameters/Customer-Id" - $ref: "#/components/parameters/Payment-Method-Id" get: summary: Retrieve a customer's payment method (Deprecated) deprecated: true operationId: retrievePaymentMethodDeprecated description: Retrieve the information of a specific payment method that is saved. responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/Customer-Payment-Method" examples: retrieved_payment_method: summary: Retrieved payment method value: 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 "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/Error" security: - Api-Key: [] tags: - Customers patch: summary: Update a customer's payment method (Deprecated) deprecated: true operationId: updatePaymentMethodDeprecated description: >- 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: - [Pay for an order](/docs/api/merchant#pay-order) - [Charge a customer's saved payment method](/docs/guides/merchant/optimise-checkout/save-payment-methods/charge-saved-payment-method) requestBody: content: application/json: schema: type: object properties: saved_for: type: string description: >- Update the value of `saved_for` from `MERCHANT` to `CUSTOMER`. This indicates that the updated payment method can't be used for merchant initiated transactions (MIT) any more. enum: - CUSTOMER required: - saved_for examples: example_request: summary: Example request value: saved_for: CUSTOMER application/xml: schema: type: object properties: {} responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/Customer-Payment-Method" examples: updated_payment_method: summary: Updated payment method value: 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 "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/Error" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/Error" security: - Api-Key: [] tags: - Customers delete: summary: Delete a customer's payment method (Deprecated) deprecated: true operationId: deletePaymentMethodDeprecated description: >- 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. responses: "204": description: No Content "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/Error" security: - Api-Key: [] tags: - Customers /api/payments/{payment_id}: parameters: - $ref: "#/components/parameters/Authorization" - $ref: "#/components/parameters/Payment-Id" get: summary: Retrieve payment details operationId: retrievePaymentDetails description: >- 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](/docs/guides/merchant/optimise-checkout/save-payment-methods/checkout-with-saved-card) - When you build a [subscription management system](/docs/guides/merchant/optimise-checkout/save-payment-methods/subscription-management) responses: "200": description: Payment details content: application/json: schema: $ref: "#/components/schemas/Payment-Retrieval" examples: revolut_pay_saved: summary: Payment completed via Revolut Pay (saved details) value: 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 revolut_pay_not_saved: summary: Payment completed via Revolut Pay (not saved details) value: id: 64905d4b-a205-aac3-a5ef-dab978b1b7ee order_id: 64905d0f-3f95-a2ac-91ea-57c77f9dbe69 state: completed payment_method: type: revolut_pay subtype: revolut_account card_payment_saved: summary: Payment completed via card (saved details) value: id: 63dd0e4a-42c4-a1a6-ab2c-6ac9d255ca4b order_id: 63dd0e3f-7b84-ab5c-927c-1a06f7c9583a state: completed payment_method: type: card brand: visa last_four: "1234" id: 64a28499-05c5-af30-bbf9-9c1b028e00b8 card_payment_not_saved: summary: Payment completed via card (not saved details) value: id: 63dd0e4a-42c4-a1a6-ab2c-6ac9d255ca4b order_id: 63dd0e3f-7b84-ab5c-927c-1a06f7c9583a state: completed payment_method: type: card brand: visa last_four: "1234" "400": description: Bad Request content: application/json: schema: type: object properties: errorId: type: string description: |- The ID of the error. You can share this ID with Revolut support for troubleshooting. timestamp: type: integer description: The date and time the error happened. examples: example-1: value: errorId: 94b27660-fdda-49ec-8b85-cd46a068ade0 timestamp: 1601296792533 "401": description: Unauthorized "404": description: Not Found content: application/json: schema: type: object properties: errorId: type: string description: |- The ID of the error. You can share this ID with Revolut support for troubleshooting. timestamp: type: integer description: The date and time the error happened. code: type: integer examples: example-1: value: errorId: 94b27660-fdda-49ec-8b85-cd46a068ade0 timestamp: 1601296792533 code: 1024 security: - Api-Key: [] tags: - Payments /api/payouts: parameters: - $ref: "#/components/parameters/Authorization" - $ref: "#/components/parameters/Revolut-Api-Version" get: summary: Retrieve a payout list operationId: retrievePayoutList description: >- 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:
| parameters: - name: currency in: query schema: type: string minLength: 3 maxLength: 3 description: |- [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code in upper case. :::info For more information about the supported currencies, see: [Help Center](https://help.revolut.com/business/help/merchant-accounts/payments/in-which-currencies-can-i-accept-payments/). ::: - name: limit in: query schema: type: integer minimum: 1 maximum: 500 description: The maximum number of payouts returned per page. Used for **pagination**. - name: from_created_date in: query schema: type: string format: date-time description: >- Retrieve all payouts with a `created_date` ≥ `from_created_date`. Used for **filtering**. Use the [ISO date format](https://en.wikipedia.org/wiki/ISO_8601): `yyyy-MM-ddTHH:mm:ss[.SSSSSS]Z`. For example, `2021-02-10T16:59:50.886826Z`. - name: to_created_date in: query schema: type: string format: date-time description: >- Retrieve all payouts with a `created_date` ≤ `to_created_date`. Used for **filtering**. Use the [ISO date format](https://en.wikipedia.org/wiki/ISO_8601): `yyyy-MM-ddTHH:mm:ss[.SSSSSS]Z`. For example, `2021-02-10T16:59:50.886826Z`. - name: state in: query schema: type: array items: type: string enum: - processing - completed - failed style: form explode: true description: |- Retrieve all payouts with specific states. You can pass several states. Used for **filtering**. If multiple states are selected, for example `completed` and `processing`, payouts with either of the selected values are returned. See this example of such a request URL: ```curl https://merchant.revolut.com/api/payouts?state=completed&state=processing ``` The parameter is case sensitive. responses: "201": description: Payouts retrieved content: application/json: schema: type: array items: $ref: "#/components/schemas/Payout" examples: default: value: - 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 "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/Error-v2" examples: default: value: code: bad_request message: Could not parse JSON timestamp: 1721049596461 headers: {} "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/Error-v2" examples: default: value: code: unauthenticated message: Authentication failed timestamp: 1721049596461 "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/Error-v2" security: - Api-Key: [] tags: - Payouts /api/payouts/{payout_id}: parameters: - $ref: "#/components/parameters/Authorization" - $ref: "#/components/parameters/Revolut-Api-Version" - $ref: "#/components/parameters/Payout-Id" get: summary: Retrieve a payout operationId: retrievePayout description: Retrieve the details of a payout. Provide the unique payout ID, and the corresponding payout information is returned. responses: "200": description: Payout retrieved content: application/json: schema: $ref: "#/components/schemas/Payout" examples: default: value: id: a830020e-090c-4717-836d-37941a27ad12 state: completed created_at: 2024-02-27T00:16:39.079285Z destination_type: current_pocket amount: 50000 currency: GBP "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/Error-v2" examples: default: value: code: bad_request message: Missing Revolut-Api-Version header timestamp: 1721049596461 headers: {} "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/Error-v2" examples: default: value: code: unauthenticated message: Authentication failed timestamp: 1721049596461 "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/Error-v2" examples: default: value: code: not_found message: The requested resource is not found timestamp: 1721050063886 security: - Api-Key: [] tags: - Payouts /api/report-runs: parameters: - $ref: "#/components/parameters/Authorization" post: summary: Create a new report run operationId: createReportRun description: >- 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](/docs/api/merchant#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` | requestBody: content: application/json: schema: discriminator: propertyName: type mapping: settlement_report: "#/components/schemas/Report-Run-Settlement-Report" custom_report: "#/components/schemas/Report-Run-Custom-Report" payout_statement_report: "#/components/schemas/Report-Run-Payout-Report" icpp_fee_breakdown_report: "#/components/schemas/Report-Run-Icpp-Report" payments_report: "#/components/schemas/Report-Run-Payments-Report" oneOf: - $ref: "#/components/schemas/Report-Run-Settlement-Report" - $ref: "#/components/schemas/Report-Run-Custom-Report" - $ref: "#/components/schemas/Report-Run-Payout-Report" - $ref: "#/components/schemas/Report-Run-Icpp-Report" - $ref: "#/components/schemas/Report-Run-Payments-Report" examples: custom_report: summary: Custom report value: 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 settlement_report: summary: Settlement report value: filter: from: 2020-01-01T00:00:00Z to: 2020-01-02T00:00:00Z entity_types: - payment format: csv type: settlement_report payout_statement_report: summary: Payout statement report value: filter: payout_id: a830020e-090c-4717-836d-37941a27ad12 format: csv type: payout_statement_report icpp_fee_breakdown_report: summary: IC++ fee breakdown report value: filter: icpp_charge_id: 41d6c699-744a-4994-91c0-9227539c587f format: csv type: icpp_fee_breakdown_report payments_report: summary: Payments report value: filter: from: 2020-01-01T00:00:00Z to: 2020-01-02T00:00:00Z entity_states: - completed - failed - declined format: csv type: payments_report responses: "201": description: Report run created, report started generating content: application/json: schema: $ref: "#/components/schemas/Report-Run-Details" examples: report_run_processing: summary: Report run processing value: report_run_id: d6f6ef64-f668-4e64-8967-1cdf8afb2561 status: processing report_run_completed: summary: Report run completed value: report_run_id: d6f6ef64-f668-4e64-8967-1cdf8afb2561 status: completed file_url: https://merchant.revolut.com/api/report-runs/d6f6ef64-f668-4e64-8967-1cdf8afb2561/file "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/Report-Run-Error" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/Report-Run-Error" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/Report-Run-Error" security: - Api-Key: [] tags: - Report runs /api/report-runs/{report_run_id}: parameters: - $ref: "#/components/parameters/Authorization" - $ref: "#/components/parameters/Report-Run-Id" get: summary: Retrieve report run details operationId: retrieveReportRunDetails description: >- 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`. responses: "200": description: Report run found content: application/json: schema: $ref: "#/components/schemas/Report-Run-Details" examples: report_run_processing: summary: Report run processing value: report_run_id: d6f6ef64-f668-4e64-8967-1cdf8afb2561 status: processing report_run_completed: summary: Report run completed value: report_run_id: d6f6ef64-f668-4e64-8967-1cdf8afb2561 status: completed file_url: https://merchant.revolut.com/api/report-runs/d6f6ef64-f668-4e64-8967-1cdf8afb2561/file "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/Report-Run-Error" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/Report-Run-Error" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/Report-Run-Error" security: - Api-Key: [] tags: - Report runs /api/report-runs/{report_run_id}/file: parameters: - $ref: "#/components/parameters/Authorization" - $ref: "#/components/parameters/Report-Run-Id" get: summary: Download report file operationId: downloadReportFile description: Use this endpoint to download the generated report file. responses: "200": description: OK content: text/csv: schema: type: string description: CSV-formatted text representing the generated report file. examples: custom-report: summary: Custom CSV report example value: |- transaction_id,order_id,payment_method,amount,currency,state,updated_date 649ae37f-99ca-a7db-a4fb-5924af14ad7c,649ae35c-2558-adea-bf98-3a7156a764e7,PAY_WITH_REVOLUT,0.05,GBP,COMPLETED,2023-06-28T13:30:46.07498Z 649ae3de-e945-af9f-98c8-1d6172e350b5,649ae3ab-3998-ab2b-ad95-41b48346be69,PAY_WITH_REVOLUT,0.05,GBP,COMPLETED,2023-06-28T13:30:46.075569Z 649ae48b-37f6-a097-9cb0-4fc2a89d9e5a,649ae479-d7e8-a139-993b-bf75865c5059,PAY_WITH_REVOLUT,0.05,GBP,COMPLETED,2023-06-28T13:38:46.084289Z 649af325-0695-ac77-8868-ab421510a964,649af29d-be4a-a854-b872-3ececa585e0a,PAY_WITH_REVOLUT,0.05,GBP,COMPLETED,2023-06-28T14:34:56.894573Z 649af3a5-efbd-af7e-8c95-022bbdb91f1b,649af383-670d-a390-b22c-799a00892645,PAY_WITH_REVOLUT,0.05,GBP,COMPLETED,2023-06-28T14:42:56.903122Z 649ab540-352a-ac19-866f-47189c00d1a2,649ab53e-53ba-a398-88e1-78cf5bd9d348,PAY_WITH_REVOLUT,0.50,GBP,COMPLETED,2023-06-28T10:14:18.000566Z payout_statement_report: summary: Payout statement CSV report example value: |- created_date,completed_date,payout_affected_date,affected_payout_amount,transaction_id,order_id,merchant_order_reference,type,related_payout_id,related_icpp_charge_id,transaction_amount,transaction_currency,billing_amount,billing_currency,state,original_transaction_id,original_transaction_amount,original_transaction_currency,original_order_id,original_merchant_order_reference,fee_amount,fee_currency,settlement_amount,settlement_currency 2024-04-10T17:34:15.928757Z,2024-04-11T17:35:03.281106Z,2024-04-11T17:35:03.281106Z,true,6616cd97-3d8a-a1df-99c6-1417fc9e1997,6616cd60-ba44-a55a-81f3-91b4edb2a5c1,,Payment,,,10000.00,GBP,10000.00,GBP,COMPLETED,6616cd97-3d8a-a1df-99c6-1417fc9e1997,10000.00,GBP,6616cd60-ba44-a55a-81f3-91b4edb2a5c1,,-100.00,GBP,9900.00,GBP 2024-04-10T17:38:08.94564Z,2024-04-11T17:38:58.500128Z,2024-04-11T17:38:58.500128Z,true,6616ce80-2cee-a314-b494-b3ff64d77e14,6616cdbf-5674-a095-bbc9-4349ea767dd1,,Payment,,,10000.00,GBP,10000.00,GBP,COMPLETED,6616ce80-2cee-a314-b494-b3ff64d77e14,10000.00,GBP,6616cdbf-5674-a095-bbc9-4349ea767dd1,,-100.00,GBP,9900.00,GBP 2024-04-10T17:42:23.260097Z,2024-04-11T17:42:58.497249Z,2024-04-11T17:42:58.497249Z,true,6616cf7f-aa77-a577-9051-fe526e109b82,6616cf1b-dfa8-aeac-b736-36e851d83376,,Payment,,,10000.00,GBP,10000.00,GBP,COMPLETED,6616cf7f-aa77-a577-9051-fe526e109b82,10000.00,GBP,6616cf1b-dfa8-aeac-b736-36e851d83376,,-100.00,GBP,9900.00,GBP payments_report: summary: Payments CSV report example value: |- payment_id,type,description,original_payment_id,order_id,state,reason,amount,currency,surcharge_amount,tip_amount,refunded_amount,created_date,merchant_order_ext_ref,payment_method,location_id,customer_id,customer_card_number,customer_card_country,customer_card_brand,customer_card_type,customer_card_category,customer_email,fee_amount,fee_currency a1b2c3d4-0001-0000-0000-000000000001,PAYMENT,Payment from customer,,o1b2c3d4-0001-0000-0000-000000000001,COMPLETED,,120,GBP,,0,0,2026-02-01T09:10:05.375Z,ORD-001,CARD,,cust-0001-0000-0000-000000000001,533325******3223,GB,VISA,DEBIT,consumer,customer@example.com,3.56,GBP a1b2c3d4-0002-0000-0000-000000000002,PAYMENT,Payment from customer,,o1b2c3d4-0002-0000-0000-000000000002,COMPLETED,,10,GBP,,0,0,2026-02-01T14:35:00.699Z,,PAY_WITH_REVOLUT,,,,,,,customer2@example.com,0.30,GBP a1b2c3d4-0003-0000-0000-000000000003,PAYMENT,Payment from customer,,o1b2c3d4-0003-0000-0000-000000000003,FAILED,Insufficient Funds,15,GBP,,0,0,2026-02-02T20:45:01.255Z,,CARD,,cust-0001-0000-0000-000000000001,533325******3223,GB,MASTERCARD_DEBIT,PREPAID,consumer,customer@example.com,, "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/Report-Run-Error" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/Report-Run-Error" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/Report-Run-Error" security: - Api-Key: [] tags: - Report runs /api/1.0/webhooks: parameters: - $ref: "#/components/parameters/Authorization" post: summary: Create a webhook (Deprecated) deprecated: true operationId: createWebhookDeprecated description: >- Set up a webhook URL so that the Merchant API can push event notifications to the specified URL. :::warning 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. ::: requestBody: content: application/json: schema: $ref: "#/components/schemas/Webhook-Creation" examples: example_webhook_request: summary: Example webhook request value: url: https://example.com/webhooks events: - ORDER_COMPLETED - ORDER_AUTHORISED responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/Webhook-With-Signing-Secret" examples: created_webhook: summary: Created webhook value: id: c6b981f4-53b3-47d5-9b24-4f87af1160eb url: https://example.com/webhooks events: - ORDER_AUTHORISED - ORDER_COMPLETED signing_secret: wsk_4jETWMz1g1b37gCONjNp84t2KSSIT7dK "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/Error" "401": description: Unauthorized callbacks: Send webhook event: $ref: "#/components/callbacks/Webhook-Event" security: - Api-Key: [] tags: - Webhooks get: summary: Retrieve a webhook list (Deprecated) deprecated: true operationId: retrieveAllWebhooksDeprecated description: Get a list of webhooks that you are currently subscribed to. responses: "200": description: OK content: application/json: schema: type: array items: $ref: "#/components/schemas/Webhook" examples: list_of_webhooks: summary: List of webhooks value: - 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 "401": description: Unauthorized security: - Api-Key: [] tags: - Webhooks /api/1.0/webhooks/{webhook_id}: parameters: - $ref: "#/components/parameters/Authorization" - $ref: "#/components/parameters/Webhook-Id" get: summary: Retrieve a webhook (Deprecated) deprecated: true operationId: retrieveWebhookDeprecated description: Get the details of a specific webhook. responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/Webhook-With-Signing-Secret" examples: retrieved_webhook: summary: Retrieved webhook value: id: c6b981f4-53b3-47d5-9b24-4f87af1160eb url: https://example.com/webhooks events: - ORDER_AUTHORISED - ORDER_COMPLETED signing_secret: wsk_4jETWMz1g1b37gCONjNp84t2KSSIT7dK "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/Error" security: - Api-Key: [] tags: - Webhooks put: summary: Update a webhook (Deprecated) deprecated: true operationId: updateWebhookDeprecated description: Update the details of a specific webhook. requestBody: content: application/json: schema: $ref: "#/components/schemas/Webhook-Creation" examples: webhook_update_request: summary: Webhook update request value: url: http://business.revolut.com events: - ORDER_COMPLETED responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/Webhook" examples: updated_webhook: summary: Updated webhook value: id: c6b981f4-53b3-47d5-9b24-4f87af1160eb url: http://business.revolut.com events: - ORDER_COMPLETED "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/Error" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/Error" security: - Api-Key: [] tags: - Webhooks delete: summary: Delete a webhook (Deprecated) deprecated: true operationId: deleteWebhookDeprecated description: Delete a webhook so that events are not sent to the specified URL any more. responses: "204": description: No Content "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/Error" security: - Api-Key: [] tags: - Webhooks /api/1.0/webhooks/{webhook_id}/rotate-signing-secret: parameters: - $ref: "#/components/parameters/Authorization" - $ref: "#/components/parameters/Webhook-Id" post: summary: Rotate a webhook signing secret (Deprecated) deprecated: true operationId: rotateWebhookSigningSecretDeprecated description: |- Rotate the `signing secret` for a specific webhook. For more information, see [Tutorials: Verify the payload signature](/docs/guides/merchant/monitor-and-observe/webhooks/verify-the-payload-signature). requestBody: content: application/json: schema: type: object properties: expiration_period: type: string format: duration description: >- The expiration period of the signing secret in the [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601#Durations). If defined, when the signing secret is rotated, it continues to be valid until the expiration period passes. Otherwise, it is invalidated immediately. Maximum expiration period is 7 days. examples: - PT5H30M examples: webhook_signing_secret_rotate_request: summary: Webhook signing secret rotation request value: expiration_period: PT5H30M responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/Webhook-With-Signing-Secret" examples: updated_webhook: summary: Updated webhook value: id: c6b981f4-53b3-47d5-9b24-4f87af1160eb url: http://business.revolut.com events: - ORDER_COMPLETED signing_secret: wsk_4jETWMz1g1b37gCONjNp84t2KSSIT6aG "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/Error" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/Error" security: - Api-Key: [] tags: - Webhooks /api/apple-pay/domains/register: parameters: - $ref: "#/components/parameters/Authorization" post: summary: Register domain for Apple Pay operationId: registerDomainApplePay description: |- 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: 1. Download the latest [domain validation file](https://assets.revolut.com/api-docs/merchant-api/files/apple-developer-merchantid-domain-association). 1. Upload the domain validation file to your website in the following folder `/.well-known/`. For example, if your website is `example.com`, the file should be available on `example.com/.well-known/apple-developer-merchantid-domain-association`, where `apple-developer-merchantid-domain-association` indicates the name of the file. requestBody: content: application/json: schema: type: object properties: domain: type: string description: Domain name of your website without the scheme (i.e. without `http://` or `https://`). examples: - revolut.com required: - domain examples: example_request: summary: Example domain registration request for Apple Pay value: domain: revolut.com responses: "204": description: Domain registered successfully "400": description: Bad Request content: application/json: schema: type: object properties: code: type: string description: >- An identifier that can be used to determine what went wrong. Error codes are not globally unique, but uniqueness is guaranteed within endpoints. message: type: string description: Human readable text describing what went wrong. required: - code examples: error_message: summary: Error message value: code: validation message: Exactly one value must be supplied for client_id security: - Api-Key: [] tags: - Apple Pay merchant registration /api/apple-pay/domains/unregister: parameters: - $ref: "#/components/parameters/Authorization" - $ref: "#/components/parameters/Revolut-Api-Version-Optional" post: summary: Unregister domain for Apple Pay operationId: unregisterDomainApplePay description: "Unregister your website from Apple Pay's registered domains. " requestBody: content: application/json: schema: type: object properties: domain: type: string description: Domain name of your website without the scheme (i.e. without `http://` or `https://`). examples: - revolut.com reason: type: string description: A short explanation why you remove the domain. maxLength: 1024 required: - domain - reason examples: example_request: summary: Example domain registration request for Apple Pay value: domain: revolut.com reason: Unregister due to domain change. responses: "204": description: Domain ungistered successfully "400": description: Bad Request content: application/json: schema: type: object properties: code: type: string description: >- An identifier that can be used to determine what went wrong. Error codes are not globally unique, but uniqueness is guaranteed within endpoints. message: type: string description: Human readable text describing what went wrong. required: - code examples: error_message: summary: Error message value: code: validation message: Exactly one value must be supplied for client_id security: - Api-Key: [] tags: - Apple Pay merchant registration /api/synchronous-webhooks: parameters: - $ref: "#/components/parameters/Authorization" post: summary: Register address validation endpoint for Fast checkout operationId: registerAddressValidationEndpoint description: >- 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](/docs/guides/merchant/optimise-checkout/fast-checkout). 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: 1. Register an URL to handle address validation 1. Validate the shipping address sent to your backend 1. 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: - [Manage multiple stores with Fast checkout](/docs/guides/merchant/optimise-checkout/fast-checkout#manage-multiple-stores-with-fast-checkout) - [Merchant API: Locations](/docs/api/merchant#tag-locations) :::note To set up a webhook for tracking order completion, failure, error, etc. events, use the [Webhooks endpoints](/docs/api/merchant#tag-webhooks). ::: requestBody: content: application/json: schema: $ref: "#/components/schemas/Synchronous-Webhook-Creation" examples: create_webhook: summary: Create synchronous webhook value: event_type: fast_checkout.validate_address url: https://backend.example.com/webhooks/validate-address create_webhook_with_location_id: summary: Create synchronous webhook with location ID value: event_type: fast_checkout.validate_address url: https://backend.example.com/webhooks/validate-address location_id: 8d9a7125-805f-40f3-a405-bc89765db996 responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/Synchronous-Webhook" examples: example_without_location: summary: Synchronous webhook response value: id: f6abc4df-eb48-417c-8e75-f7c6d7ad394f signing_key: swsk_y5z3LEHYZ9ndote3qegzWD6uL4t1lfp1 url: https://backend.example.com/webhooks/validate-address event_type: fast_checkout.validate_address example_with_location: summary: Synchronous webhook response with location ID value: id: f6abc4df-eb48-417c-8e75-f7c6d7ad394f signing_key: swsk_y5z3LEHYZ9ndote3qegzWD6uL4t1lfp1 url: https://backend.example.com/webhooks/validate-address event_type: fast_checkout.validate_address location_id: b0ebede4-5cbc-4951-977f-70329faa8769 "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/Error" "401": description: Unauthorized security: - Api-Key: [] tags: - Other get: summary: Retrieve a synchronous webhook list operationId: retrieveSynchronousWebhookList description: >- Retrieve a list of synchronous webhook objects. You can use this endpoint to see your different address validation endpoints registered to different locations. :::info For more information about locations, see: [Merchant API: Locations](/docs/api/merchant#tag-locations). ::: responses: "200": description: Synchronous webhook list returned content: application/json: schema: type: array items: $ref: "#/components/schemas/Synchronous-Webhook" examples: example_without_location: summary: List of synchronous webhooks value: - 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 "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/Error" "401": description: Unauthorized security: - Api-Key: [] tags: - Other /api/synchronous-webhooks/{synchronous_webhook_id}: parameters: - $ref: "#/components/parameters/Authorization" - $ref: "#/components/parameters/Synchronous-Webhook-Id" delete: summary: Delete a synchronous webhook operationId: deleteSynchronousWebhook description: Delete a specific synchronous webhook registration, based on its ID. responses: "204": description: Synchronous webhook deleted "401": description: Unauthorized "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/Error" security: - Api-Key: [] tags: - Other /api/locations: parameters: - $ref: "#/components/parameters/Authorization" post: summary: Create a location operationId: createLocation description: Create a `Location` object. Supports `online` and `physical` location types. requestBody: content: application/json: schema: $ref: "#/components/schemas/Location-Creation" examples: example_online_location: $ref: "#/components/examples/Req-Location-Online" example_physical_location: $ref: "#/components/examples/Req-Location-Physical" responses: "201": description: Location created content: application/json: schema: $ref: "#/components/schemas/Location" examples: example_online_location: $ref: "#/components/examples/Res-Location-Online" example_physical_location: $ref: "#/components/examples/Res-Location-Physical" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/Error" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/Error" security: - Api-Key: [] tags: - Locations get: summary: Retrieve location list operationId: retrieveLocationList description: >- Retrieve a list of locations registered for the merchant. :::note [Default behavior] 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. ::: parameters: - $ref: "#/components/parameters/Location-Type" responses: "200": description: OK content: application/json: schema: type: array items: $ref: "#/components/schemas/Location" examples: list_of_locations: summary: Location list value: - 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 "401": description: Unauthorized security: - Api-Key: [] tags: - Locations /api/locations/{location_id}: parameters: - $ref: "#/components/parameters/Authorization" - $ref: "#/components/parameters/Location-Id" get: summary: Retrieve a location operationId: retrieveLocation description: Retrieve details of a specific location, based on its ID. responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/Location" examples: example_online_location: $ref: "#/components/examples/Res-Location-Online" example_physical_location: $ref: "#/components/examples/Res-Location-Physical" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/Error" security: - Api-Key: [] tags: - Locations patch: summary: Update a location operationId: updateLocation description: >- 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. :::note The value of the location's `type` parameter cannot be updated. ::: requestBody: content: application/json: schema: $ref: "#/components/schemas/Location-Update" examples: online_location: summary: Online location example value: name: Cars website - Name update details: domain: cars.example.com physical_location: summary: Physical location example value: name: Example Street Store details: opening_hours: monday: - from: 10:00 to: 18:00 wednesday: - from: 11:00 to: 18:00 responses: "200": description: Location updated content: application/json: schema: $ref: "#/components/schemas/Location" examples: online_location: summary: Online location example value: id: 8d9a7125-805f-40f3-a405-bc89765db996 name: Cars website - Name update type: online details: domain: cars.example.com physical_location: summary: Physical location example value: name: Example Street Store type: physical details: address: null 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: 10:00 to: 18:00 tuesday: - from: 10:00 to: 13:00 - from: 16:00 to: 18:00 wednesday: - from: 11:00 to: 18:00 "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/Error" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/Error" security: - Api-Key: [] tags: - Locations delete: summary: Delete a location operationId: deleteLocation description: Delete a specific location, based on its ID. responses: "204": description: Location deleted "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/Error" security: - Api-Key: [] tags: - Locations /api/terminals: parameters: - $ref: "#/components/parameters/Authorization" - $ref: "#/components/parameters/Revolut-Api-Version-Optional" get: summary: Retrieve terminal list operationId: retrieveTerminalList description: |- 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. :::tip 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. ::: :::info For more information about integration, see: [Push payments to Revolut Terminal](/docs/guides/merchant/accept-payments/in-person-payments/terminal/push-payments). ::: parameters: - $ref: "#/components/parameters/Operation-Mode" - $ref: "#/components/parameters/Location-Id-Query" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/Terminals-Response" examples: terminals_list: $ref: "#/components/examples/Res-Terminals-List" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/Error-v2" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/Error-v2" security: - Api-Key: [] tags: - Terminals /api/orders/{order_id}/payment-intents: parameters: - $ref: "#/components/parameters/Authorization" - $ref: "#/components/parameters/Revolut-Api-Version-Optional" - $ref: "#/components/parameters/Order-Id" post: summary: Create a payment intent operationId: createPaymentIntent description: |- 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 a `location_id` - Terminal must be online, in `pos` operation 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`, or `failed`) - When the payment intent reaches `completed` state, use the returned `payment_id` to retrieve the final payment status :::info For the complete push payments flow, see: [Push payments to Revolut Terminal](/docs/guides/merchant/accept-payments/in-person-payments/terminal/push-payments). ::: requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/Payment-Intent-Creation" examples: create_payment_intent: $ref: "#/components/examples/Req-Payment-Intent" responses: "201": description: Payment intent created content: application/json: schema: $ref: "#/components/schemas/Payment-Intent" examples: payment_intent_pending: $ref: "#/components/examples/Res-Payment-Intent-Pending" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/Error" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/Error" security: - Api-Key: [] tags: - Payment intents /api/payment-intents/{payment_intent_id}: parameters: - $ref: "#/components/parameters/Authorization" - $ref: "#/components/parameters/Revolut-Api-Version-Optional" - $ref: "#/components/parameters/Payment-Intent-Id" get: summary: Retrieve a payment intent operationId: retrievePaymentIntent description: |- 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](/docs/api/merchant#retrieve-payment-details) | | `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) | :::tip [Polling strategy] - Poll every second while the state is `pending` or `processing` - Set a reasonable timeout (e.g., 60 seconds) to handle cases where the customer abandons the payment ::: :::info For the complete push payments flow, see: [Push payments to Revolut Terminal](/docs/guides/merchant/accept-payments/in-person-payments/terminal/push-payments). ::: responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/Payment-Intent" examples: payment_intent_pending: $ref: "#/components/examples/Res-Payment-Intent-Pending" payment_intent_processing: $ref: "#/components/examples/Res-Payment-Intent-Processing" payment_intent_completed: $ref: "#/components/examples/Res-Payment-Intent-Completed" payment_intent_cancelled: $ref: "#/components/examples/Res-Payment-Intent-Cancelled" payment_intent_failed: $ref: "#/components/examples/Res-Payment-Intent-Failed" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/Error" security: - Api-Key: [] tags: - Payment intents /api/payment-intents/{payment_intent_id}/cancel: parameters: - $ref: "#/components/parameters/Authorization" - $ref: "#/components/parameters/Revolut-Api-Version-Optional" - $ref: "#/components/parameters/Payment-Intent-Id" post: summary: Cancel a payment intent operationId: cancelPaymentIntent description: |- 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. :::warning **Requirements:** - Payment intent must be in `pending` state - Cannot cancel payment intents that are already `completed`, `cancelled`, or `failed` ::: :::info For the complete push payments flow, see: [Push payments to Revolut Terminal](/docs/guides/merchant/accept-payments/in-person-payments/terminal/push-payments). ::: responses: "200": description: Payment intent cancelled content: application/json: schema: $ref: "#/components/schemas/Payment-Intent" examples: payment_intent_cancelled: $ref: "#/components/examples/Res-Payment-Intent-Cancelled" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/Error" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/Error" security: - Api-Key: [] tags: - Payment intents components: securitySchemes: Api-Key: type: apiKey in: header name: Authorization description: >- Each Merchant API request must contain an authorization header in the following format: ``` 'Authorization: Bearer ' ``` 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. :::info For detailed instructions on generating your API keys, see: [Generate API keys](/docs/guides/merchant/get-started). ::: SSL: type: http scheme: SSL description: >- :::note This authentication protocol is used exclusively when using [Fast checkout](/docs/guides/merchant/optimise-checkout/fast-checkout). ::: Connection over HTTPS is using SSL authentication. For successful authentication, your system's certificate should be issued by a Public Certificate Authority (PCA) and your system should trust Revolut's public certificate. Payload-Signature: type: apiKey in: header name: Revolut-Pay-Payload-Signature description: >- :::note This authentication protocol is used exclusively when using [Fast checkout](/docs/guides/merchant/optimise-checkout/fast-checkout). ::: Data integrity and authorship will be verified using a payload-based signature. The response of a successful URL registration for address validation (see: [Register address validation for Fast checkout](/docs/api/merchant#register-address-validation-endpoint)) will contain a secret signing key. The signing key will be used by Revolut to compute a Hash-based Message Authentication Code (HMAC) payload signature whenever the registered URL is called, which should be verified by your backend. parameters: Authorization: name: Authorization in: header schema: type: string format: Bearer examples: - Bearer sk_1234567890ABCdefGHIjklMNOpqrSTUvwxYZ_1234567890-Ab_cdeFGHijkLMNopq required: true description: >- This parameter accepts the [Merchant API Secret key](https://business.revolut.com/settings/merchant-api) to authorise requests coming from the merchant's backend. It ensures that ensures that each request is authenticated and authorised by verifying the secret key. The secret key should be included in all request headers as a `Bearer` token. :::info For more information, see: [Generate API keys](/docs/guides/merchant/get-started) ::: Revolut-Api-Version: name: Revolut-Api-Version in: header schema: type: string format: date enum: - 2023-09-01 - 2024-05-01 - 2024-09-01 - 2025-10-16 - 2025-12-04 - 2026-03-12 - 2026-04-20 examples: - 2026-04-20 required: true description: >- The version of the Merchant API, specified in `YYYY-MM-DD` format. If not specified, you will receive an error. :::info For more information about API versioning, see: [API versions](/docs/guides/merchant/reference/versioning/api-versions). ::: x-config-always-visible-in-example: true Order-Id: name: order_id in: path schema: type: string format: uuid description: A UUID string, typically used to identify resources. required: true description: The ID of the `Order` object. Revolut-Api-Version-Optional: name: Revolut-Api-Version in: header schema: type: string format: date enum: - 2023-09-01 - 2024-05-01 - 2024-09-01 - 2025-10-16 - 2025-12-04 - 2026-03-12 - 2026-04-20 examples: - 2026-04-20 description: >- The version of the Merchant API, specified in `YYYY-MM-DD` format. :::info For more information about API versioning, see: [API versions](/docs/guides/merchant/reference/versioning/api-versions). ::: x-config-always-visible-in-example: true Idempotency-Key: name: Idempotency-Key in: header schema: type: string required: false description: >- The `Idempotency-Key` ensures that requests are processed only once, preventing multiple executions of the same operation due to retries or duplicate requests. This header is optional and can accept any unique string value the merchant uses. A recommended practice is to use a unique identifier from your system (such as the entity's ID or a request UUID) as the idempotency key. This facilitates tracking and managing requests effectively. Customer-Id: name: customer_id in: path schema: type: string format: uuid description: A UUID string, typically used to identify resources. required: true description: The ID of the `Customer` object. Payment-Method-Id: name: payment_method_id in: path schema: type: string format: uuid description: A UUID string, typically used to identify resources. required: true description: The ID of the payment method. Payment-Id: name: payment_id in: path schema: type: string format: uuid description: A UUID string, typically used to identify resources. required: true description: The ID of the `Payment` object. Payout-Id: name: payout_id in: path schema: type: string format: uuid description: A UUID string, typically used to identify resources. required: true description: The ID of the `Payout` object. Report-Run-Id: name: report_run_id in: path schema: type: string format: uuid description: A UUID string, typically used to identify resources. required: true description: Unique ID of the report run. Webhook-Id: name: webhook_id in: path schema: type: string format: uuid description: A UUID string, typically used to identify resources. required: true description: The ID of the webhook. Synchronous-Webhook-Id: name: synchronous_webhook_id in: path schema: type: string format: uuid description: A UUID string, typically used to identify resources. required: true description: The ID of the synchronous webhook. Location-Type: name: type in: query schema: type: string enum: - online - physical description: Filter the list by location type. Location-Id: name: location_id schema: type: string format: uuid description: A UUID string, typically used to identify resources. in: path required: true description: The ID of the location. Operation-Mode: name: operation_mode in: query required: false explode: true description: >- Filter terminals by operation mode. | Value | Description | |-------|-------------| | `pos` | Returns only terminals in Pay at Counter mode | | `payment_acceptance` | Returns only terminals in standard checkout mode | schema: $ref: "#/components/schemas/Terminal-Operation-Mode" Location-Id-Query: name: location_id schema: type: string format: uuid description: A UUID string, typically used to identify resources. in: query required: false description: Filter results by location ID. Payment-Intent-Id: name: payment_intent_id in: path required: true description: The unique identifier of the payment intent. schema: $ref: "#/components/schemas/Payment-Intent-Id" schemas: Order-Amount: type: integer description: >- The order total expressed in minor currency units, according to the [ISO 4217 standard](https://en.wikipedia.org/wiki/ISO_4217). For example, `7034` in `EUR` corresponds to €70.34. :::info Conversion between major and minor units varies by currency. For instance, `100` minor units equal £1.00 in `GBP`, whereas in `ISK` they represent 100 units. For more details, see the [ISO 4217 standard](https://en.wikipedia.org/wiki/ISO_4217). ::: Currency: type: string format: ISO 4217 minLength: 3 maxLength: 3 description: |- [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code in upper case. :::info For more information about the supported currencies, see: [Help Center](https://help.revolut.com/business/help/merchant-accounts/payments/in-which-currencies-can-i-accept-payments/). ::: Settlement-Currency: type: string description: |- [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code in upper case. If `settlement_currency` is different from the value of `currency`, the money will be exchanged when the amount is settled to your merchant account. In case of a refund or chargeback, the money will be exchanged to the order's initial `currency`. If `settlement_currency` is not specified, this value is taken from `currency`. :::info For more information about the supported currencies, see: [Help Center](https://help.revolut.com/business/help/merchant-accounts/payments/in-which-currencies-can-i-accept-payments/). ::: Order-Description: type: string description: The description of the order. Full-Name: type: string description: The full name of the customer. Phone: type: string description: The phone number of the customer in [E.164 format](https://en.wikipedia.org/wiki/E.164). Email: type: string format: email description: The email address of the customer. Date-Of-Birth: type: string format: date description: The birth date of the customer. Customer-v2: type: object description: >- Object containing information about a customer. If you have it, we strongly advise providing at least either `id`, `phone`, or `email`. Using the [Customers operations](/docs/api/merchant#tag-customers), you can manage customer instances. The following behaviours apply to different use cases: | Use case | API behavior | | -------- | ------------ | | Existing customer | If `id` was provided, we ignore other customer details and associate the customer with the order.

If either `email`, `phone`, or `full_name` was provided (without an existing customer's `id`), we always create a new customer, irrespective of another, existing customer object having the same details. | | New customer | If either `email`, `phone`, or `full_name` was provided, we create a new customer, irrespective of another customer object having the same details.

If `id` of a non-existent customer was provided, we return a `404` error, irrespective of other details provided. | :::note To avoid unintentional duplication of customer records, search for an existing customer by email or phone using the [List customers](/docs/api/merchant#retrieve-customer-list) endpoint first, then provide `customer.id` in the order. ::: properties: id: type: string format: uuid description: >- Permanent ID of a customer used to retrieve, update, delete a customer. This ID can also be used to link customer to an order. :::note If you provide the customer's ID during order creation, no other customer data is required, they will be parsed automatically from the referenced customer object. ::: full_name: $ref: "#/components/schemas/Full-Name" phone: $ref: "#/components/schemas/Phone" email: $ref: "#/components/schemas/Email" date_of_birth: $ref: "#/components/schemas/Date-Of-Birth" Address-v2: type: object description: Object containing address details. properties: street_line_1: type: string description: Street line 1 information. maxLength: 100 street_line_2: type: string description: Street line 2 information. maxLength: 100 region: type: string description: The region associated with the address. maxLength: 100 city: type: string description: The city associated with the address. maxLength: 100 country_code: type: string description: The 2-letter country code of the country associated with the address. maxLength: 2 postcode: type: string description: The postcode associated with the address. maxLength: 100 required: - country_code - postcode Enforce-Challenge-v2: type: string description: >- The enforce challenge mode. `automatic` is used by default. | Parameter value | Description | | --------------- | ----------- | | `automatic` | The payments created for an order will have challenge requirement calculated by our fraud mechanisms. Not all payments will trigger a 3DS challenge. | | `forced` | The payments created for an order will always require a 3DS challenge. Currently only supported for card payments. | default: automatic enum: - automatic - forced Capture-Mode-v2: type: string description: >- The capture mode of the order. `automatic` is used by default. | Parameter value | Description | | --------------- | ----------- | | `automatic` | The order is captured automatically after payment authorisation. | | `manual` | The order is not captured automatically. You must manually capture the order later. | :::info For more information, see [Capture an order](/docs/api/merchant#capture-order). ::: default: automatic enum: - automatic - manual Authorisation-Type: type: string description: >- The type of authorisation for the order. Used with manual capture mode. If omitted, `final` is used by default. ### Pre-authorisation Pre-authorisation allows you to reserve funds on a customer's card without immediately capturing them. This is useful for scenarios like: - Hotel bookings where the final amount may vary - Car rentals where additional charges may apply - Deposits that need to be held temporarily | Parameter value | Description | | --------------- | ----------- | | `final` | Standard authorisation for immediate or near-immediate capture. | | `pre_authorisation` | Reserve funds for later capture, used with manual capture mode. | :::note Pre-authorisation must be used with `capture_mode: manual`. For more information, see [Capture an order](/docs/api/merchant#capture-order). ::: default: final enum: - final - pre_authorisation Cancel-Authorised-After: type: string format: duration description: >- Automatic cancellation period for uncaptured orders, specified in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. After this period, the authorised payment is automatically cancelled and the order is cancelled. Maximum: 7 days = `P7D`. :::note The following limitations apply: - Cannot be a negative value. - Cannot be updated if the new value is less than or equal to the elapsed time since authorisation. **Failing scenario:** - Original value: 7 days - Time since authorisation: 3 days - Update value: 2 days In this scenario, an error is returned. **Successful scenario:** - Original value: 7 days - Time since authorisation: 3 days - Update value: 4 days In this scenario, the parameter can be updated. - Cannot be updated if cancellation is ≤ 30 minutes away. **Failing scenario:** - Original value: 12 hours - Time since authorisation: 11 hours 40 minutes In this scenario, an error is returned. **Successful scenario:** - Original value: 12 hours - Time since authorisation: 11 hours 20 minutes In this scenario, the parameter can be updated. ::: Expire-Pending-After: type: string format: duration description: >- Automatic expiration period for pending orders, specified in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. Orders in `pending` state will be automatically failed if they stay unpaid for longer than the period specified. When the order expires, it transitions to the `failed` state and an `ORDER_FAILED` webhook event is triggered. :::note - This field can only be set during order creation and cannot be updated afterward. - Must be between `PT1M` (1 minute) and `PT720H` (30 days). - Cannot be a negative value. ::: examples: - PT15M Location-Id: type: string format: uuid description: >- Unique ID representing the location where merchants sells products. :::info For more information, see: [Locations](/docs/api/merchant#tag-locations). ::: Metadata: type: object description: >- Additional information to track your orders in your system, by providing custom metadata using `"" : ""` pairs. :::warning **Restrictions:** - Both keys and values must be `string`s - Values cannot be `null`. - Max number of key-value pairs: `50` - Max length of values: `500` characters - Format of keys: Must start with a letter and contain only letters, digits, and underscores. Max 40 characters. Pattern: `^[a-zA-Z][a-zA-Z\\d_]{0,39}$` ::: maxProperties: 50 additionalProperties: type: string maxLength: 500 description: Additional metadata value provided with the corresponding metadata key. examples: - order_reference: ORD-12345 customer_segment: premium internal_note: VIP customer - priority handling Industry-Data-Type: type: string enum: - airline - car_rental - crypto - event - lodging - marketplace description: >- Type of the industry-specific data object, determining what additional data is expected. Available types: | Object type | Description | | ------------- | ----------- | | `airline` | Object containing information about a specific airline ticket purchase. | | `car_rental` | Object containing information about a car rental booking associated with the order. | | `crypto` | Object containing information about crypto transactions associated with the order. | | `marketplace` | This object is required by Mastercard and Visa for merchants operating as marketplaces under the **Merchant Category Code (MCC):** `5262`. The marketplace object ensures compliance with the card schemes' regulations by providing detailed information about the subseller involved in the transaction. | | `event` | Object containing information about event ticket bookings associated with the order. | | `lodging` | Object containing information about lodging bookings associated with the order. | Booking-Id: type: string description: >- A unique identifier provided by the merchant associated with the order. This `booking_id` is used to reference and correlate booking information with the Merchant API and the merchant's internal system. Refundability: type: string enum: - refundable - non_refundable - partially_refundable description: Parameter indicating whether the booking is refundable, partially refundable, or not refundable. Passenger: type: object properties: first_name: type: string description: Passenger's first name. last_name: type: string description: Passenger's last name. required: - first_name - last_name Passengers: type: array description: Array containing information of passengers associated with the booking. items: $ref: "#/components/schemas/Passenger" Journey-Leg: type: object properties: sequence: type: integer description: >- Sequence of the journey legs. Increment by 1 for each flight included in the ticket. For example: For a `FRA > LHR > DUB > LHR > FRA` journey the sequence will be assigned as: - `FRA > LHR`: 1 - `LHR > DUB`: 2 - `DUB > LHR`: 3 - `LHR > FRA`: 4 departure_airport_code: type: string description: The [IATA](https://www.iata.org/en/services/codes) 3-letter airport code for the departure airport. arrival_airport_code: type: string description: The [IATA](https://www.iata.org/en/services/codes) 3-letter airport code for the arrival airport. flight_number: type: string description: The flight identifier, without airline code. fare_base_code: type: string description: The fare base code for the given journey leg. travel_date: type: string format: date-time description: The UTC date and time of the flight departure for the given journey leg. airline_name: type: string description: The name of the airline associated with the journey leg. airline_code: type: string description: The IATA 2-letter accounting code identifying the airline associated with the journey leg. pnr: type: string format: alphanumeric pattern: ^[a-zA-Z0-9]*$ maxLength: 20 description: >- The Passenger Name Record (PNR) for the journey leg issued by the airline. PNR is a unique identifier for the booking, acting as a digital certificate allowing passengers to retrieve or manage their booking details. :::warning This is a required field for OTAs. ::: required: - sequence - departure_airport_code - arrival_airport_code - travel_date - airline_name - airline_code Journey-Legs: type: array description: >- Array containing information of journey legs associated with the booking. :::info This field is required for activating **Revolut Flight Alerts** functionalities within the Revolut app. This information is used to compile a tracking widget that provides real-time updates on flight status and sends notifications, such as a check-in reminders, boarding alerts, and notifications for cancellations or delays. To enable the widget the following fields are required on order creation or update, before capturing the order: ``` sequence, departure_airport_code, arrival_airport_code, flight_number, travel_date, airline_name, airline_code, ``` ::: items: $ref: "#/components/schemas/Journey-Leg" Airline-Data: type: object description: |- Object containing additional information about an airline booking associated with the order. Use this object to provide required data to enable **Revolut Flight Alerts**. This feature allows users to receive real-time flight updates such as check-in reminders, boarding alerts, and notifications for cancellations or delays in the Revolut app. To enable **Revolut Flight Alerts** functionalities in the Revolut app, the following fields are **required** on order creation or update, before capturing the order: ``` tickets_purchase, journey_legs, booking_url ``` :::note These are the specific data field requirements for merchants who must provide airline data. Note that these requirements can be extended on a case by case basis as decided by Revolut. | Required for airline/charter merchants | Required for OTA merchants | | -------------------------------------- | -------------------------- | |
  • `booking_id`
  • `fulfillment_date`
  • `passengers[].first_name`
  • `passengers[].last_name`
  • `journey_legs[].pnr`
  • `journey_legs[].sequence`
  • `journey_legs[].flight_number`
  • `journey_legs[].travel_date`
  • `journey_legs[].airline_code`
  • `journey_legs[].departure_airport_code`
  • `journey_legs[].arrival_airport_code`
|
  • `booking_id`
  • `fulfillment_date`
  • `passengers[].first_name`
  • `passengers[].last_name`
  • `journey_legs[].pnr`
  • `journey_legs[].arrival_airport_code`
| ::: properties: type: $ref: "#/components/schemas/Industry-Data-Type" booking_id: $ref: "#/components/schemas/Booking-Id" fulfillment_date: type: string format: date-time description: >- The UTC date and time of the final journey leg. :::warning The following limitations apply: - When creating or updating an order, `fulfillment_date` cannot be set to a date in the past. - When updating an order, if the current `fulfillment_date` value is already in the past, it cannot be modified. The date must remain as is to maintain data integrity for completed transactions. ::: tickets_purchase: type: boolean description: >- Flag indicating whether the order includes actual ticket purchases. Set to `true` if the order contains ticket purchases, and `false` if it does not (e.g., it **only** contains seat reservations, or baggage upgrades). :::info This field is required for activating **Revolut Flight Alerts** functionalities within the Revolut app. Provide the info on order creation or update, before capturing the order. ::: ticket_type: type: string enum: - fixed - flexible description: >- The type of the ticket. | Parameter value | Description | | --------------- | ----------- | | `fixed` | Non-modifiable once confirmed. | | `flexible` | Allows modifications or cancellations under specified conditions. | crs_code: type: string maxLength: 4 description: The code of the Computer Reservation System (CRS) used to make the booking and purchase the ticket. ticket_change_indicator: type: string enum: - new - modification description: Parameter indicating whether this order is related to a new ticket reservation or a modification of an existing one. refundability: $ref: "#/components/schemas/Refundability" passengers: $ref: "#/components/schemas/Passengers" journey_legs: $ref: "#/components/schemas/Journey-Legs" booking_url: type: string format: uri pattern: ^https?:\/{2}.+/gi maxLength: 2000 description: >- URL to the online portal for managing the airline booking, which includes check-in functionality. This URL may be a personalised, pre-populated check-in link specific to the user or a generic link, and it is essential for enabling direct access to booking details within the Revolut app. :::info This field is required for activating **Revolut Flight Alerts** functionalities within the Revolut app. Provide the info on order creation or update, before capturing the order. ::: :::warning Restrictions: - Must be a valid URI as defined by [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986) - URI scheme is required and must be either `http` or `https` - URI host is required and cannot be `localhost` or an IP address - Max length: `2000` - Reserved or invalid characters must be percent-encoded (for example, use `%20` instead of a space) ::: required: - type - booking_id Crypto-Transaction: type: object properties: id: type: string maxLength: 255 description: The public transaction hash of the crypto transaction. status: type: string enum: - pending - failed - cancelled - completed description: The status of the crypto transaction. recipient_wallet_id: type: string maxLength: 255 description: >- The wallet ID of the recipient. :::note At least one of the parameters: `recipient_user_id` or `recipient_wallet_id` is required. ::: recipient_user_id: type: string maxLength: 255 description: >- The user ID of the recipient. :::note At least one of the parameters: `recipient_user_id` or `recipient_wallet_id` is required. ::: required: - id - status - recipient Crypto-Transactions: type: object description: >- Object containing information about crypto transactions associated with the order. :::info These are the specific data field requirements for merchants offering crypto services. Note that these requirements can be extended on a case by case basis as decided by Revolut. ``` transactions[].id transactions[].status transactions[].recipient_wallet_id subseller_mcc subseller_url customer.full_name customer.date_of_birth ``` ::: properties: type: $ref: "#/components/schemas/Industry-Data-Type" transactions: type: array description: Array of crypto transaction data associated with the order. items: $ref: "#/components/schemas/Crypto-Transaction" minItems: 1 subseller_mcc: type: string description: >- A string representing the four-digit [Merchant Category Code (MCC)](https://en.wikipedia.org/wiki/Merchant_category_code) of the subseller. This code should be provided when a customer completes a payment on a subseller's website rather than directly on the merchant's website, providing insight into the type of business conducted by the subseller. maxLength: 4 minLength: 4 pattern: ^\d{4}$ subseller_url: type: string format: uri pattern: ^https?:\/{2}.+/gi maxLength: 2000 description: >- The URL of the subseller's website. This parameter should be provided when a customer completes a payment on a subseller's website rather than directly on the merchant's website, providing additional insight into the type of business conducted by the subseller. :::warning Restrictions: - Must be a valid URI as defined by [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986) - URI scheme is required and must be either `http` or `https` - URI host is required and cannot be `localhost` or an IP address - Max length: `2000` - Reserved or invalid characters must be percent-encoded (for example, use `%20` instead of a space) ::: required: - type - transactions Address-v4: type: object description: Details of a physical address. properties: street_line_1: type: string description: Primary address line. maxLength: 100 street_line_2: type: string description: Secondary address line, such as floor and apartment number. maxLength: 100 region: type: string description: State or province of the address. maxLength: 100 city: type: string description: City of the address. maxLength: 100 country_code: type: string pattern: ^[A-Z]{2}$ description: ISO 2-letter country code. minLength: 2 maxLength: 2 country_subdivision_code: type: string pattern: ^[A-Z]{2}-[A-Z0-9]{1,3}$ description: >- The subdivision code represents the state, province, or region within the country, following the [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2) standard. This code uniquely identifies subdivisions within a country. For example, for London in the United Kingdom, use `GB-LND`. :::warning The parameter is required for countries listed on the [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2) page. ::: minLength: 5 maxLength: 6 postcode: type: string description: Postal code of the address. maxLength: 100 required: - street_line_1 - city - country_code - postcode Subseller: type: object description: Information about the subseller related to this order. properties: id: type: string description: The ID of the subseller in the marketplace's internal system. minLength: 1 maxLength: 15 name: type: string description: The business or legal name of the subseller. minLength: 1 maxLength: 50 website: type: string format: uri pattern: ^https?:\/{2}.+/gi maxLength: 255 description: >- The URL of the website of the subseller. :::warning Restrictions: - Must be a valid URI as defined by [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986) - URI scheme is required and must be either `http` or `https` - URI host is required and cannot be `localhost` or an IP address - Max length: `255` - Reserved or invalid characters must be percent-encoded (for example, use `%20` instead of a space) ::: phone: type: string description: The phone number of the subseller. address: $ref: "#/components/schemas/Address-v4" required: - id - name - website - phone - address Marketplace: type: object description: >- This object is required by Mastercard and Visa for merchants operating as marketplaces under the Merchant Category Code (MCC) `5262`. The marketplace object ensures compliance with the card schemes' regulations by providing detailed information about the subseller involved in the transaction. :::info These are the specific data field requirements for merchants who must provide marketplace data. ``` subseller.id subseller.name subseller.phone ``` ::: properties: type: $ref: "#/components/schemas/Industry-Data-Type" subseller: $ref: "#/components/schemas/Subseller" required: - type - subseller Supplier-Payment-Date: type: string format: date-time description: "[ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date and time when the funds are released to merchants." Ticket: type: object description: Object containing information about a ticket associated with the booking. properties: id: type: string description: A unique identifier provided by the merchant associated with the ticket. transferable: type: boolean description: Indicates whether the ticket is transferable to another buyer. refundability: $ref: "#/components/schemas/Refundability" required: - id Event: type: object description: "Object containing booking information about a specific event. " properties: start_date: type: string format: date-time description: "[ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date and time when the event starts." end_date: type: string format: date-time description: "[ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date and time when the event ends." supplier: type: string description: Legal name of the ticket vendor/event organiser. supplier_payment_date: $ref: "#/components/schemas/Supplier-Payment-Date" name: type: string description: The name of the event. location: type: object description: The address of the event location. properties: street_line_1: type: string description: Primary address line. maxLength: 100 street_line_2: type: string description: Secondary address line, such as floor and apartment number. maxLength: 100 region: type: string description: State or province of the address. maxLength: 100 city: type: string description: City of the address. maxLength: 100 country_code: type: string pattern: ^[A-Z]{2}$ description: ISO 2-letter country code. minLength: 2 maxLength: 2 postcode: type: string description: Postal code of the address. maxLength: 100 required: - street_line_1 - city - country_code - postcode category: type: string enum: - concert - conference - convention - exhibition - festival - party - performance - other description: The type of the event. market: type: string enum: - primary - secondary description: >- Indicates the relationship between the ticket vendor and the event organiser. | Parameter value | Description | | --------------- | ----------- | | `primary` | The merchant is the organiser and primary distributor of the tickets. | | `secondary` | The merchant is a reseller, only distributing the tickets. | tickets: type: array items: $ref: "#/components/schemas/Ticket" description: A list of tickets associated with the booking. Events: type: object description: >- Object containing booking information for a list of event tickets associated with the order. :::info These are the specific data field requirements for merchants who must provide event data. Note that these requirements can be extended on a case by case basis as decided by Revolut. ``` booking_id events[].start_date events[].end_date events[].supplier events[].tickets[].id ``` ::: properties: type: $ref: "#/components/schemas/Industry-Data-Type" booking_id: $ref: "#/components/schemas/Booking-Id" events: type: array description: A list of events associated with the booking. items: $ref: "#/components/schemas/Event" required: - type - booking_id Guest: type: object properties: first_name: type: string description: Guest's first name. last_name: type: string description: Guest's last name. required: - first_name - last_name Guests: type: array items: $ref: "#/components/schemas/Guest" description: List of guests associated with the booking. Lodging: type: object description: >- Object containing details of a lodging booking. :::info These are the specific data field requirements for merchants who must provide lodging data. Note that these requirements can be extended on a case by case basis as decided by Revolut. ``` booking_id check_in_date check_out_date supplier_payment_date ``` ::: properties: type: $ref: "#/components/schemas/Industry-Data-Type" booking_id: $ref: "#/components/schemas/Booking-Id" check_in_date: type: string format: date-time description: "[ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date and time of the check-in." check_out_date: type: string format: date-time description: "[ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date and time of the check-out." supplier_payment_date: $ref: "#/components/schemas/Supplier-Payment-Date" category: type: string enum: - bed_and_breakfast - hostel - hotel - short_term_rental - other description: The type of the accommodation associated with the booking. booking_type: type: string enum: - fixed - flexible description: >- Indicates whether the booking terms are fixed or flexible. | Parameter value | Description | | --------------- | ----------- | | `fixed` | Non-modifiable once confirmed. | | `flexible` | Allows modifications or cancellations under specified conditions. | refundability: $ref: "#/components/schemas/Refundability" location: type: object description: Address of the accommodation. properties: street_line_1: type: string description: Primary address line. maxLength: 100 street_line_2: type: string description: Secondary address line, such as floor and apartment number. maxLength: 100 region: type: string description: State or province of the address. maxLength: 100 city: type: string description: City of the address. maxLength: 100 country_code: type: string pattern: ^[A-Z]{2}$ description: ISO 2-letter country code. minLength: 2 maxLength: 2 postcode: type: string description: Postal code of the address. maxLength: 100 required: - street_line_1 - city - country_code - postcode guests: $ref: "#/components/schemas/Guests" required: - type - booking_id Industry-Data: type: object description: >- Object containing industry-specific information associated with the order. :::info In the following cases, industry-specific info is required. Omitting this information may trigger additional scrutiny and risk mitigation actions by the Revolut risk team. | Transaction type | Required for | | ---------------- | ----------- | | `airline` | Airlines and Online Travel Agencies (OTAs). | | `crypto` | Crypto merchants. | | `marketplace` | Marketplace merchants. | | `event` | Event ticket sellers. | | `lodging` | Lodging providers and OTAs. | ::: discriminator: propertyName: type mapping: airline: "#/components/schemas/Airline-Data" crypto: "#/components/schemas/Crypto-Transactions" marketplace: "#/components/schemas/Marketplace" event: "#/components/schemas/Events" lodging: "#/components/schemas/Lodging" oneOf: - $ref: "#/components/schemas/Airline-Data" - $ref: "#/components/schemas/Crypto-Transactions" - $ref: "#/components/schemas/Marketplace" - $ref: "#/components/schemas/Events" - $ref: "#/components/schemas/Lodging" Merchant-Order-Url: type: string format: uri pattern: ^https?:\/{2}.+/gi maxLength: 2000 description: >- The URL of the order stored in the merchant's order management system. This URL will be included in the order confirmation email for payments made via Revolut Pay. If specified, this URL will override the default link to the merchant's **Business website** configured in the Revolut Business account. :::warning Restrictions: - Must be a valid URI as defined by [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986) - URI scheme is required and must be either `http` or `https` - URI host is required and cannot be `localhost` or an IP address - Max length: `2000` - Reserved or invalid characters must be percent-encoded (for example, use `%20` instead of a space) ::: Merchant-Order-External-Reference: type: string description: >- Merchant order ID for external reference. Use this field to set the ID that your own system can use to easily track orders. Merchant-Order-Data: type: object description: "Object for providing additional information stored in the merchant's order management system. " properties: url: $ref: "#/components/schemas/Merchant-Order-Url" reference: $ref: "#/components/schemas/Merchant-Order-External-Reference" Upcoming-Payment: type: object description: Object containing information about upcoming payments associated with the order. properties: date: type: string format: date-time description: The date and time in [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601) when the upcoming payment is scheduled to be executed. payment_method_id: type: string description: >- The unique ID of the customer's payment method used to complete the scheduled payment. :::info For more information about operations related to customer's payment methods, see: - [Retrieve payment method list of a customer](/docs/api/merchant#retrieve-payment-method-list) - [Retrieve a customer's payment method](/docs/api/merchant#retrieve-payment-method) - [Update a customer's payment method](/docs/api/merchant#update-payment-method) - [Delete a customer's payment method](/docs/api/merchant#delete-payment-method) ::: required: - date - payment_method_id Redirect-Url: type: string format: uri pattern: ^https?:\/{2}.+/gi maxLength: 2000 description: |- The URL your customer will be redirected to after a successful payment on the hosted checkout page (`checkout_url` parameter's value of the order). :::warning Restrictions: - Must be a valid URI as defined by [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986) - URI scheme is required and must be either `http` or `https` - URI host is required and cannot be `localhost` or an IP address - Max length: `2000` - Reserved or invalid characters must be percent-encoded (for example, use `%20` instead of a space) ::: :::info For more information on how to use the `redirect_url`, see: [Custom redirection via the API](/docs/guides/merchant/accept-payments/online-payments/hosted-checkout-page/api#custom-post-payment-redirection-optional) ::: Statement-Descriptor-Suffix: type: string description: >- You can set a dynamic statement descriptor for your orders by providing a custom suffix. A statement descriptor is the text shown on cardholders' bank or card statements, helping them recognise a transaction or merchant. This field can be used to send extra information with the statement descriptor for card transactions. The complete descriptor is built using the following format: `{base}*{suffix}`, where: - **`{base}`** is the existing descriptor configured in the Revolut Business dashboard (**Settings > Business account > Merchant profile > Statement descriptor**). - **`{suffix}`** is defined by the `statement_descriptor_suffix` field. :::note - If the combined descriptor's length (base + suffix) exceeds the character limits of card scheme providers, the final value will be truncated. For example if the limit is 22 characters, the base descriptor is `"base"` and the suffix is `"testdescriptorsuffix"`, the final descriptor becomes `"base*testdescriptorsuf"`. - The final statement descriptor shown on a cardholder's statement may vary by issuing bank, as some banks apply their own custom formatting or truncation rules. ::: minLength: 1 maxLength: 19 pattern: ^[^*\n\r\\]+$ Order-Creation-v2: type: object description: Object schema containing information about order creation body request parameters. properties: amount: $ref: "#/components/schemas/Order-Amount" currency: $ref: "#/components/schemas/Currency" settlement_currency: $ref: "#/components/schemas/Settlement-Currency" description: $ref: "#/components/schemas/Order-Description" customer: $ref: "#/components/schemas/Customer-v2" shipping_address: $ref: "#/components/schemas/Address-v2" enforce_challenge: $ref: "#/components/schemas/Enforce-Challenge-v2" capture_mode: $ref: "#/components/schemas/Capture-Mode-v2" authorisation_type: $ref: "#/components/schemas/Authorisation-Type" cancel_authorised_after: $ref: "#/components/schemas/Cancel-Authorised-After" expire_pending_after: $ref: "#/components/schemas/Expire-Pending-After" location_id: $ref: "#/components/schemas/Location-Id" metadata: $ref: "#/components/schemas/Metadata" industry_data: $ref: "#/components/schemas/Industry-Data" merchant_order_data: $ref: "#/components/schemas/Merchant-Order-Data" upcoming_payment_data: $ref: "#/components/schemas/Upcoming-Payment" redirect_url: $ref: "#/components/schemas/Redirect-Url" statement_descriptor_suffix: $ref: "#/components/schemas/Statement-Descriptor-Suffix" required: - amount - currency Order-Id: type: string format: uuid description: Permanent order ID used to retrieve, capture, cancel, or refund an order after authorization. Order-Token: type: string description: |- Temporary ID for the order, which expires when the payment is authorised. The order `token` is used for [token-based initialisation](/docs/sdks/merchant-web-sdk/initialisation/token-based), and is returned by the `createOrder` callback in the following payment methods: - [Embedded Checkout](/docs/sdks/merchant-web-sdk/payment-methods/embedded-checkout#embedded-checkout-options-interface) - [Revolut Pay](/docs/sdks/merchant-web-sdk/payment-methods/revolut-pay#widget-payments-revolut-pay-options) - [Apple Pay and Google Pay](/docs/sdks/merchant-web-sdk/payment-methods/apple-pay-google-pay#payment-request-options-interface) - [Pay by Bank](/docs/sdks/merchant-web-sdk/payment-methods/pay-by-bank#pay-by-bank-options-interface) Order-Type-v2: type: string description: The type of the order. enum: - payment - payment_request - refund - chargeback - chargeback_reversal - credit_reimbursement Order-State: type: string description: >- The state of the order in its lifecycle. | State | Description | |-------|-------------| | `pending` | Order created, awaiting payment | | `processing` | Payment is being processed | | `authorised` | Payment authorised but not yet captured (for manual capture) | | `completed` | Payment successfully captured and settled | | `cancelled` | Order was cancelled | | `failed` | Payment failed | For more information, see: [Order and payment lifecycle](/docs/guides/merchant/reference/order-lifecycle) enum: - pending - processing - authorised - completed - cancelled - failed examples: - authorised Outstanding-Amount: type: integer description: >- The amount not yet paid for a given order (in minor currency units). For example, `7034` represents €70.34. The value in this field may differ from `amount` if there are partial payments associated with the order. Refunded-Amount: type: integer description: >- The amount that was refunded from the order (in minor currency units). For example, `7034` represents €70.34. This applies to orders that have been refunded (i.e., orders of type `payment` that have a related `refund` order). Payment-Id: type: string format: uuid description: The ID of the payment. Payment-State-v2: type: string description: The status of the payment. enum: - pending - authentication_challenge - authentication_verified - authorisation_started - authorisation_passed - authorised - capture_started - captured - refund_validated - refund_started - cancellation_started - declining - completing - cancelling - failing - completed - declined - soft_declined - cancelled - failed Decline-Reason-v2: type: string description: >- The reason for a `failed` or `declined` payment. A failed or declined payment can result from multiple reasons. To learn more, check our [failure reasons](/docs/guides/merchant/reference/error-codes/decline-reasons). enum: - 3ds_challenge_abandoned - 3ds_challenge_failed_manually - cardholder_name_missing - customer_challenge_abandoned - customer_challenge_failed - customer_name_mismatch - do_not_honour - expired_card - high_risk - insufficient_funds - invalid_address - invalid_amount - invalid_card - invalid_country - invalid_cvv - invalid_email - invalid_expiry - invalid_merchant - invalid_phone - invalid_pin - issuer_not_available - pick_up_card - rejected_by_customer - restricted_card - suspected_fraud - technical_error - transaction_not_allowed_for_cardholder - unknown_card - withdrawal_limit_exceeded Bank-Message: type: string description: The reason for a `failed` or `declined` payment, sent by the financial institution processing the payment. Payment-Created: type: string format: date-time description: The date and time the payment was created. Payment-Updated: type: string format: date-time description: The date and time the payment was last updated. Payment-Token: type: string format: uuid description: >- Temporary token of the payment used to fetch the reward offer during checkout and link user registrations to the given offers. The token is only valid for a limited time. Payment-Amount: type: integer format: int64 minimum: 0 description: >- The payment amount in minor units (e.g., cents). The value of this field depends on the payment type and state. | Payment type | State | Amount value | |--------------|-------|--------------| | Standard payment | Any | Total payment amount | | Pre-authorised payment | `authorisation_started` | New amount being authorised (during increment processing) | | Pre-authorised payment | `authorised` | Currently authorised amount (equals `authorised_amount`) | :::info For pre-authorised payments, see the `authorised_amount` field for tracking the currently authorised amount separately. ::: examples: - 600 Payment-Authorised-Amount: type: integer description: >- The currently authorised amount for this payment (in minor units). For pre-authorised payments with incremental authorization: - Initially equals the `amount` field - Remains unchanged during increment processing - Updates to new amount upon successful increment - Remains at original amount if increment is declined For standard payments, this field may not be present or will equal the `amount` field. examples: - 600 Payment-Settled-Amount: type: integer description: The amount of the settled payment (minor currency unit). For example, `7034` stands for €70.34. Payment-Settled-Currency: type: string description: |- The currency of the settled payment. [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code in upper case. :::info For more information about the supported currencies, see: [Help Center](https://help.revolut.com/business/help/merchant-accounts/payments/in-which-currencies-can-i-accept-payments/). ::: Payment-Method-Type: type: string enum: - apple_pay - card - google_pay - revolut_pay_card - revolut_pay_account - sepa_direct_debit description: >- The type of payment method used to pay for the order. Available values: | Payment method `type` | Description | | --------------------- | ----------- | | `apple_pay` | The customer paid the order using Apple Pay. | | `card` | The customer paid the order using their credit or debit card. | | `google_pay` | The customer paid the order using Google Pay. | | `revolut_pay_card` | The customer paid the order via Revolut Pay using their credit or debit card. | | `revolut_pay_account` | The customer paid the order via Revolut Pay using their Revolut account. | | `sepa_direct_debit` | The customer paid the order using SEPA Direct Debit. | Card-Checks-v2: type: object description: The details of the check for card payment. Only for orders with successful payments. properties: three_ds: type: object description: >- The details of the 3D Secure check. Only for orders with successful payments. :::note Not returned for Apple Pay and Google Pay payments. ::: properties: eci: type: string description: The Electronic Commerce Indicator (ECI) value corresponds to the authentication result and indicates the level of security used when the payment information was provided. state: type: string description: The result of 3D Secure check. enum: - verified - failed - challenge version: type: integer description: The 3D Secure version. cvv_verification: type: string description: |- The result of CVV verification. | Parameter value | Description | | ----- | ----------- | | `match` | CVV matches the card's CVV | | `not_match` | CVV does not match the card's CVV | | `incorrect` | CVV format is incorrect for this type of card | | `not_processed` | CVV verification was not performed | enum: - match - not_match - incorrect - not_processed address: type: string description: The result of address verification. enum: - match - not_match - n_a - invalid postcode: type: string description: The result of postcode verification. enum: - match - not_match - n_a - invalid cardholder: type: string description: The result of cardholder verification. enum: - match - not_match - n_a - invalid Authorisation-Code: type: string description: >- The authorisation code (or auth code) is a short, alphanumeric code returned by the cardholder's issuing bank to the merchant's terminal or payment gateway. It serves as confirmation that the transaction has been approved and funds are available. pattern: ^[a-zA-Z0-9]{2,6}$ minLength: 2 maxLength: 6 examples: - T483XF Arn: type: string description: |- Acquirer Reference Number (ARN) of the payment. :::note Only returned for refund payments made by a card. ::: minLength: 23 maxLength: 23 examples: - "74839572049583726403928" Capture-Deadline: type: string format: date-time description: >- The date and time by which the payment must be captured. After this deadline, the authorised funds may be automatically released by the card issuer. Fingerprint: type: string minLength: 44 maxLength: 44 description: >- A unique identifier for a payment method, always 44 characters long. This fingerprint can be used to uniquely identify various payment methods. #### Fingerprint generation | Payment method | Description | | -------- | ----------- | | **All payment methods** | A fingerprint is generated for all payment methods, including cards, Revolut Pay (card, account-to-account payments), Apple Pay, and Google Pay. | | **Cards (Revolut Pay & Card Gateway)** | For cards, the fingerprint is based on the PAN. Cards processed via Revolut Pay and our card gateway will share the same fingerprint. Renewed cards (new expiry/CVV) retain the same fingerprint for efficient blocking. | | **Apple Pay & Google Pay** | Since Apple Pay and Google Pay provide us Device PANs (DPAN), the fingerprint is based on the DPAN provided by Apple/Google, not the connected card's PAN. This means that a new DPAN (and fingerprint) is generated for cards in case they are re-added to the customer's digital wallet, or added to different devices. | #### Detecting duplicate payment methods Fingerprints are a valuable tool for detecting duplicate payment methods by identifying if a payment method has been seen before. This capability, in turn, helps in preventing various types of misuse (e.g., exploitation of free trials, or association with known problematic accounts, which can be a form of fraud). To effectively use fingerprints for this purpose, you will need to create and maintain your own lists (e.g., blocklists of known problematic fingerprints, allowlists for trusted customers, or tracking frequently used fingerprints). The ideal way to utilise fingerprints is by combining them with a manual capture process. While automatic capture with subsequent refunds for problematic payments is possible, manual capture based on fingerprint validation is recommended. During your manual capture workflow, after a payment was authorised: - Check the fingerprint status by comparing it against your maintained lists and internal business rules. - If you decide to proceed with the payment (e.g., the fingerprint is not on a blocklist, or matches a trusted customer's previous payment method): [Capture the order](/docs/api/merchant#capture-order). - If you decide not to proceed with the payment (e.g., the fingerprint matches a known fraudulent fingerprint, or exhibits suspicious patterns): [Cancel the order](/docs/api/merchant#cancel-order). examples: - 1JAllfQY4POhBV8DaddAQ4LC5RbMP8LMLvUdJW4s5JY= Network-Transaction-Id: type: string description: >- The Network Transaction ID (NTI) is a unique identifier assigned by the card scheme (e.g., Visa or Mastercard) to a card transaction. It can be used to trace the transaction across the payment network, link recurring or instalment payments to the original authorisation, and support dispute resolution. Apple-Pay: type: object description: Object containing details of a card used via Apple Pay. properties: id: type: string format: uuid description: >- ID of the saved payment method. :::note The `id` parameter is only returned when the payment method is saved. ::: type: $ref: "#/components/schemas/Payment-Method-Type" card_brand: type: string description: The type of the card. enum: - visa - mastercard - american_express funding: type: string description: The type of card funding. enum: - credit - debit - prepaid card_country_code: type: string description: The 2-letter country code of the country where the card was issued. card_bin: type: string description: The BIN of the card. minLength: 6 maxLength: 6 card_last_four: type: string description: The last four digits of the card number. minLength: 4 maxLength: 4 card_expiry: type: string format: MM/YY description: The expiry date of the card in the format of MM/YY. cardholder_name: type: string description: The name of the cardholder. checks: $ref: "#/components/schemas/Card-Checks-v2" authorisation_code: $ref: "#/components/schemas/Authorisation-Code" arn: $ref: "#/components/schemas/Arn" capture_deadline: $ref: "#/components/schemas/Capture-Deadline" fingerprint: $ref: "#/components/schemas/Fingerprint" network_transaction_id: $ref: "#/components/schemas/Network-Transaction-Id" required: - type Card: type: object description: Object containing details of the card used for the payment. properties: id: type: string format: uuid description: >- ID of the saved payment method. :::note The `id` parameter is only returned when the payment method is saved. ::: type: $ref: "#/components/schemas/Payment-Method-Type" card_brand: type: string description: The type of the card. enum: - visa - mastercard - american_express funding: type: string description: The type of card funding. enum: - credit - debit - prepaid card_country_code: type: string description: The 2-letter country code of the country where the card was issued. card_bin: type: string description: The BIN of the card. minLength: 6 maxLength: 6 card_last_four: type: string description: The last four digits of the card number. minLength: 4 maxLength: 4 card_expiry: type: string format: MM/YY description: The expiry date of the card in the format of MM/YY. cardholder_name: type: string description: The name of the cardholder. checks: $ref: "#/components/schemas/Card-Checks-v2" authorisation_code: $ref: "#/components/schemas/Authorisation-Code" arn: $ref: "#/components/schemas/Arn" capture_deadline: $ref: "#/components/schemas/Capture-Deadline" fingerprint: $ref: "#/components/schemas/Fingerprint" network_transaction_id: $ref: "#/components/schemas/Network-Transaction-Id" required: - type Google-Pay: type: object description: Object containing details of a card used via Google Pay. properties: id: type: string format: uuid description: >- ID of the saved payment method. :::note The `id` parameter is only returned when the payment method is saved. ::: type: $ref: "#/components/schemas/Payment-Method-Type" card_brand: type: string description: The type of the card. enum: - visa - mastercard - american_express funding: type: string description: The type of card funding. enum: - credit - debit - prepaid card_country_code: type: string description: The 2-letter country code of the country where the card was issued. card_bin: type: string description: The BIN of the card. minLength: 6 maxLength: 6 card_last_four: type: string description: The last four digits of the card number. minLength: 4 maxLength: 4 card_expiry: type: string format: MM/YY description: The expiry date of the card in the format of MM/YY. cardholder_name: type: string description: The name of the cardholder. checks: $ref: "#/components/schemas/Card-Checks-v2" authorisation_code: $ref: "#/components/schemas/Authorisation-Code" arn: $ref: "#/components/schemas/Arn" capture_deadline: $ref: "#/components/schemas/Capture-Deadline" fingerprint: $ref: "#/components/schemas/Fingerprint" network_transaction_id: $ref: "#/components/schemas/Network-Transaction-Id" required: - type Revolut-Pay-Card: type: object description: Object containing details of a card used via Revolut Pay. properties: id: type: string format: uuid description: >- ID of the saved payment method. :::note The `id` parameter is only returned when the payment method is saved. ::: type: $ref: "#/components/schemas/Payment-Method-Type" card_brand: type: string description: The type of the card. enum: - visa - mastercard - american_express funding: type: string description: The type of card funding. enum: - credit - debit - prepaid card_country_code: type: string description: The 2-letter country code of the country where the card was issued. card_bin: type: string description: The BIN of the card. minLength: 6 maxLength: 6 card_last_four: type: string description: The last four digits of the card number. minLength: 4 maxLength: 4 card_expiry: type: string format: MM/YY description: The expiry date of the card in the format of MM/YY. cardholder_name: type: string description: The name of the cardholder. checks: $ref: "#/components/schemas/Card-Checks-v2" authorisation_code: $ref: "#/components/schemas/Authorisation-Code" arn: $ref: "#/components/schemas/Arn" capture_deadline: $ref: "#/components/schemas/Capture-Deadline" fingerprint: $ref: "#/components/schemas/Fingerprint" network_transaction_id: $ref: "#/components/schemas/Network-Transaction-Id" required: - type Revolut-Pay-Account: type: object properties: id: type: string format: uuid description: >- ID of the saved payment method. :::note The `id` parameter is only returned when the payment method is saved. ::: type: $ref: "#/components/schemas/Payment-Method-Type" fingerprint: $ref: "#/components/schemas/Fingerprint" required: - type Sepa-Direct-Debit-Debtor-Iban-Last-Four: type: string description: The last four digits of the debtor's IBAN. minLength: 4 maxLength: 4 Sepa-Direct-Debit-Debtor-Name: type: string description: The full name of the debtor as provided in the mandate. Sepa-Direct-Debit-Mandate-Reference: type: string description: The unique mandate reference generated by Revolut. Include this in pre-debit notifications sent to your customers. Sepa-Direct-Debit: type: object description: |- Object containing details of a SEPA Direct Debit payment. :::info For more information, see: [SEPA Direct Debit server-to-server integration](/docs/guides/merchant/payment-methods/sepa-direct-debit/server-to-server) ::: properties: id: type: string format: uuid description: >- ID of the saved payment method. :::note The `id` parameter is only returned when the payment method is saved for the merchant. ::: type: $ref: "#/components/schemas/Payment-Method-Type" debtor_iban_last_four: $ref: "#/components/schemas/Sepa-Direct-Debit-Debtor-Iban-Last-Four" debtor_name: $ref: "#/components/schemas/Sepa-Direct-Debit-Debtor-Name" mandate_reference: $ref: "#/components/schemas/Sepa-Direct-Debit-Mandate-Reference" required: - type Payment-Method-v2: type: object description: The details of the payment method used to make the payment. discriminator: propertyName: type mapping: apple_pay: "#/components/schemas/Apple-Pay" card: "#/components/schemas/Card" google_pay: "#/components/schemas/Google-Pay" revolut_pay_card: "#/components/schemas/Revolut-Pay-Card" revolut_pay_account: "#/components/schemas/Revolut-Pay-Account" sepa_direct_debit: "#/components/schemas/Sepa-Direct-Debit" oneOf: - $ref: "#/components/schemas/Apple-Pay" - $ref: "#/components/schemas/Card" - $ref: "#/components/schemas/Google-Pay" - $ref: "#/components/schemas/Revolut-Pay-Card" - $ref: "#/components/schemas/Revolut-Pay-Account" - $ref: "#/components/schemas/Sepa-Direct-Debit" Authentication-Challenge-Type: type: string enum: - three_ds - three_ds_fingerprint description: Type of the authentication challenge the payment triggers. Three-Ds: title: three_ds type: object description: Information about the 3DS challenge. properties: type: $ref: "#/components/schemas/Authentication-Challenge-Type" acs_url: type: string format: url description: The URL of the authentication challenge. required: - type - acs_url Three-Ds-Fingerprint: title: three_ds_fingerprint type: object description: Information about the 3DS fingerprint challenge. properties: type: $ref: "#/components/schemas/Authentication-Challenge-Type" fingerprint_url: type: string format: url description: The URL of the fingerprint. (Used only internally by Revolut.) fingerprint_data: type: string format: JSON description: >- Data about the fingerprint used for authentication. (Used only internally by Revolut.) required: - type - fingerprint_url - fingerprint_data Authentication-Challenge: type: object description: >- Details about the authentication challenge that should be performed to complete the authentication process. For more information about Revolut's 3DS solution, see: [3D Secure overview](/docs/guides/merchant/reference/3d-secure). Only returned if the payment's state is `authentication_challenge`. discriminator: propertyName: type mapping: three_ds: "#/components/schemas/Three-Ds" three_ds_fingerprint: "#/components/schemas/Three-Ds-Fingerprint" oneOf: - $ref: "#/components/schemas/Three-Ds" - $ref: "#/components/schemas/Three-Ds-Fingerprint" Payment-Risk-Level: type: string description: |- The risk level of the card. If the risk level is `high`, the payment might be declined. enum: - low - high Fee: type: object properties: type: type: string description: The type of the order fee. enum: - fx - acquiring amount: type: integer description: The amount of the payment fee (minor currency unit). For example, enter `7034` for €70.34 in the field. currency: type: string description: |- The currency of the payment fee. [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code in upper case. :::info For more information about the supported currencies, see: [Help Center](https://help.revolut.com/business/help/merchant-accounts/payments/in-which-currencies-can-i-accept-payments/). ::: Fees: type: array description: The details of the order fee. items: $ref: "#/components/schemas/Fee" Payer: title: Payer type: object description: >- The person who made the payment. This object is present when an email or phone number is provided during the payment flow. Capturing payer details lets you identify exactly who authorised the charge, reach the right person for receipts or refund queries, and support compliance or fraud-review workflows where the paying identity matters. properties: email: $ref: "#/components/schemas/Email" description: The email of the person who made the payment. phone: $ref: "#/components/schemas/Phone" description: The phone number of the payer in [E.164 format](https://en.wikipedia.org/wiki/E.164). Payment-v2: type: object description: >- Represents a payment for an order. For pre-authorised payments, the `authorised_amount` field tracks the currently authorised amount, which may differ from `amount` during incremental authorisation processing. properties: id: $ref: "#/components/schemas/Payment-Id" state: $ref: "#/components/schemas/Payment-State-v2" decline_reason: $ref: "#/components/schemas/Decline-Reason-v2" bank_message: $ref: "#/components/schemas/Bank-Message" created_at: $ref: "#/components/schemas/Payment-Created" updated_at: $ref: "#/components/schemas/Payment-Updated" token: $ref: "#/components/schemas/Payment-Token" amount: $ref: "#/components/schemas/Payment-Amount" authorised_amount: $ref: "#/components/schemas/Payment-Authorised-Amount" currency: $ref: "#/components/schemas/Currency" settled_amount: $ref: "#/components/schemas/Payment-Settled-Amount" settled_currency: $ref: "#/components/schemas/Payment-Settled-Currency" payment_method: $ref: "#/components/schemas/Payment-Method-v2" authentication_challenge: $ref: "#/components/schemas/Authentication-Challenge" billing_address: $ref: "#/components/schemas/Address-v2" risk_level: $ref: "#/components/schemas/Payment-Risk-Level" fees: $ref: "#/components/schemas/Fees" payer: $ref: "#/components/schemas/Payer" required: - id - state - created_at - updated_at - amount Checkout-Url: type: string description: Link to a checkout page hosted by Revolut. format: uri Order-v2: title: Order v2 type: object description: To process the order from a credit or debit card, you create an `Order` object. You can then retrieve, capture, cancel, refund, or pay an order using its unique `id`. Alternatively, you can use its unique `token` to process a card payment with the Revolut Checkout Widget. properties: id: $ref: "#/components/schemas/Order-Id" token: $ref: "#/components/schemas/Order-Token" type: $ref: "#/components/schemas/Order-Type-v2" state: $ref: "#/components/schemas/Order-State" created_at: type: string description: The date and time the order was created. format: date-time updated_at: type: string description: The date and time the order was last updated. format: date-time description: $ref: "#/components/schemas/Order-Description" capture_mode: $ref: "#/components/schemas/Capture-Mode-v2" authorisation_type: $ref: "#/components/schemas/Authorisation-Type" cancel_authorised_after: $ref: "#/components/schemas/Cancel-Authorised-After" amount: $ref: "#/components/schemas/Order-Amount" outstanding_amount: $ref: "#/components/schemas/Outstanding-Amount" refunded_amount: $ref: "#/components/schemas/Refunded-Amount" currency: $ref: "#/components/schemas/Currency" settlement_currency: $ref: "#/components/schemas/Settlement-Currency" customer: $ref: "#/components/schemas/Customer-v2" shipping_address: $ref: "#/components/schemas/Address-v2" payments: type: array description: The details of all the payments that have been made towards this order (successful or unsuccessful). items: $ref: "#/components/schemas/Payment-v2" location_id: $ref: "#/components/schemas/Location-Id" metadata: $ref: "#/components/schemas/Metadata" industry_data: $ref: "#/components/schemas/Industry-Data" merchant_order_data: $ref: "#/components/schemas/Merchant-Order-Data" upcoming_payment_data: $ref: "#/components/schemas/Upcoming-Payment" checkout_url: $ref: "#/components/schemas/Checkout-Url" redirect_url: $ref: "#/components/schemas/Redirect-Url" enforce_challenge: $ref: "#/components/schemas/Enforce-Challenge-v2" statement_descriptor_suffix: $ref: "#/components/schemas/Statement-Descriptor-Suffix" Error-v2: title: Error type: object properties: code: type: string description: >- An identifier that can be used to determine what went wrong. Error codes are not globally unique, but uniqueness is guaranteed within endpoints. message: type: string description: Some human readable text describing what went wrong. timestamp: type: integer description: The [UNIX timestamp](https://www.unixtimestamp.com/) of the date and time the error happened. Order-Update-v2: type: object description: Object schema containing information about order update request. properties: amount: $ref: "#/components/schemas/Order-Amount" currency: $ref: "#/components/schemas/Currency" settlement_currency: $ref: "#/components/schemas/Settlement-Currency" description: $ref: "#/components/schemas/Order-Description" customer: $ref: "#/components/schemas/Customer-v2" shipping_address: $ref: "#/components/schemas/Address-v2" enforce_challenge: $ref: "#/components/schemas/Enforce-Challenge-v2" capture_mode: $ref: "#/components/schemas/Capture-Mode-v2" cancel_authorised_after: $ref: "#/components/schemas/Cancel-Authorised-After" metadata: $ref: "#/components/schemas/Metadata" industry_data: $ref: "#/components/schemas/Industry-Data" merchant_order_data: $ref: "#/components/schemas/Merchant-Order-Data" upcoming_payment_data: $ref: "#/components/schemas/Upcoming-Payment" redirect_url: $ref: "#/components/schemas/Redirect-Url" statement_descriptor_suffix: $ref: "#/components/schemas/Statement-Descriptor-Suffix" Address: title: Address type: object properties: street_line_1: type: string description: Street line 1 information. street_line_2: type: string description: Street line 2 information. region: type: string description: The region associated with the address. city: type: string description: The city associated with the address. country_code: type: string description: The country associated with the address. postcode: type: string description: The postcode associated with the address. required: - country_code - postcode Simplified-Order: title: Simplified-Order type: object properties: id: type: string description: Permanent order ID used to retrieve, capture, cancel, or refund an order after authorisation. type: type: string description: The type of the order. enum: - PAYMENT - REFUND - CHARGEBACK state: type: string description: >- The state of the order. :::info For more information about the order lifecycle, see: [Order and payment lifecycle](/docs/guides/merchant/reference/order-lifecycle). ::: enum: - PENDING - PROCESSING - AUTHORISED - COMPLETED - CANCELLED - FAILED created_at: type: string description: The date and time the order was created. format: date-time updated_at: type: string description: The date and time the order was last updated. format: date-time completed_at: type: string description: The date and time the order was completed. format: date-time description: type: string description: The description of the order. capture_mode: type: string description: >- The capture mode of the order. `AUTOMATIC` is used by default. - `AUTOMATIC`: The order is captured automatically after payment authorisation. - `MANUAL`: The order is not captured automatically. You must manually capture the order later. For more information, see [Capture an order](/docs/api/merchant#capture-order). settlement_currency: type: string description: |- [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code in upper case. All payments made towards this order are settled in this currency. :::info For more information about the supported currencies, see: [Help Center](https://help.revolut.com/business/help/merchant-accounts/payments/in-which-currencies-can-i-accept-payments/). ::: merchant_order_ext_ref: type: string description: >- Merchant order ID for external reference. Use this field to set the ID that your own system can use to easily track orders. customer_id: type: string description: The ID of the [customer](/docs/api/merchant#tag-customers) associated with this order. email: type: string description: The email of the customer. format: email phone: type: string description: The phone number of the customer. order_amount: type: object description: The amount and currency of the order. required: - value - currency properties: value: type: integer description: The amount of the order (minor currency unit). For example, enter `7034` for €70.34 in the field. currency: type: string description: |- The currency of the order. [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code in upper case. :::info For more information about the supported currencies, see: [Help Center](https://help.revolut.com/business/help/merchant-accounts/payments/in-which-currencies-can-i-accept-payments/). ::: order_outstanding_amount: type: object description: The amount and currency outstanding to be paid for this order. properties: value: type: integer description: The amount of the order (minor currency unit) that is outstanding. For example, enter `7034` for €70.34 in the field. currency: type: string description: |- The currency of the amount that is outstanding. [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code in upper case. :::info For more information about the supported currencies, see: [Help Center](https://help.revolut.com/business/help/merchant-accounts/payments/in-which-currencies-can-i-accept-payments/). ::: shipping_address: $ref: "#/components/schemas/Address" required: - id - type - state - created_at - updated_at - order_amount description: The `Order` object returned when you retrieve a list of orders. Error: title: Error type: object properties: errorId: type: string description: The ID of the error. You can share this ID with Revolut support for troubleshooting. timestamp: type: integer description: The date and time the error happened. required: - errorId - timestamp Order-Capture-Amount: type: integer description: >- Specify an amount to capture, in minor currency units. The amount must not exceed the authorised amount. An order can only be captured once. Partial capture is supported by sending an amount lower than the authorised amount. The uncaptured amount will be voided. If you resend a capture request for an order that is already captured, no additional capture is performed. Resending with the same amount returns the current order state, while resending with a different amount returns an error. If not provided, it defaults to the authorised amount (full capture will be executed). Order-Capture: type: object description: Order capture request parameters. properties: amount: $ref: "#/components/schemas/Order-Capture-Amount" Order-Refund: type: object properties: amount: type: integer description: >- The amount of the refund (minor currency unit). For example, enter `7034` for €70.34 in the field. This amount can't exceed the remaining amount of the original order. To get the refundable amount, subtract the `value` of the `refunded_amount` from the `value` of the `order_amount` in the original order. See [Retrieve an order](/docs/api/merchant#retrieve-order). description: type: string description: The description of the refund. merchant_order_ext_ref: $ref: "#/components/schemas/Merchant-Order-External-Reference" metadata: $ref: "#/components/schemas/Metadata" required: - amount Capture-Mode: type: string description: >- The capture mode of the order. `AUTOMATIC` is used by default. - `AUTOMATIC`: The order is captured automatically after payment authorisation. - `MANUAL`: The order is not captured automatically. You must manually capture the order later. For more information, see [Capture an order](/docs/api/merchant#capture-order). enum: - AUTOMATIC - MANUAL Payment-Method: title: Payment-Method type: object description: The details of the payment method used to make the payment. properties: id: type: string description: The ID of the payment method. This value is present only if the payment method was previously saved. format: uuid type: type: string description: The type of the payment. enum: - CARD - REVOLUT card: type: object description: The details of the card. Only present for payments with `payment_method.type` = `CARD`. properties: card_brand: type: string description: The type of the card. enum: - VISA - MASTERCARD funding: type: string description: The type of card funding. enum: - CREDIT - DEBIT - PREPAID card_country: type: string description: The country where the card was issued. card_bin: type: string description: The BIN of the card. minLength: 6 maxLength: 6 card_last_four: type: string description: The last four digits of the card. minLength: 4 maxLength: 4 card_expiry: type: string description: The expiry date of the card in the format of MM/YY. cardholder_name: type: string description: The name of the cardholder. checks: type: object description: The details of the check for card payment. Only for orders with successful payments. properties: three_ds: type: object description: The details of the 3D Secure check. Only for orders with successful payments. properties: state: type: string description: The result of 3D Secure check. enum: - VERIFIED - FAILED - CHALLENGE version: type: integer description: The 3D Secure version. cvv_verification: type: string description: >- The result of CVV verification. | Verification result | Description | | ------------------- | ----------- | | `MATCH` | Provided CVV matches the card's CVV | | `NOT_MATCH` | Provided CVV does not match the card's CVV | | `INCORRECT` | Provided CVV format is incorrect for this type of card | | `NOT_PROCESSED` | CVV verification was not performed | enum: - MATCH - NOT_MATCH - INCORRECT - NOT_PROCESSED address: type: string description: The result of address verification. enum: - MATCH - NOT_MATCH - N_A - INVALID postcode: type: string description: The result of postcode verification. enum: - MATCH - NOT_MATCH - N_A - INVALID cardholder: type: string description: The result of cardholder verification. enum: - MATCH - NOT_MATCH - N_A - INVALID Payment: title: Payment type: object description: "" properties: id: type: string description: The ID of the payment. state: type: string description: The state of the payment. enum: - PROCESSING - AUTHORISED - CAPTURED - COMPLETED - FAILED - DECLINED - CANCELLED failure_reason: type: string description: |- The reason for a `FAILED` or `DECLINED` payment. A failed or declined payment can result from multiple reasons. To learn more, check our [decline reasons](/docs/guides/merchant/reference/error-codes/decline-reasons). enum: - do_not_honour - 3ds_challenge_abandoned - 3ds_challenge_failed - 3ds_challenge_failed_manually - insufficient_funds - transaction_not_allowed_for_cardholder - high_risk - cardholder_name_missing - unknown_card - invalid_card - invalid_email - restricted_card - expired_card - rejected_by_customer - withdrawal_limit_exceeded - pick_up_card - invalid_amount created_at: type: string description: The date and time the payment was created. format: date-time updated_at: type: string description: The date and time the payment was last updated. format: date-time token: type: string description: |- Temporary token of the payment used to fetch the reward offer during checkout and link user registrations to the given offers. The token is only valid for a limited time. amount: type: object description: The amount and currency of the payment. required: - value - currency properties: value: type: integer description: >- The amount of the payment (minor currency unit). For example, enter `7034` for €70.34 in the field. currency: type: string description: |- The currency of the payment. [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code in upper case. :::info For more information about the supported currencies, see: [Help Center](https://help.revolut.com/business/help/merchant-accounts/payments/in-which-currencies-can-i-accept-payments/). ::: settled_amount: type: object description: The amount and currency of the settled payment. properties: value: type: integer description: >- The amount of the settled payment (minor currency unit). For example, enter `7034` for €70.34 in the field. currency: type: string description: |- The currency of the settled payment. [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code in upper case. :::info For more information about the supported currencies, see: [Help Center](https://help.revolut.com/business/help/merchant-accounts/payments/in-which-currencies-can-i-accept-payments/). ::: payment_method: $ref: "#/components/schemas/Payment-Method" billing_address: $ref: "#/components/schemas/Address" risk_level: type: string description: |- The risk level of the card. If the risk level is `HIGH`, the payment might be declined. enum: - LOW - HIGH fees: type: array description: The details of the order fee. items: type: object properties: type: type: string description: The type of the order fee. enum: - FX - ACQUIRING amount: type: object description: The amount and currency of the payment fee. properties: value: type: integer description: |- The amount of the payment fee (minor currency unit). For example, enter `7034` for €70.34 in the field. currency: type: string description: |- The currency of the payment fee. [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code in upper case. :::info For more information about the supported currencies, see: [Help Center](https://help.revolut.com/business/help/merchant-accounts/payments/in-which-currencies-can-i-accept-payments/). ::: required: - id - state - created_at - updated_at - amount Order-Related: title: Order-Related type: object properties: id: type: string description: The ID of the related order. You can use this ID to get more information about the related order using the [Retrieve an order](/docs/api/merchant#retrieve-order) operation. type: type: string description: The type of the related order. enum: - PAYMENT - REFUND - CHARGEBACK state: type: string description: The state of the related order. enum: - PENDING - PROCESSING - AUTHORISED - COMPLETED - CANCELLED - FAILED amount: type: object description: The amount and currency of the related order. properties: value: $ref: "#/components/schemas/Order-Amount" currency: $ref: "#/components/schemas/Currency" Merchant-Order-Uri: type: string format: uri pattern: ^https?:\/{2}.+/gi maxLength: 2000 description: >- The URI of the order stored in the merchant's order management system. This URI will be included in the order confirmation email for payments made via Revolut Pay. If specified, this URI will override the default link to the merchant's **Business website** configured in the Revolut Business account. :::warning Restrictions: - Must be a valid URI as defined by [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986) - URI scheme is required and must be either `http` or `https` - URI host is required and cannot be `localhost` or an IP address - Max length: `2000` - Reserved or invalid characters must be percent-encoded (for example, use `%20` instead of a space) ::: Order: title: Order type: object description: >- An Order object helps you through the process of accepting payments from your customers. Create an order for every customer session or while an order is being created in your own system. Then, the order goes through multiple states using the [Revolut Checkout Widget](/docs/sdks/merchant-web-sdk/install-widget) to collect payments from your customers. properties: id: $ref: "#/components/schemas/Order-Id" public_id: type: string description: |- Temporary ID for the order. It expires when the payment is authorized. type: type: string description: The type of the order. enum: - PAYMENT - REFUND - CHARGEBACK state: type: string description: >- The state of the order. :::info For more information about the order lifecycle, see: [Order and payment lifecycle](/docs/guides/merchant/reference/order-lifecycle). ::: enum: - PENDING - PROCESSING - AUTHORISED - COMPLETED - CANCELLED - FAILED created_at: type: string description: The date and time the order was created. format: date-time updated_at: type: string description: The date and time the order was last updated. format: date-time completed_at: type: string description: The date and time the order was completed. format: date-time description: $ref: "#/components/schemas/Order-Description" capture_mode: $ref: "#/components/schemas/Capture-Mode" settlement_currency: $ref: "#/components/schemas/Settlement-Currency" merchant_order_ext_ref: $ref: "#/components/schemas/Merchant-Order-External-Reference" customer_id: type: string description: The ID of the [customer](/docs/api/merchant#tag-customers) associated with this order. email: type: string description: The email of the customer. format: email phone: type: string description: The phone number of the customer. full_name: type: string description: The customer's full name. order_amount: type: object description: The amount and currency of the order. required: - value - currency properties: value: $ref: "#/components/schemas/Order-Amount" currency: $ref: "#/components/schemas/Currency" order_outstanding_amount: type: object description: The amount and currency outstanding to be paid for this order. properties: value: type: integer description: The amount of the order (minor currency unit) that is outstanding. For example, enter `7034` for €70.34 in the field. currency: type: string description: |- The currency of the amount that is outstanding. [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code in upper case. :::info For more information about the supported currencies, see: [Help Center](https://help.revolut.com/business/help/merchant-accounts/payments/in-which-currencies-can-i-accept-payments/). ::: refunded_amount: type: object description: The amount and currency of the refunded order. properties: value: type: integer description: The amount of the refunded order (minor currency unit). For example, enter `7034` for €70.34 in the field. currency: type: string description: |- The currency of the refunded order. [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code in upper case. :::info For more information about the supported currencies, see: [Help Center](https://help.revolut.com/business/help/merchant-accounts/payments/in-which-currencies-can-i-accept-payments/). ::: shipping_address: $ref: "#/components/schemas/Address" payments: type: array description: The details of all the payment attempts that have been made towards this order (successful or unsuccessful). items: $ref: "#/components/schemas/Payment" related: type: array description: The details of related orders. You can use the ID of the related order to [Retrieve the order information](/docs/api/merchant#retrieve-order). items: $ref: "#/components/schemas/Order-Related" metadata: $ref: "#/components/schemas/Metadata" checkout_url: $ref: "#/components/schemas/Checkout-Url" merchant_order_uri: $ref: "#/components/schemas/Merchant-Order-Uri" required: - id - type - state - created_at - updated_at - order_amount RPay-Account: properties: type: type: string enum: - card - revolut_pay description: The type of payment method used to pay for the order. subtype: type: string enum: - revolut_account - card description: Indicates whether the customer used their card or Revolut account via Revolut Pay. id: type: string format: uuid description: |- ID of the saved payment method. :::note The `id` parameter is only returned if the payment method is saved. ::: required: - type - subtype RPay-Card: properties: type: type: string enum: - card - revolut_pay description: The type of payment method used to pay for the order. subtype: type: string enum: - revolut_account - card description: Indicates whether the customer used their card or Revolut account via Revolut Pay. id: type: string format: uuid description: |- ID of the saved payment method. :::note The `id` parameter is only returned if the payment method is saved. ::: brand: type: string description: The type of the card. last_four: type: string description: The last four digits of the card number. required: - type - subtype Revolut-Pay: discriminator: propertyName: subtype mapping: revolut_pay_account: "#/components/schemas/RPay-Account" revolut_pay_card: "#/components/schemas/RPay-Card" oneOf: - $ref: "#/components/schemas/RPay-Account" - $ref: "#/components/schemas/RPay-Card" Card-For-Payment-Details: properties: type: type: string enum: - card - revolut_pay description: The type of payment method used to pay for the order. brand: type: string description: The type of the card. last_four: type: string description: The last four digits of the card number. id: type: string format: uuid description: |- ID of the saved payment method. :::note The `id` parameter is only returned if the payment method is saved. ::: required: - type Payment-Retrieval: type: object properties: id: $ref: "#/components/schemas/Payment-Id" order_id: $ref: "#/components/schemas/Order-Id" payment_method: type: object description: The payment method used to pay for the order. discriminator: propertyName: type mapping: revolut_pay: "#/components/schemas/Revolut-Pay" card: "#/components/schemas/Card-For-Payment-Details" sepa_direct_debit: "#/components/schemas/Sepa-Direct-Debit" oneOf: - $ref: "#/components/schemas/Revolut-Pay" - $ref: "#/components/schemas/Card-For-Payment-Details" - $ref: "#/components/schemas/Sepa-Direct-Debit" token: $ref: "#/components/schemas/Payment-Token" amount: $ref: "#/components/schemas/Payment-Amount" currency: $ref: "#/components/schemas/Currency" state: $ref: "#/components/schemas/Payment-State-v2" decline_reason: $ref: "#/components/schemas/Decline-Reason-v2" authentication_challenge: $ref: "#/components/schemas/Authentication-Challenge" required: - id - order_id - payment_method Browser-Environment: type: object description: Browser environment properties: type: type: string enum: - browser description: Type of environment where the payment was made. examples: - browser time_zone_utc_offset: type: integer description: Defines the offset to UTC in minutes. examples: - 180 color_depth: type: integer description: The browser's available colour depth. examples: - 32 screen_width: type: integer description: The browser's screen width in pixels. examples: - 1920 screen_height: type: integer description: The browser's screen height in pixels. examples: - 1080 java_enabled: type: boolean description: Indicates if the browser has Java enabled. examples: - false challenge_window_width: type: integer description: Defines the width of the pop-up window where the authentication challenge appears. examples: - 640 browser_url: type: string format: url description: The URL of the page where the payment was initiated. examples: - https://business.revolut.com required: - type - time_zone_utc_offset - color_depth - screen_width - screen_height - java_enabled Environment: description: >- Environment object, indicating in which environment the payment was made. :::warning Only required if `initiator: customer`. ::: :::note Only `browser` is available at the moment. ::: type: object discriminator: propertyName: type mapping: browser: "#/components/schemas/Browser-Environment" oneOf: - $ref: "#/components/schemas/Browser-Environment" Saved-Payment-Method: type: object properties: saved_payment_method: type: object description: Object containing information about the saved payment method used to pay for the order. properties: type: type: string enum: - card - revolut_pay description: Type of saved payment method. examples: - card id: type: string description: Saved payment method ID. initiator: type: string description: >- Indicates who is allowed to initiate the payment. :::note Using this endpoint, only merchant initiated payments are supported with Revolut Pay. ::: enum: - customer - merchant examples: - customer environment: $ref: "#/components/schemas/Environment" required: - type - id - initiator - environment required: - saved_payment_method Customer: title: Customer type: object description: "" properties: id: type: string description: Permanent customer ID used to retrieve, update, and delete a customer. full_name: type: string description: The full name of the customer. business_name: type: string description: The name of the customer's business. phone: type: string description: The phone number of the customer in [E.164 format](https://en.wikipedia.org/wiki/E.164). created_at: type: string description: The date and time the customer was created. format: date-time updated_at: type: string description: The data and time the customer was last updated. format: date-time email: type: string description: The email address of the customer. format: email date_of_birth: $ref: "#/components/schemas/Date-Of-Birth" required: - id - created_at - updated_at - email Customer-Creation: type: object properties: full_name: type: string description: The full name of the customer. business_name: type: string description: The name of the customer's business. email: type: string description: The email address of the customer. format: email phone: type: string description: The phone number of the customer in [E.164 format](https://en.wikipedia.org/wiki/E.164). date_of_birth: $ref: "#/components/schemas/Date-Of-Birth" required: - email Customer-Payment-Method: title: Payment method object type: object description: "" properties: id: type: string format: uuid description: The ID of the payment method. type: type: string enum: - CARD - REVOLUT_PAY description: >- The type of the payment method. :::note Only merchant initiated transactions are supported for saved `REVOLUT_PAY` payment methods. ::: saved_for: type: string enum: - CUSTOMER - MERCHANT description: >- Indicates in which case this saved payment method can be used for payments. - `CUSTOMER`: This payment method can be used only when the customer is on the checkout page. - `MERCHANT`: This payment method can be used without the customer being on the checkout page, and the merchant can initiate transactions, for example, to take payments for recurring transactions. method_details: type: object description: The details of the payment method. properties: bin: type: string maxLength: 6 minLength: 6 description: The BIN of the payment card. last4: type: string maxLength: 4 minLength: 4 description: The last four digits of the payment card. expiry_month: type: number description: The expiry month of the payment card. expiry_year: type: number description: The expiry year of the payment card. cardholder_name: type: string description: The name of the cardholder. billing_address: type: object description: The billing address of the payment method. properties: street_line_1: type: string minLength: 1 description: Street line 1 information. street_line_2: type: string minLength: 1 description: Street line 2 information. postcode: type: string minLength: 1 description: The postcode associated with the address. city: type: string minLength: 1 description: The city associated with the address. region: type: string minLength: 1 description: The region associated with the address. country_code: type: string minLength: 1 description: The country associated with the address. brand: type: string description: The brand of the payment card. enum: - VISA - MASTERCARD - MAESTRO funding: type: string enum: - DEBIT - CREDIT - PREPAID - DEFERRED_DEBIT - CHARGE description: The funding type of the payment card. issuer: type: string description: The issuer of the payment card. issuer_country: type: string description: Two-letter country code of the country where the payment card was issued. created_at: type: string description: The date and time the payment card was added. format: date-time required: - id Customer-With-Payment-Method: title: Customer object with Payment Method object type: object properties: id: type: string description: Permanent customer ID used to retrieve, update, and delete a customer. full_name: type: string description: The full name of the customer. business_name: type: string description: The name of the customer's business. phone: type: string description: The phone number of the customer in [E.164 format](https://en.wikipedia.org/wiki/E.164). created_at: type: string description: The date and time the customer was created. format: date-time updated_at: type: string description: The data and time the customer was last updated. format: date-time email: type: string description: The email address of the customer. format: email date_of_birth: $ref: "#/components/schemas/Date-Of-Birth" payment_methods: type: array uniqueItems: false description: All the payment methods for this customer. items: $ref: "#/components/schemas/Customer-Payment-Method" required: - id - created_at - updated_at - email Customer-Update: type: object properties: full_name: type: string description: The full name of the customer. business_name: type: string description: The name of the customer's business. email: type: string description: >- The email address of the customer. :::note This value must be unique for each customer for one merchant. If the email address matches an existing customer, an error is returned. ::: format: email phone: type: string description: The phone number of the customer in [E.164 format](https://en.wikipedia.org/wiki/E.164). date_of_birth: $ref: "#/components/schemas/Date-Of-Birth" Payout-Id: type: string format: uuid description: Permanent payout ID used for payouts operations. Payout-State: type: string enum: - processing - completed - failed description: The state of the payout. Payout-Destination-Type: type: string enum: - current_pocket - external_beneficiary description: >- The destination of the payout funds when a merchant initiates a withdrawal from their merchant account. | Destination type | Description | | ---------------- | ----------- | | `current_pocket` | The funds were moved from the merchant account to the business account within the platform. This indicates an **internal transfer**, allowing the merchant to access the funds within their own business account. | | `external_beneficiary` | The funds were transferred to an external bank account or beneficiary outside the platform. This indicates a **transfer to an external account**, enabling the merchant to withdraw funds to external financial institutions. | Payout-Amount: type: integer minimum: 1 description: The total amount of the payout in minor currency units. For example, `7034` represents €70.34. Payout: type: object properties: id: $ref: "#/components/schemas/Payout-Id" state: $ref: "#/components/schemas/Payout-State" created_at: type: string format: date-time description: The date and time the payout was created. destination_type: $ref: "#/components/schemas/Payout-Destination-Type" amount: $ref: "#/components/schemas/Payout-Amount" currency: $ref: "#/components/schemas/Currency" required: - id - state - created_at - destination_type Report-Run-From: type: string format: date-time description: >- This parameter specifies the start boundary for filtering transaction data in the report based on an order's `payments.created_at` parameter. It accepts ETC/UTC date and time in [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601) and includes all transactions created on or after this timestamp. Combined with the `to` parameter, this determines the report's timeframe, including all transactions between the two values. For example, by setting the `from` parameter to `2021-01-01T00:00:00Z`, the report will include transactions created from the first second of January 1, 2021, UTC, and onwards. Report-Run-To: type: string format: date-time description: >- This parameter specifies the end boundary for filtering transaction data in the report based on an order's `payments.created_at` parameter. It accepts ETC/UTC date and time in [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601) and includes all transactions created before this timestamp (exclusive). Combined with the `from` parameter, this determines the timeframe for the report, including all transactions between the two values. For example, setting the `to` parameter to `2021-12-31T23:59:59Z` will include all transactions in the report created up to, but not including, the last second of December 31, 2021, UTC. Report-Run-Entity-Types: type: array items: type: string enum: - payment - refund - dispute description: Select transactions by type to be included in the report. Report-Run-Entity-States: type: array items: type: string enum: - completed - processing - cancelled - reverted description: >- Select transactions by state to be included in the report. If not provided, only `completed` transactions will be included in the report. Report-Run-Currency: type: string description: |- Select transactions with specific currencies to include in the report. Provide [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code in upper case. :::info For more information about the supported currencies, see: [Help Center](https://help.revolut.com/business/help/merchant-accounts/payments/in-which-currencies-can-i-accept-payments/). ::: minLength: 3 maxLength: 3 examples: - GBP Report-Run-Location-Id: type: string format: uuid description: >- Select transactions by location ID to be included in the report. :::info For more information, see: [Locations](/docs/api/merchant#tag-locations). ::: Report-Run-Filter: type: object description: Filtering parameters to be applied to the report. properties: from: $ref: "#/components/schemas/Report-Run-From" to: $ref: "#/components/schemas/Report-Run-To" entity_types: $ref: "#/components/schemas/Report-Run-Entity-Types" entity_states: $ref: "#/components/schemas/Report-Run-Entity-States" currency: $ref: "#/components/schemas/Report-Run-Currency" location_id: $ref: "#/components/schemas/Report-Run-Location-Id" required: - from - to Report-Run-Format: type: string enum: - csv description: Format of the generated report file. examples: - csv Report-Run-Type: type: string description: >- Type of the report. Possible values: | Type of report | Description | | -------------- | ----------- | | `settlement_report` | Settlement report is a report including transactions settled to the user account. This parameter sets the predefined `options` and list of represented columns. | | `custom_report` | Custom reports require users to define `options`. | | `payout_statement_report` | Payout statement Reports provide a detailed breakdown of all transactions contributing to a specific payout amount. It requires the additional parameter `filter.payout_id`, which should be obtained from the payout ID retrieved via the [payout list endpoint](/docs/api/merchant#retrieve-payout-list) or from [webhook events](/docs/api/merchant#create-webhook). | | `icpp_fee_breakdown_report` | IC++ fee breakdown reports provide a detailed breakdown of fees for each IC++ transaction related to a payout. It requires the additional parameter `filter.icpp_charge_id`, which should be obtained from the `related_icpp_charge_id` column in the Payout statement report. A separate report should be generated for each IC++ transaction. | | `payments_report` | Payments report provides details of all payments associated with a Merchant account, including failed and declined payments. Supports filtering by `from` and `to` creation timestamps, and optionally by `entity_states`. | enum: - settlement_report - custom_report - payout_statement_report - icpp_fee_breakdown_report - payments_report examples: - settlement_report Report-Run-Options: type: object description: Further options to customize the report. properties: timezone: type: string description: >- Defaults to `ETC/UTC`. Defines the output timezone for all timestamps displayed in the report. Has no effect on `from` or `to` parameters. examples: - Europe/London columns: type: array items: type: string description: >- Names of the columns to be included in the report. If the `columns` parameter is not defined in the request, all available columns will be included in the report. An empty array will return an error. If you created orders using the `metadata` object, you can include them in the report by adding them with `metadata.` prefix. For example: `metadata.custom_attribute`. Available columns: | Column name | Description | | ----------- | ----------- | | `transaction_id` | Unique identifier of the transaction related to an order. | | `order_id` | Unique identifier of the order. | | `started_date` | Date and time the transaction was created. | | `updated_date` | Date and time the transaction was last updated. | | `completed_date` | Date and time the transaction was completed. | | `type` | Type of the order. | | `state` | State of the order. | | `description` | Description of the order. | | `merchant_order_ext_ref` | Merchant's order identifier for external reference. | | `customer_id` | Unique identifier of the customer related to an order. | | `amount` | Total amount of the order. | | `currency` | The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code that represents the currency of the order. | | `settlement_amount` | Total amount settled on the merchant's account. | | `settlement_currency` | The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code that represents the currency of the settled amount. | | `fee_amount` | Total amount of extra fees applied to the order. | | `fee_currency` | The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code that represents the currency of extra fees. | | `processing_fee_amount` | Total amount of processing fees applied to the order. | | `processing_fee_currency` | The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code that represents the currency of processing fees. | | `payment_method` | Type of the payment method the customer used to pay for the order. | | `browser_url` | The URL where the customer initiated the payment. | | `related_icpp_charge_id` | Unique identifier of the IC++ charge related to the transaction. **This column is only available in the `payout_statement_report`.** | | `location_id` | Unique identifier of the location related to the transaction. **This column is only available in `settlement_report` and `custom_report`.** | examples: - - transaction_id - amount - metadata.custom_attribute Report-Run-Settlement-Report: title: Settlement report type: object description: A settlement report contains all the query information for generating reports of settled transactions associated with a Merchant account. properties: filter: $ref: "#/components/schemas/Report-Run-Filter" format: $ref: "#/components/schemas/Report-Run-Format" type: $ref: "#/components/schemas/Report-Run-Type" options: $ref: "#/components/schemas/Report-Run-Options" required: - filter - format - type Report-Run-Custom-Report: title: Custom report type: object description: A custom report contains all the query information for generating reports of selected transactions associated with a Merchant account. properties: filter: $ref: "#/components/schemas/Report-Run-Filter" format: $ref: "#/components/schemas/Report-Run-Format" type: $ref: "#/components/schemas/Report-Run-Type" options: $ref: "#/components/schemas/Report-Run-Options" required: - filter - format - type Report-Run-Payout-Filter: type: object description: Filtering parameters to be applied to the report. properties: payout_id: $ref: "#/components/schemas/Payout-Id" required: - payout_id Report-Run-Payout-Report: title: Payout settlement report type: object description: A payout settlement report contains all the query information for generating reports of a selected payout associated with a Merchant account. properties: filter: $ref: "#/components/schemas/Report-Run-Payout-Filter" format: $ref: "#/components/schemas/Report-Run-Format" type: $ref: "#/components/schemas/Report-Run-Type" options: $ref: "#/components/schemas/Report-Run-Options" required: - filter - format - type Icpp-Charge-Id: type: string format: uuid description: >- Permanent ID of of the IC++ fee related to a payout transaction. This ID can be obtained from the `related_icpp_charge_id` column of a payout statement report. Report-Run-Icpp-Filter: type: object description: Filtering parameters to be applied to the report. properties: icpp_charge_id: $ref: "#/components/schemas/Icpp-Charge-Id" required: - icpp_charge_id Report-Run-Icpp-Report: title: IC++ fee breakdown report type: object description: A IC++ fee breakdown report contains all the query information for generating reports of fees for each IC++ transaction related to a payout. properties: filter: $ref: "#/components/schemas/Report-Run-Icpp-Filter" format: $ref: "#/components/schemas/Report-Run-Format" type: $ref: "#/components/schemas/Report-Run-Type" options: $ref: "#/components/schemas/Report-Run-Options" required: - filter - format - type Report-Run-Payments-Entity-States: type: array items: type: string enum: - completed - failed - declined - cancelled description: |- Select payments by state to be included in the report. If not provided, payments in all states will be included in the report. Report-Run-Payments-Filter: type: object description: Filtering parameters to be applied to the report. properties: from: $ref: "#/components/schemas/Report-Run-From" to: $ref: "#/components/schemas/Report-Run-To" entity_states: $ref: "#/components/schemas/Report-Run-Payments-Entity-States" required: - from - to Report-Run-Payments-Options: type: object description: Further options to customize the report. properties: timezone: type: string description: >- Defaults to `ETC/UTC`. Defines the output timezone for all timestamps displayed in the report. Has no effect on `from` or `to` parameters. examples: - Europe/London columns: type: array items: type: string description: >- Names of the columns to be included in the report. If the `columns` parameter is not defined in the request, all available columns will be included in the report. An empty array will return an error. Available columns: | Column name | Description | | ----------- | ----------- | | `payment_id` | Unique identifier of the payment. | | `type` | Type of the payment, for example: `PAYMENT` or `REFUND`. | | `description` | Description of the payment. | | `original_payment_id` | For refunds, the unique identifier of the original payment. | | `order_id` | Unique identifier of the order associated with the payment. | | `state` | State of the payment, for example: `COMPLETED`, `FAILED`, or `DECLINED`. | | `reason` | Reason for a failed or declined payment, for example: `Insufficient Funds`. | | `amount` | Total amount of the payment. | | `currency` | The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code of the payment. | | `surcharge_amount` | Surcharge amount applied to the payment, if any. | | `tip_amount` | Tip amount included in the payment, if any. | | `refunded_amount` | Amount refunded for the payment. | | `created_date` | Date and time the payment was created. | | `merchant_order_ext_ref` | Merchant's order identifier for external reference. | | `payment_method` | Payment method used, for example: `CARD` or `PAY_WITH_REVOLUT`. | | `location_id` | Unique identifier of the location where the payment was made. | | `customer_id` | Unique identifier of the customer. | | `customer_card_number` | Masked card number used for the payment. | | `customer_card_country` | Country of the card used for the payment, as an [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) code. | | `customer_card_brand` | Card brand used for the payment, for example: `VISA` or `MASTERCARD_DEBIT`. | | `customer_card_type` | Card funding type, for example: `DEBIT` or `PREPAID`. | | `customer_card_category` | Card category, for example: `consumer` or `business`. | | `customer_email` | Email address of the customer. | | `fee_amount` | Total fee amount charged for the payment. | | `fee_currency` | The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code of the fee. | examples: - - payment_id - type - state - amount - currency Report-Run-Payments-Report: title: Payments report type: object description: A payments report contains all the query information for generating reports of payments associated with a Merchant account, including failed and declined payments. properties: filter: $ref: "#/components/schemas/Report-Run-Payments-Filter" format: $ref: "#/components/schemas/Report-Run-Format" type: $ref: "#/components/schemas/Report-Run-Type" options: $ref: "#/components/schemas/Report-Run-Payments-Options" required: - filter - format - type Report-Run-Details: title: ReportRunDetails type: object description: The `ReportRunDetails` object contains all information associated with a specific report run, identified by the `report_run_id`. properties: report_run_id: type: string format: uuid description: Unique ID used for accessing report details. Use this to check report generation status. status: type: string description: Current status of the report run. enum: - processing - completed - failed - expired file_url: type: string description: Use this link to download report file. Not available, until `status` is `completed`. required: - report_run_id - status Report-Run-Error: title: Report run error type: object properties: code: type: string description: >- An identifier that can be used to determine what went wrong. Error codes are not globally unique, but uniqueness is guaranteed within endpoints. message: type: string description: Some human readable text describing what went wrong. timestamp: type: integer description: The date and time the error happened. required: - code - message - timestamp Webhook-Id: type: string format: uuid description: The ID of the webhook. Webhook-Url: type: string format: uri pattern: ^https?:\/{2}.+/gi maxLength: 2000 description: >- Your webhook's URL to which event notifications will be sent. Must be a valid HTTP or HTTPS URL, capable of receiving `POST` requests. :::warning Restrictions: - Must be a valid URI as defined by [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986) - URI scheme is required and must be either `http` or `https` - URI host is required and cannot be `localhost` or an IP address - Max length: `2000` - Reserved or invalid characters must be percent-encoded (for example, use `%20` instead of a space) ::: Webhook-Events: type: array description: >- List of event types that the webhook is configured to listen to. Each event is related to status changes of a specific object in the Merchant API: | Object | Event types | | --------- | ----------- | | `Order` |
  • `ORDER_COMPLETED`
  • `ORDER_AUTHORISED`
  • `ORDER_CANCELLED`
  • `ORDER_FAILED`
  • `ORDER_INCREMENTAL_AUTHORISATION_AUTHORISED`
  • `ORDER_INCREMENTAL_AUTHORISATION_DECLINED`
  • `ORDER_INCREMENTAL_AUTHORISATION_FAILED`
| | `Payment` |
  • `ORDER_PAYMENT_AUTHENTICATION_CHALLENGED`
  • `ORDER_PAYMENT_AUTHENTICATED`
  • `ORDER_PAYMENT_DECLINED`
  • `ORDER_PAYMENT_FAILED`
| | `Subscription` |
  • `SUBSCRIPTION_INITIATED`
  • `SUBSCRIPTION_FINISHED`
  • `SUBSCRIPTION_CANCELLED`
  • `SUBSCRIPTION_OVERDUE`
| | `Payout` |
  • `PAYOUT_INITIATED`
  • `PAYOUT_COMPLETED`
  • `PAYOUT_FAILED`
| | `Dispute` |
  • `DISPUTE_ACTION_REQUIRED`
  • `DISPUTE_UNDER_REVIEW`
  • `DISPUTE_WON`
  • `DISPUTE_LOST`
| items: type: string description: The available event types your can listen to. enum: - ORDER_COMPLETED - ORDER_AUTHORISED - ORDER_CANCELLED - ORDER_FAILED - ORDER_INCREMENTAL_AUTHORISATION_AUTHORISED - ORDER_INCREMENTAL_AUTHORISATION_DECLINED - ORDER_INCREMENTAL_AUTHORISATION_FAILED - ORDER_PAYMENT_AUTHENTICATION_CHALLENGED - ORDER_PAYMENT_AUTHENTICATED - ORDER_PAYMENT_DECLINED - ORDER_PAYMENT_FAILED - SUBSCRIPTION_INITIATED - SUBSCRIPTION_FINISHED - SUBSCRIPTION_CANCELLED - SUBSCRIPTION_OVERDUE - PAYOUT_INITIATED - PAYOUT_COMPLETED - PAYOUT_FAILED - DISPUTE_ACTION_REQUIRED - DISPUTE_UNDER_REVIEW - DISPUTE_WON - DISPUTE_LOST minItems: 1 Webhook: title: Webhook type: object description: >- 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. When the payment is cleared and the order is completed, Revolut servers will send a notification to the URL of your choice. This is a much 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 that 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 such as `ORDER_COMPLETED` and `ORDER_AUTHORISED`. properties: id: $ref: "#/components/schemas/Webhook-Id" url: $ref: "#/components/schemas/Webhook-Url" events: $ref: "#/components/schemas/Webhook-Events" required: - id Webhook-Creation: title: Webhook schema for creation and update operations type: object properties: url: $ref: "#/components/schemas/Webhook-Url" events: $ref: "#/components/schemas/Webhook-Events" required: - url - events Webhook-Signing-Secret: type: string description: The signing secret for the webhook. Use it to verify the signature for the webhook request's payload. Webhook-With-Signing-Secret: title: Webhook with signing secret type: object properties: id: $ref: "#/components/schemas/Webhook-Id" url: $ref: "#/components/schemas/Webhook-Url" events: $ref: "#/components/schemas/Webhook-Events" signing_secret: $ref: "#/components/schemas/Webhook-Signing-Secret" required: - id - signing_secret Webhook-Callback-Event: type: string enum: - ORDER_COMPLETED - ORDER_AUTHORISED - ORDER_CANCELLED - ORDER_FAILED - ORDER_INCREMENTAL_AUTHORISATION_AUTHORISED - ORDER_INCREMENTAL_AUTHORISATION_DECLINED - ORDER_INCREMENTAL_AUTHORISATION_FAILED - ORDER_PAYMENT_AUTHENTICATION_CHALLENGED - ORDER_PAYMENT_AUTHENTICATED - ORDER_PAYMENT_DECLINED - ORDER_PAYMENT_FAILED - SUBSCRIPTION_INITIATED - SUBSCRIPTION_FINISHED - SUBSCRIPTION_CANCELLED - SUBSCRIPTION_OVERDUE - PAYOUT_INITIATED - PAYOUT_COMPLETED - PAYOUT_FAILED - DISPUTE_ACTION_REQUIRED - DISPUTE_UNDER_REVIEW - DISPUTE_WON - DISPUTE_LOST description: >- The event type of the webhook notification that's sent by Revolut to your webhook URL. Each event is related to status changes of a specific object in the Merchant API: | Object | Event types | | --------- | ----------- | | `Order` |
  • `ORDER_COMPLETED`
  • `ORDER_AUTHORISED`
  • `ORDER_CANCELLED`
  • `ORDER_FAILED`
  • `ORDER_INCREMENTAL_AUTHORISATION_AUTHORISED`
  • `ORDER_INCREMENTAL_AUTHORISATION_DECLINED`
  • `ORDER_INCREMENTAL_AUTHORISATION_FAILED`
| | `Payment` |
  • `ORDER_PAYMENT_AUTHENTICATION_CHALLENGED`
  • `ORDER_PAYMENT_AUTHENTICATED`
  • `ORDER_PAYMENT_DECLINED`
  • `ORDER_PAYMENT_FAILED`
| | `Subscription` |
  • `SUBSCRIPTION_INITIATED`
  • `SUBSCRIPTION_FINISHED`
  • `SUBSCRIPTION_CANCELLED`
  • `SUBSCRIPTION_OVERDUE`
| | `Payout` |
  • `PAYOUT_INITIATED`
  • `PAYOUT_COMPLETED`
  • `PAYOUT_FAILED`
| | `Dispute` |
  • `DISPUTE_ACTION_REQUIRED`
  • `DISPUTE_UNDER_REVIEW`
  • `DISPUTE_WON`
  • `DISPUTE_LOST`
| Webhook-Order-Event: type: object properties: event: $ref: "#/components/schemas/Webhook-Callback-Event" order_id: type: string format: uuid description: The ID of the order the event is related to. merchant_order_ext_ref: type: string description: |- The information sent during order creation in the `merchant_order_data.reference` field. incremental_authorisation_ext_reference: type: string description: The reference sent in the `reference` field of the [Increment authorisation](/docs/api/merchant#increment-authorisation) request. Only present for incremental authorisation events. required: - event - order_id Webhook-Subscription-Event: type: object properties: event: $ref: "#/components/schemas/Webhook-Callback-Event" subscription_id: type: string format: uuid description: The ID of the subscription the event is related to. external_reference: type: string description: The information sent in the `external_reference` field of the [Create a subscription](/docs/api/merchant#create-subscription) request. required: - event - subscription_id Webhook-Payout-Event: type: object properties: event: $ref: "#/components/schemas/Webhook-Callback-Event" payout_id: type: string format: uuid description: The ID of the payout the event is related to. required: - event - payout_id Webhook-Dispute-Event: type: object properties: event: $ref: "#/components/schemas/Webhook-Callback-Event" dispute_id: type: string format: uuid description: The ID of the dispute the event is related to. required: - event - dispute_id Synchronous-Webhook: title: SynchronousWebhook type: object properties: id: type: string format: uuid description: The ID of the synchronous webhook object. signing_key: type: string pattern: ^swsk_[a-zA-Z0-9]{32}$ description: "A randomly generated signing key, which can be used by merchants to authenticate requests from Revolut by verifying the signature. For more information, see: [Verify the payload signature](/docs/guides/merchant/monitor-and-observe/webhooks/verif\ y-the-payload-signature)." url: type: string format: uri pattern: ^https:\/{2}.+/gi maxLength: 2000 description: >- The valid URL of the endpoint, that uses HTTPS URL schema. Revolut sends the shipping address of the customer to this URL for validation. :::warning Restrictions: - Must be a valid URI as defined by [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986) - URI scheme is required and must be `https` - URI host is required and cannot be `localhost` or an IP address - Max length: `2000` - Reserved or invalid characters must be percent-encoded (for example, use `%20` instead of a space) ::: event_type: type: string enum: - fast_checkout.validate_address description: >- Type of event this synchronous webhook is configured for. :::note At the moment, synchronous webhooks only support address validation events. ::: location_id: $ref: "#/components/schemas/Location-Id" required: - id - signing_key - url - event_type Synchronous-Webhook-Creation: title: SynchronousWebhookCreation type: object description: >- The `SynchronousWebhook` object allows merchants to register endpoints on their backend for receiving predefined event types. Currently, only address validation events are available. In addition, merchants can specify locations representing their online stores, enabling them to set up different webhooks for different stores. properties: event_type: type: string enum: - fast_checkout.validate_address description: >- Type of event this synchronous webhook is configured for. :::note At the moment, synchronous webhooks only support address validation events. ::: url: type: string format: uri pattern: ^https:\/{2}.+/gi maxLength: 2000 description: >- The valid URL of the endpoint, that uses HTTPS URL schema. Revolut sends the shipping address of the customer to this URL for validation. :::warning Restrictions: - Must be a valid URI as defined by [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986) - URI scheme is required and must be `https` - URI host is required and cannot be `localhost` or an IP address - Max length: `2000` - Reserved or invalid characters must be percent-encoded (for example, use `%20` instead of a space) ::: location_id: $ref: "#/components/schemas/Location-Id" required: - event_type - url Location-Name: type: string description: |- Name of the location. :::warning The `name` parameter's value must be unique across all locations. ::: Location-Type: type: string description: |- Type of the location. | Value | Description | | ----- | ----------- | | `online` | Represents an online store. | | `physical` | Represents a physical point of sale. | enum: - online - physical Location-Online-Details: type: object description: Additional details of the location. properties: domain: type: string description: |- Domain address of the location. Required for online locations. :::warning The `domain` parameter's value must be unique across all locations. ::: required: - domain Location-Online: type: object properties: id: $ref: "#/components/schemas/Location-Id" name: $ref: "#/components/schemas/Location-Name" type: $ref: "#/components/schemas/Location-Type" details: $ref: "#/components/schemas/Location-Online-Details" required: - id - name - type - details Address-v3: type: object description: Details of a physical address. properties: street_line_1: type: string description: Primary address line. maxLength: 100 street_line_2: type: string description: Secondary address line, such as floor and apartment number. maxLength: 100 region: type: string description: State or province of the address. maxLength: 100 city: type: string description: City of the address. maxLength: 100 country_code: type: string pattern: ^[A-Z]{2}$ description: ISO 2-letter country code. minLength: 2 maxLength: 2 postcode: type: string description: Postal code of the address. maxLength: 100 required: - street_line_1 - city - country_code - postcode Geo-Location: type: object description: Coordinates of the location. properties: lat: type: number format: double description: The latitude of the location, in decimal degrees. minimum: -90 maximum: 90 lon: type: number format: double description: To longitude of the location, in decimal degrees. minimum: -180 maximum: 180 required: - lat - lon Day-Opening-Hours: type: array description: |- A list of one or more time intervals for a single day. A day can have multiple intervals (e.g., closing for a lunch break). items: type: object properties: from: type: string format: time description: >- The local time when the interval begins. :::note The format is `hh:mm[:ss]`; seconds are optional and must be `00` if provided. ::: examples: - 09:00:00 to: type: string format: time description: >- The local time when the interval ends. :::note The format is `hh:mm[:ss]`; seconds are optional and must be `00` if provided. ::: examples: - 18:00:00 required: - from - to Opening-Hours: type: object description: |- An object containing the opening hours for each day of the week. A day can have multiple intervals (e.g., closing for a lunch break). properties: monday: description: Opening hours for Monday. $ref: "#/components/schemas/Day-Opening-Hours" tuesday: description: Opening hours for Tuesday. $ref: "#/components/schemas/Day-Opening-Hours" wednesday: description: Opening hours for Wednesday. $ref: "#/components/schemas/Day-Opening-Hours" thursday: description: Opening hours for Thursday. $ref: "#/components/schemas/Day-Opening-Hours" friday: description: Opening hours for Friday. $ref: "#/components/schemas/Day-Opening-Hours" saturday: description: Opening hours for Saturday. $ref: "#/components/schemas/Day-Opening-Hours" sunday: description: Opening hours for Sunday. $ref: "#/components/schemas/Day-Opening-Hours" Location-Physical-Details: type: object description: Additional details of the location. properties: address: $ref: "#/components/schemas/Address-v3" geo_location: $ref: "#/components/schemas/Geo-Location" opening_hours: $ref: "#/components/schemas/Opening-Hours" required: - address - geo_location - opening_hours Location-Physical: title: Location type: object properties: id: $ref: "#/components/schemas/Location-Id" name: $ref: "#/components/schemas/Location-Name" type: $ref: "#/components/schemas/Location-Type" details: $ref: "#/components/schemas/Location-Physical-Details" required: - id - name - type - details Location: title: Location type: object description: Location object represents merchant locations depending on type. oneOf: - $ref: "#/components/schemas/Location-Online" - $ref: "#/components/schemas/Location-Physical" discriminator: propertyName: type mapping: online: "#/components/schemas/Location-Online" physical: "#/components/schemas/Location-Physical" Location-Creation-Online: type: object properties: name: $ref: "#/components/schemas/Location-Name" type: $ref: "#/components/schemas/Location-Type" details: $ref: "#/components/schemas/Location-Online-Details" required: - name - type - details Location-Creation-Physical: type: object properties: name: $ref: "#/components/schemas/Location-Name" type: $ref: "#/components/schemas/Location-Type" details: $ref: "#/components/schemas/Location-Physical-Details" required: - name - type - details Location-Creation: type: object description: Request body for creating a location. The structure of the `details` object depends on the `type` of the location. oneOf: - $ref: "#/components/schemas/Location-Creation-Online" - $ref: "#/components/schemas/Location-Creation-Physical" discriminator: propertyName: type mapping: online: "#/components/schemas/Location-Creation-Online" physical: "#/components/schemas/Location-Creation-Physical" Location-Update-Online: type: object properties: name: $ref: "#/components/schemas/Location-Name" details: $ref: "#/components/schemas/Location-Online-Details" Location-Update-Physical: title: Location type: object description: Location object represents merchant locations depending on type. oneOf: - $ref: "#/components/schemas/Location-Online" - $ref: "#/components/schemas/Location-Physical" discriminator: propertyName: type mapping: online: "#/components/schemas/Location-Online" physical: "#/components/schemas/Location-Physical" Location-Update: type: object description: Request body for updating a location. The structure of the `details` object depends on the `type` of the location. oneOf: - $ref: "#/components/schemas/Location-Update-Online" - $ref: "#/components/schemas/Location-Update-Physical" discriminator: propertyName: type mapping: online: "#/components/schemas/Location-Update-Online" physical: "#/components/schemas/Location-Update-Physical" Terminal-Operation-Mode: title: Terminal operation mode type: string description: >- The operation mode of the terminal. | Value | Description | |-------|-------------| | `pos` | Returns only terminals in Pay at Counter mode | | `payment_acceptance` | Returns only terminals in standard checkout mode | enum: - pos - payment_acceptance Terminal-Id: title: Terminal ID type: string format: uuid description: The unique identifier of the terminal. Terminal-Name: title: Terminal name type: string description: The name of the terminal device. Terminal-Type: title: Terminal type type: string description: The hardware type/model of the terminal device. enum: - youtransactor_ucube_touch - newland_n950 - newland_n750 - newland_r25p Terminal-Serial-Number: title: Terminal serial number type: string description: The serial number of the terminal device. examples: - RT-00123456 Terminal-Battery-Level: title: Terminal battery level type: integer description: The current battery level of the terminal as a percentage (0-100). minimum: 0 maximum: 100 Terminal-Online: title: Terminal online status type: boolean description: |- Indicates whether the terminal is currently online and connected. | Value | Description | |-------|-------------| | `true` | Terminal is online and available | | `false` | Terminal is offline | Terminal-Last-Online-At: title: Terminal last online timestamp type: string format: date-time description: The date and time when the terminal was last seen online. Terminal: title: Terminal type: object description: Represents a Revolut Terminal device. properties: id: $ref: "#/components/schemas/Terminal-Id" name: $ref: "#/components/schemas/Terminal-Name" type: $ref: "#/components/schemas/Terminal-Type" serial_number: $ref: "#/components/schemas/Terminal-Serial-Number" battery_level: $ref: "#/components/schemas/Terminal-Battery-Level" online: $ref: "#/components/schemas/Terminal-Online" last_online_at: $ref: "#/components/schemas/Terminal-Last-Online-At" required: - id - name - type - serial_number - battery_level - online - last_online_at Terminals: type: array description: List of terminal devices. items: $ref: "#/components/schemas/Terminal" Terminals-Response: title: Terminals response type: object description: Response containing a list of terminals. properties: terminals: $ref: "#/components/schemas/Terminals" required: - terminals Payment-Intent-Amount: title: Payment Intent amount type: integer description: >- The payment amount expressed in minor currency units, according to the [ISO 4217 standard](https://en.wikipedia.org/wiki/ISO_4217). For example, `7034` in `EUR` corresponds to €70.34. :::info Conversion between major and minor units varies by currency. For instance, `100` minor units equal £1.00 in `GBP`, whereas in `ISK` they represent 100 units. For more details, see the [ISO 4217 standard](https://en.wikipedia.org/wiki/ISO_4217). ::: Payment-Intent-Creation: title: Payment Intent creation type: object description: Request body for creating a payment intent to push to a terminal. properties: amount: $ref: "#/components/schemas/Payment-Intent-Amount" terminal_id: $ref: "#/components/schemas/Terminal-Id" required: - amount - terminal_id Payment-Intent-Id: title: Payment Intent ID type: string format: uuid description: The unique identifier of the payment intent. Payment-Intent-State: type: string description: >- The current state of the payment intent. | 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 authorization is complete, includes a `payment_id` in the response | | `cancelled` | Payment intent was cancelled (by system or customer) | | `failed` | Payment intent failed due to technical issues (timeout, terminal unavailable, network error) | enum: - pending - processing - completed - cancelled - failed Payment-Intent: title: Payment Intent type: object description: >- Represents a payment intent that has been pushed to a Revolut Terminal device. When the payment intent reaches `completed` state, it includes a `payment_id` that can be used to [retrieve the final payment status](/docs/api/merchant#retrieve-payment-details). properties: id: $ref: "#/components/schemas/Payment-Intent-Id" state: $ref: "#/components/schemas/Payment-Intent-State" terminal_id: $ref: "#/components/schemas/Terminal-Id" order_id: $ref: "#/components/schemas/Order-Id" payment_id: $ref: "#/components/schemas/Payment-Id" amount: $ref: "#/components/schemas/Payment-Intent-Amount" currency: $ref: "#/components/schemas/Currency" created_at: type: string format: date-time description: The date and time the payment intent was created. updated_at: type: string format: date-time description: The date and time the payment intent was last updated. required: - id - order_id - state - amount - currency - terminal_id - created_at - updated_at examples: Req-Order-Min: summary: Example order with minimal required parameters value: amount: 500 currency: GBP Req-Order-Additional: summary: Example order with additional parameters value: amount: 500 currency: GBP capture_mode: manual cancel_authorised_after: PT30M expire_pending_after: PT15M customer: email: example@example.com date_of_birth: 1990-01-01 description: Example product shipping_address: street_line_1: 7 Westferry Circus city: London country_code: GB postcode: E14 4HD enforce_challenge: forced metadata: product_type: Example merchant_order_data: url: https://www.example.com/orders/12345 redirect_url: https://www.example.com/redirect statement_descriptor_suffix: "12345" Req-Order-Pre-Auth: summary: Example order with pre-authorisation value: amount: 5000 currency: GBP capture_mode: manual authorisation_type: pre_authorisation description: Hotel reservation deposit cancel_authorised_after: PT72H Req-Order-Airline: summary: Example order with additional airline data value: amount: 500 currency: GBP settlement_currency: EUR description: Example order description customer: full_name: Example Customer phone: "+441234567890" email: example@example.com enforce_challenge: forced capture_mode: manual cancel_authorised_after: PT30M industry_data: type: airline booking_id: unique-booking-id-12345 fulfillment_date: 2023-07-10T14:00:00.069624Z ticket_type: flexible crs_code: DATS ticket_change_indicator: new refundability: refundable passengers: - first_name: Example last_name: Customer - first_name: John last_name: Doe journey_legs: - sequence: 1 departure_airport_code: FRA arrival_airport_code: LHR flight_number: "670" fare_base_code: J travel_date: 2023-07-10T10:00:00.069624Z airline_name: AerLingus airline_code: EI - sequence: 2 departure_airport_code: LHR arrival_airport_code: DUB flight_number: "678" fare_base_code: J travel_date: 2023-07-10T15:00:00.069624Z airline_name: AerLingus airline_code: EI - sequence: 3 departure_airport_code: DUB arrival_airport_code: LHR flight_number: "679" fare_base_code: F travel_date: 2023-07-15T10:00:00.069624Z airline_name: AerLingus airline_code: EI - sequence: 4 departure_airport_code: LHR arrival_airport_code: FRA flight_number: "671" fare_base_code: F travel_date: 2023-07-10T14:00:00.069624Z airline_name: AerLingus airline_code: EI booking_url: https://example.com/bookings/1234 merchant_order_data: url: https://www.example.com/ticketnumber-12345 reference: example_airline_reference redirect_url: https://www.example.com/redirect Req-Order-Car-Rental: summary: Example order with additional car rental data value: amount: 500 currency: GBP settlement_currency: GBP description: Example car rental order customer: full_name: Example Customer phone: "+447700900000" email: example@example.com enforce_challenge: forced capture_mode: manual cancel_authorised_after: PT30M industry_data: type: car_rental booking_id: example_booking_id pick_up_date: 2026-03-01T11:00:00Z drop_off_date: 2026-03-05T16:30:00Z refundability: partially_refundable pick_up_location: street_line_1: 1 Example Street city: London country_code: GB postcode: SW1A 1AA drop_off_location: street_line_1: 10 Another Road city: Manchester country_code: GB postcode: M1 1AA distance_limit: limit: 500 unit: miles additional_distance_cost: amount: 150 currency: GBP merchant_order_data: url: https://www.example.com/rental/example_booking_id reference: example_car_rental_reference redirect_url: https://www.example.com/redirect Req-Order-Crypto: summary: Example order with additional crypto transaction data value: amount: 26100 currency: EUR settlement_currency: EUR description: Customer wants to buy 0.01 BTC customer: id: db186257-3031-4726-98ea-f2260ea115f0 capture_mode: manual cancel_authorised_after: PT30M industry_data: type: crypto transactions: - id: 7b2a8ed4-5889-4c0c-a8cc-299aff1c881b status: pending recipient_wallet_id: 64a6f159-0a60-a446-880e-e449a1f62f7c subseller_mcc: "1234" subseller_url: https://example.com merchant_order_data: url: https://www.example.com/cryptotransactionnumber-12345 reference: example_crypto_reference redirect_url: https://www.example.com/redirect Req-Order-Marketplace: summary: Example order with additional marketplace data value: amount: 10000 currency: EUR industry_data: type: marketplace subseller: id: 123-45-67 name: Example Subseller website: https://example.com/123-45-67 phone: "+441234567890" address: street_line_1: 1 Canada Square street_line_2: Revolut LTD, Level 39 postcode: E14 4HD country_code: GB country_subdivision_code: GB-LND city: London region: Greater London Req-Order-Event: summary: Example order with additional event data value: amount: 100 currency: GBP industry_data: type: event booking_id: example_booking_123 events: - start_date: 2025-03-04T14:00:00Z end_date: 2025-03-04T17:00:00Z supplier: Example Supplier supplier_payment_date: 2025-03-03T14:00:15Z name: Example Event location: street_line_1: Example Street 123 street_line_2: II/123 region: London city: London country_code: GB postcode: "123456" category: exhibition market: primary tickets: - id: example_ticket_1 transferable: false refundability: partially_refundable - id: example_ticket_2 transferable: true refundability: non_refundable - id: example_ticket_3 Req-Order-Lodging: summary: Example order with additional lodging data value: amount: 100 currency: GBP industry_data: type: lodging booking_id: example_booking_123 check_in_date: 2025-05-01T15:00:00Z check_out_date: 2025-05-05T11:00:00Z supplier_payment_date: 2025-05-05T11:00:00Z category: bed_and_breakfast booking_type: flexible refundability: partially_refundable location: street_line_1: Example Street 123 street_line_2: II/123 region: London city: London country_code: GB postcode: "123456" guests: - first_name: First last_name: Guest - first_name: Second last_name: Guest Res-Order-Min: summary: Example order response with minimal required parameters value: 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 Res-Order-Additional: summary: Example order response with additional parameters value: id: 6516e6ec-c7f7-a0fb-a6d3-add05fa46d2f token: 1058031d-1e71-4d07-9f97-5ad388a1346c type: payment state: pending created_at: 2023-09-29T15:02:04.083787Z updated_at: 2023-09-29T15:02:04.083787Z amount: 500 currency: GBP outstanding_amount: 500 capture_mode: manual authorisation_type: final cancel_authorised_after: PT30M description: Example product checkout_url: https://checkout.revolut.com/payment-link/1058031d-1e71-4d07-9f97-5ad388a1346c redirect_url: https://www.example.com/redirect shipping_address: street_line_1: 7 Westferry Circus city: London country_code: GB postcode: E14 4HD metadata: product_type: Example enforce_challenge: forced customer: id: 467646d6-e452-4d1e-a401-703f09cd3818 email: example@example.com date_of_birth: 1990-01-01 merchant_order_data: url: https://example.com/orders/12345 statement_descriptor_suffix: "12345" Res-Order-Pre-Auth: summary: Example order response with pre-authorisation and card payment value: id: 6516e61c-d279-a454-a837-bc52ce55ed49 token: 0adc0e3c-ab44-4f33-bcc0-534ded7354ce type: payment state: authorised created_at: 2023-09-29T14:58:36.079398Z updated_at: 2023-09-29T14:58:36.079398Z amount: 5000 currency: GBP outstanding_amount: 5000 capture_mode: manual authorisation_type: pre_authorisation cancel_authorised_after: PT72H description: Hotel reservation deposit checkout_url: https://checkout.revolut.com/payment-link/0adc0e3c-ab44-4f33-bcc0-534ded7354ce enforce_challenge: automatic payments: - id: 6516f38a-a12b-aca3-83f2-6ed16d6ed246 state: authorised created_at: 2023-09-29T14:55:54.579311Z updated_at: 2023-09-29T14:56:38.403232Z amount: 5000 currency: GBP settled_amount: 5000 settled_currency: GBP billing_address: country_code: GB postcode: SW1A 1AA risk_level: low fees: [] payer: email: example.payer@example.com phone: "+447911123456" payment_method: type: card card_brand: visa funding: credit card_country_code: GB card_bin: "411111" card_last_four: "1111" card_expiry: 12/25 cardholder_name: Example Holder capture_deadline: 2023-10-06T14:55:54.579311Z fingerprint: 1JAllfQY4POhBV8DaddAQ4LC5RbMP8LMLvUdJW4s5JY= network_transaction_id: "1234567890123456" Res-Order-Airline: summary: Example order response with additional airline data value: id: 6516ed0c-098f-aa19-80e5-9d92f52b35e0 token: 061f2c63-e36b-421e-9ece-5adfcd580886 type: payment state: pending created_at: 2023-09-29T15:28:12.114992Z updated_at: 2023-09-29T15:28:12.114992Z amount: 500 currency: GBP outstanding_amount: 500 settlement_currency: EUR capture_mode: manual authorisation_type: final description: Example order description checkout_url: https://checkout.revolut.com/payment-link/061f2c63-e36b-421e-9ece-5adfcd580886 redirect_url: https://www.example.com/redirect cancel_authorised_after: PT30M industry_data: type: airline booking_id: unique-booking-id-12345 fulfillment_date: 2023-07-10T14:00:00.069624Z ticket_type: flexible crs_code: DATS ticket_change_indicator: new refundability: refundable passengers: - first_name: Example last_name: Customer - first_name: John last_name: Doe journey_legs: - sequence: 1 departure_airport_code: FRA arrival_airport_code: LHR flight_number: "670" fare_base_code: J travel_date: 2023-07-10T10:00:00.069624Z airline_name: AerLingus airline_code: EI - sequence: 2 departure_airport_code: LHR arrival_airport_code: DUB flight_number: "678" fare_base_code: J travel_date: 2023-07-10T15:00:00.069624Z airline_name: AerLingus airline_code: EI - sequence: 3 departure_airport_code: DUB arrival_airport_code: LHR flight_number: "679" fare_base_code: F travel_date: 2023-07-15T10:00:00.069624Z airline_name: AerLingus airline_code: EI - sequence: 4 departure_airport_code: LHR arrival_airport_code: FRA flight_number: "671" fare_base_code: F travel_date: 2023-07-10T14:00:00.069624Z airline_name: AerLingus airline_code: EI booking_url: https://example.com/bookings/1234 enforce_challenge: forced customer: id: db186257-3031-4726-98ea-f2260ea115f0 email: example@example.com phone: "+441234567890" full_name: Example Customer merchant_order_data: url: https://www.example.com/ticketnumber-12345 reference: example_airline_reference Res-Order-Car-Rental: summary: Example order response with additional car rental data value: id: 6516ed0c-098f-aa19-80e5-9d92f52b35e0 token: 061f2c63-e36b-421e-9ece-5adfcd580886 type: payment state: pending created_at: 2025-01-29T15:28:12.114992Z updated_at: 2025-01-29T15:28:12.114992Z amount: 500 currency: GBP outstanding_amount: 500 settlement_currency: GBP capture_mode: manual authorisation_type: final description: Example car rental order checkout_url: https://checkout.revolut.com/payment-link/061f2c63-e36b-421e-9ece-5adfcd580886 redirect_url: https://www.example.com/redirect cancel_authorised_after: PT30M industry_data: type: car_rental booking_id: example_booking_id pick_up_date: 2026-03-01T11:00:00Z drop_off_date: 2026-03-05T16:30:00Z refundability: partially_refundable pick_up_location: street_line_1: 1 Example Street city: London country_code: GB postcode: SW1A 1AA drop_off_location: street_line_1: 10 Another Road city: Manchester country_code: GB postcode: M1 1AA distance_limit: limit: 500 unit: miles additional_distance_cost: amount: 150 currency: GBP enforce_challenge: forced customer: id: db186257-3031-4726-98ea-f2260ea115f0 email: example@example.com phone: "+447700900000" full_name: Example Customer merchant_order_data: url: https://www.example.com/rental/example_booking_id reference: example_car_rental_reference Res-Order-Crypto: summary: Example order response with additional crypto transaction data value: id: 6516edb9-74af-ae47-829b-1475e807a8d7 token: 1e619c26-d954-4d45-94ab-aba1e407fcee type: payment state: pending created_at: 2023-09-29T15:31:05.746826Z updated_at: 2023-09-29T15:31:05.746826Z amount: 26100 currency: EUR outstanding_amount: 26100 settlement_currency: EUR capture_mode: manual authorisation_type: final description: Customer wants to buy 0.01 BTC checkout_url: https://checkout.revolut.com/payment-link/1e619c26-d954-4d45-94ab-aba1e407fcee redirect_url: https://www.example.com/redirect industry_data: type: crypto transactions: - id: 7b2a8ed4-5889-4c0c-a8cc-299aff1c881b status: pending recipient_wallet_id: 64a6f159-0a60-a446-880e-e449a1f62f7c subseller_mcc: "1234" subseller_url: https://example.com enforce_challenge: automatic customer: id: db186257-3031-4726-98ea-f2260ea115f0 email: example@example.com phone: "+44123456789" full_name: Example Customer merchant_order_data: url: https://www.example.com/cryptotransactionnumber-12345 reference: example_crypto_reference Res-Order-Marketplace: summary: Example order response with additional marketplace data value: id: 670920dc-d343-abf8-963a-68ae1bc8ae58 token: 41aabe45-b444-45e6-8363-f0433452e138 type: payment state: pending created_at: 2024-10-11T12:58:04.826974Z updated_at: 2024-10-11T12:58:04.826974Z amount: 10000 currency: EUR outstanding_amount: 10000 capture_mode: automatic authorisation_type: final checkout_url: https://checkout.revolut.com/payment-link/41aabe45-b444-45e6-8363-f0433452e138 industry_data: type: marketplace subseller: id: 123-45-67 name: Example Subseller address: street_line_1: 1 Canada Square street_line_2: Revolut LTD, Level 39 region: Greater London city: London country_code: GB country_subdivision_code: GB-LND postcode: E14 4HD website: https://example.com/123-45-67 phone: "+441234567890" enforce_challenge: automatic Res-Order-Event: summary: Example order response with additional event data value: id: 67bf20c4-59a5-a7a9-81ad-052fda5f80eb token: 8737a497-9bae-4647-90bf-1abe2fd9162a type: payment state: pending created_at: 2025-02-26T14:10:12.804901Z updated_at: 2025-02-26T14:10:12.804901Z amount: 100 currency: GBP outstanding_amount: 100 capture_mode: automatic authorisation_type: final checkout_url: https://checkout.revolut.com/payment-link/8737a497-9bae-4647-90bf-1abe2fd9162a industry_data: type: event booking_id: example_booking_123 events: - start_date: 2025-03-04T14:00:00Z end_date: 2025-03-04T17:00:00Z supplier: Example Supplier supplier_payment_date: 2025-03-03T14:00:15Z name: Example Event location: street_line_1: Example Street 123 street_line_2: II/123 region: London city: London country_code: GB postcode: "123456" category: exhibition market: primary tickets: - id: example_ticket_1 transferable: false refundability: partially_refundable - id: example_ticket_2 transferable: true refundability: non_refundable - id: example_ticket_3 enforce_challenge: automatic Res-Order-Lodging: summary: Example order response with additional lodging data value: id: 67c70d42-1545-a73d-a4a5-35b7ac49e1da token: 9effe2b6-8907-4954-9e9b-696f763f7e08 type: payment state: pending created_at: 2025-03-04T14:25:06.099782Z updated_at: 2025-03-04T14:25:06.099782Z amount: 100 currency: GBP outstanding_amount: 100 capture_mode: automatic authorisation_type: final checkout_url: https://checkout.revolut.com/payment-link/9effe2b6-8907-4954-9e9b-696f763f7e08 industry_data: type: lodging booking_id: example_booking_123 check_out_date: 2025-05-05T11:00:00Z booking_type: flexible refundability: partially_refundable location: street_line_1: Example Street 123 street_line_2: II/123 region: London city: London country_code: GB postcode: "123456" guests: - first_name: First last_name: Guest - first_name: Second last_name: Guest check_in_date: 2025-05-01T15:00:00Z supplier_payment_date: 2025-05-05T11:00:00Z category: bed_and_breakfast enforce_challenge: automatic Req-Order-Capture-Min: summary: Capture with amount only value: amount: 100 Res-Order-Cancel-Min: summary: Example order response with minimal required parameters value: 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 Res-Order-Cancel-Additional: summary: Example order response with additional parameters value: id: 6516f379-c03f-adf3-a2bf-24b328909731 token: 91533c29-47d1-4ae9-a73f-74225fd4b176 type: payment state: cancelled created_at: 2023-09-29T15:55:37.201407Z updated_at: 2023-09-29T15:56:38.398961Z amount: 500 currency: GBP refunded_amount: 0 outstanding_amount: 500 capture_mode: manual authorisation_type: final cancel_authorised_after: PT30M description: Example product checkout_url: https://checkout.revolut.com/payment-link/91533c29-47d1-4ae9-a73f-74225fd4b176 redirect_url: https://www.example.com/redirect shipping_address: street_line_1: 7 Westferry Circus city: London country_code: GB postcode: E14 4HD metadata: product_type: Example payments: - id: 6516f38a-a12b-aca3-83f2-6ed16d6ed246 state: authorised created_at: 2023-09-29T15:55:54.579311Z updated_at: 2023-09-29T15:56:38.403232Z amount: 500 currency: GBP settled_amount: 500 settled_currency: GBP billing_address: street_line_1: 26 Atkins Avenue street_line_2: New York 42233 city: SentinelFraudLow country_code: GB postcode: PE3 9UP risk_level: low fees: [] payer: email: example.payer@example.com phone: "+447911123456" payment_method: type: revolut_pay_account fingerprint: 1JAllfQY4POhBV8DaddAQ4LC5RbMP8LMLvUdJW4s5JY= enforce_challenge: forced customer: id: 3c131306-0a0a-4f54-99d7-3fb2e027c6f7 email: example@example.com phone: "+441234567890" full_name: Example Customer merchant_order_data: url: https://example.com/orders/12345 statement_descriptor_suffix: "12345" Res-Order-Cancel-Airline: summary: Example order response with additional airline data value: id: 6516f2f3-fd2c-ac2c-9bf2-3e02711dd3fb token: 245e63f3-1e44-40db-bcd4-4448263d3fa2 type: payment state: cancelled created_at: 2023-09-29T15:53:23.234913Z updated_at: 2023-09-29T16:24:39.366956Z amount: 500 currency: GBP outstanding_amount: 500 settlement_currency: EUR capture_mode: manual authorisation_type: final description: Example order description checkout_url: https://checkout.revolut.com/payment-link/245e63f3-1e44-40db-bcd4-4448263d3fa2 redirect_url: https://www.example.com/redirect cancel_authorised_after: PT30M industry_data: type: airline booking_id: unique-booking-id-12345 fulfillment_date: 2023-07-10T14:00:00.069624Z ticket_type: flexible crs_code: DATS ticket_change_indicator: new refundability: refundable passengers: - first_name: Example last_name: Customer - first_name: John last_name: Doe journey_legs: - sequence: 1 departure_airport_code: FRA arrival_airport_code: LHR flight_number: "670" fare_base_code: J travel_date: 2023-07-10T10:00:00.069624Z airline_name: AerLingus airline_code: EI - sequence: 2 departure_airport_code: LHR arrival_airport_code: DUB flight_number: "678" fare_base_code: J travel_date: 2023-07-10T15:00:00.069624Z airline_name: AerLingus airline_code: EI - sequence: 3 departure_airport_code: DUB arrival_airport_code: LHR flight_number: "679" fare_base_code: F travel_date: 2023-07-15T10:00:00.069624Z airline_name: AerLingus airline_code: EI - sequence: 4 departure_airport_code: LHR arrival_airport_code: FRA flight_number: "671" fare_base_code: F travel_date: 2023-07-10T14:00:00.069624Z airline_name: AerLingus airline_code: EI booking_url: https://example.com/bookings/1234 payments: - id: 6516f315-f713-a5fd-8299-f28820937409 state: failed created_at: 2023-09-29T15:53:57.268142Z updated_at: 2023-09-29T16:24:39.374460Z amount: 500 currency: GBP settled_amount: 576 settled_currency: EUR risk_level: low fees: [] payer: email: example.payer@example.com phone: "+447911123456" payment_method: type: card fingerprint: 1JAllfQY4POhBV8DaddAQ4LC5RbMP8LMLvUdJW4s5JY= network_transaction_id: "1234567890123456" card_brand: mastercard funding: credit card_country_code: MT card_bin: "542071" card_last_four: "0016" card_expiry: 12/28 cardholder_name: Example Holder checks: three_ds: state: verified version: 2 cvv_verification: match enforce_challenge: forced customer: id: db186257-3031-4726-98ea-f2260ea115f0 email: example@example.com phone: "+441234567890" full_name: Example Customer merchant_order_data: url: https://www.airline.com/ticketnumber-12345 reference: example_airline_reference Res-Order-Cancel-Crypto: summary: Example order response with additional crypto transaction data value: id: 6516f11e-5eb1-a223-858d-2c9a7f2a7189 token: 74dce962-2f86-4d86-98b3-a0c590bccc56 type: payment state: cancelled created_at: 2023-09-29T15:45:34.922508Z updated_at: 2023-09-29T15:50:37.989334Z amount: 26100 currency: EUR refunded_amount: 0 outstanding_amount: 26100 settlement_currency: EUR capture_mode: manual authorisation_type: final cancel_authorised_after: PT30M description: Customer wants to buy 0.01 BTC checkout_url: https://checkout.revolut.com/payment-link/74dce962-2f86-4d86-98b3-a0c590bccc56 redirect_url: https://www.example.com/redirect industry_data: type: crypto transactions: - id: 7b2a8ed4-5889-4c0c-a8cc-299aff1c881b status: pending recipient_wallet_id: 64a6f159-0a60-a446-880e-e449a1f62f7c subseller_mcc: "1234" subseller_url: https://example.com payments: - id: 6516f139-a0ad-aaf9-a3a5-0f6ee8c9fde5 state: failed decline_reason: technical_error created_at: 2023-09-29T15:46:01.823402Z updated_at: 2023-09-29T15:46:03.199834Z amount: 26100 currency: EUR settled_amount: 26100 settled_currency: EUR risk_level: low fees: [] payer: email: example.payer@example.com phone: "+447911123456" payment_method: type: card fingerprint: 1JAllfQY4POhBV8DaddAQ4LC5RbMP8LMLvUdJW4s5JY= network_transaction_id: "1234567890123456" card_brand: mastercard funding: credit card_country_code: MT card_bin: "542071" card_last_four: "0016" card_expiry: 12/28 cardholder_name: Test Holder checks: three_ds: state: failed version: 2 - id: 6516f186-0cf3-aefe-b6da-af1a5dad1630 state: authorised created_at: 2023-09-29T15:47:18.050227Z updated_at: 2023-09-29T15:50:37.993217Z amount: 26100 currency: EUR settled_amount: 26100 settled_currency: EUR billing_address: street_line_1: 26 Atkins Avenue street_line_2: New York 42233 city: SentinelFraudLow country_code: GB postcode: PE3 9UP risk_level: low fees: [] payer: email: example.payer@example.com phone: "+447911123456" payment_method: type: revolut_pay_account fingerprint: 1JAllfQY4POhBV8DaddAQ4LC5RbMP8LMLvUdJW4s5JY= enforce_challenge: automatic customer: id: 3c131306-0a0a-4f54-99d7-3fb2e027c6f7 email: example@example.com phone: "+441234567890" full_name: Example Customer merchant_order_data: url: https://www.example.com/cryptotransactionnumber-12345 reference: example_crypto_reference Res-Order-Cancel-Marketplace: summary: Example order response with additional marketplace data value: id: 670920dc-d343-abf8-963a-68ae1bc8ae58 token: 41aabe45-b444-45e6-8363-f0433452e138 type: payment state: cancelled created_at: 2024-10-11T12:58:04.826974Z updated_at: 2024-10-11T12:58:04.826974Z amount: 10000 currency: EUR outstanding_amount: 10000 capture_mode: automatic authorisation_type: final checkout_url: https://checkout.revolut.com/payment-link/41aabe45-b444-45e6-8363-f0433452e138 industry_data: type: marketplace subseller: id: 123-45-67 name: Example Subseller address: street_line_1: 1 Canada Square street_line_2: Revolut LTD, Level 39 region: Greater London city: London country_code: GB country_subdivision_code: GB-LND postcode: E14 4HD website: https://example.com/123-45-67 phone: "+441234567890" enforce_challenge: automatic Res-Order-Cancel-Event: summary: Example order response with additional event data value: id: 67bf20c4-59a5-a7a9-81ad-052fda5f80eb token: 8737a497-9bae-4647-90bf-1abe2fd9162a type: payment state: cancelled created_at: 2025-02-26T14:10:12.804901Z updated_at: 2025-02-26T14:10:12.804901Z amount: 100 currency: GBP outstanding_amount: 100 capture_mode: automatic authorisation_type: final checkout_url: https://checkout.revolut.com/payment-link/8737a497-9bae-4647-90bf-1abe2fd9162a industry_data: type: event booking_id: example_booking_123 events: - start_date: 2025-03-04T14:00:00Z end_date: 2025-03-04T17:00:00Z supplier: Example Supplier supplier_payment_date: 2025-03-03T14:00:15Z name: Example Event location: street_line_1: Example Street 123 street_line_2: II/123 region: London city: London country_code: GB postcode: "123456" category: exhibition market: primary tickets: - id: example_ticket_1 transferable: false refundability: partially_refundable - id: example_ticket_2 transferable: true refundability: non_refundable - id: example_ticket_3 enforce_challenge: automatic Res-Order-Cancel-Lodging: summary: Example order response with additional lodging data value: id: 67c70d42-1545-a73d-a4a5-35b7ac49e1da token: 9effe2b6-8907-4954-9e9b-696f763f7e08 type: payment state: cancelled created_at: 2025-03-04T14:25:06.099782Z updated_at: 2025-03-04T14:25:06.099782Z amount: 100 currency: GBP outstanding_amount: 100 capture_mode: automatic authorisation_type: final checkout_url: https://checkout.revolut.com/payment-link/9effe2b6-8907-4954-9e9b-696f763f7e08 industry_data: type: lodging booking_id: example_booking_123 check_out_date: 2025-05-05T11:00:00Z booking_type: flexible refundability: partially_refundable location: street_line_1: Example Street 123 street_line_2: II/123 region: London city: London country_code: GB postcode: "123456" guests: - first_name: First last_name: Guest - first_name: Second last_name: Guest check_in_date: 2025-05-01T15:00:00Z supplier_payment_date: 2025-05-05T11:00:00Z category: bed_and_breakfast enforce_challenge: automatic Req-Location-Online: summary: Online location request example value: name: Grocery website type: online details: domain: groceries.example.com Req-Location-Physical: summary: Physical location request example value: 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 Res-Location-Online: summary: Online location request example value: id: 8d9a7125-805f-40f3-a405-bc89765db996 name: Grocery website type: online details: domain: groceries.example.com Res-Location-Physical: summary: Physical location request example value: id: 8d9a7125-805f-40f3-a405-bc89765db996 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 Res-Terminals-List: summary: List of terminals at a location value: 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 Req-Payment-Intent: summary: Create payment intent request example value: amount: 2500 terminal_id: 0e53f673-7705-473a-a263-89a3e7647c3d Res-Payment-Intent-Pending: summary: Payment intent pending value: id: b4d58add-b3fe-40e4-a70a-8c78df977888 state: pending order_id: 5c9fc54e-11b4-4f7f-8686-4a64d4d20db4 amount: 2500 currency: GBP Res-Payment-Intent-Processing: summary: Payment intent processing value: id: b4d58add-b3fe-40e4-a70a-8c78df977888 order_id: 5c9fc54e-11b4-4f7f-8686-4a64d4d20db4 state: processing amount: 2500 currency: GBP terminal_id: 0e53f673-7705-473a-a263-89a3e7647c3d created_at: 2025-01-15T11:01:00Z updated_at: 2025-01-15T11:02:15Z Res-Payment-Intent-Completed: summary: Payment intent completed value: id: b4d58add-b3fe-40e4-a70a-8c78df977888 state: completed terminal_id: 0e53f673-7705-473a-a263-89a3e7647c3d order_id: 5c9fc54e-11b4-4f7f-8686-4a64d4d20db4 payment_id: 7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d amount: 2500 currency: GBP created_at: 2025-01-15T11:01:00Z updated_at: 2025-01-15T11:02:30Z Res-Payment-Intent-Cancelled: summary: Payment intent cancelled value: 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 Res-Payment-Intent-Failed: summary: Payment intent failed value: id: b4d58add-b3fe-40e4-a70a-8c78df977888 state: failed 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:03:00Z callbacks: Webhook-Event: "{$request.body#/url}": post: summary: Send webhook event to webhook URL description: |- The following webhook event payload is sent as a HTTP POST request to the URL registered as the merchant's webhook server via the [Create a webhook](/docs/api/merchant#create-webhook) operation. The delivery of the webhook events happen asynchronously, based on the events you subscribed to. :::info For more information, see: [Use webhooks to track order and payment lifecycle](/docs/guides/merchant/monitor-and-observe/webhooks/using-webhooks). ::: ### IP allowlisting To ensure secure delivery of webhook events, please allowlist the following IP addresses from which the events originate: **Production webhook IPs:** - `35.246.21.235` - `34.89.70.170` **Sandbox webhook IPs:** - `35.242.130.242` - `35.242.162.241` parameters: - name: Revolut-Request-Timestamp in: header required: true schema: type: string description: |- The [UNIX timestamp](https://www.unixtimestamp.com/) of the date and time when the webhook event was sent from Revolut. Used to verify the webhook event payload was actually sent by Revolut. :::info For more information, see: [Verify payload signature](/docs/guides/merchant/monitor-and-observe/webhooks/verify-the-payload-signature) ::: - name: Revolut-Signature in: header required: true schema: type: string description: |- The payload signature computed by Revolut using a Hash-based Message Authentication Code (HMAC). Used to verify the webhook event payload was actually sent by Revolut. :::info For more information, see: [Verify payload signature](/docs/guides/merchant/monitor-and-observe/webhooks/verify-the-payload-signature) ::: requestBody: required: true content: application/json: schema: discriminator: propertyName: event mapping: Order or payment event: "#/components/schemas/Webhook-Order-Event" Subscription: "#/components/schemas/Webhook-Subscription-Event" Payout event: "#/components/schemas/Webhook-Payout-Event" Dispute event: "#/components/schemas/Webhook-Dispute-Event" oneOf: - $ref: "#/components/schemas/Webhook-Order-Event" - $ref: "#/components/schemas/Webhook-Subscription-Event" - $ref: "#/components/schemas/Webhook-Payout-Event" - $ref: "#/components/schemas/Webhook-Dispute-Event" examples: order_event: summary: Webhook event related to an order or payment value: event: ORDER_COMPLETED order_id: 6634c172-3398-ac93-aee9-50de0282e3ac merchant_order_ext_ref: "Example reference #123" subscription_event: summary: Webhook event related to a subscription value: event: SUBSCRIPTION_INITIATED subscription_id: 550e8400-e29b-41d4-a716-446655440000 external_reference: ext-ref-12345 incremental_auth_authorised: summary: Webhook event for successful incremental authorisation value: event: ORDER_INCREMENTAL_AUTHORISATION_AUTHORISED order_id: 6634c172-3398-ac93-aee9-50de0282e3ac incremental_authorisation_ext_reference: CHG-67890 incremental_auth_declined: summary: Webhook event for declined incremental authorisation value: event: ORDER_INCREMENTAL_AUTHORISATION_DECLINED order_id: 6634c172-3398-ac93-aee9-50de0282e3ac incremental_authorisation_ext_reference: CHG-67891 incremental_auth_failed: summary: Webhook event for failed incremental authorisation value: event: ORDER_INCREMENTAL_AUTHORISATION_FAILED order_id: 6634c172-3398-ac93-aee9-50de0282e3ac incremental_authorisation_ext_reference: CHG-67892 payout_event: summary: Webhook event related to a payout value: event: PAYOUT_COMPLETED payout_id: 6634c172-3398-ac93-aee9-50de0282e3ac dispute_event: summary: Webhook event related to a dispute value: event: DISPUTE_ACTION_REQUIRED dispute_id: ab934829-e4ba-4e7f-8a21-365cad85c763 responses: "204": description: >- If the webhook event was delivered successfully, we recommend to respond with a `204` code. :::info You can respond to and acknowledge the delivery of a webhook event by any HTTP response code between `200-399`. ::: 4XX: description: If the webhook event delivery times out or the delivery of the events fails, you can respond with any HTTP `4XX` code. In this case, Revolut will retry sending the webhook event 3 more times, each with a 10-minute delay. x-ext-urls: {}