openapi: 3.1.1 info: title: Merchant API version: 2026-04-20 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#tag-orders) - [Customer management](/docs/api/merchant#tag-customers) - [Payment management](/docs/api/merchant#tag-payments) - [Subscription management](/docs/api/merchant#tag-subscriptions) - [Payout management](/docs/api/merchant#tag-payouts) - [Dispute management](/docs/api/merchant#tag-disputes) - [Reporting analytics](/docs/api/merchant#tag-report-runs) - [Webhook management](/docs/api/merchant#tag-webhooks) - [Location management](/docs/api/merchant#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: 2026-04-20' ``` :::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-an-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-an-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-a-customer) endpoint and you can then retrieve, update and delete a customer using its `id`. `Customer` objects enable you to track multiple transactions in your system associated with the same customer in the Merchant API. You can save and store payment methods of a customer in the `payment_method` object, for more information, see: [Charge a customer's saved payment method](/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: Subscriptions description: >- The Subscriptions API provides a complete solution for creating and managing recurring billing for your customers. You can automatically charge customers on flexible billing cycles, manage sophisticated subscription plans, and track the entire billing history for every subscriber. ## How it works? A subscription's billing structure is defined by a **Subscription plan**. This model gives you granular control: - **Plans** contain one or more **variations** (e.g., a "Gold" plan could have "Monthly" and "Yearly" variations). - **Variations** can have multiple **phases** (e.g., a 7-day free trial followed by a regular billing phase). This powerful structure allows you to build complex pricing models, including free trials, introductory offers, and tiered pricing. ## Key features - **Flexible pricing models:** Create plans with multiple variations and phases to support any billing scenario. - **Automated charging:** Automatically charge a customer's saved payment method at the start of each billing cycle. - **Hosted onboarding:** For new customers, generate a setup order with a redirect URL to Revolut's Hosted Payment Page, allowing them to securely add a payment method. - **Lifecycle tracking:** Monitor each billing cycle's state, view all associated orders, and access complete payment histories. - **Full subscription management:** Easily update customer payment methods, cancel subscriptions, and view a complete billing history. - 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-a-payout-list) endpoint or from [webhook events related to payouts](/docs/api/merchant#create-a-webhook#callbacks). - name: Disputes description: >- Endpoints that allow merchants to view customer payment disputes. It provides a robust framework with high-level states (e.g., `won`, `lost`, `needs_response`, `under_review`) and detailed substates (e.g., `lost_expired`, `pre_arbitration`, `won_pre_arbitration`, etc.) to accurately track the dispute lifecycle. Additionally, the API integrates standard dispute reason codes and human-readable descriptions, offering a customisable approach to dispute resolution that facilitates effective dispute management. - 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-a-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-an-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-a-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-fast-checkout) 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-a-payment-intent) 1. **Status tracking:** Poll the payment intent status until completion using [Retrieve a payment intent](/docs/api/merchant#retrieve-a-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-a-payment-intent) 1. **Track:** Poll the payment intent status by [retrieving payment intent details](/docs/api/merchant#retrieve-a-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-a-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 built 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) ### Pre-authorisation and incremental authorisation Orders can be created with `authorisation_type: pre_authorisation` to enable incremental authorisation. This allows you to increase the authorised amount after the initial authorisation. **Requirements:** - `capture_mode` must be set to `manual` - `authorisation_type` must be set to `pre_authorisation` **Payment method support:** Pre-authorisation orders support card, Apple Pay, and Google Pay only — enforced at the API level and on the hosted checkout page. Revolut Pay account-to-account (A2A) payments, Pay by Bank, and SEPA Direct Debit are not supported for pre-authorisation orders. **`cancel_authorised_after`:** For pre-authorisation orders, `cancel_authorised_after` can be set to a maximum of 30 days (`P30D`). For final authorisation orders, the 7-day maximum (`P7D`) still applies. If omitted, only `capture_deadline` governs expiry. **Example use cases:** - Hotels: authorise deposit, then increment for room service and minibar - Car rentals: authorise deposit, then increment for damages or fuel :::info For more information, see: - [Pre-authorisation guide](/docs/guides/merchant/operations/capture-and-settlement/advanced-authorisation/pre-authorisation) - [Incremental authorisation guide](/docs/guides/merchant/operations/capture-and-settlement/advanced-authorisation/incremental-authorisation) - [Increment authorisation endpoint](/docs/api/merchant#increment-authorisation) :::
Industry-specific requirements If you operate in any of the industries listed below, sharing industry-specific data is mandatory. Not providing the necessary information will result in further scrutiny from Revolut and/or the imposition of risk mitigation actions. | Industry | Related fields | | ------- | --------------- | | Retail merchants | `line_items`, `shipping` | | Airlines | `industry_data` with `type: airline` | | Car rentals | `industry_data` with `type: car_rental` | | Hotels & accommodation | `industry_data` with `type: lodging` | | Travel agencies (OTAs) | `industry_data` with `type: airline` and `industry_data` with `type: lodging` | | Crypto merchants | `industry_data` with `type: crypto` | | Event ticket sellers | `industry_data` with `type: event` | | Marketplace merchants | `industry_data` with `type: marketplace` |
requestBody: content: application/json: schema: $ref: "#/components/schemas/Order-Creation-v7" examples: example_order_min_params: $ref: "#/components/examples/Req-Order-Min" example_order_additional: $ref: "#/components/examples/Req-Order-Additional-v2" example_order_pre_auth: $ref: "#/components/examples/Req-Order-Pre-Auth" example_order_line_items: $ref: "#/components/examples/Req-Order-Line-Items" example_order_shipping: $ref: "#/components/examples/Req-Order-Shipping" example_order_airline: $ref: "#/components/examples/Req-Order-Airline-v2" example_order_car_rental: $ref: "#/components/examples/Req-Order-Car-Rental-v2" example_order_crypto: $ref: "#/components/examples/Req-Order-Crypto-v3" example_order_marketplace: $ref: "#/components/examples/Req-Order-Marketplace-v3" example_order_event: $ref: "#/components/examples/Req-Order-Event-v2" example_order_lodging: $ref: "#/components/examples/Req-Order-Lodging-v2" example_order_multi_industry: $ref: "#/components/examples/Req-Order-Multi-Industry" responses: "201": description: Order created content: application/json: schema: $ref: "#/components/schemas/Order-v7" examples: example_order_min_params: $ref: "#/components/examples/Res-Order-Min" example_order_additional: $ref: "#/components/examples/Res-Order-Additional-v2" example_order_pre_auth: $ref: "#/components/examples/Res-Order-Pre-Auth" example_order_line_items: $ref: "#/components/examples/Res-Order-Line-Items" example_order_shipping: $ref: "#/components/examples/Res-Order-Shipping" example_order_airline: $ref: "#/components/examples/Res-Order-Airline-v2" example_order_car_rental: $ref: "#/components/examples/Res-Order-Car-Rental-v2" example_order_crypto: $ref: "#/components/examples/Res-Order-Crypto-v3" example_order_marketplace: $ref: "#/components/examples/Res-Order-Marketplace-v3" example_order_event: $ref: "#/components/examples/Res-Order-Event-v2" example_order_lodging: $ref: "#/components/examples/Res-Order-Lodging-v2" example_order_multi_industry: $ref: "#/components/examples/Res-Order-Multi-Industry" "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: [] get: summary: Retrieve an order list operationId: retrieveOrderList description: >- Get a paginated list of your orders, returned as a wrapped `orders` array. The response contains simplified `Order` objects. To get the full details of a specific order, use the [Retrieve an order](/docs/api/merchant#retrieve-an-order) endpoint. parameters: - $ref: "#/components/parameters/Limit" - $ref: "#/components/parameters/From" - $ref: "#/components/parameters/To" - $ref: "#/components/parameters/Customer-Id-Query" - $ref: "#/components/parameters/Merchant-Order-Data-Reference" - $ref: "#/components/parameters/Order-State-Query" - $ref: "#/components/parameters/Location-Id-Query" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/Orders-v2" examples: list_of_orders: $ref: "#/components/examples/Res-Orders-List-v2" "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" 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-v7" examples: example_order_min_params: $ref: "#/components/examples/Res-Order-Min" example_order_additional: $ref: "#/components/examples/Res-Order-Additional-v2" example_order_pre_auth: $ref: "#/components/examples/Res-Order-Pre-Auth" example_order_line_items: $ref: "#/components/examples/Res-Order-Line-Items" example_order_shipping: $ref: "#/components/examples/Res-Order-Shipping" example_order_airline: $ref: "#/components/examples/Res-Order-Airline-v2" example_order_car_rental: $ref: "#/components/examples/Res-Order-Car-Rental-v2" example_order_crypto: $ref: "#/components/examples/Res-Order-Crypto-v3" example_order_marketplace: $ref: "#/components/examples/Res-Order-Marketplace-v3" example_order_event: $ref: "#/components/examples/Res-Order-Event-v2" example_order_lodging: $ref: "#/components/examples/Res-Order-Lodging-v2" example_order_multi_industry: $ref: "#/components/examples/Res-Order-Multi-Industry" "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-v7" 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-v7" 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/orders/{order_id}/increment-authorisation: parameters: - $ref: "#/components/parameters/Authorization" - $ref: "#/components/parameters/Revolut-Api-Version" - $ref: "#/components/parameters/Order-Id" post: summary: Increment authorisation operationId: incrementAuthorisation description: |- Increase the authorised amount on a pre-authorised order. This operation allows you to increment the authorised amount for orders created with `authorisation_type: pre_authorisation` and `capture_mode: manual`. :::note Currently, only card payments are supported. ::: ### Common use-cases - Hotel additional charges (e.g., minibar, room service) - Car rental damage or fuel charges - Equipment rental extensions ### How it works 1. Create an order with `capture_mode: manual` and `authorisation_type: pre_authorisation` 1. Take payment using one of our card payment solutions 1. When payment/order reaches `authorised` state, you can increment authorised amount 1. When no more increments are expected, [capture the order](/docs/api/merchant#capture-an-order) to complete the transaction :::warning - Can only increment orders in `authorised` state - Must have `authorisation_type: pre_authorisation` and `capture_mode: manual` - Sum of all increment amounts cannot exceed 5x the initial amount - Maximum 10 increments per order - Process increments sequentially to avoid declines - Currently only supported for card payments ::: :::info For more information, see: [Incremental authorisation guide](/docs/guides/merchant/operations/capture-and-settlement/advanced-authorisation/incremental-authorisation) ::: requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/Incremental-Authorisation-Request" examples: basic_increment: $ref: "#/components/examples/Req-Order-Increment-Auth-Basic" increment_with_additional: $ref: "#/components/examples/Req-Order-Increment-Auth-Additional" responses: "200": description: Authorization increment initiated successfully content: application/json: schema: $ref: "#/components/schemas/Order-v7" examples: increment_in_progress: $ref: "#/components/examples/Res-Order-Increment-Processing" increment_authorised: $ref: "#/components/examples/Res-Order-Increment-Authorised" increment_declined: $ref: "#/components/examples/Res-Order-Increment-Declined" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/Error-v2" examples: invalid_amount: value: code: validation message: "New amount: 3 should be greater or equal to order amount: 500" timestamp: 1768397646286 "404": description: Order not found content: application/json: schema: $ref: "#/components/schemas/Error-v2" examples: default: value: code: not_found message: Order not found timestamp: 1768397646286 "422": description: Unprocessable Entity - Order state doesn't allow increment content: application/json: schema: $ref: "#/components/schemas/Error-v2" examples: invalid_state: summary: Invalid state value: code: bad_state message: No authorised card not present payment found for order 69732536-0379-a2e2-8983-15e7184f8fc6. timestamp: 1768397646286 invalid_auth_type: summary: Wrong authorisation type value: code: order_invalid_authorisation_type message: Operation cannot be performed for order 697325ca-a9a2-a922-8df5-c603664da5a5 because order authorisation type is final and expected is pre_authorisation timestamp: 1768397646286 tags: - Orders security: - Api-Key: [] /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-an-order), you can choose one of the following capture modes: | **Capture mode** | **Description** | | ---------------- | --------------- | | `automatic` | The order is captured automatically after payment authorisation. No further actions are needed. | | `manual` | The order is not captured automatically and stays in `authorised` state. You must manually capture the order using the steps outlined below. | :::warning By default, uncaptured orders with **final authorisation** (`authorisation_type: final`) remain in `authorised` state for **7 days**. If not captured within this period, the funds are returned to the customer's original payment method. The capture deadline can be customised: - Use `cancel_authorised_after` parameter when creating an order to set a custom expiry period - The effective deadline is the earlier of `cancel_authorised_after` and the card/network clearing window - `capture_deadline` is set when the order becomes `authorised` and doesn't change afterwards - Use **pre-authorisation** (`authorisation_type: pre_authorisation`) for extended clearing windows (up to 30 days) and incremental authorisation support (see tip below) ::: :::tip [Extended clearing windows] If your business requires longer authorisation hold periods (up to 30 days depending on card scheme and MCC), use [pre-authorisation](/docs/guides/merchant/operations/capture-and-settlement/advanced-authorisation/pre-authorisation) instead of standard authorisation. Pre-authorisation also supports [incremental authorisation](/docs/guides/merchant/operations/capture-and-settlement/advanced-authorisation/incremental-authorisation) for variable-amount scenarios. ::: ### 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 ::: #### Updating line items at capture You can optionally provide `line_items` when capturing an order. This allows you to adjust the final order details at the time of capture, which is useful for scenarios such as: - **Partial captures:** Specify which items are being captured when capturing less than the full amount. Line items help accurately reflect which items were captured versus voided (see [Partial capture](#partial-capture) above). - **Final adjustments:** Update order details when the delivered items differ from the initial authorisation (e.g., out-of-stock items, substitutions, quantity changes). :::warning If you provide `line_items` when capturing, they will **overwrite** the original line items provided during order creation or update. Ensure you include all items you want associated with the captured order. ::: :::info For a comprehensive guide including use cases and examples, see: [Authorise a payment to capture later](/docs/guides/merchant/operations/capture-and-settlement/capture-later#update-line-items-at-capture). ::: ## 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-an-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-v2" examples: example_minimal: $ref: "#/components/examples/Req-Order-Capture-Min" example_with_line_items: $ref: "#/components/examples/Req-Order-Capture-Line-Items" responses: "200": description: Order captured content: application/json: schema: $ref: "#/components/schemas/Order-v7" examples: captured_order_minimal: $ref: "#/components/examples/Res-Order-Capture-Min" captured_order_line_items: $ref: "#/components/examples/Res-Order-Capture-Line-Items" "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-v7" examples: example_order_min: $ref: "#/components/examples/Res-Order-Cancel-Min" example_order_additional: $ref: "#/components/examples/Res-Order-Cancel-Additional-v2" example_order_line_items: $ref: "#/components/examples/Res-Order-Cancel-Line-Items" example_order_shipping: $ref: "#/components/examples/Res-Order-Cancel-Shipping" example_order_airline: $ref: "#/components/examples/Res-Order-Cancel-Airline-v2" example_order_crypto: $ref: "#/components/examples/Res-Order-Cancel-Crypto-v3" example_order_marketplace: $ref: "#/components/examples/Res-Order-Cancel-Marketplace-v3" example_order_event: $ref: "#/components/examples/Res-Order-Cancel-Event-v2" example_order_lodging: $ref: "#/components/examples/Res-Order-Cancel-Lodging-v2" example_order_multi_industry: $ref: "#/components/examples/Res-Order-Cancel-Multi-Industry" "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}/refund: parameters: - $ref: "#/components/parameters/Authorization" - $ref: "#/components/parameters/Revolut-Api-Version" - $ref: "#/components/parameters/Idempotency-Key" - $ref: "#/components/parameters/Order-Id" post: summary: Refund an order operationId: refundOrder 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. - The refund operation generates a new order with `type: refund`. This new order represents a full or partial refund of the original amount paid. - Multiple partial refunds can be issued for a single order, given the total refunded amount does not exceed the original order amount. - Refund orders will contain `related_order_id` which links to the original order that was refunded. - Refunds can only be initiated for orders that are in a `completed` state. Orders in any other state are not eligible for refunds to ensure transaction integrity and to prevent errors. :::note Consider using the `Idempotency-Key` header to make the refund operation idempotent, preventing duplicate refund processing in cases of multiple submissions. ::: :::info For more information see our [Refund payments](/docs/guides/merchant/operations/refunds) guide. ::: requestBody: content: application/json: schema: $ref: "#/components/schemas/Order-Refund-v2" examples: refund_with_minimal_params: $ref: "#/components/examples/Req-Refund-Min" refund_with_additional_params: $ref: "#/components/examples/Req-Refund-Additional" responses: "201": description: Refund order successfully created content: application/json: schema: $ref: "#/components/schemas/Order-v7" examples: refund_with_minimal_params: $ref: "#/components/examples/Res-Refund-Min" refund_with_additional_params: $ref: "#/components/examples/Res-Refund-Additional" "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: 1750265245422 "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/Error-v2" examples: default: value: code: unauthenticated message: Authentication failed timestamp: 1750265245422 "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/Error-v2" examples: default: value: code: not_found message: Order with id 6852e963-0009-a5a4-9609-50b3addc5425 was not found timestamp: 1750265369820 "422": description: Unprocessable Entity content: application/json: schema: $ref: "#/components/schemas/Error-v2" 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-of-a-customer) 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/customers: parameters: - $ref: "#/components/parameters/Authorization" - $ref: "#/components/parameters/Revolut-Api-Version-2024-09-01-Min" post: summary: Create a customer operationId: createCustomer description: |- Create a `customer` object. :::note [No automatic deduplication] The API does not prevent creating multiple customers with the same email address or phone number. This can be intentional, for example, to maintain separate customer records per storefront or brand under the same account. To avoid unintentional duplicates, search for existing customers by email or phone using the [List customers](/docs/api/merchant#retrieve-a-customer-list) endpoint before creating a new one. ::: ### Save payment methods If you wish to save a customer's payment details using any of the available payment methods on the Revolut Checkout Widget ([Revolut Pay](/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-an-order) For more information, see: [Charge a customer's saved payment method](/docs/guides/merchant/optimise-checkout/save-payment-methods/charge-saved-payment-method).
AFT processing requirements For merchants in the following industries, `full_name` and `date_of_birth` are required for Account Funding Transaction (AFT) processing: | Industry | Required fields | | -------- | --------------- | | Crypto | `full_name`, `date_of_birth` | | Financial Institutions | `full_name`, `date_of_birth` | | Stored Value / Wallets | `full_name`, `date_of_birth` |
requestBody: content: application/json: schema: $ref: "#/components/schemas/Customer-Creation-v2" examples: example_customer_creation: $ref: "#/components/examples/Req-Customer-Creation-v2" responses: "201": description: Created content: application/json: schema: $ref: "#/components/schemas/Customer-Created" examples: created_customer: $ref: "#/components/examples/Res-Customer-Created" "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: - Customers get: summary: Retrieve a customer list operationId: retrieveCustomerList description: >- Get a paginated list of your customer profiles. | Filtering | Pagination | | --------- | ---------- | | Filter the customers that you want to retrieve, for example, only retrieve customers created within a specific date range.

Parameters used for filtering:
| View customers without loading all of them at once, for example, return a specified number of customers per page.

Parameters used for pagination:
| To paginate through all results: 1. Make an initial request with the desired `limit` and any filter parameters. 1. If more results are available, the response includes a `next_page_token`. 1. Pass `next_page_token` as `page_token` in your next request, keeping all other parameters unchanged. 1. Repeat until `next_page_token` is no longer present in the response. parameters: - $ref: "#/components/parameters/Limit" - $ref: "#/components/parameters/Page-Token" - $ref: "#/components/parameters/From" - $ref: "#/components/parameters/To" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/Customers" examples: list_of_customers: $ref: "#/components/examples/Res-Customers-List" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/Error-v2" security: - Api-Key: [] tags: - Customers /api/customers/{customer_id}: parameters: - $ref: "#/components/parameters/Authorization" - $ref: "#/components/parameters/Revolut-Api-Version-2024-09-01-Min" - $ref: "#/components/parameters/Customer-Id" get: summary: Retrieve a customer operationId: retrieveCustomer description: Get the information about a specific customer, including their saved payment methods. responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/Customer-v3" examples: retrieved_customer: $ref: "#/components/examples/Res-Customer-v3" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/Error-v2" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/Error-v2" security: - Api-Key: [] tags: - Customers patch: summary: Update a customer operationId: updateCustomer description: >- Update the attributes of a specific customer. All request body fields are optional. Only the fields provided will be updated.
AFT processing requirements For merchants in the following industries, `full_name` and `date_of_birth` are required for Account Funding Transaction (AFT) processing: | Industry | Required fields | | -------- | --------------- | | Crypto | `full_name`, `date_of_birth` | | Financial Institutions | `full_name`, `date_of_birth` | | Stored Value / Wallets | `full_name`, `date_of_birth` |
requestBody: content: application/json: schema: $ref: "#/components/schemas/Customer-Update-v2" examples: example_customer_update: $ref: "#/components/examples/Req-Customer-Update-v2" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/Customer-v3" examples: updated_customer: $ref: "#/components/examples/Res-Customer-v3" "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" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/Error-v2" security: - Api-Key: [] tags: - Customers delete: summary: Delete a customer operationId: deleteCustomer description: Delete the profile of a specific customer. responses: "204": description: No Content "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/Error-v2" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/Error-v2" security: - Api-Key: [] tags: - Customers /api/customers/{customer_id}/payment-methods: parameters: - $ref: "#/components/parameters/Authorization" - $ref: "#/components/parameters/Revolut-Api-Version-2024-09-01-Min" - $ref: "#/components/parameters/Customer-Id" get: summary: Retrieve payment method list of a customer operationId: retrievePaymentMethodList description: >- Retrieve all the saved payment methods for a specific customer. This can be useful in the following example cases: - To show what payment information is stored for the customer. - To try a different payment method if the first payment method fails when a recurring transaction occurs. parameters: - $ref: "#/components/parameters/Only-Merchant" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/Customer-Payment-Methods-v2" examples: list_of_payment_methods: $ref: "#/components/examples/Res-Customer-Payment-Methods-List" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/Error-v2" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/Error-v2" security: - Api-Key: [] tags: - Customers /api/customers/{customer_id}/payment-methods/{payment_method_id}: parameters: - $ref: "#/components/parameters/Authorization" - $ref: "#/components/parameters/Revolut-Api-Version-2024-09-01-Min" - $ref: "#/components/parameters/Customer-Id" - $ref: "#/components/parameters/Payment-Method-Id" get: summary: Retrieve a customer's payment method operationId: retrievePaymentMethod description: "Retrieve the information of a specific saved payment method for a customer. " responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/Payment-Method-v4" examples: retrieved_payment_method: $ref: "#/components/examples/Res-Customer-Payment-Method" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/Error-v2" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/Error-v2" security: - Api-Key: [] tags: - Customers patch: summary: Update a customer's payment method operationId: updatePaymentMethod description: |- Update the attributes of a specific saved payment method for a customer. :::note Updating `saved_for` to `customer` is a one-way operation — you can't change it back to `merchant`. Once updated, this payment method can no longer be used for merchant-initiated transactions (MIT), for example, to charge recurring payments. It can only be used when the customer is on the checkout page. For more information, see: - [Pay for an order](/docs/api/merchant#pay-for-an-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: $ref: "#/components/schemas/Payment-Method-Update" examples: example_payment_method_update: $ref: "#/components/examples/Req-Payment-Method-Update" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/Payment-Method-v4" examples: updated_payment_method: $ref: "#/components/examples/Res-Customer-Payment-Method" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/Error-v2" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/Error-v2" security: - Api-Key: [] tags: - Customers delete: summary: Delete a customer's payment method operationId: deletePaymentMethod description: >- Delete a specific saved payment method. The payment method is completely removed from the customer's saved payment methods. To reuse a deleted payment method, direct your customer to the checkout page to save their card details again. responses: "204": description: No Content "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/Error-v2" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/Error-v2" security: - Api-Key: [] tags: - Customers /api/disputes: parameters: - $ref: "#/components/parameters/Authorization" - $ref: "#/components/parameters/Revolut-Api-Version" get: summary: Retrieve a dispute list operationId: retrieveDisputeList servers: - description: Production server (uses live data) url: https://merchant.revolut.com description: >- Retrieve a list of disputes associated with your merchant account. :::note This endpoint is only available in **Production** environment. ::: You can also use the query parameters for: | Filtering | Pagination | | --------- | ---------- | | Filter the diputes that you want to retrieve, for example, only retrieve the disputes that have a specific state.

Parameters used for filtering:
| View the disputes without loading all of them at once, for example, return a specified number of disputes per page.

Parameters used for pagination:
| parameters: - $ref: "#/components/parameters/Limit" - $ref: "#/components/parameters/From-Created-Date" - $ref: "#/components/parameters/To-Created-Date" - $ref: "#/components/parameters/Dispute-State-Query" - $ref: "#/components/parameters/Payment-Id-Query" responses: "200": description: List of disputes retrieved content: application/json: schema: $ref: "#/components/schemas/Disputes" examples: dispute_list: $ref: "#/components/examples/Res-Dispute-List" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/Error-v2" examples: default: value: code: validation message: limit must be between 1 and 500 timestamp: 1601296792533 "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/Error-v2" examples: default: value: code: unauthenticated message: Authentication failed timestamp: 1721049596461 security: - Api-Key: [] tags: - Disputes /api/disputes/{dispute_id}: parameters: - $ref: "#/components/parameters/Authorization" - $ref: "#/components/parameters/Revolut-Api-Version" - $ref: "#/components/parameters/Dispute-Id" get: summary: Retrieve a dispute operationId: retrieveDispute servers: - description: Production server (uses live data) url: https://merchant.revolut.com description: |- Retrieve the details of a specific dispute by its ID. :::note This endpoint is only available in **Production** environment. ::: responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/Dispute" examples: card_dispute: $ref: "#/components/examples/Res-Dispute-Card" sepa_direct_debit_dispute: $ref: "#/components/examples/Res-Dispute-Sepa-Direct-Debit" "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: 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: The requested resource is not found timestamp: 1721050063886 security: - Api-Key: [] tags: - Disputes /api/disputes/{dispute_id}/accept: parameters: - $ref: "#/components/parameters/Authorization" - $ref: "#/components/parameters/Revolut-Api-Version" - $ref: "#/components/parameters/Dispute-Id" post: summary: Accept a dispute operationId: acceptDispute servers: - description: Production server (uses live data) url: https://merchant.revolut.com description: |- Marks a specific dispute as accepted. After accepting a dispute, you cannot challenge it. :::note This endpoint is only available in **Production** environment. ::: responses: "204": description: Dispute accepted successfully "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: 1601296792533 "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/Error-v2" examples: default: value: code: unauthenticated message: Authentication failed timestamp: 1721049596461 "403": description: Forbidden content: application/json: schema: $ref: "#/components/schemas/Error-v2" examples: default: value: code: not_found message: The requested operation is forbidden timestamp: 1721050063886 "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 "422": description: Unprocessable entity content: application/json: schema: $ref: "#/components/schemas/Error-v2" security: - Api-Key: [] tags: - Disputes /api/disputes/{dispute_id}/evidences: parameters: - $ref: "#/components/parameters/Authorization" - $ref: "#/components/parameters/Revolut-Api-Version" - $ref: "#/components/parameters/Content-Type" - $ref: "#/components/parameters/Dispute-Id" post: summary: Upload evidence for a dispute operationId: uploadDisputeEvidence servers: - description: Production server (uses live data) url: https://merchant.revolut.com description: >- Allows uploading a single evidence file for a specific dispute. Use these evidences to provide proof for claims when challenging a dispute. :::warning **Limitations:** - Maximum `100` uploaded files are allowed per dispute. - Maximum file size: `10MB`. - Allowed file types: `PDF`, `PNG`, `JPEG`. ::: :::note This endpoint is only available in **Production** environment. ::: requestBody: required: true content: multipart/form-data: encoding: file: contentType: application/pdf, image/png, image/jpeg schema: $ref: "#/components/schemas/Dispute-Evidence-Creation" responses: "201": description: Evidence uploaded successfully content: application/json: schema: $ref: "#/components/schemas/Dispute-Evidence" examples: evidence_uploaded: $ref: "#/components/examples/Res-Dispute-Evidence" "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: 1601296792533 "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/Error-v2" examples: default: value: code: unauthenticated message: Authentication failed timestamp: 1721049596461 "403": description: Forbidden content: application/json: schema: $ref: "#/components/schemas/Error-v2" examples: default: value: code: not_found message: The requested operation is forbidden timestamp: 1721050063886 "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 "422": description: Unprocessable entity content: application/json: schema: $ref: "#/components/schemas/Error-v2" security: - Api-Key: [] tags: - Disputes /api/disputes/{dispute_id}/challenge: parameters: - $ref: "#/components/parameters/Authorization" - $ref: "#/components/parameters/Revolut-Api-Version" - $ref: "#/components/parameters/Dispute-Id" post: summary: Challenge a dispute operationId: challengeDispute servers: - description: Production server (uses live data) url: https://merchant.revolut.com description: >- Allows challenging a dispute with a reason, comment and associated evidences. Use the uploaded evidences to provide proof for the challenge. A dispute previously accepted, cannot be challenged. :::note This endpoint is only available in **Production** environment. ::: requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/Dispute-Challenge" examples: challenge_min: $ref: "#/components/examples/Req-Dispute-Challenge-Min" challenge_with_evidence: $ref: "#/components/examples/Req-Dispute-Challenge-With-Evidence" responses: "204": description: Dispute challenged successfully "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: 1601296792533 "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/Error-v2" examples: default: value: code: unauthenticated message: Authentication failed timestamp: 1721049596461 "403": description: Forbidden content: application/json: schema: $ref: "#/components/schemas/Error-v2" examples: default: value: code: not_found message: The requested operation is forbidden timestamp: 1721050063886 "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 "422": description: Unprocessable entity content: application/json: schema: $ref: "#/components/schemas/Error-v2" security: - Api-Key: [] tags: - Disputes /api/payments/{payment_id}: parameters: - $ref: "#/components/parameters/Authorization" - $ref: "#/components/parameters/Payment-Id" - $ref: "#/components/parameters/Revolut-Api-Version-Optional" 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-v3" examples: revolut_pay_saved: summary: Payment completed via Revolut Pay (card, saved details) value: id: 6633855a-0e4f-a768-8b2c-e765d8872505 state: captured created_at: 2024-05-02T12:21:46.638369Z updated_at: 2024-05-02T12:21:55.198089Z token: 0b277730-8b3c-48d4-ab63-8903f40ee520 amount: 100 currency: GBP settled_amount: 77 settled_currency: GBP risk_level: low fees: - type: acquiring amount: 23 currency: GBP payment_method: id: 6633855a-3b39-ad95-9782-cd1327ffa0e7 type: revolut_pay_card fingerprint: 1JAllfQY4POhBV8DaddAQ4LC5RbMP8LMLvUdJW4s5JY= card_brand: visa funding: credit card_country_code: MT card_bin: "123456" card_last_four: "1234" card_expiry: 12/28 cardholder_name: Example Holder checks: three_ds: eci: "06" state: verified version: 2 order_id: 66338534-28a7-a68e-b312-43722430df1b revolut_pay_not_saved: summary: Payment completed via Revolut Pay (account, not saved details) value: id: 66338688-fd73-a358-a82d-97da413c5325 state: captured created_at: 2024-05-02T12:26:48.134039Z updated_at: 2024-05-02T12:26:49.514594Z token: 8061e645-35e0-42bb-8318-603abaeab7b7 amount: 100 currency: GBP settled_amount: 79 settled_currency: GBP billing_address: street_line_1: 123 Example Street street_line_2: Building A, 3rd Floor city: Example City region: Example Region country_code: GB postcode: E14 4HD risk_level: low fees: - type: acquiring amount: 21 currency: GBP payment_method: type: revolut_pay_account fingerprint: 1JAllfQY4POhBV8DaddAQ4LC5RbMP8LMLvUdJW4s5JY= order_id: 6633865d-d911-a98c-8715-425f8731640c apple_tap_to_pay: summary: Payment declined via Apple Tap to Pay value: id: 66338688-fd73-a358-a82d-97da413c5325 state: declined created_at: 2024-05-02T12:26:48.134039Z updated_at: 2024-05-02T12:26:49.514594Z token: 8061e645-35e0-42bb-8318-603abaeab7b7 amount: 100 currency: GBP settled_amount: 79 settled_currency: GBP billing_address: street_line_1: 123 Example Street street_line_2: Building A, 3rd Floor city: Example City region: Example Region country_code: GB postcode: E14 4HD risk_level: low fees: - type: acquiring amount: 21 currency: GBP payment_method: type: apple_tap_to_pay failure_reason: pin_data_required order_id: 6633865d-d911-a98c-8715-425f8731640c apple_pay: summary: Payment completed via Apple Pay value: id: 66338688-fd73-a358-a82d-97da413c5325 state: captured created_at: 2024-05-02T12:26:48.134039Z updated_at: 2024-05-02T12:26:49.514594Z token: 8061e645-35e0-42bb-8318-603abaeab7b7 amount: 100 currency: GBP settled_amount: 79 settled_currency: GBP billing_address: street_line_1: 123 Example Street street_line_2: Building A, 3rd Floor city: Example City region: Example Region country_code: GB postcode: E14 4HD risk_level: low fees: - type: acquiring amount: 21 currency: GBP payment_method: type: apple_pay fingerprint: 1JAllfQY4POhBV8DaddAQ4LC5RbMP8LMLvUdJW4s5JY= order_id: 6633865d-d911-a98c-8715-425f8731640c google_pay: summary: Payment completed via Google Pay value: id: 66338688-fd73-a358-a82d-97da413c5325 state: captured created_at: 2024-05-02T12:26:48.134039Z updated_at: 2024-05-02T12:26:49.514594Z token: 8061e645-35e0-42bb-8318-603abaeab7b7 amount: 100 currency: GBP settled_amount: 79 settled_currency: GBP billing_address: street_line_1: 123 Example Street street_line_2: Building A, 3rd Floor city: Example City region: Example Region country_code: GB postcode: E14 4HD risk_level: low fees: - type: acquiring amount: 21 currency: GBP payment_method: type: google_pay fingerprint: 1JAllfQY4POhBV8DaddAQ4LC5RbMP8LMLvUdJW4s5JY= order_id: 6633865d-d911-a98c-8715-425f8731640c card_payment_saved: summary: Payment completed via card (saved details) value: id: 663387f1-1c2e-a295-b143-9f1fb1eec175 state: captured created_at: 2024-05-02T12:32:49.033945Z updated_at: 2024-05-02T12:32:57.003519Z token: 294358bf-3818-49b2-aacc-7ca971f52695 amount: 100 currency: GBP settled_amount: 79 settled_currency: GBP billing_address: street_line_1: 123 Example Street street_line_2: Building A, 3rd Floor city: Example City region: Example Region country_code: GB postcode: E14 4HD risk_level: low fees: - type: acquiring amount: 21 currency: GBP payment_method: id: 663387f1-c91e-a464-908a-1cc4548ebc6a type: card fingerprint: 1JAllfQY4POhBV8DaddAQ4LC5RbMP8LMLvUdJW4s5JY= card_brand: visa funding: credit card_country_code: GB card_bin: "123456" card_last_four: "1234" card_expiry: 12/30 cardholder_name: Test Holder checks: three_ds: eci: "06" state: verified version: 2 cvv_verification: match address: match postcode: match cardholder: n_a order_id: 663387bd-8484-ac57-93a7-3751dc154bbc card_payment_not_saved: summary: Payment completed via card (not saved details) value: id: 663387f1-1c2e-a295-b143-9f1fb1eec175 state: captured created_at: 2024-05-02T12:32:49.033945Z updated_at: 2024-05-02T12:32:57.003519Z token: 294358bf-3818-49b2-aacc-7ca971f52695 amount: 100 currency: GBP settled_amount: 79 settled_currency: GBP billing_address: street_line_1: 123 Example Street street_line_2: Building A, 3rd Floor city: Example City region: Example Region country_code: GB postcode: E14 4HD risk_level: low fees: - type: acquiring amount: 21 currency: GBP payment_method: type: card fingerprint: 1JAllfQY4POhBV8DaddAQ4LC5RbMP8LMLvUdJW4s5JY= card_brand: visa funding: credit card_country_code: GB card_bin: "123456" card_last_four: "1234" card_expiry: 12/30 cardholder_name: Test Holder checks: three_ds: eci: "06" state: verified version: 2 cvv_verification: match address: match postcode: match cardholder: n_a order_id: 663387bd-8484-ac57-93a7-3751dc154bbc card_three_ds_fingerprint: $ref: "#/components/examples/Res-Payment-Authentication-Challenge-Fingerprint" "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/subscription-plans: parameters: - $ref: "#/components/parameters/Authorization" - $ref: "#/components/parameters/Revolut-Api-Version" servers: - description: Production server (uses live data) url: https://merchant.revolut.com post: summary: Create a subscription plan operationId: createSubscriptionPlan description: >- Create a new subscription plan with one or more pricing variations. A subscription plan defines the billing structure for subscriptions. Each plan can have multiple variations (e.g., monthly vs. yearly), and each variation can have multiple billing phases (e.g., trial period followed by regular billing). These plans are designed for flexibility, allowing you to combine fixed recurring fees with unit-based or usage-based charges into a single, unified subscription. ## How subscription plans work A subscription plan consists of four hierarchical levels: 1. **Plan**: The top-level container (e.g., "Standard Plan") 1. **Variations**: Different pricing options (e.g., monthly vs. yearly) 1. **Phases**: Sequential billing stages within each variation 1. **Subscription items**: Individual line items within a phase that define **how** to charge (e.g., a base fee plus per-unit charges) ### Phases and billing items If a `trial_duration` is defined at the variation level, billing phases begin immediately after the trial ends. Phases execute in sequence based on their `ordinal` value (1, 2, 3, etc.): | Concept | Behaviour | | ------- | --------- | | **Cycle control** | Each phase has a `cycle_duration` (e.g., `P1M` for monthly). Use `cycle_count` to limit how many cycles occur; if `null` or omitted, the phase runs indefinitely. | | **Sequential transition** | When a phase completes its cycles, the subscription advances to the next `ordinal`. If no next phase exists, the subscription stops automatically. | | **Item composition** | Each phase contains one or more `subscription_items` defining how charges are calculated: **flat** items apply a fixed cost multiplied by `quantity`; **usage** items are metered at the end of the cycle based on reported consumption. | :::tip [Example: Multi-item billing] A plan combining a **base platform fee** and **monthly user licenses**: **Variation:** `Monthly Team` **Phase 1** — `ordinal: 1`, `cycle_duration: P1M` | Item | Type | `amount` | `quantity` | | ---- | ---- | -------- | ---------- | | **Base platform fee** | `flat` | `4900` (£49.00) | `1` | | **User licenses** | `flat` | `1000` (£10.00 per unit) | `5` | The customer is billed a fixed platform fee plus £10.00 for each of their 5 active licenses every month. ::: tags: - Subscriptions requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/Subscription-Plan-Creation" examples: simple_plan: $ref: "#/components/examples/Req-Subscription-Plan-Simple" trial_plan_with_duration: $ref: "#/components/examples/Req-Subscription-Plan-With-Trial-Duration" limited_plan: $ref: "#/components/examples/Req-Subscription-Plan-Limited" usage_base_plan: $ref: "#/components/examples/Req-Subscription-Plan-Usage-Base" hybrid_plan: $ref: "#/components/examples/Req-Subscription-Plan-Hybrid" package_plan: $ref: "#/components/examples/Req-Subscription-Plan-Package" items_plan: $ref: "#/components/examples/Req-Subscription-Plan-With-Items" responses: "201": description: Subscription plan created successfully content: application/json: schema: $ref: "#/components/schemas/Subscription-Plan" examples: simple_plan: $ref: "#/components/examples/Res-Subscription-Plan-Simple" trial_plan_with_duration: $ref: "#/components/examples/Res-Subscription-Plan-With-Trial-Duration" limited_plan: $ref: "#/components/examples/Res-Subscription-Plan-Limited" usage_base_plan: $ref: "#/components/examples/Res-Subscription-Plan-Usage-Base" hybrid_plan: $ref: "#/components/examples/Res-Subscription-Plan-Hybrid" package_plan: $ref: "#/components/examples/Res-Subscription-Plan-Package" items_plan: $ref: "#/components/examples/Res-Subscription-Plan-With-Items" "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" default: description: Error response content: application/json: schema: $ref: "#/components/schemas/Error-v2" security: - Api-Key: [] get: summary: Retrieve a subscription plan list operationId: retrieveSubscriptionPlanList description: >- Retrieve all subscription plans configured for your merchant account. You can use the query parameters for: | Filtering | Pagination | | --------- | ---------- | | Filter the subscription plans that you want to retrieve, for example, only retrieve plans created within a specific date range.

Parameters used for filtering:
| View the subscription plans without loading all of them at once, for example, return a specified number of plans per page.

Parameters used for pagination:
| tags: - Subscriptions parameters: - $ref: "#/components/parameters/Limit" - $ref: "#/components/parameters/From" - $ref: "#/components/parameters/To" - $ref: "#/components/parameters/Page-Token" responses: "200": description: List of subscription plans retrieved successfully content: application/json: schema: $ref: "#/components/schemas/Subscription-Plans" examples: plans_list: $ref: "#/components/examples/Res-Subscription-Plans-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" default: description: Error response content: application/json: schema: $ref: "#/components/schemas/Error-v2" security: - Api-Key: [] /api/subscription-plans/{subscription_plan_id}: parameters: - $ref: "#/components/parameters/Authorization" - $ref: "#/components/parameters/Revolut-Api-Version" - $ref: "#/components/parameters/Subscription-Plan-Id" servers: - description: Production server (uses live data) url: https://merchant.revolut.com get: summary: Retrieve a subscription plan operationId: retrieveSubscriptionPlan description: >- Retrieve a specific subscription plan by its unique identifier. A subscription plan contains **variations** (different pricing options like monthly vs. yearly), and each variation contains **phases** (sequential billing stages). Phases execute based on their `ordinal` value. When a phase completes its `cycle_count`, the subscription moves to the next phase. If `cycle_count` is `null` or omitted, the phase continues indefinitely. :::note If a `trial_duration` is defined, phases begin immediately after the trial ends. ::: tags: - Subscriptions responses: "200": description: Subscription plan retrieved successfully content: application/json: schema: $ref: "#/components/schemas/Subscription-Plan" examples: simple_plan: $ref: "#/components/examples/Res-Subscription-Plan-Simple" trial_plan_with_duration: $ref: "#/components/examples/Res-Subscription-Plan-With-Trial-Duration" limited_plan: $ref: "#/components/examples/Res-Subscription-Plan-Limited" "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" "404": description: Subscription plan not found content: application/json: schema: $ref: "#/components/schemas/Error-v2" default: description: Error response content: application/json: schema: $ref: "#/components/schemas/Error-v2" security: - Api-Key: [] /api/subscriptions: parameters: - $ref: "#/components/parameters/Authorization" - $ref: "#/components/parameters/Revolut-Api-Version" servers: - description: Production server (uses live data) url: https://merchant.revolut.com post: summary: Create a subscription operationId: createSubscription description: >- Create a new subscription for a customer using a subscription plan variation. There are several supported flows for creating and activating subscriptions, depending on your integration needs. :::note The customer must already exist in the API. The `customer_id` is required for all subscription flows. :::
#### Flow 1: Hosted Payment Page (HPP) Use this flow to redirect the customer to Revolut's Hosted Payment Page to complete the first payment and save their payment method. **Backend flow:** 1. Create a subscription with optional `setup_order_redirect_url`: | `setup_order_redirect_url` | Behaviour | | -------------------------- | --------- | | **Provided** | The setup order's `redirect_url` field is set to this value. | | **Omitted** | The setup order uses Revolut's default redirect behaviour. | 1. The subscription is created in a `pending` state with a `setup_order_id` in the response. 1. [Retrieve the order](/docs/api/merchant#retrieve-an-order) using `setup_order_id` as the `order_id` in the path to get the `checkout_url`. 1. Redirect the customer to the `checkout_url` for the Hosted Payment Page. **Customer flow:** 1. Customer is redirected to Revolut's Hosted Payment Page. 1. Customer completes payment on the HPP, and their payment method is saved. 1. Customer redirect after payment depends on your setup: | `setup_order_redirect_url` | Customer redirect | | -------------------------- | ----------------- | | **Provided** | Customer is redirected to your custom URL. | | **Omitted** | Customer sees the default Revolut completion screen. | **Key characteristics:** - Customer completes payment on Revolut's hosted page - Payment method is automatically saved for future billing cycles - Optional custom redirect after payment - Best for web-based integrations
#### Flow 2: Widget or card-not-present (CNP) payment Use this flow when you want to embed the payment experience directly on your website using one of Revolut's payment widgets or handle card-not-present payments. **Backend flow:** 1. Create a subscription with minimal required parameters. 1. The subscription is created in a `pending` state with a `setup_order_id` in the response. 1. [Retrieve the order](/docs/api/merchant#retrieve-an-order) using `setup_order_id` as the `order_id` in the path to get order details for your integration. 1. Integrate your payment solution (widget, SDK, or CNP method) on your frontend, ensuring it's configured to save the customer's payment method for recurring billing. **Customer flow:** 1. Customer stays on your website/application. 1. Customer completes payment, and their payment method is saved for future billing cycles. **Key characteristics:** - Payment experience embedded directly in your application - Customer never leaves your website - Payment method is saved for future billing cycles - Best for native mobile apps or fully custom web experiences
tags: - Subscriptions parameters: - $ref: "#/components/parameters/Idempotency-Key" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/Subscription-Creation" examples: with_setup_order: $ref: "#/components/examples/Req-Subscription-Setup-Order" with_setup_order_no_url: $ref: "#/components/examples/Req-Subscription-Setup-Order-No-URL" with_trial: $ref: "#/components/examples/Req-Subscription-With-Trial" skip_trial: $ref: "#/components/examples/Req-Subscription-Skip-Trial" responses: "201": description: Subscription created successfully content: application/json: schema: $ref: "#/components/schemas/Subscription" examples: with_setup_order: $ref: "#/components/examples/Res-Subscription-Setup-Order" with_setup_order_no_url: $ref: "#/components/examples/Res-Subscription-Setup-Order-No-URL" "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" default: description: Error response content: application/json: schema: $ref: "#/components/schemas/Error-v2" security: - Api-Key: [] get: summary: Retrieve a subscription list operationId: retrieveSubscriptionList description: >- Retrieve all subscriptions for the merchant account. You can use the query parameters for: | Filtering | Pagination | | --------- | ---------- | | Filter the subscriptions that you want to retrieve, for example, only retrieve subscriptions created within a specific date range or with a specific external reference.

Parameters used for filtering:
| View the subscriptions without loading all of them at once, for example, return a specified number of subscriptions per page.

Parameters used for pagination:
| tags: - Subscriptions parameters: - $ref: "#/components/parameters/Limit" - $ref: "#/components/parameters/From" - $ref: "#/components/parameters/To" - name: external_reference in: query schema: type: string description: Return subscriptions with a specific `external_reference`. Used for **filtering**. required: false - $ref: "#/components/parameters/Page-Token" responses: "200": description: List of subscriptions retrieved successfully content: application/json: schema: $ref: "#/components/schemas/Subscriptions" examples: subscriptions_list: $ref: "#/components/examples/Res-Subscriptions-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" default: description: Error response content: application/json: schema: $ref: "#/components/schemas/Error-v2" security: - Api-Key: [] /api/subscriptions/{subscription_id}: parameters: - $ref: "#/components/parameters/Authorization" - $ref: "#/components/parameters/Revolut-Api-Version" - $ref: "#/components/parameters/Subscription-Id" servers: - description: Production server (uses live data) url: https://merchant.revolut.com get: summary: Retrieve a subscription operationId: retrieveSubscription description: >- Retrieve a subscription by its unique identifier. Use this endpoint to get the current state and details of a specific subscription. tags: - Subscriptions responses: "200": description: Subscription retrieved successfully content: application/json: schema: $ref: "#/components/schemas/Subscription" examples: active_subscription: $ref: "#/components/examples/Res-Subscription-Active" "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" "404": description: Subscription not found content: application/json: schema: $ref: "#/components/schemas/Error-v2" default: description: Error response content: application/json: schema: $ref: "#/components/schemas/Error-v2" security: - Api-Key: [] patch: summary: Update a subscription operationId: updateSubscription description: >- Update a subscription's details. You can update a subscription and specific parameters based on the value of the `state` parameter: | State parameter value | Modifiable parameters | | --------------------- | --------------------- | | `pending`, `active`, `overdue`, `paused` | You can modify all listed parameters. | | `cancelled`, `finished` | You cannot modify parameters. These are final states. | **Common use cases:** - **Update external reference**: When you need to sync with updated customer records in your system, correct an initial reference value, or re-map the subscription to a different internal tracking ID to maintain consistency with your database. tags: - Subscriptions requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/Subscription-Update" examples: update_subscription: $ref: "#/components/examples/Req-Subscription-Update" responses: "200": description: Subscription updated successfully content: application/json: schema: $ref: "#/components/schemas/Subscription" examples: updated_subscription: $ref: "#/components/examples/Res-Subscription-Active" "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" "404": description: Subscription not found content: application/json: schema: $ref: "#/components/schemas/Error-v2" default: description: Error response content: application/json: schema: $ref: "#/components/schemas/Error-v2" security: - Api-Key: [] /api/subscriptions/{subscription_id}/change-plan: parameters: - $ref: "#/components/parameters/Authorization" - $ref: "#/components/parameters/Revolut-Api-Version" - $ref: "#/components/parameters/Subscription-Id" servers: - description: Production server (uses live data) url: https://merchant.revolut.com post: summary: Change a subscription plan operationId: changeSubscriptionPlan description: >- Schedule a plan change for a subscription. The change is applied at the end of the current billing cycle. ### Use cases - **Plan upgrades:** Moving a customer to a higher-tier plan with more features or capacity. - **Plan downgrades:** Moving a customer to a lower-tier plan that better fits their usage and budget. - **Customer requests:** Accommodating a customer's request to switch to a different plan variation. ### How it works When you schedule a plan change, the subscription continues operating under its current plan variation until the current billing cycle ends. At that point, the next cycle is created under the new plan variation. - **Scheduled change:** The plan change is scheduled to take effect `at_cycle_end`. The current cycle completes normally, and the new plan variation applies starting from the next cycle. - **Plan variation phases:** Some plan variations are divided into phases - distinct pricing or duration periods within a single variation. If the target plan variation has multiple phases, use `plan_variation_phase_id` to specify which phase to start from. If omitted, the change starts from the first phase. - **Trial periods:** If the target plan variation includes a trial period, it is skipped when changing plans. Trial periods only apply when a subscription is first created. - **Subsequent cycles:** After the transition, future cycles follow the cadence and pricing defined by the new plan variation. tags: - Subscriptions requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/Subscription-Change-Plan" examples: change_plan: $ref: "#/components/examples/Req-Subscription-Change-Plan" change_plan_with_reason: $ref: "#/components/examples/Req-Subscription-Change-Plan-With-Reason" change_plan_with_phase: $ref: "#/components/examples/Req-Subscription-Change-Plan-With-Phase" responses: "204": description: Plan change scheduled successfully "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/Error-v2" examples: immediate_not_supported: summary: Immediate plan change not supported value: code: bad_request message: Immediate plan change is not supported. Please provide 'scheduled' field (e.g. 'at_cycle_end') timestamp: 1601296792533 "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/Error-v2" "404": description: Subscription not found content: application/json: schema: $ref: "#/components/schemas/Error-v2" "422": description: Unprocessable entity content: application/json: schema: $ref: "#/components/schemas/Error-v2" examples: subscription_finished: summary: Subscription is finished value: code: subscription_finished message: The subscription is finished timestamp: 1601296792533 next_cycle_exists: summary: Next cycle already exists with a different plan variation value: code: subscription_cycle_next_cycle_exists message: Next cycle already exists with a different plan variation timestamp: 1601296792533 default: description: Error response content: application/json: schema: $ref: "#/components/schemas/Error-v2" security: - Api-Key: [] /api/subscriptions/{subscription_id}/change-renewal-date: parameters: - $ref: "#/components/parameters/Authorization" - $ref: "#/components/parameters/Revolut-Api-Version" - $ref: "#/components/parameters/Subscription-Id" servers: - description: Production server (uses live data) url: https://merchant.revolut.com post: summary: Update a subscription renewal date operationId: updateSubscriptionRenewalDate description: >- Reschedule the upcoming payment date for an active subscription cycle. This is a command endpoint — the renewal date is not a direct field on the Subscription resource, but is derived from the current active cycle's `end_date`. ### Use cases - **Payment extensions:** Granting a customer more time to pay. - **Service delays:** Adjusting the billing date if service delivery is delayed. - **Billing alignment:** Moving a payment date to better suit a customer's financial schedule. ### How it works Extending the current cycle's `end_date` naturally postpones the start of the next cycle and its associated payment trigger, providing flexibility for both the merchant and the customer. The relationship between the cycle end and the billing execution depends on the plan type: - **Non-usage plans:** The next cycle's start date is the same as the billing date. The moment the current cycle ends, the next cycle begins and the payment is attempted. - **Usage-based plans (buffer & overlap):** To allow merchants time to finalize usage data, the billing date is scheduled after the cycle `end_date`. - Usage continues to be aggregated until the updated `end_date`. - When the current cycle (Cycle 1) reaches its updated `end_date`, **Cycle 2 starts immediately** to ensure no service interruption. - The billing for Cycle 1 occurs a few hours later (12-hour buffer). This window allows you to upload or edit usages for the period that just ended while the customer is already technically in their next cycle. - Rescheduling the `renewal_date` pushes this entire sequence—the end of Cycle 1, the start of Cycle 2, and the delayed billing trigger—further into the future. Subsequent cycles resume the original plan cadence (e.g., monthly) from the new date. tags: - Subscriptions requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/Subscription-Update-Renewal-Date" examples: simple_plan: $ref: "#/components/examples/Req-Subscription-Update-Renewal-Date" responses: "204": description: Renewal date updated successfully "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" "404": description: Subscription not found content: application/json: schema: $ref: "#/components/schemas/Error-v2" "422": description: Unprocessable entity (business rule violation) content: application/json: schema: $ref: "#/components/schemas/Error-v2" examples: subscription_finished: summary: Subscription is finished value: code: subscription_finished message: The subscription is finished timestamp: 1601296792533 next_cycle_exists: summary: Next cycle already exists value: code: subscription_cycle_next_cycle_exists message: Cannot change cycle end date when next cycle already exists timestamp: 1601296792533 end_date_too_early: summary: Renewal date is too early value: code: subscription_cycle_end_date_too_early message: The end date is too early timestamp: 1601296792533 end_date_too_far: summary: Renewal date is too far in the future value: code: subscription_cycle_end_date_too_far message: The end date is too far in the future timestamp: 1601296792533 default: description: Error response content: application/json: schema: $ref: "#/components/schemas/Error-v2" security: - Api-Key: [] /api/subscriptions/{subscription_id}/cancel: parameters: - $ref: "#/components/parameters/Authorization" - $ref: "#/components/parameters/Revolut-Api-Version" - $ref: "#/components/parameters/Subscription-Id" servers: - description: Production server (uses live data) url: https://merchant.revolut.com post: summary: Cancel a subscription operationId: cancelSubscription description: >- Cancel a subscription. You can cancel a subscription in any state except `cancelled` or `finished`. When you cancel a subscription, it will be marked as `cancelled` and no further billing cycles will be created. Any pending orders will be cancelled. tags: - Subscriptions responses: "204": description: Subscription cancelled successfully "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" "404": description: Subscription not found content: application/json: schema: $ref: "#/components/schemas/Error-v2" default: description: Error response content: application/json: schema: $ref: "#/components/schemas/Error-v2" security: - Api-Key: [] /api/subscriptions/{subscription_id}/cycles: parameters: - $ref: "#/components/parameters/Authorization" - $ref: "#/components/parameters/Revolut-Api-Version" - $ref: "#/components/parameters/Subscription-Id" servers: - description: Production server (uses live data) url: https://merchant.revolut.com get: summary: Retrieve a subscription cycle list operationId: retrieveSubscriptionCycleList description: >- Retrieve all billing cycles for a specific subscription. You can use the query parameters for: | Filtering | Pagination | | --------- | ---------- | | Filter the subscription cycles that you want to retrieve, for example, only retrieve cycles that started within a specific date range.

Parameters used for filtering:
| View the subscription cycles without loading all of them at once, for example, return a specified number of cycles per page.

Parameters used for pagination:
| tags: - Subscriptions parameters: - $ref: "#/components/parameters/Limit" - $ref: "#/components/parameters/From" - $ref: "#/components/parameters/To" - $ref: "#/components/parameters/Page-Token" responses: "200": description: List of subscription cycles retrieved successfully content: application/json: schema: $ref: "#/components/schemas/Subscription-Cycles" examples: cycles_list: $ref: "#/components/examples/Res-Subscription-Cycles-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" "404": description: Subscription not found content: application/json: schema: $ref: "#/components/schemas/Error-v2" default: description: Error response content: application/json: schema: $ref: "#/components/schemas/Error-v2" security: - Api-Key: [] /api/subscriptions/{subscription_id}/cycles/{cycle_id}: parameters: - $ref: "#/components/parameters/Authorization" - $ref: "#/components/parameters/Revolut-Api-Version" - $ref: "#/components/parameters/Subscription-Id" - $ref: "#/components/parameters/Cycle-Id" servers: - description: Production server (uses live data) url: https://merchant.revolut.com get: summary: Retrieve a subscription cycle operationId: retrieveSubscriptionCycle description: >- Retrieve a specific billing cycle for a subscription by its unique identifier. Use this endpoint to get the details and current state of a particular billing cycle. tags: - Subscriptions responses: "200": description: Subscription cycle retrieved successfully content: application/json: schema: $ref: "#/components/schemas/Subscription-Cycle" examples: finished_cycle: $ref: "#/components/examples/Res-Subscription-Cycle-Finished" "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" "404": description: Subscription cycle not found content: application/json: schema: $ref: "#/components/schemas/Error-v2" default: description: Error response content: application/json: schema: $ref: "#/components/schemas/Error-v2" security: - Api-Key: [] /api/subscription-usages: parameters: - $ref: "#/components/parameters/Authorization" - $ref: "#/components/parameters/Revolut-Api-Version" servers: - description: Production server (uses live data) url: https://merchant.revolut.com post: summary: Create a subscription usage operationId: createSubscriptionUsage description: >- Report a unit of consumption against a usage-based subscription item. Revolut accumulates reported records throughout the billing cycle and processes the charge after the cycle's `usage_cutoff_date`. ### Resolve the billing cycle Revolut automatically identifies the applicable billing cycle from the `usage_date` you provide. The following submission windows are accepted: | Window | Rule | | ------ | ---- | | Active cycle | `usage_date` falls within the current cycle (`start_date ≤ usage_date < end_date`). | | Past cycle correction | `usage_date` falls within a recently ended cycle, and the request is made before that cycle's `usage_cutoff_date` (12 hours after `end_date` by default). | | Next upcoming cycle | `usage_date` falls within the one next future cycle. Revolut creates a `pending` cycle to hold the record until it becomes active. | Any `usage_date` outside these windows causes the request to be rejected. ### How Revolut calculates the charge After the `usage_cutoff_date` passes, all records for each usage item are aggregated using the method defined on the subscription plan: | Method | Behaviour | | ------ | --------- | | `sum` | Totals all reported values during the cycle. Use for cumulative metrics (e.g., total GB transferred). | | `latest` | Uses the most recently reported value at the `usage_cutoff_date`. If no usages are reported during the cycle, the charge is 0. Use for gauge-style metrics (e.g., active seat count at month-end). | | `max` | Uses the highest value reported during the cycle. Use for capacity-based billing (e.g., peak concurrent connections). | The aggregated total is multiplied by the unit price to produce the final charge. tags: - Subscriptions requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/Subscription-Usage-Creation" examples: report_usage: $ref: "#/components/examples/Req-Subscription-Usage" responses: "201": description: Usage reported successfully content: application/json: schema: $ref: "#/components/schemas/Subscription-Usage" examples: usage_record: $ref: "#/components/examples/Res-Subscription-Usage" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/Error-v2" examples: item_code_not_found: summary: Subscription item code not found value: code: subscription_item_code_not_found message: Subscription item code 'api_calls' not found for phase timestamp: 1743465600 "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/Error-v2" "422": description: Unprocessable entity (business rule violation) content: application/json: schema: $ref: "#/components/schemas/Error-v2" examples: subscription_finished: summary: Subscription is finished value: code: subscription_finished message: Cannot add usage to a finished subscription timestamp: 1743465600 usage_after_last_cycle: summary: Usage date after last cycle value: code: subscription_usage_after_last_cycle message: Usage date is after the last cycle timestamp: 1743465600 usage_before_start: summary: Usage date before subscription start value: code: subscription_usage_before_subscription_start message: Usage date is before the subscription start date timestamp: 1743465600 future_cycle_limit_exceeded: summary: Future cycle limit exceeded value: code: subscription_usage_future_cycle_limit_exceeded message: Cannot add usage for cycles too far in the future timestamp: 1743465600 usage_locked: summary: Cycle is past the usage cutoff date value: code: subscription_usage_locked message: Cannot modify usage for a locked cycle timestamp: 1743465600 default: description: Error response content: application/json: schema: $ref: "#/components/schemas/Error-v2" security: - Api-Key: [] get: summary: Retrieve a subscription usage list operationId: retrieveSubscriptionUsageList description: >- Retrieve all usage records for the merchant account. Results are ordered by `usage_date`, unlike other list endpoints which order by `created_at`. You can use the query parameters for: | Filtering | Pagination | | --------- | ---------- | | Filter the usage records that you want to retrieve, for example, only retrieve records for a specific subscription or billing cycle.

Parameters used for filtering:
| View usage records without loading all of them at once, for example, return a specified number of records per page.

Parameters used for pagination:
| tags: - Subscriptions parameters: - $ref: "#/components/parameters/Limit" - $ref: "#/components/parameters/From-Usage-Date" - $ref: "#/components/parameters/To-Usage-Date" - $ref: "#/components/parameters/Subscription-Id-Query" - $ref: "#/components/parameters/Subscription-Cycle-Id-Query" - $ref: "#/components/parameters/Page-Token" responses: "200": description: List of subscription usages retrieved successfully content: application/json: schema: $ref: "#/components/schemas/Subscription-Usages" examples: usage_list: $ref: "#/components/examples/Res-Usage-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" default: description: Error response content: application/json: schema: $ref: "#/components/schemas/Error-v2" security: - Api-Key: [] /api/subscription-usages/{usage_id}: parameters: - $ref: "#/components/parameters/Authorization" - $ref: "#/components/parameters/Revolut-Api-Version" - $ref: "#/components/parameters/Usage-Id" servers: - description: Production server (uses live data) url: https://merchant.revolut.com get: summary: Retrieve a subscription usage operationId: retrieveSubscriptionUsage description: >- Retrieve a usage record by its unique identifier. Use this endpoint to get the details of a specific usage that was reported or updated. tags: - Subscriptions responses: "200": description: Usage record retrieved successfully content: application/json: schema: $ref: "#/components/schemas/Subscription-Usage" examples: usage_record: $ref: "#/components/examples/Res-Subscription-Usage" "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" "404": description: Usage not found content: application/json: schema: $ref: "#/components/schemas/Error-v2" default: description: Error response content: application/json: schema: $ref: "#/components/schemas/Error-v2" security: - Api-Key: [] patch: summary: Update a subscription usage operationId: updateSubscriptionUsage description: Update the quantity or metadata of a subscription usage record. tags: - Subscriptions requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/Subscription-Usage-Update" examples: update_usage_quantity: $ref: "#/components/examples/Req-Subscription-Usage-Update-Quantity" update_usage_metadata: $ref: "#/components/examples/Req-Subscription-Usage-Update-Metadata" update_usage: $ref: "#/components/examples/Req-Subscription-Usage-Update" responses: "200": description: Usage updated successfully content: application/json: schema: $ref: "#/components/schemas/Subscription-Usage" examples: updated_usage: $ref: "#/components/examples/Res-Subscription-Usage" "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" "404": description: Usage not found content: application/json: schema: $ref: "#/components/schemas/Error-v2" "422": description: Unprocessable entity (business rule violation) content: application/json: schema: $ref: "#/components/schemas/Error-v2" examples: usage_locked: summary: Cycle is past the usage cutoff date value: code: subscription_usage_locked message: Cannot modify usage for a locked cycle timestamp: 1743465600 default: description: Error response content: application/json: schema: $ref: "#/components/schemas/Error-v2" security: - Api-Key: [] delete: summary: Delete a subscription usage operationId: deleteSubscriptionUsage description: Delete a subscription usage record. This operation is only permitted while the billing cycle is still open. tags: - Subscriptions responses: "204": description: Usage deleted successfully "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" "404": description: Usage not found content: application/json: schema: $ref: "#/components/schemas/Error-v2" "422": description: Unprocessable entity (business rule violation) content: application/json: schema: $ref: "#/components/schemas/Error-v2" examples: usage_locked: summary: Cycle is past the usage cutoff date value: code: subscription_usage_locked message: Cannot modify usage for a locked cycle timestamp: 1743465600 default: description: Error response content: application/json: schema: $ref: "#/components/schemas/Error-v2" security: - Api-Key: [] /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/webhooks: parameters: - $ref: "#/components/parameters/Authorization" - $ref: "#/components/parameters/Revolut-Api-Version-2024-09-01-Min" post: summary: Create a webhook operationId: createWebhook 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: $ref: "#/components/examples/Req-Webhook-Create" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/Webhook-v2" examples: created_webhook: $ref: "#/components/examples/Res-Webhook-v2" "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" "422": description: Unprocessable Content content: application/json: schema: $ref: "#/components/schemas/Error-v2" callbacks: Send webhook event: $ref: "#/components/callbacks/Webhook-Event" security: - Api-Key: [] tags: - Webhooks get: summary: Retrieve a webhook list operationId: retrieveWebhookList description: Get a list of webhooks that you are currently subscribed to. responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/Webhooks" examples: list_of_webhooks: $ref: "#/components/examples/Res-Webhooks-List" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/Error-v2" security: - Api-Key: [] tags: - Webhooks /api/webhooks/{webhook_id}: parameters: - $ref: "#/components/parameters/Authorization" - $ref: "#/components/parameters/Revolut-Api-Version-2024-09-01-Min" - $ref: "#/components/parameters/Webhook-Id" get: summary: Retrieve a webhook operationId: retrieveWebhook description: "Get the details of a specific webhook, including its `signing_secret`. " responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/Webhook-v2" examples: retrieved_webhook: $ref: "#/components/examples/Res-Webhook-v2" "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 patch: summary: Update a webhook operationId: updateWebhook description: >- Update the URL or events for a specific webhook. All request body fields are optional. Only the fields provided will be updated. requestBody: content: application/json: schema: $ref: "#/components/schemas/Webhook-Update" examples: webhook_update_request: $ref: "#/components/examples/Req-Webhook-Update" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/Webhook-v2" examples: updated_webhook: $ref: "#/components/examples/Res-Webhook-v2" "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" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/Error-v2" security: - Api-Key: [] tags: - Webhooks delete: summary: Delete a webhook operationId: deleteWebhook description: Delete a webhook so that events are no longer sent to the specified URL. responses: "204": description: No Content "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/Error-v2" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/Error-v2" security: - Api-Key: [] tags: - Webhooks /api/webhooks/{webhook_id}/rotate-signing-secret: parameters: - $ref: "#/components/parameters/Authorization" - $ref: "#/components/parameters/Revolut-Api-Version-2024-09-01-Min" - $ref: "#/components/parameters/Webhook-Id" post: summary: Rotate a webhook signing secret operationId: rotateWebhookSigningSecret description: |- Rotate the `signing_secret` for a specific webhook. The updated signing secret is returned in the response as part of the full webhook object. :::info 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: $ref: "#/components/examples/Req-Webhook-Rotate-Signing-Secret" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/Webhook-v2" examples: updated_webhook: $ref: "#/components/examples/Res-Webhook-v2" "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" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/Error-v2" 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#generate-api-keys). ::: 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-for-fast-checkout)) 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/apis?tab=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: [Authentication](/docs/api/merchant#authentication) ::: 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 Limit: name: limit in: query schema: type: integer minimum: 1 maximum: 500 default: 100 description: Maximum number of records to return. Used for **pagination**. required: false From: name: from in: query schema: type: string format: date-time description: Filter records created from this date/time. Used for **filtering**. required: false To: name: to in: query schema: type: string format: date-time description: Filter records created until this date/time. Used for **filtering**. required: false Customer-Id-Query: name: customer_id in: query schema: type: string format: uuid description: Filter orders by the ID of the customer. required: false Merchant-Order-Data-Reference: name: merchant_order_data_reference in: query schema: $ref: "#/components/schemas/Merchant-Order-External-Reference" description: Filter orders by your own order reference set in `merchant_order_data.reference`. required: false Order-State-Query: name: state in: query required: false explode: true description: >- Filter orders by state. Repeat the parameter to filter by multiple states. | Value | 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 | schema: type: array items: $ref: "#/components/schemas/Order-State" 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. 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. Revolut-Api-Version-2024-09-01-Min: name: Revolut-Api-Version in: header schema: type: string format: date enum: - 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. This endpoint is available from version `2024-09-01`. If a version earlier than `2024-09-01` is provided, the endpoint returns a `404` response. 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 Page-Token: name: page_token in: query schema: type: string description: >- Token for retrieving the next page of results. Used for **pagination**. To paginate through results: 1. Make an initial request with the desired `limit`. 1. The response will include a `next_page_token` if more results are available. 1. Use that token in the `page_token` parameter of your next request. 1. Repeat until `next_page_token` is not present. :::note When using `page_token`, you must include all query parameters from the initial request (such as `from`, `to`, or other filter parameters) to maintain consistent filtering across pages. ::: required: false 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. Only-Merchant: name: only_merchant in: query schema: type: boolean description: |- If `true`, returns only the saved payment methods that can be used for merchant-initiated transactions (MIT). required: false 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. From-Created-Date: name: from_created_date in: query required: false schema: type: string format: date-time description: >- Retrieve records with a `created_at` value ≥ `from_created_date`. Use the [ISO 8601 date-time format](https://en.wikipedia.org/wiki/ISO_8601): `yyyy-MM-ddTHH:mm:ss[.SSSSSS]Z`. To-Created-Date: name: to_created_date in: query required: false schema: type: string format: date-time description: >- Retrieve records with a `created_at` value ≤ `to_created_date`. Use the [ISO 8601 date-time format](https://en.wikipedia.org/wiki/ISO_8601): `yyyy-MM-ddTHH:mm:ss[.SSSSSS]Z`. Dispute-State-Query: name: state in: query required: false schema: type: array items: type: string enum: - needs_response - under_review - won - lost style: form explode: true description: >- Filter disputes by state. Repeat the parameter to filter by multiple states. | Value | Description | |-------|-------------| | `needs_response` | Dispute requires your response | | `under_review` | Dispute is being reviewed | | `won` | Dispute resolved in your favour | | `lost` | Dispute resolved against you | The parameter is case sensitive. Payment-Id-Query: name: payment_id in: query required: false schema: type: array items: type: string format: uuid style: form explode: true description: >- Filter disputes by the ID of the associated payment. Repeat the parameter to filter by multiple payment IDs. ``` https://merchant.revolut.com/api/disputes?payment_id=123&payment_id=456 ``` Dispute-Id: name: dispute_id in: path schema: type: string format: uuid description: A UUID string, typically used to identify resources. required: true description: The ID of the `Dispute` object. Content-Type: name: Content-Type in: header required: true schema: type: string description: The content type sent in the request. examples: default: value: multipart/form-data 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. Subscription-Plan-Id: name: subscription_plan_id in: path schema: type: string format: uuid description: A UUID string, typically used to identify resources. required: true description: The ID of the subscription plan. Subscription-Id: name: subscription_id in: path schema: type: string format: uuid description: A UUID string, typically used to identify resources. required: true description: The ID of the subscription. Cycle-Id: name: cycle_id in: path schema: type: string format: uuid description: A UUID string, typically used to identify resources. required: true description: The ID of the subscription cycle. From-Usage-Date: name: from_usage_date in: query schema: type: string format: date-time description: Filter usage records with a `usage_date` on or after this date and time. required: false To-Usage-Date: name: to_usage_date in: query schema: type: string format: date-time description: Filter usage records with a `usage_date` before this date and time. required: false Subscription-Id-Query: name: subscription_id in: query schema: type: string format: uuid description: Filter usages by the ID of the subscription. required: false Subscription-Cycle-Id-Query: name: subscription_cycle_id in: query schema: type: string format: uuid description: Filter usages by the ID of the subscription cycle. required: false Usage-Id: name: usage_id in: path schema: type: string format: uuid description: A UUID string, typically used to identify resources. required: true description: The ID of the usage record. 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" 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: 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. 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 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#embeddedcheckout options-interface) - [Revolut Pay](/docs/sdks/merchant-web-sdk/payment-methods/revolut-pay#widgetpaymentsrevolutpayoptions) - [Apple Pay and Google Pay](/docs/sdks/merchant-web-sdk/payment-methods/apple-pay-google-pay#paymentrequestoptions-interface) - [Pay by Bank](/docs/sdks/merchant-web-sdk/payment-methods/pay-by-bank#paybybankoptions-interface) Order-Type-v2: type: string description: The type of the order. enum: - payment - payment_request - refund - chargeback - chargeback_reversal - credit_reimbursement Order-Amount-v2: 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). - If `line_items` are provided, the order `amount` must equal the sum of all line items' `total_amount`. - For card payments with a non-zero amount, the order `amount` must be at least **$0.005** (or equivalent in different currencies, calculated using Revolut's exchange rate on the payment date). Otherwise, card payments can't be performed. ::: 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/). ::: 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. 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-an-order). ::: default: automatic enum: - automatic - manual 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 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-an-order). ::: default: final enum: - final - pre_authorisation Order-Description: type: string description: The description of the order. 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 Related-Order-Id: type: string format: uuid description: >- The unique ID of the original order that was refunded and this refund is associated with. You can use this ID to get more information about the related order using the [Retrieve an order](/docs/api/merchant#retrieve-an-order) operation. :::note This field is only returned for orders with `type: refund`. ::: Customer-Id: type: string format: uuid description: Unique identifier for the customer. Email: type: string format: email description: The email address of the customer. Phone: type: string description: The phone number of the customer in [E.164 format](https://en.wikipedia.org/wiki/E.164). Full-Name: type: string description: The full name of the customer. Date-Of-Birth: type: string format: date description: The birth date of the customer. Order-Customer-v2: title: Order customer type: object description: >- A lightweight customer object embedded in an order. This is a simplified representation intended for the order context. For the full customer object including all payment methods, use the [Retrieve a customer](/docs/api/merchant#retrieve-a-customer) endpoint. properties: id: $ref: "#/components/schemas/Customer-Id" email: $ref: "#/components/schemas/Email" phone: $ref: "#/components/schemas/Phone" full_name: $ref: "#/components/schemas/Full-Name" date_of_birth: $ref: "#/components/schemas/Date-Of-Birth" required: - id Quantity: type: object description: Object representing the quantity details of a line item, including the amount and its associated unit of measurement. properties: value: type: number format: double minimum: 0 description: The number of units of the line item. unit: type: string maxLength: 100 description: The measurement unit for the quantity, such as `cm`, or `kg`. required: - value Discount: type: object description: Details of a discount applied to the line item, including its name and monetary value. properties: name: type: string maxLength: 100 description: The specific name or label of the discount applied to the line item. amount: type: integer format: int64 minimum: 0 description: "The monetary value of the discount. " required: - name - amount Tax: type: object description: Details about a tax applied to the line item, including its name and the corresponding amount. properties: name: type: string description: The specific name or designation of the tax applied to the line item. maxLength: 100 amount: type: integer format: int64 description: The monetary value of the tax in minor currency units (e.g., cents for EUR). minimum: 0 required: - name - amount Image-Url: type: string format: uri pattern: ^https?:\/{2}.+/gi maxLength: 2000 description: >- URL to an image associated with the line item. :::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) ::: Line-Item: type: object properties: name: type: string maxLength: 250 description: Name of the line item. type: type: string enum: - physical - service description: Type of the line item. quantity: $ref: "#/components/schemas/Quantity" unit_price_amount: type: integer format: int64 minimum: 0 description: The unit price of the line item. total_amount: type: integer format: int64 description: The total amount to be paid for the line item, including taxes and discounts. external_id: type: string maxLength: 250 description: Unique identifier of line item in the merchant's system. discounts: type: array maxItems: 50 description: A list of discounts applied to the line item. Each discount should be subtracted from the total amount payable for the item. items: $ref: "#/components/schemas/Discount" taxes: type: array maxItems: 50 description: A list of taxes applied to the line item. Each tax should be added to the total amount payable for the item. items: $ref: "#/components/schemas/Tax" image_urls: type: array maxItems: 50 description: A list of URLs pointing to images related to the line item. These images can provide visual details or representations of the item. items: $ref: "#/components/schemas/Image-Url" description: type: string maxLength: 1024 description: Description of the line item. url: type: string format: uri pattern: ^https?:\/{2}.+/gi maxLength: 2000 description: >- An HTTP/HTTPS URL that links to more information about the line item, such as a product page or details. :::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: - name - unit_price_amount - total_amount - quantity - type Line-Items: type: array maxItems: 250 description: >- An array of line items included in the order. Each line item represents an individual product or service, along with its quantity, price, taxes, and discounts. :::info Required for merchants collecting payment for one or multiple products/services in one transaction. Omitting this information may trigger additional scrutiny and risk mitigation actions by Revolut. ::: items: $ref: "#/components/schemas/Line-Item" 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-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" 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). ::: 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) ::: 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. ::: 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-Simplified-v2: title: Simplified order type: object description: >- A simplified order object returned in list responses. To get the full details of an order, use the [Retrieve an order](/docs/api/merchant#retrieve-an-order) endpoint. 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 format: date-time description: The date and time the order was created. updated_at: type: string format: date-time description: The date and time the order was last updated. amount: $ref: "#/components/schemas/Order-Amount-v2" currency: $ref: "#/components/schemas/Currency" outstanding_amount: $ref: "#/components/schemas/Outstanding-Amount" capture_mode: $ref: "#/components/schemas/Capture-Mode-v2" enforce_challenge: $ref: "#/components/schemas/Enforce-Challenge-v2" authorisation_type: $ref: "#/components/schemas/Authorisation-Type" description: $ref: "#/components/schemas/Order-Description" metadata: $ref: "#/components/schemas/Metadata" related_order_id: $ref: "#/components/schemas/Related-Order-Id" customer: $ref: "#/components/schemas/Order-Customer-v2" line_items: $ref: "#/components/schemas/Line-Items" merchant_order_data: $ref: "#/components/schemas/Merchant-Order-Data" location_id: $ref: "#/components/schemas/Location-Id" redirect_url: $ref: "#/components/schemas/Redirect-Url" cancel_authorised_after: $ref: "#/components/schemas/Cancel-Authorised-After" statement_descriptor_suffix: $ref: "#/components/schemas/Statement-Descriptor-Suffix" required: - id - type - state - created_at - updated_at - amount - currency - outstanding_amount - capture_mode - enforce_challenge Orders-v2: type: object required: - orders properties: orders: type: array description: List of orders. items: $ref: "#/components/schemas/Order-Simplified-v2" 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. 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/). ::: 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-a-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-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 Contact: type: object description: |- Contact details for someone responsible for the shipment. :::warning At least `email` or `phone` is required. ::: properties: name: type: string description: Full name of the contact person. maxLength: 250 email: type: string format: email description: Email address of the contact person. phone: type: string description: Phone number of the contact person. Shipment: type: object description: Details of an individual shipment. properties: shipping_company_name: type: string maxLength: 250 description: Name of the company handling the shipment. tracking_number: type: string maxLength: 500 description: Unique tracking number for the shipment. estimated_delivery_date: type: string format: date-time description: |- Estimated delivery date and time for the shipment. The time should also include the customer's timezone. tracking_url: type: string format: uri pattern: ^https?:\/{2}.+/gi maxLength: 2000 description: >- An HTTP/HTTPS URL where the shipment can be tracked. :::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: - shipping_company_name - tracking_number Shipments: type: array description: List of individual shipment details. maxItems: 50 items: $ref: "#/components/schemas/Shipment" Shipping: type: object description: >- Details about the shipping related to the order, including address, contact information, and individual shipments. :::info Required for merchants shipping physical goods. Omitting this information may trigger additional scrutiny and risk mitigation actions by Revolut. ::: properties: address: $ref: "#/components/schemas/Address-v3" contact: $ref: "#/components/schemas/Contact" shipments: $ref: "#/components/schemas/Shipments" Cancel-Authorised-After-v2: 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 period depends on the order's `authorisation_type`: - `pre_authorisation`: 30 days = `P30D` - `final`: 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 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-v2: 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: 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: - booking_id 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 Car-Rental-v2: type: object description: >- Object containing additional information about a car rental booking associated with the order. :::info These are the specific data field requirements for merchants offering car rental. Note that these requirements can be extended on a case by case basis as decided by Revolut. ``` booking_id drop_off_date refundability ``` ::: properties: booking_id: $ref: "#/components/schemas/Booking-Id" pick_up_date: type: string format: date-time description: The UTC date and time of the pick-up. pick_up_location: $ref: "#/components/schemas/Address-v2" drop_off_date: type: string format: date-time description: The UTC date and time of the drop-off. drop_off_location: $ref: "#/components/schemas/Address-v2" refundability: $ref: "#/components/schemas/Refundability" distance_limit: type: object description: Object containing distance limit information. properties: limit: type: integer description: The maximum distance allowed. unit: type: string description: The unit of distance. enum: - miles - km additional_distance_cost: type: object description: Cost for exceeding the distance limit. properties: amount: type: integer description: The amount of the cost in minor currency units. For example, enter `7034` for €70.34. currency: $ref: "#/components/schemas/Currency" required: - booking_id - drop_off_date 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 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 Mcc: type: string description: A string representing the four-digit [Merchant Category Code (MCC)](https://en.wikipedia.org/wiki/Merchant_category_code) of the conversion affiliate. maxLength: 4 minLength: 4 pattern: ^\d{4}$ Crypto-Transactions-v3: type: object description: >- Object containing information about crypto transactions associated with the order. :::info Processing crypto on-ramp transactions with Revolut has additional compliance requirements. Please reach out to your account executive for additional details. **Required data fields for crypto services:** ``` transactions[].id transactions[].status transactions[].recipient_wallet_id seller.id seller.name seller.website seller.phone seller.address seller.mcc customer.full_name customer.date_of_birth ``` Note that these requirements can be extended on a case by case basis as decided by Revolut. ::: properties: transactions: type: array description: Array of crypto transaction data associated with the order. items: $ref: "#/components/schemas/Crypto-Transaction" minItems: 1 seller: type: object description: >- Information about the crypto conversion affiliate. This 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. :::note This needs to be provided only by crypto on-ramp providers for payments they are processing for conversion affiliates. For their own payments, `seller` can be omitted. ::: properties: mcc: $ref: "#/components/schemas/Mcc" id: type: string description: The ID of the seller in the merchant's internal system. minLength: 1 maxLength: 15 name: type: string description: The business or legal name of the seller. minLength: 1 maxLength: 50 website: type: string format: uri pattern: ^https?:\/{2}.+/gi maxLength: 255 description: >- The URL of the website of the seller. :::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 seller. address: $ref: "#/components/schemas/Address-v4" required: - id - name - website - phone - address - mcc required: - transactions Marketplace-v3: 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 seller involved in the transaction. :::info These are the specific data field requirements for merchants who must provide marketplace data. ``` seller.id seller.name seller.website seller.phone seller.address ``` ::: properties: seller: type: object description: Information about the subseller on the marketplace platform. properties: id: type: string description: The ID of the seller in the merchant's internal system. minLength: 1 maxLength: 15 name: type: string description: The business or legal name of the seller. minLength: 1 maxLength: 50 website: type: string format: uri pattern: ^https?:\/{2}.+/gi maxLength: 255 description: >- The URL of the website of the seller. :::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 seller. address: $ref: "#/components/schemas/Address-v4" required: - id - name - website - phone - address required: - seller 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-v2: 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: 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: - booking_id Lodging-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." Lodging-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." Lodging-Category: type: string enum: - bed_and_breakfast - hostel - hotel - short_term_rental - other description: The type of the accommodation associated with the booking. Lodging-Supplier: type: object description: Object containing supplier information about the lodging provider. properties: id: type: string description: Unique identifier of the lodging supplier. name: type: string description: Legal name of the lodging supplier. payment_date: $ref: "#/components/schemas/Supplier-Payment-Date" Lodging-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. Lodging-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 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-Item: type: object description: Object containing details of an individual lodging entry. properties: check_in_date: $ref: "#/components/schemas/Lodging-Check-In-Date" check_out_date: $ref: "#/components/schemas/Lodging-Check-Out-Date" category: $ref: "#/components/schemas/Lodging-Category" supplier: $ref: "#/components/schemas/Lodging-Supplier" booking_type: $ref: "#/components/schemas/Lodging-Booking-Type" refundability: $ref: "#/components/schemas/Refundability" location: $ref: "#/components/schemas/Lodging-Location" guests: $ref: "#/components/schemas/Guests" Lodging-v3: 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 lodgings[].check_in_date lodgings[].check_out_date lodgings[].supplier.payment_date ``` ::: properties: booking_id: $ref: "#/components/schemas/Booking-Id" lodgings: type: array description: List of lodging entries associated with this booking. items: $ref: "#/components/schemas/Lodging-Item" required: - booking_id Industry-Data-v3: type: object description: >- Object containing industry-specific information associated with the order. You can provide data for one or multiple industries in a single 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). | | `car_rental` | Car Rental Merchants and Online Travel Agencies (OTAs). | | `crypto` | Crypto merchants. | | `marketplace` | Marketplace merchants. | | `event` | Event ticket sellers. | | `lodging` | Lodging providers. | ::: properties: airline: $ref: "#/components/schemas/Airline-Data-v2" car_rental: $ref: "#/components/schemas/Car-Rental-v2" crypto: $ref: "#/components/schemas/Crypto-Transactions-v3" marketplace: $ref: "#/components/schemas/Marketplace-v3" event: $ref: "#/components/schemas/Events-v2" lodging: $ref: "#/components/schemas/Lodging-v3" 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-of-a-customer) - [Retrieve a customer's payment method](/docs/api/merchant#retrieve-a-customer-s-payment-method) - [Update a customer's payment method](/docs/api/merchant#update-a-customer-s-payment-method) - [Delete a customer's payment method](/docs/api/merchant#delete-a-customer-s-payment-method) ::: required: - date - payment_method_id Order-Creation-v7: type: object description: Object schema containing information about order creation body request parameters. properties: amount: $ref: "#/components/schemas/Order-Amount-v2" currency: $ref: "#/components/schemas/Currency" settlement_currency: $ref: "#/components/schemas/Settlement-Currency" description: $ref: "#/components/schemas/Order-Description" customer: $ref: "#/components/schemas/Customer-v2" enforce_challenge: $ref: "#/components/schemas/Enforce-Challenge-v2" line_items: $ref: "#/components/schemas/Line-Items" shipping: $ref: "#/components/schemas/Shipping" capture_mode: $ref: "#/components/schemas/Capture-Mode-v2" authorisation_type: $ref: "#/components/schemas/Authorisation-Type" cancel_authorised_after: $ref: "#/components/schemas/Cancel-Authorised-After-v2" 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-v3" 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 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-an-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-an-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/accept-payments/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-v2: title: three_ds_fingerprint type: object description: Information about the 3DS fingerprint challenge. properties: type: $ref: "#/components/schemas/Authentication-Challenge-Type" fingerprint_html: type: string description: >- Base64-encoded HTML string for the 3DS fingerprint challenge. This HTML is fully constructed by Revolut — no modifications are needed. Decode this value using a `base64` decoder and render the resulting HTML in your front-end application. Revolut automatically moves the payment to the full 3DS challenge if the fingerprint is not handled within 15 seconds. contentEncoding: base64 required: - type - fingerprint_html Authentication-Challenge-v2: 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-v2" oneOf: - $ref: "#/components/schemas/Three-Ds" - $ref: "#/components/schemas/Three-Ds-Fingerprint-v2" 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-v3: 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-v2" 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 Increment-Reference: type: string maxLength: 255 description: >- External reference for this incremental authorisation. :::tip Use your internal charge or invoice ID. This reference is returned in webhooks for easy matching to your system. ::: examples: - CHG-67890 Incremental-Authorisation: type: object description: >- Represents a single incremental authorisation attempt on an order. The `incremental_authorisations` array tracks all increment attempts (successful and failed) in chronological order. properties: new_amount: type: integer description: The new total amount requested in this increment (in minor units). examples: - 600 old_amount: type: integer description: The previously authorised amount before this increment (in minor units). examples: - 500 state: type: string enum: - pending - processing - authorised - declined - failed description: >- The state of this incremental authorization attempt. | State | Description | |-------|-------------| | `pending` | Increment registered in system, not yet submitted to card network | | `processing` | Increment is being processed by card network | | `authorised` | Increment was successfully authorised | | `declined` | Increment was declined by card issuer | | `failed` | Increment failed due to technical error (not an issuer decline) | reference: $ref: "#/components/schemas/Increment-Reference" line_items: type: array description: >- Line items associated with this increment (if provided). :::note If the increment is successful, these line items will override the existing order line items. ::: items: $ref: "#/components/schemas/Line-Item" reason: type: string description: |- Reason why increment was declined or failed. :::note Only present when `state` is `declined` or `failed`. ::: examples: - insufficient_funds Incremental-Authorisations: type: array description: |- History of incremental authorisation attempts for this order. Only present for orders with `authorisation_type: pre_authorisation`. Contains all increment attempts in chronological order. items: $ref: "#/components/schemas/Incremental-Authorisation" Checkout-Url: type: string description: Link to a checkout page hosted by Revolut. format: uri Order-v7: title: Order v7 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-v2" 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" 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-v3" incremental_authorisations: $ref: "#/components/schemas/Incremental-Authorisations" location_id: $ref: "#/components/schemas/Location-Id" metadata: $ref: "#/components/schemas/Metadata" industry_data: $ref: "#/components/schemas/Industry-Data-v3" 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" shipping: $ref: "#/components/schemas/Shipping" enforce_challenge: $ref: "#/components/schemas/Enforce-Challenge-v2" line_items: $ref: "#/components/schemas/Line-Items" statement_descriptor_suffix: $ref: "#/components/schemas/Statement-Descriptor-Suffix" related_order_id: $ref: "#/components/schemas/Related-Order-Id" Order-Update-v7: type: object description: Object schema containing information about order update body request parameters. properties: amount: $ref: "#/components/schemas/Order-Amount-v2" currency: $ref: "#/components/schemas/Currency" settlement_currency: $ref: "#/components/schemas/Settlement-Currency" description: $ref: "#/components/schemas/Order-Description" customer: $ref: "#/components/schemas/Customer-v2" enforce_challenge: $ref: "#/components/schemas/Enforce-Challenge-v2" line_items: $ref: "#/components/schemas/Line-Items" shipping: $ref: "#/components/schemas/Shipping" capture_mode: $ref: "#/components/schemas/Capture-Mode-v2" cancel_authorised_after: $ref: "#/components/schemas/Cancel-Authorised-After-v2" expire_pending_after: $ref: "#/components/schemas/Expire-Pending-After" metadata: $ref: "#/components/schemas/Metadata" industry_data: $ref: "#/components/schemas/Industry-Data-v3" 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" Increment-Amount: type: integer minimum: 1 description: >- The new total amount to be authorised (in minor units, e.g., cents). This should be the **full new amount**, not the increment value. For example, if the current authorised amount is `500` and you want to add 100, pass `600`. :::warning - Must be greater than or equal to the current authorised amount (incrementing with same amount allowed to extend capture deadline for Mastercard) - The sum of all increment amounts cannot exceed 5x the initial authorised amount (e.g., initial amount £100 allows up to £500 in total increments) ::: examples: - 600 Incremental-Authorisation-Request: type: object properties: amount: $ref: "#/components/schemas/Increment-Amount" reference: $ref: "#/components/schemas/Increment-Reference" line_items: $ref: "#/components/schemas/Line-Items" required: - amount 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-v2: type: object description: >- Order capture request parameters. You can optionally provide line items when capturing an order. This is useful when you need to adjust the final order details at capture time (for example, when doing partial captures with specific items, or when the final delivered items differ from the initial authorisation). :::warning If you provide `line_items` when capturing, they will **overwrite** the original line items that were provided during order creation or update. Make sure to include all the items you want to be associated with the captured order. ::: properties: amount: $ref: "#/components/schemas/Order-Capture-Amount" line_items: $ref: "#/components/schemas/Line-Items" Refund-Amount: type: integer description: The amount to be refunded, specified in the smallest currency unit (e.g., cents for USD, pence for GBP). examples: - 100 Refund-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. **Must match the `currency` of the original order to be refunded.** :::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-Refund-v2: type: object description: The request body for creating a refund order. required: - amount - currency properties: amount: $ref: "#/components/schemas/Refund-Amount" currency: $ref: "#/components/schemas/Refund-Currency" merchant_order_data: type: object description: Object for providing additional information stored in the merchant's order management system. properties: reference: $ref: "#/components/schemas/Merchant-Order-External-Reference" metadata: $ref: "#/components/schemas/Metadata" description: type: string description: An optional, user-facing description for the refund. This may be displayed to the customer. examples: - Refund for returned item. 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 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-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 Next-Page-Token: type: - string - "null" description: >- Token for retrieving the next page of results. Use this token as the value of the `page_token` query parameter in your next request to retrieve the next page. If not present, there are no more results to retrieve. Customer-Simplified: title: Customer type: object description: A customer object. properties: id: $ref: "#/components/schemas/Customer-Id" full_name: $ref: "#/components/schemas/Full-Name" email: $ref: "#/components/schemas/Email" phone: $ref: "#/components/schemas/Phone" created_at: type: string format: date-time description: The date and time the customer was created. updated_at: type: string format: date-time description: The date and time the customer was last updated. required: - id - created_at - updated_at - email Customers: type: object required: - customers properties: next_page_token: $ref: "#/components/schemas/Next-Page-Token" customers: type: array description: List of customers. items: $ref: "#/components/schemas/Customer-Simplified" Customer-Creation-v2: title: Customer creation type: object description: The request body for creating a customer. properties: full_name: $ref: "#/components/schemas/Full-Name" email: $ref: "#/components/schemas/Email" phone: $ref: "#/components/schemas/Phone" date_of_birth: $ref: "#/components/schemas/Date-Of-Birth" required: - email Customer-Created: title: Customer type: object description: A customer object. properties: id: $ref: "#/components/schemas/Customer-Id" full_name: $ref: "#/components/schemas/Full-Name" email: $ref: "#/components/schemas/Email" phone: $ref: "#/components/schemas/Phone" created_at: type: string format: date-time description: The date and time the customer was created. updated_at: type: string format: date-time description: The date and time the customer was last updated. required: - id - created_at - updated_at - email Payment-Method-Id: type: string format: uuid description: Unique identifier for the payment method. Payment-Method-Type-v2: type: string description: The type of the payment method. enum: - card - revolut_pay - sepa_direct_debit Saved-For: type: string enum: - customer - merchant description: >- Indicates in which case this saved payment method can be used for payments. | Value | Description | | ----- | ----------- | | `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. | Payment-Method-Created-At: type: string format: date-time description: The date and time the payment method was added. Card-Bin: type: string description: The BIN (Bank Identification Number) of the payment card, typically the first 6-8 digits. Card-Last-Four: type: string minLength: 4 maxLength: 4 description: The last four digits of the payment card number. Card-Expiry-Month: type: integer description: The expiry month of the payment card. Card-Expiry-Year: type: integer description: The expiry year of the payment card. Cardholder-Name: type: string description: The name of the cardholder as it appears on the card. Card-Brand-v2: type: string description: The brand of the payment card. enum: - visa - mastercard - american_express Card-Funding-v2: type: string description: The funding type of the payment card. enum: - debit - credit - prepaid Card-Issuer: type: string description: The name of the card-issuing bank or institution. Card-Issuer-Country: type: string minLength: 2 maxLength: 2 description: The ISO 3166-1 alpha-2 country code of the country where the payment card was issued. Billing-Address: title: Billing address type: object description: The billing address associated with the payment method. 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: - country_code - postcode Card-v2: title: Card payment method type: object description: >- A saved card payment method. :::info The `checks` object (3DS, CVV, address verification) is not included as it is specific to the transactional payment context. ::: properties: id: $ref: "#/components/schemas/Payment-Method-Id" type: $ref: "#/components/schemas/Payment-Method-Type-v2" saved_for: $ref: "#/components/schemas/Saved-For" created_at: $ref: "#/components/schemas/Payment-Method-Created-At" bin: $ref: "#/components/schemas/Card-Bin" last_four: $ref: "#/components/schemas/Card-Last-Four" expiry_month: $ref: "#/components/schemas/Card-Expiry-Month" expiry_year: $ref: "#/components/schemas/Card-Expiry-Year" cardholder_name: $ref: "#/components/schemas/Cardholder-Name" brand: $ref: "#/components/schemas/Card-Brand-v2" funding: $ref: "#/components/schemas/Card-Funding-v2" issuer: $ref: "#/components/schemas/Card-Issuer" issuer_country: $ref: "#/components/schemas/Card-Issuer-Country" billing_address: $ref: "#/components/schemas/Billing-Address" required: - id - type - created_at Revolut-Pay-v2: title: Revolut Pay payment method type: object description: |- A saved Revolut Pay payment method on a customer profile. Both Revolut Pay card-backed and account-to-account (A2A) variants are represented by this single type at the saved payment method level. No underlying card details are exposed here; use the order-level `payments[].payment_method` object (types `revolut_pay_card` / `revolut_pay_account`) for per-transaction details. properties: id: $ref: "#/components/schemas/Payment-Method-Id" type: $ref: "#/components/schemas/Payment-Method-Type-v2" saved_for: $ref: "#/components/schemas/Saved-For" created_at: $ref: "#/components/schemas/Payment-Method-Created-At" required: - id - type - created_at Sepa-Direct-Debit-v2: title: SEPA Direct Debit payment method type: object description: |- A saved SEPA Direct Debit payment method on a customer profile. :::info For more information, see: [SEPA Direct Debit server-to-server integration](/docs/guides/merchant/accept-payments/payment-methods/sepa-direct-debit/server-to-server) ::: properties: id: $ref: "#/components/schemas/Payment-Method-Id" type: $ref: "#/components/schemas/Payment-Method-Type-v2" saved_for: $ref: "#/components/schemas/Saved-For" 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" billing_address: $ref: "#/components/schemas/Billing-Address" created_at: $ref: "#/components/schemas/Payment-Method-Created-At" required: - id - type - created_at Payment-Method-v4: title: Payment method description: >- A saved payment method on a customer profile. Use the `type` field to determine the specific payment method variant. :::note This schema represents a stored credential available for future charges and supports three types: `card`, `revolut_pay`, and `sepa_direct_debit`. It differs from the `payment_method` object on a Payment, which is a transactional snapshot of how a specific charge was executed and includes additional detail such as wallet wrappers (`apple_pay`, `google_pay`) and Revolut Pay funding source (`revolut_pay_card` vs `revolut_pay_account`). ::: discriminator: propertyName: type mapping: card: "#/components/schemas/Card-v2" revolut_pay: "#/components/schemas/Revolut-Pay-v2" sepa_direct_debit: "#/components/schemas/Sepa-Direct-Debit-v2" oneOf: - $ref: "#/components/schemas/Card-v2" - $ref: "#/components/schemas/Revolut-Pay-v2" - $ref: "#/components/schemas/Sepa-Direct-Debit-v2" Customer-v3: title: Customer type: object description: A customer object. properties: id: $ref: "#/components/schemas/Customer-Id" full_name: $ref: "#/components/schemas/Full-Name" email: $ref: "#/components/schemas/Email" phone: $ref: "#/components/schemas/Phone" created_at: type: string format: date-time description: The date and time the customer was created. updated_at: type: string format: date-time description: The date and time the customer was last updated. payment_methods: type: array description: >- Saved payment methods associated with this customer. Each entry represents a payment method authorised for future charges. Two types are supported: `card` (with full card details) and `revolut_pay` (covers both card-backed and account-to-account Revolut Pay variants). Use the `type` field on each item to identify the variant. items: $ref: "#/components/schemas/Payment-Method-v4" required: - id - created_at - updated_at - email - payment_methods Customer-Update-v2: title: Customer update type: object description: >- The request body for updating a customer. All fields are optional. Only the fields provided in the request will be updated. :::note `business_name` is not supported in this version of the API. ::: properties: full_name: $ref: "#/components/schemas/Full-Name" email: $ref: "#/components/schemas/Email" phone: $ref: "#/components/schemas/Phone" date_of_birth: $ref: "#/components/schemas/Date-Of-Birth" Customer-Payment-Methods-v2: type: object required: - payment_methods properties: payment_methods: type: array description: >- Saved payment methods associated with this customer. Each entry represents a payment method authorised for future charges. Two types are supported: `card` (with full card details) and `revolut_pay` (covers both card-backed and account-to-account Revolut Pay variants). Use the `type` field on each item to identify the variant. items: $ref: "#/components/schemas/Payment-Method-v4" Payment-Method-Update: title: Payment method update type: object description: Fields to update on a saved payment method. properties: saved_for: type: string enum: - customer description: >- Update the value of `saved_for` from `merchant` to `customer`. Once updated, this payment method can no longer be used for merchant-initiated transactions (MIT). It can only be used when the customer is present on the checkout page. | Value | Description | | ----- | ----------- | | `customer` | Restrict this payment method to customer-initiated transactions only. | Dispute-Payment-Id: type: string format: uuid description: The ID of the original payment that was disputed. Dispute-Payment-Order-Id: type: string format: uuid description: The ID of the order linked to the original disputed payment. Dispute-Payment-Created-At: type: string format: date-time description: "[ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date and time when the original disputed payment was created." Dispute-Payment-Arn: type: string description: |- Acquirer Reference Number (ARN) of the original payment. :::note Only returned for payments made by a card. ::: Dispute-Payment-Amount: type: integer description: >- Amount of the original payment 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). ::: Dispute-Payment-Method-Type: type: string enum: - apple_pay - apple_tap_to_pay - card - google_pay - revolut_pay_account - revolut_pay_card - sepa_direct_debit description: >- Type of the payment method used for the original payment. Available values: | Payment method `type` | Description | | --------------------- | ----------- | | `apple_pay` | The customer paid the order using Apple Pay. | | `apple_tap_to_pay` | The customer paid the order using Apple Tap to 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 via SEPA Direct Debit. | Dispute-Payment-Method-Apple-Pay: type: object description: Object containing details of a card used via Apple Pay. properties: type: $ref: "#/components/schemas/Dispute-Payment-Method-Type" card_brand: $ref: "#/components/schemas/Card-Brand-v2" card_last_four: $ref: "#/components/schemas/Card-Last-Four" required: - type Dispute-Payment-Method-Apple-Tap-To-Pay: type: object description: Object containing details of a payment made via Apple Tap to Pay. properties: type: $ref: "#/components/schemas/Dispute-Payment-Method-Type" required: - type Dispute-Payment-Method-Card: type: object description: Object containing details of the card used for the payment. properties: type: $ref: "#/components/schemas/Dispute-Payment-Method-Type" card_brand: $ref: "#/components/schemas/Card-Brand-v2" card_last_four: $ref: "#/components/schemas/Card-Last-Four" required: - type Dispute-Payment-Method-Google-Pay: type: object description: Object containing details of a card used via Google Pay. properties: type: $ref: "#/components/schemas/Dispute-Payment-Method-Type" card_brand: $ref: "#/components/schemas/Card-Brand-v2" card_last_four: $ref: "#/components/schemas/Card-Last-Four" required: - type Dispute-Payment-Method-Revolut-Pay-Account: type: object description: Object containing details of a payment made via Revolut Pay account. properties: type: $ref: "#/components/schemas/Dispute-Payment-Method-Type" required: - type Dispute-Payment-Method-Revolut-Pay-Card: type: object description: Object containing details of a card used via Revolut Pay. properties: type: $ref: "#/components/schemas/Dispute-Payment-Method-Type" card_brand: $ref: "#/components/schemas/Card-Brand-v2" card_last_four: $ref: "#/components/schemas/Card-Last-Four" required: - type Dispute-Payment-Method-Sepa-Direct-Debit: type: object description: Object containing details of a SEPA Direct Debit payment. properties: type: $ref: "#/components/schemas/Dispute-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 Dispute-Payment-Method: type: object description: |- Payment method used for the original payment. Use the `type` field to determine the specific payment method variant. discriminator: propertyName: type mapping: apple_pay: "#/components/schemas/Dispute-Payment-Method-Apple-Pay" apple_tap_to_pay: "#/components/schemas/Dispute-Payment-Method-Apple-Tap-To-Pay" card: "#/components/schemas/Dispute-Payment-Method-Card" google_pay: "#/components/schemas/Dispute-Payment-Method-Google-Pay" revolut_pay_account: "#/components/schemas/Dispute-Payment-Method-Revolut-Pay-Account" revolut_pay_card: "#/components/schemas/Dispute-Payment-Method-Revolut-Pay-Card" sepa_direct_debit: "#/components/schemas/Dispute-Payment-Method-Sepa-Direct-Debit" oneOf: - $ref: "#/components/schemas/Dispute-Payment-Method-Apple-Pay" - $ref: "#/components/schemas/Dispute-Payment-Method-Apple-Tap-To-Pay" - $ref: "#/components/schemas/Dispute-Payment-Method-Card" - $ref: "#/components/schemas/Dispute-Payment-Method-Google-Pay" - $ref: "#/components/schemas/Dispute-Payment-Method-Revolut-Pay-Account" - $ref: "#/components/schemas/Dispute-Payment-Method-Revolut-Pay-Card" - $ref: "#/components/schemas/Dispute-Payment-Method-Sepa-Direct-Debit" Dispute-Payment: type: object description: Object containing the details of the original payment associated with the dispute. properties: id: $ref: "#/components/schemas/Dispute-Payment-Id" order_id: $ref: "#/components/schemas/Dispute-Payment-Order-Id" created_at: $ref: "#/components/schemas/Dispute-Payment-Created-At" arn: $ref: "#/components/schemas/Dispute-Payment-Arn" amount: $ref: "#/components/schemas/Dispute-Payment-Amount" currency: $ref: "#/components/schemas/Currency" payment_method: $ref: "#/components/schemas/Dispute-Payment-Method" Dispute: type: object properties: id: type: string format: uuid description: Unique identifier of the dispute. state: type: string enum: - needs_response - under_review - won - lost description: >- Represents the state of the dispute. It indicates either the final outcome of the dispute or if further action is required. | Parameter value | Description | | --------------- | ----------- | | `needs_response` | Indicates that the dispute requires a response or action from the merchant. | | `under_review` | Indicates that the dispute is currently under review, and the outcome is pending. | | `won` | Indicates that the dispute has been resolved in favor of the merchant. | | `lost` | Indicates that the dispute has been resolved against the merchant. | substate: type: string enum: - arbitration - lost_accepted - lost_arbitration - lost_expired - lost_pre_arbitration - lost_representment - new - pre_arbitration - representment - won_arbitration - won_pre_arbitration - won_representment - won_reversal description: >- Provides additional granularity about the dispute state. It details the progression of the dispute process, showing the current stage or phase. | Parameter value | Description | | --------------- | ----------- | | `new` | The dispute has been recently created and is in the initial phase, awaiting further processing. | | `lost_expired` | The dispute has been lost due to expiration, likely because the merchant did not respond within the required timeframe. | | `pre_arbitration` | The dispute is in the pre-arbitration phase, where preliminary evidence is being gathered before a formal arbitration process. | | `won_pre_arbitration`| The merchant secured a win during the pre-arbitration phase based on the evidence provided. | | `lost_pre_arbitration` | The dispute was lost during the pre-arbitration phase, indicating that the preliminary review did not favor the merchant. | | `lost_accepted` | The loss has been accepted as final, implying that no further contestation is likely or needed. | | `arbitration` | The dispute has escalated to the arbitration stage, where a neutral third party is reviewing the evidence. | | `won_arbitration` | The merchant won the dispute during the arbitration process. | | `lost_arbitration` | The merchant lost the dispute during the arbitration process. | created_at: type: string format: date-time description: "[ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date and time when the dispute was created." updated_at: type: string format: date-time description: "[ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date and time when the dispute was last updated." response_due_date: type: string format: date-time description: >- [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date and time until when the merchant needs to respond to the dispute. The response time by default is 15 days after the dispute is created. If no response is provided by this date, the dispute transitions to: - `state: lost` - `substate: lost_expired` reason_code: type: string description: |- Dispute reason code from the payment scheme, following standard formats defined by individual providers. :::info For complete, official lists of dispute codes, see: - **Visa**: [Visa Core Rules and Visa Product and Service Rules](https://corporate.visa.com/content/dam/VCOM/download/about-visa/visa-rules-public.pdf) - **Mastercard**: [Chargeback Guide - Merchant Edition](https://www.mastercard.com/content/dam/public/mastercardcom/na/global-site/documents/chargeback-guide.pdf) - **American Express**: [Chargeback Codes](https://www.americanexpress.com/content/dam/amex/au/en/merchant/static/chargebackcodeguide.pdf) ::: reason_description: type: string description: Provides a human-readable explanation for the dispute reason codes. amount: type: integer description: >- Disputed 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). ::: currency: $ref: "#/components/schemas/Currency" payment: $ref: "#/components/schemas/Dispute-Payment" Disputes: type: array description: An array containing a list of disputes. items: $ref: "#/components/schemas/Dispute" Dispute-Evidence-Creation: type: object properties: file: type: string description: >- The single evidence file to upload. The client must ensure this part has its own `Content-Type` header specifying the media type of the file (e.g., `application/pdf`, `image/png`, `image/jpeg`). Must be one of the allowed types: `PDF`, `PNG`, `JPEG`. contentMediaType: application/octet-stream required: - file Dispute-Evidence: type: object properties: id: type: string format: uuid description: The ID of the uploaded evidence. examples: - ad2ca3d0-67e9-4cea-b455-e39dd319113d required: - id Dispute-Challenge-Reason: type: string description: The reason for challenging the dispute. enum: - product_already_delivered - refund_already_issued - disagree_with_customers_claim examples: - refund_already_issued Dispute-Challenge-Comment: type: string description: Additional explanation or comment for the challenge, if needed. maxLength: 250 examples: - Refund PDF attached as evidence. Dispute-Challenge-Evidences: type: array description: >- A list of IDs of previously uploaded evidence files to associate with this challenge. :::warning Each evidence ID can only be used for **a single challenge**. This means, that evidences already assigned to a challenge **cannot be reused** for other challenges. ::: items: type: string format: uuid description: ID of a previously uploaded evidence file. minItems: 1 maxItems: 10 uniqueItems: true examples: - - 121ac27c-b00a-44d0-9120-efeeec7c912d - 0010e98d-0653-4dbe-8a4f-70cd5e9491f2 Dispute-Challenge: type: object required: - reason - evidences properties: reason: $ref: "#/components/schemas/Dispute-Challenge-Reason" comment: $ref: "#/components/schemas/Dispute-Challenge-Comment" evidences: $ref: "#/components/schemas/Dispute-Challenge-Evidences" Payment-Retrieval-v3: 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: order_id: type: string format: uuid description: The ID of the associated order. 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-v2" 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 Subscription-Plan-Id: type: string format: uuid description: Unique identifier for the subscription plan. Subscription-Plan-Name: type: string minLength: 1 maxLength: 1024 description: The name of the subscription plan. Subscription-Plan-Trial-Duration: type: string format: duration description: >- The default trial period duration for this subscription plan in [ISO 8601 duration format](https://en.wikipedia.org/wiki/ISO_8601#Durations) (e.g., "P14D" for 14 days). This value serves as the default trial duration for all subscriptions created from this plan. Individual subscriptions can override this value at creation time. :::note Only days (`D`) are allowed. Time components such as hours, minutes, or seconds are not permitted. ::: pattern: ^P[0-9]+D$ examples: - P14D Subscription-Plan-State: type: string enum: - active - deactivated description: >- The state of the subscription plan. | State | Description | | ----- | ----------- | | `active` | The plan is active and can be used to create new subscriptions. | | `deactivated` | The plan has been deactivated and cannot be used for new subscriptions. | Subscription-Plan-Created: type: string format: date-time description: The date and time the subscription plan was created in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. Subscription-Plan-Updated: type: string format: date-time description: The date and time the subscription plan was last updated in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. Subscription-Plan-Variation-Id: type: string format: uuid description: Unique identifier for the subscription plan variation. Subscription-Plan-Phase-Id: type: string format: uuid description: Unique identifier for the subscription plan phase. Subscription-Plan-Ordinal: type: integer minimum: 1 description: >- The sequential order of this phase in the subscription billing lifecycle. Phases execute in ascending order based on this value: - Phase with `ordinal=1` executes first - Phase with `ordinal=2` executes second, and so on When a phase completes its `cycle_count`, the subscription automatically progresses to the phase with the next `ordinal` value. **Example**: A subscription with phases ordered as `ordinal=1` (trial), `ordinal=2` (regular), `ordinal=3` (discounted) will progress through them in that sequence. title: Subscription-Plan-Ordinal Cycle-Duration: type: string format: duration description: >- The length of each billing cycle for this phase in [ISO 8601 duration format](https://en.wikipedia.org/wiki/ISO_8601#Durations). This determines how often the customer is billed during this phase. The total time spent in a phase is `cycle_duration × cycle_count`. **Common durations**: | Duration | Description | | -------- | ----------- | | `P1M` | 1 month | | `P1Y` | 1 year | | `P15D` | 15 days | | `P1W` | 1 week | | `PT2H` | 2 hours | **Example**: If `cycle_duration=P1M` and `cycle_count=12`, the customer will be billed monthly for 12 months (1 year total). Cycle-Count: type: - integer - "null" minimum: 1 description: >- Number of billing cycles for this phase before moving to the next phase. | Value | Behavior | | ----- | -------- | | `null` or omitted | Phase continues indefinitely. The subscription remains in this phase with no automatic progression. | | Specific number (e.g., `1`, `3`, `12`) | After completing this many billing cycles, the subscription automatically moves to the next phase as determined by the `ordinal` field. | **Example**: If `cycle_count=3` and `cycle_duration=P1M`, the subscription will complete 3 monthly cycles then move to the phase with the next highest `ordinal` value. :::note If no next phase exists in after a cycle with a specific `cycle_count`, the subscription will automatically stop when it completes its cycles. ::: title: Cycle-Count Subscription-Amount: type: integer minimum: 0 description: >- Subscription amount in minor currency units (e.g., cents for USD, pence for GBP). For example, `9900` in `GBP` represents £99.00. :::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). ::: Subscription-Item-Id: type: string format: uuid description: The unique identifier of the subscription item. Subscription-Item-Name: type: string description: The name of the subscription item. maxLength: 250 examples: - Base Subscription Fee Subscription-Item-Type: type: string description: The type of subscription item. enum: - flat - usage examples: - flat Subscription-Item-Package-Size: type: number description: >- The number of units grouped together as a single billable package. Used to enable pricing of items that are too inexpensive to charge individually. For example, a `package_size` of `1000` with a unit price of 10 minor units (£0.10 in GBP) lets you sell 1000 tokens for £0.10 — effectively pricing each token at £0.0001, below the minimum chargeable amount. Set to `1` to price each unit individually. examples: - 1 Subscription-Item-Unit: type: string description: The unit of measurement for the item. maxLength: 100 examples: - subscription Subscription-Item-Quantity: type: number description: The quantity of the item. examples: - 1 Subscription-Item-Flat: type: object description: Object structure of flat subscription item. properties: id: $ref: "#/components/schemas/Subscription-Item-Id" name: $ref: "#/components/schemas/Subscription-Item-Name" type: $ref: "#/components/schemas/Subscription-Item-Type" package_size: $ref: "#/components/schemas/Subscription-Item-Package-Size" unit: $ref: "#/components/schemas/Subscription-Item-Unit" quantity: $ref: "#/components/schemas/Subscription-Item-Quantity" amount: type: integer description: Amount in minor currency units (e.g., cents for USD). examples: - 9900 currency: $ref: "#/components/schemas/Currency" required: - id - name - type - amount - currency - unit - quantity Subscription-Item-Tier: type: object properties: upper_quantity_threshold: type: - number - "null" description: The upper bound of the tier (exclusive). Null means unlimited. examples: - 100 amount: type: integer description: Per-unit amount in minor currency units (e.g., cents for USD) charged for usage within this tier's threshold range. examples: - 500 required: - amount Subscription-Item-Code: type: string description: >- A merchant-defined identifier for a usage-based subscription item. You set this code on each usage item when creating a subscription plan, and supply it when reporting consumption on [Create a subscription usage endpoint](/docs/api/merchant#create-a-subscription-usage) to target the correct metered item. This allows a subscription with multiple usage items (e.g., `api_calls` and `storage_gb`) to receive consumption reports against the right item without relying on internal IDs. The code must be unique within a plan phase. maxLength: 250 examples: - api_calls Usage-Aggregation-Method: type: string description: >- The method used to aggregate usage events over a billing cycle to calculate the chargeable amount. | Value | Behaviour | | ----- | --------- | | `sum` | Totals all reported usage events during the cycle. Use for cumulative metrics (e.g., API calls, data transferred). | | `latest` | Uses the most recently reported value at the end of the cycle. If no usage is reported in a cycle, `0` is used — values do not carry over from previous cycles. Use for gauge-style metrics (e.g., active seats). | | `max` | Uses the peak value reported during the cycle. Use for capacity-based billing (e.g., max concurrent connections). | enum: - sum - latest - max examples: - sum Subscription-Item-Usage: type: object description: Object structure of usage subscription item. properties: id: $ref: "#/components/schemas/Subscription-Item-Id" name: $ref: "#/components/schemas/Subscription-Item-Name" type: $ref: "#/components/schemas/Subscription-Item-Type" package_size: $ref: "#/components/schemas/Subscription-Item-Package-Size" unit: $ref: "#/components/schemas/Subscription-Item-Unit" amount: type: integer description: Flat amount per unit in minor currency units. Mutually exclusive with `tiers`. examples: - 10 currency: $ref: "#/components/schemas/Currency" tiers: type: array description: Graduated pricing tiers. Mutually exclusive with `amount`. items: $ref: "#/components/schemas/Subscription-Item-Tier" code: $ref: "#/components/schemas/Subscription-Item-Code" usage_aggregation_method: $ref: "#/components/schemas/Usage-Aggregation-Method" required: - id - name - type - currency - unit - code - usage_aggregation_method Subscription-Item: title: Subscription item type: object description: A subscription item that defines a billing line within a plan phase. Can be either a fixed-fee (flat) item or a metered (usage) item. discriminator: propertyName: type mapping: flat: "#/components/schemas/Subscription-Item-Flat" usage: "#/components/schemas/Subscription-Item-Usage" oneOf: - $ref: "#/components/schemas/Subscription-Item-Flat" - $ref: "#/components/schemas/Subscription-Item-Usage" Subscription-Items: type: array description: A list of subscription items for this phase. items: $ref: "#/components/schemas/Subscription-Item" Subscription-Plan-Phase: type: object properties: id: $ref: "#/components/schemas/Subscription-Plan-Phase-Id" ordinal: $ref: "#/components/schemas/Subscription-Plan-Ordinal" cycle_duration: $ref: "#/components/schemas/Cycle-Duration" cycle_count: $ref: "#/components/schemas/Cycle-Count" amount: $ref: "#/components/schemas/Subscription-Amount" currency: $ref: "#/components/schemas/Currency" subscription_items: $ref: "#/components/schemas/Subscription-Items" required: - id - ordinal - cycle_duration Subscription-Plan-Variation: type: object required: - id - phases properties: id: $ref: "#/components/schemas/Subscription-Plan-Variation-Id" phases: type: array description: List of billing phases for this variation. items: $ref: "#/components/schemas/Subscription-Plan-Phase" Subscription-Plan: type: object required: - id - name - state - created_at - updated_at - variations properties: id: $ref: "#/components/schemas/Subscription-Plan-Id" name: $ref: "#/components/schemas/Subscription-Plan-Name" trial_duration: $ref: "#/components/schemas/Subscription-Plan-Trial-Duration" state: $ref: "#/components/schemas/Subscription-Plan-State" created_at: $ref: "#/components/schemas/Subscription-Plan-Created" updated_at: $ref: "#/components/schemas/Subscription-Plan-Updated" variations: type: array description: List of subscription plan variations. items: $ref: "#/components/schemas/Subscription-Plan-Variation" Subscription-Plans: type: object required: - subscription_plans properties: next_page_token: type: - string - "null" description: |- Token for retrieving the next page of results. If not present, there are no more results to retrieve. subscription_plans: type: array description: List of subscription plans. items: $ref: "#/components/schemas/Subscription-Plan" Subscription-Item-Flat-Creation: type: object description: Object structure of flat subscription item. properties: name: $ref: "#/components/schemas/Subscription-Item-Name" type: $ref: "#/components/schemas/Subscription-Item-Type" package_size: $ref: "#/components/schemas/Subscription-Item-Package-Size" unit: $ref: "#/components/schemas/Subscription-Item-Unit" quantity: $ref: "#/components/schemas/Subscription-Item-Quantity" amount: type: integer description: Amount in minor currency units (e.g., cents for USD). examples: - 9900 currency: $ref: "#/components/schemas/Currency" required: - name - type - amount - currency - unit - quantity Subscription-Item-Usage-Creation: type: object description: Object structure for usage subscription item. properties: name: $ref: "#/components/schemas/Subscription-Item-Name" type: $ref: "#/components/schemas/Subscription-Item-Type" package_size: $ref: "#/components/schemas/Subscription-Item-Package-Size" unit: $ref: "#/components/schemas/Subscription-Item-Unit" amount: type: integer description: Flat amount per unit in minor currency units. Mutually exclusive with `tiers`. examples: - 10 currency: $ref: "#/components/schemas/Currency" tiers: type: array description: Graduated pricing tiers. Mutually exclusive with `amount`. items: $ref: "#/components/schemas/Subscription-Item-Tier" code: $ref: "#/components/schemas/Subscription-Item-Code" usage_aggregation_method: $ref: "#/components/schemas/Usage-Aggregation-Method" required: - name - type - currency - unit - code - usage_aggregation_method Subscription-Item-Creation: title: Subscription item type: object description: A subscription item for a plan phase. Can be either a fixed-fee (flat) item or a metered (usage) item. discriminator: propertyName: type mapping: flat: "#/components/schemas/Subscription-Item-Flat-Creation" usage: "#/components/schemas/Subscription-Item-Usage-Creation" oneOf: - $ref: "#/components/schemas/Subscription-Item-Flat-Creation" - $ref: "#/components/schemas/Subscription-Item-Usage-Creation" Subscription-Items-Creation: type: array description: A list of subscription items for this phase. items: $ref: "#/components/schemas/Subscription-Item-Creation" Subscription-Plan-Phase-Creation: type: object properties: ordinal: $ref: "#/components/schemas/Subscription-Plan-Ordinal" cycle_duration: $ref: "#/components/schemas/Cycle-Duration" cycle_count: $ref: "#/components/schemas/Cycle-Count" amount: $ref: "#/components/schemas/Subscription-Amount" currency: $ref: "#/components/schemas/Currency" subscription_items: $ref: "#/components/schemas/Subscription-Items-Creation" required: - ordinal - cycle_duration - amount - currency Subscription-Plan-Variation-Creation: type: object required: - phases properties: phases: type: array minItems: 1 description: List of billing phases for this variation. items: $ref: "#/components/schemas/Subscription-Plan-Phase-Creation" Subscription-Plan-Creation: type: object required: - name - variations properties: name: $ref: "#/components/schemas/Subscription-Plan-Name" trial_duration: $ref: "#/components/schemas/Subscription-Plan-Trial-Duration" variations: type: array minItems: 1 description: List of subscription plan variations (e.g., monthly, yearly pricing options). items: $ref: "#/components/schemas/Subscription-Plan-Variation-Creation" Subscription-Id: type: string format: uuid description: Unique identifier for the subscription. Subscription-External-Reference: type: string maxLength: 1024 description: >- Optional external reference for the subscription. Use this field to store your own system's identifier for easy tracking and correlation. Subscription-State: type: string enum: - pending - active - overdue - paused - cancelled - finished description: >- The state of the subscription. | State | Description | | ----- | ----------- | | `pending` | The subscription has been created but is not yet active. This typically occurs when awaiting the first payment or setup completion. | | `active` | The subscription is currently active and billing cycles are processing normally. | | `overdue` | The subscription has a failed payment and is awaiting resolution. | | `paused` | The subscription has been temporarily paused and no billing will occur. | | `cancelled` | The subscription has been cancelled and will not renew. | | `finished` | The subscription has completed all billing cycles (for limited-duration subscriptions). | Subscription-Payment-Method-Type: type: string enum: - automatic - manual description: >- The type of payment method used for the subscription. | Type | Description | | ---- | ----------- | | `automatic` | Payments are automatically charged to the customer's saved payment method. | | `manual` | Payments require manual processing by the customer. | Subscription-Created: type: string format: date-time description: The date and time the subscription was created in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. Subscription-Updated: type: string format: date-time description: The date and time the subscription was last updated in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. Subscription-Start-Date: type: - string - "null" format: date-time description: >- The date and time the subscription started in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. This field is `null` until the subscription becomes active. Subscription-Cycle-Id: type: string format: uuid description: Unique identifier for the subscription cycle. Subscription-Trial-Duration: type: string format: duration description: >- The trial period duration for this subscription in [ISO 8601 duration format](https://en.wikipedia.org/wiki/ISO_8601#Durations) (e.g., "P14D" for 14 days). ### Override plan defaults Subscription plans can define a default trial duration. When creating a subscription, you can use this field to override the plan's default trial period: | Field value | Behaviour | Example | | ----------- | -------- | ------- | | **Not provided** | Uses the trial duration defined in the plan (if any) | Plan has `"P7D"` → subscription gets 7-day trial | | **Different value** | Overrides the plan's default trial duration | Plan has `"P7D"` → set to `"P30D"` for promotional offer, or `"P3D"` to reduce | | **`"P0D"`** | Explicitly skips the trial period | Plan has `"P7D"` → set to `"P0D"` to skip trial entirely | :::note Only days (`D`) are allowed. Time components such as hours, minutes, or seconds are not permitted. ::: pattern: ^P[0-9]+D$ examples: - P14D Subscription-Trial-End-Date: type: - string - "null" format: date-time description: >- The date and time when the subscription's trial period ends in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. This value is automatically calculated by the system as: `start_date` + `trial_duration` The `trial_duration` used in the calculation comes from either: - The subscription's custom `trial_duration` (if provided at creation time), or - The plan's default `trial_duration` (if no override was specified) This field is `null` when the subscription has no trial period (e.g., when `trial_duration` is not set or is `"P0D"`). examples: - 2025-06-19T21:00:00.036001Z Setup-Order-Id: type: string format: uuid description: >- The ID of the order created for handling the setup payment for the subscription. Use the [Retrieve an order](/docs/api/merchant#retrieve-an-order) endpoint with this ID to get order details, including the `checkout_url` for redirecting customers to the Hosted Payment Page or the `token` for widget integration. :::note The order is created in parallel to the subscription and is used to collect the initial payment and save the customer's payment method for future billing cycles. ::: Subscription-Scheduled-Action-Type: type: string description: >- The type of the scheduled action. | Value | Description | | ----- | ----------- | | `cancel` | A cancellation scheduled to take effect at the end of the current billing cycle. | | `change_plan_variation` | A plan variation change scheduled to take effect at the end of the current billing cycle. | enum: - cancel - change_plan_variation examples: - change_plan_variation Subscription-Change-Plan-Reason: type: string description: >- The reason for the scheduled action. This field is informational and does not affect how the action is processed. | Value | Description | | ----- | ----------- | | `customer_request` | The action was requested by the customer. | | `merchant_request` | The action was initiated by the merchant. | enum: - customer_request - merchant_request default: merchant_request examples: - customer_request Subscription-Scheduled-Action-Cancel: title: Subscription-Scheduled-Action-Cancel type: object description: A cancellation scheduled to take effect at the end of the current billing cycle. required: - type - reason properties: type: $ref: "#/components/schemas/Subscription-Scheduled-Action-Type" reason: $ref: "#/components/schemas/Subscription-Change-Plan-Reason" Subscription-Scheduled-Action-Change-Plan: title: Subscription-Scheduled-Action-Change-Plan type: object description: A plan variation change scheduled to take effect at the end of the current billing cycle. required: - type - reason - plan_variation_id properties: type: $ref: "#/components/schemas/Subscription-Scheduled-Action-Type" reason: $ref: "#/components/schemas/Subscription-Change-Plan-Reason" plan_variation_id: $ref: "#/components/schemas/Subscription-Plan-Variation-Id" plan_variation_phase_id: $ref: "#/components/schemas/Subscription-Plan-Phase-Id" Subscription-Scheduled-Action: description: A pending scheduled action on the subscription, applied at the end of the current billing cycle. type: object discriminator: propertyName: type mapping: cancel: "#/components/schemas/Subscription-Scheduled-Action-Cancel" change_plan_variation: "#/components/schemas/Subscription-Scheduled-Action-Change-Plan" oneOf: - $ref: "#/components/schemas/Subscription-Scheduled-Action-Cancel" - $ref: "#/components/schemas/Subscription-Scheduled-Action-Change-Plan" Subscription: type: object required: - id - state - customer_id - plan_id - plan_variation_id - payment_method_type - created_at - updated_at - current_cycle_id properties: id: $ref: "#/components/schemas/Subscription-Id" external_reference: $ref: "#/components/schemas/Subscription-External-Reference" state: $ref: "#/components/schemas/Subscription-State" customer_id: $ref: "#/components/schemas/Customer-Id" plan_id: $ref: "#/components/schemas/Subscription-Plan-Id" plan_variation_id: $ref: "#/components/schemas/Subscription-Plan-Variation-Id" payment_method_type: $ref: "#/components/schemas/Subscription-Payment-Method-Type" payment_method_id: $ref: "#/components/schemas/Payment-Method-Id" created_at: $ref: "#/components/schemas/Subscription-Created" updated_at: $ref: "#/components/schemas/Subscription-Updated" start_date: $ref: "#/components/schemas/Subscription-Start-Date" current_cycle_id: $ref: "#/components/schemas/Subscription-Cycle-Id" trial_duration: $ref: "#/components/schemas/Subscription-Trial-Duration" trial_end_date: $ref: "#/components/schemas/Subscription-Trial-End-Date" setup_order_id: $ref: "#/components/schemas/Setup-Order-Id" scheduled_action: $ref: "#/components/schemas/Subscription-Scheduled-Action" Subscriptions: type: object required: - subscriptions properties: next_page_token: $ref: "#/components/schemas/Next-Page-Token" subscriptions: type: array description: List of subscriptions. items: $ref: "#/components/schemas/Subscription" Setup-Order-Redirect-URL: type: string format: uri pattern: ^https?:\/{2}.+/gi maxLength: 2000 description: >- The URL to which the customer is redirected after completing the setup order on the Revolut Hosted Payment Page. When provided, the response will include a `setup_order_id`. Use the [Retrieve an order](/docs/api/merchant#retrieve-an-order) endpoint with this `setup_order_id` to get the `checkout_url` for redirecting the customer to the Hosted Payment Page. :::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) ::: Subscription-Creation: type: object required: - plan_variation_id - customer_id properties: plan_variation_id: $ref: "#/components/schemas/Subscription-Plan-Variation-Id" customer_id: $ref: "#/components/schemas/Customer-Id" external_reference: $ref: "#/components/schemas/Subscription-External-Reference" setup_order_redirect_url: $ref: "#/components/schemas/Setup-Order-Redirect-URL" trial_duration: $ref: "#/components/schemas/Subscription-Trial-Duration" Subscription-Update: type: object properties: external_reference: $ref: "#/components/schemas/Subscription-External-Reference" Subscription-Change-Plan: type: object properties: plan_variation_id: $ref: "#/components/schemas/Subscription-Plan-Variation-Id" plan_variation_phase_id: $ref: "#/components/schemas/Subscription-Plan-Phase-Id" scheduled: type: string description: >- When the plan change should take effect. | Value | Description | | ----- | ----------- | | `at_cycle_end` | The change is applied at the end of the current billing cycle. | enum: - at_cycle_end examples: - at_cycle_end reason: $ref: "#/components/schemas/Subscription-Change-Plan-Reason" required: - plan_variation_id - scheduled Subscription-Update-Renewal-Date: type: object properties: renewal_date: type: string format: date-time description: >- The new renewal date for the subscription, expressed as a UTC date-time value. Must be set to a date later than the current renewal date; earlier dates are rejected. examples: - 2026-07-01T00:00:00Z required: - renewal_date Cycle-Number: type: integer minimum: 1 description: >- The sequential cycle number within the subscription. Starts at `1` for the first cycle and increments with each new billing cycle. Previous-Cycle-Id: type: - string - "null" format: uuid description: |- The unique identifier of the previous billing cycle. This field is `null` for the first cycle in a subscription. Subscription-Cycle-State: type: string enum: - pending - active - finished description: >- The state of the subscription cycle. | State | Description | | ----- | ----------- | | `pending` | The cycle has been created but has not yet started. A cycle can enter this state automatically when usage is reported for a future cycle via `POST /api/subscription-usages`. | | `active` | The cycle is currently active and in progress. | | `finished` | The cycle has completed. | Subscription-Cycle-Start-Date: type: string format: date-time description: The date and time the subscription cycle starts in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. Subscription-Cycle-End-Date: type: string format: date-time description: The date and time the subscription cycle ends in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. Subscription-Cycle-Usage-Cutoff-Date: type: string format: date-time description: >- The deadline for submitting or correcting usage records for this cycle, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. Set to 12 hours after the cycle's `end_date` by default. After this time, Revolut aggregates all reported usage records and creates the `post_billing_order_id` to initiate the charge. :::note Only present for cycles that include usage-based subscription items. ::: Subscription-Cycle-Post-Billing-Order-Id: type: string format: uuid description: >- The ID of the order created after the cycle's `usage_cutoff_date` to charge usage-based items accumulated during the cycle. | Scenario | Detail | | -------- | ------ | | Ongoing subscription | This order also acts as the next cycle's `order_id`, combining usage post-billing for the current cycle with pre-billing for the next. | | Last cycle | A standalone finishing order is created to charge all usage from this cycle. | | Subscription ended with unpaid cycles | The finishing order consolidates all outstanding usage charges, including any from previous cycles where payment failed. | :::note Only present for cycles that include usage-based subscription items. ::: Subscription-Cycle-Trial: type: boolean description: >- Indicates whether this billing cycle occurs during the subscription's trial period. This value is automatically calculated by the system based on the cycle's timing relative to the subscription's trial period. Returns `true` if the cycle is within the trial period (before `trial_end_date`), otherwise `false`. Trial cycles typically have different billing behavior, such as reduced or zero charges. default: false examples: - false Subscription-Cycle: type: object required: - id - subscription_id - plan_variation_id - number - state properties: id: $ref: "#/components/schemas/Subscription-Cycle-Id" subscription_id: $ref: "#/components/schemas/Subscription-Id" plan_variation_id: $ref: "#/components/schemas/Subscription-Plan-Variation-Id" plan_variation_phase_id: $ref: "#/components/schemas/Subscription-Plan-Phase-Id" number: $ref: "#/components/schemas/Cycle-Number" previous_cycle_id: $ref: "#/components/schemas/Previous-Cycle-Id" state: $ref: "#/components/schemas/Subscription-Cycle-State" start_date: $ref: "#/components/schemas/Subscription-Cycle-Start-Date" end_date: $ref: "#/components/schemas/Subscription-Cycle-End-Date" usage_cutoff_date: $ref: "#/components/schemas/Subscription-Cycle-Usage-Cutoff-Date" order_id: $ref: "#/components/schemas/Order-Id" post_billing_order_id: $ref: "#/components/schemas/Subscription-Cycle-Post-Billing-Order-Id" trial: $ref: "#/components/schemas/Subscription-Cycle-Trial" Subscription-Cycles: type: object required: - cycles properties: next_page_token: type: - string - "null" description: |- Token for retrieving the next page of results. If not present, there are no more results to retrieve. cycles: type: array description: List of subscription cycles. items: $ref: "#/components/schemas/Subscription-Cycle" Subscription-Usage-Id: type: string format: uuid description: The unique identifier of the usage record. Subscription-Usage-Date: type: string format: date-time description: >- The timestamp indicating when the consumption actually occurred. | Constraint | Detail | | ---------- | ------ | | Format | ISO 8601 date-time string (e.g., `YYYY-MM-DDTHH:mm:ssZ`). | | Timezone | Must be UTC. | | Validation | Revolut uses this to identify the applicable billing cycle. Accepted for the active cycle (`start_date ≤ usage_date < end_date`), for a recently ended cycle before its `usage_cutoff_date`, and for the one next upcoming cycle. Other dates are rejected. | examples: - 2026-03-01T21:00:00Z Subscription-Usage-Quantity: type: number exclusiveMinimum: 0 description: |- The quantity of consumption to record for this usage report. Supports up to 20 digits before and 20 digits after the decimal point. examples: - 100.5 Subscription-Usage-Metadata: type: object description: >- Key-value pairs you can attach to a usage record for your own tracking and reporting purposes. | Constraint | Detail | | ---------- | ------ | | Keys | Maximum 50 keys per record. | | Value types | String, number, or boolean only. | | Number precision | Up to 20 digits before and 20 digits after the decimal point. | additionalProperties: anyOf: - type: string - type: number - type: boolean maxProperties: 50 examples: - user_id: "12345" api_version: v2 usage_rate: 1.5 is_trial: true Subscription-Usage-Created-Date: type: string format: date-time description: The date and time the usage record was created in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. examples: - 2026-03-01T21:05:00Z Subscription-Usage-Updated-Date: type: string format: date-time description: The date and time the usage record was last updated in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. examples: - 2026-03-01T21:05:00Z Subscription-Usage: type: object required: - id - subscription_id - subscription_cycle_id - subscription_item_code - usage_date - quantity - created_at - updated_at properties: id: $ref: "#/components/schemas/Subscription-Usage-Id" subscription_id: $ref: "#/components/schemas/Subscription-Id" subscription_cycle_id: $ref: "#/components/schemas/Subscription-Cycle-Id" subscription_item_code: $ref: "#/components/schemas/Subscription-Item-Code" usage_date: $ref: "#/components/schemas/Subscription-Usage-Date" quantity: $ref: "#/components/schemas/Subscription-Usage-Quantity" metadata: $ref: "#/components/schemas/Subscription-Usage-Metadata" created_at: $ref: "#/components/schemas/Subscription-Usage-Created-Date" updated_at: $ref: "#/components/schemas/Subscription-Usage-Updated-Date" Subscription-Usages: type: object properties: next_page_token: $ref: "#/components/schemas/Next-Page-Token" subscription_usages: type: array description: List of subscription usages. items: $ref: "#/components/schemas/Subscription-Usage" Subscription-Usage-Creation: type: object required: - subscription_id - subscription_item_code - usage_date - quantity properties: subscription_id: $ref: "#/components/schemas/Subscription-Id" subscription_item_code: $ref: "#/components/schemas/Subscription-Item-Code" usage_date: $ref: "#/components/schemas/Subscription-Usage-Date" quantity: $ref: "#/components/schemas/Subscription-Usage-Quantity" metadata: $ref: "#/components/schemas/Subscription-Usage-Metadata" Subscription-Usage-Update: type: object properties: quantity: $ref: "#/components/schemas/Subscription-Usage-Quantity" metadata: $ref: "#/components/schemas/Subscription-Usage-Metadata" 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-a-payout-list) or from [webhook events](/docs/api/merchant#create-a-webhook#callbacks). | | `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-Signing-Secret: type: string description: The signing secret for the webhook. Use it to verify the signature for the webhook request's payload. Webhook-v2: title: Webhook type: object description: >- A webhook object. Unlike the legacy API, `signing_secret` is included in all webhook responses, not only on creation. 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 - url - events - signing_secret Webhooks: type: object required: - webhooks properties: webhooks: type: array description: List of webhooks. maxItems: 10 items: $ref: "#/components/schemas/Webhook-v2" 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-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-a-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 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 Webhook-Update: title: Webhook update type: object description: >- The request body for updating a webhook. All fields are optional. Only the fields provided in the request will be updated. properties: url: $ref: "#/components/schemas/Webhook-Url" events: $ref: "#/components/schemas/Webhook-Events" 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: [Payload Signature](/docs/api/merchant#authentication)." 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 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: Res-Orders-List-v2: summary: List of orders value: orders: - id: a1b2c3d4-0001-0000-0000-000000000001 token: b2c3d4e5-0001-0000-0000-000000000001 type: payment state: completed created_at: 2025-03-10T08:30:00Z updated_at: 2025-03-10T08:32:15Z amount: 4999 currency: GBP outstanding_amount: 0 capture_mode: automatic enforce_challenge: automatic description: Premium subscription customer: id: c3d4e5f6-0001-0000-0000-000000000001 email: jane.doe@example.com full_name: Jane Doe phone: "+441234567890" - id: a1b2c3d4-0002-0000-0000-000000000002 token: b2c3d4e5-0002-0000-0000-000000000002 type: payment state: completed created_at: 2025-03-11T09:00:00Z updated_at: 2025-03-11T09:01:45Z amount: 12500 currency: EUR outstanding_amount: 0 capture_mode: automatic enforce_challenge: automatic description: Shopping cart customer: id: c3d4e5f6-0002-0000-0000-000000000002 email: john.smith@example.com full_name: John Smith line_items: - name: Wireless headphones quantity: 1 unit_price: 9900 total_amount: 9900 - name: Phone case quantity: 2 unit_price: 1300 total_amount: 2600 - id: a1b2c3d4-0003-0000-0000-000000000003 type: refund state: completed created_at: 2025-03-12T11:15:00Z updated_at: 2025-03-12T11:16:30Z amount: 4999 currency: GBP outstanding_amount: 0 capture_mode: automatic enforce_challenge: automatic related_order_id: a1b2c3d4-0001-0000-0000-000000000001 merchant_order_data: order_id: ORD-2025-001 description: Customer-requested refund - id: a1b2c3d4-0004-0000-0000-000000000004 token: b2c3d4e5-0004-0000-0000-000000000004 type: payment state: authorised created_at: 2025-03-13T14:00:00Z updated_at: 2025-03-13T14:00:30Z amount: 35000 currency: USD outstanding_amount: 35000 capture_mode: manual enforce_challenge: automatic description: Enterprise software licence cancel_authorised_after: 2025-03-20T14:00:00Z customer: id: c3d4e5f6-0003-0000-0000-000000000003 email: alex.johnson@example.com full_name: Alex Johnson - id: a1b2c3d4-0005-0000-0000-000000000005 token: b2c3d4e5-0005-0000-0000-000000000005 type: payment state: completed created_at: 2025-03-14T16:45:00Z updated_at: 2025-03-14T16:46:00Z amount: 799 currency: GBP outstanding_amount: 0 capture_mode: automatic enforce_challenge: automatic description: Coffee and pastry location_id: d4e5f6a7-0001-0000-0000-000000000001 Req-Order-Min: summary: Example order with minimal required parameters value: amount: 500 currency: GBP Req-Order-Additional-v2: 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-Line-Items: summary: Example order with line items value: amount: 770 currency: GBP line_items: - name: Example item 1 type: physical quantity: value: 2 unit: kg unit_price_amount: 100 total_amount: 170 external_id: external_id_123 discounts: - name: Discount 1 amount: 50 taxes: - name: 10% VAT amount: 20 image_urls: - https://www.example.com/line-item-image1 - https://www.example.com/line-item-image2 description: First line item url: https://www.example.com - name: Example item 2 type: service quantity: value: 10 unit: pieces unit_price_amount: 100 total_amount: 600 external_id: external_id_456 discounts: - name: Discount 2 amount: 500 taxes: - name: 10% VAT amount: 100 image_urls: - https://www.example.com/line-item-image3 - https://www.example.com/line-item-image4 description: Second line item url: https://www.example.com Req-Order-Shipping: summary: Example order with shipping details value: amount: 500 currency: GBP shipping: address: street_line_1: Example Street 123 street_line_2: II/123 region: London city: London country_code: GB postcode: "123456" contact: name: Example Contact email: example.contact@example.com phone: "+441234567890" shipments: - shipping_company_name: Example Shipping Co. tracking_number: "123456789" estimated_delivery_date: 2024-12-03T10:15:30+02:00[Europe/Paris] tracking_url: https://www.example.com/tracking/123456789 Req-Order-Airline-v2: 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: airline: type: airline booking_id: unique-booking-id-12345 fulfillment_date: 2025-12-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: 2025-12-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: 2025-12-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: 2025-12-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: 2025-12-15T14: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-v2: 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: car_rental: 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-v3: 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: crypto: type: crypto transactions: - id: 7b2a8ed4-5889-4c0c-a8cc-299aff1c881b status: pending recipient_wallet_id: 64a6f159-0a60-a446-880e-e449a1f62f7c seller: id: a13638ab-3e90-4b05-9f69-23abc655775b name: Ramp Provider Company Name website: https://example.com phone: "123456789" mcc: "6051" address: street_line_1: 456 Crypto Ave city: New York postcode: "10001" country_code: US merchant_order_data: url: https://www.example.com/cryptotransactionnumber-12345 reference: example_crypto_reference redirect_url: https://www.example.com/redirect Req-Order-Marketplace-v3: summary: Example order with additional marketplace data value: amount: 10000 currency: EUR industry_data: marketplace: type: marketplace seller: id: 123-45-67 name: Example Seller 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-v2: summary: Example order with additional event data value: amount: 100 currency: GBP industry_data: event: type: event booking_id: example_booking_123 events: - start_date: 2025-12-20T14:00:00Z end_date: 2025-12-20T17:00:00Z supplier: Example Supplier supplier_payment_date: 2025-12-19T14: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 transferable: false refundability: refundable Req-Order-Lodging-v2: summary: Example order with additional lodging data value: amount: 100 currency: GBP industry_data: lodging: type: lodging booking_id: example_booking_123 lodgings: - check_in_date: 2025-12-05T15:00:00Z check_out_date: 2025-12-10T11:00:00Z category: bed_and_breakfast supplier: id: example_supplier_123 name: Example Supplier payment_date: 2025-01-03T14:00:15Z 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 Req-Order-Multi-Industry: summary: Example order with multiple industry types value: amount: 1500 currency: GBP description: Flight + Hotel Package customer: full_name: Example Customer phone: "+441234567890" email: example@example.com capture_mode: manual industry_data: airline: type: airline booking_id: flight-booking-456 fulfillment_date: 2026-01-20T18:00:00Z ticket_type: flexible refundability: refundable passengers: - first_name: Example last_name: Customer journey_legs: - sequence: 1 departure_airport_code: LHR arrival_airport_code: BCN flight_number: "123" travel_date: 2026-01-15T08:00:00Z airline_name: Example Airlines airline_code: EX - sequence: 2 departure_airport_code: BCN arrival_airport_code: LHR flight_number: "456" travel_date: 2026-01-20T16:00:00Z airline_name: Example Airlines airline_code: EX booking_url: https://example.com/bookings/flight-456 lodging: type: lodging booking_id: hotel-booking-789 lodgings: - check_in_date: 2026-01-15T15:00:00Z check_out_date: 2026-01-20T11:00:00Z category: hotel supplier: id: example_supplier_123 name: Example Supplier payment_date: 2025-01-03T14:00:15Z booking_type: flexible refundability: refundable location: street_line_1: 123 Barcelona Street city: Barcelona country_code: ES postcode: "08001" guests: - first_name: Example last_name: Customer 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-v2: 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-Line-Items: description: Example order response with line items value: id: 66bcc998-4209-ac6e-96fe-2910b949c516 token: 0bcfcc1d-9ee9-4476-b36c-cf4abba2e45a type: payment state: pending created_at: 2024-08-14T15:13:28.814729Z updated_at: 2024-08-14T15:13:28.814729Z amount: 770 currency: GBP outstanding_amount: 770 capture_mode: automatic authorisation_type: final checkout_url: https://checkout.revolut.com/payment-link/0bcfcc1d-9ee9-4476-b36c-cf4abba2e45a enforce_challenge: automatic line_items: - name: Example item 1 unit_price_amount: 100 quantity: value: 2 unit: kg type: physical discounts: - name: Discount 1 amount: 50 taxes: - name: 10% VAT amount: 20 total_amount: 170 image_urls: - https://www.example.com/line-item-image1 - https://www.example.com/line-item-image2 description: First line item external_id: external_id_123 url: https://www.example.com - name: Example item 2 unit_price_amount: 100 quantity: value: 10 unit: pieces type: service discounts: - name: Discount 2 amount: 500 taxes: - name: 10% VAT amount: 100 total_amount: 600 image_urls: - https://www.example.com/line_item_image3 - https://www.example.com/line_item_image4 description: Second line item external_id: external_id_456 url: https://www.example.com Res-Order-Shipping: summary: Example order response with shipping details value: id: 66c5e449-36d3-af78-a832-328150ddc6a3 token: b1145e3e-30c7-4dd6-b84c-680dccd39dde type: payment state: pending created_at: 2024-08-21T12:57:45.793605Z updated_at: 2024-08-21T12:57:45.793605Z amount: 770 currency: GBP outstanding_amount: 770 capture_mode: automatic authorisation_type: final checkout_url: https://checkout.revolut.com/payment-link/b1145e3e-30c7-4dd6-b84c-680dccd39dde shipping: address: street_line_1: Example Street 123 street_line_2: II/123 region: London city: London country_code: GB postcode: "123456" contact: name: Example Contact email: example.contact@example.com phone: "+441234567890" shipments: - shipping_company_name: Example Shipping Co. tracking_number: "123456789" estimated_delivery_date: 2024-12-03T10:15:30+02:00[Europe/Paris] tracking_url: https://www.example.com/tracking/123456789 enforce_challenge: automatic Res-Order-Airline-v2: 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: 2025-12-01T15:28:12.114992Z updated_at: 2025-12-01T15: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: airline: type: airline booking_id: unique-booking-id-12345 fulfillment_date: 2025-12-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: 2025-12-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: 2025-12-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: 2025-12-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: 2025-12-15T14: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-v2: 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-12-01T15:28:12.114992Z updated_at: 2025-12-01T15: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: car_rental: 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-v3: 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: 2025-12-01T15:31:05.746826Z updated_at: 2025-12-01T15: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: crypto: type: crypto transactions: - id: 7b2a8ed4-5889-4c0c-a8cc-299aff1c881b status: pending recipient_wallet_id: 64a6f159-0a60-a446-880e-e449a1f62f7c seller: id: a13638ab-3e90-4b05-9f69-23abc655775b name: Ramp Provider Company Name website: https://example.com phone: "123456789" mcc: "6051" address: street_line_1: 456 Crypto Ave city: New York postcode: "10001" country_code: US 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-v3: 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: 2025-12-01T12:58:04.826974Z updated_at: 2025-12-01T12: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: marketplace: type: marketplace seller: id: 123-45-67 name: Example Seller 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-v2: 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-12-01T14:10:12.804901Z updated_at: 2025-12-01T14: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: event: type: event booking_id: example_booking_123 events: - start_date: 2025-12-20T14:00:00Z end_date: 2025-12-20T17:00:00Z supplier: Example Supplier supplier_payment_date: 2025-12-19T14: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 transferable: false refundability: refundable enforce_challenge: automatic Res-Order-Lodging-v2: 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-12-01T14:25:06.099782Z updated_at: 2025-12-01T14: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: lodging: type: lodging booking_id: example_booking_123 lodgings: - check_in_date: 2025-12-05T15:00:00Z check_out_date: 2025-12-10T11:00:00Z category: bed_and_breakfast supplier: id: example_supplier_123 name: Example Supplier payment_date: 2025-01-03T14:00:15Z 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 enforce_challenge: automatic Res-Order-Multi-Industry: summary: Example order response with multiple industry types value: id: 6516ed0c-098f-aa19-80e5-9d92f52b35e0 token: 061f2c63-e36b-421e-9ece-5adfcd580886 type: payment state: pending created_at: 2025-12-01T15:28:12.114992Z updated_at: 2025-12-01T15:28:12.114992Z amount: 1500 currency: GBP outstanding_amount: 1500 capture_mode: manual authorisation_type: final description: Flight + Hotel Package checkout_url: https://checkout.revolut.com/payment-link/061f2c63-e36b-421e-9ece-5adfcd580886 industry_data: airline: type: airline booking_id: flight-booking-456 fulfillment_date: 2026-01-20T18:00:00Z ticket_type: flexible refundability: refundable passengers: - first_name: Example last_name: Customer journey_legs: - sequence: 1 departure_airport_code: LHR arrival_airport_code: BCN flight_number: "123" travel_date: 2026-01-15T08:00:00Z airline_name: Example Airlines airline_code: EX - sequence: 2 departure_airport_code: BCN arrival_airport_code: LHR flight_number: "456" travel_date: 2026-01-20T16:00:00Z airline_name: Example Airlines airline_code: EX booking_url: https://example.com/bookings/flight-456 lodging: type: lodging booking_id: hotel-booking-789 lodgings: - check_in_date: 2026-01-15T15:00:00Z check_out_date: 2026-01-20T11:00:00Z category: hotel supplier: id: example_supplier_123 name: Example Supplier payment_date: 2025-01-03T14:00:15Z booking_type: flexible refundability: refundable location: street_line_1: 123 Barcelona Street city: Barcelona country_code: ES postcode: "08001" guests: - first_name: Example last_name: Customer enforce_challenge: automatic customer: id: db186257-3031-4726-98ea-f2260ea115f0 email: example@example.com phone: "+441234567890" full_name: Example Customer Req-Order-Increment-Auth-Basic: summary: Example increment with minimal required parameters value: amount: 600 Req-Order-Increment-Auth-Additional: summary: Example increment with additional parameters value: amount: 6000 reference: CHG-67890 line_items: - name: Minibar type: physical quantity: value: 1 unit_price_amount: 2500 total_amount: 2500 - name: Room service type: physical quantity: value: 1 unit_price_amount: 3500 total_amount: 3500 Res-Order-Increment-Processing: summary: Increment in progress value: id: 6920869a-8d8d-aefd-a3c3-8fe4690e4323 token: 0823794d-28e9-4fdd-a130-3293ff9dd57b type: payment state: processing created_at: 2025-11-21T15:34:50.351537Z updated_at: 2025-11-21T15:35:12.123456Z amount: 500 currency: EUR outstanding_amount: 500 capture_mode: manual authorisation_type: pre_authorisation incremental_authorisations: - new_amount: 600 old_amount: 500 state: processing reference: "1263738" payments: - id: 696a4ce4-2aaf-a008-9f26-f47cf8ab1678 state: authorisation_started created_at: 2025-11-21T15:34:50.474085Z updated_at: 2025-11-21T15:35:12.300608Z token: 928f25b1-121c-4669-ab9f-d0b7a5804576 amount: 600 authorised_amount: 500 currency: EUR settled_amount: 500 settled_currency: EUR billing_address: country_code: US postcode: "94102" risk_level: low fees: [] payer: email: example.payer@example.com phone: "+447911123456" payment_method: type: card card_brand: visa funding: debit card_country_code: US card_bin: "424242" card_last_four: "4242" card_expiry: 12/35 cardholder_name: Example Customer checks: three_ds: eci: "05" state: verified version: 2 cvv_verification: not_processed address: n_a postcode: n_a cardholder: n_a fingerprint: aadDmPDArelhtk5QK3zqccaPi39zEDp6/uKuUsA9LHE= network_transaction_id: "1234567890123456" authorisation_code: "100000" arn: "12345678912345678912345" capture_deadline: 2025-11-28T15:34:50.513Z checkout_url: https://checkout.revolut.com/payment-link/0823794d-28e9-4fdd-a130-3293ff9dd57b enforce_challenge: automatic Res-Order-Increment-Authorised: summary: Increment authorised successfully value: id: 6920869a-8d8d-aefd-a3c3-8fe4690e4323 token: 0823794d-28e9-4fdd-a130-3293ff9dd57b type: payment state: authorised created_at: 2025-11-21T15:34:50.351537Z updated_at: 2025-11-21T15:35:15.789012Z amount: 600 currency: EUR outstanding_amount: 600 capture_mode: manual authorisation_type: pre_authorisation incremental_authorisations: - new_amount: 600 old_amount: 500 state: authorised reference: "1263738" payments: - id: 696a4ce4-2aaf-a008-9f26-f47cf8ab1678 state: authorised created_at: 2025-11-21T15:34:50.474085Z updated_at: 2025-11-21T15:35:15.789012Z token: 928f25b1-121c-4669-ab9f-d0b7a5804576 amount: 600 authorised_amount: 600 currency: EUR settled_amount: 600 settled_currency: EUR billing_address: country_code: US postcode: "94102" risk_level: low fees: [] payer: email: example.payer@example.com phone: "+447911123456" payment_method: type: card card_brand: visa funding: debit card_country_code: US card_bin: "424242" card_last_four: "4242" card_expiry: 12/35 cardholder_name: Example Customer checks: three_ds: eci: "05" state: verified version: 2 cvv_verification: not_processed address: n_a postcode: n_a cardholder: n_a fingerprint: aadDmPDArelhtk5QK3zqccaPi39zEDp6/uKuUsA9LHE= network_transaction_id: "1234567890123456" authorisation_code: "100000" arn: "12345678912345678912345" capture_deadline: 2025-11-28T15:34:50.513Z Res-Order-Increment-Declined: summary: Increment declined value: id: 6920869a-8d8d-aefd-a3c3-8fe4690e4323 token: 0823794d-28e9-4fdd-a130-3293ff9dd57b type: payment state: authorised created_at: 2025-11-21T15:34:50.351537Z updated_at: 2025-11-21T15:35:15.789012Z amount: 500 currency: EUR outstanding_amount: 500 capture_mode: manual authorisation_type: pre_authorisation incremental_authorisations: - new_amount: 600 old_amount: 500 state: declined reference: "1263738" reason: insufficient_funds payments: - id: 696a4ce4-2aaf-a008-9f26-f47cf8ab1678 state: authorised created_at: 2025-11-21T15:34:50.474085Z updated_at: 2025-11-21T15:35:15.789012Z token: 928f25b1-121c-4669-ab9f-d0b7a5804576 amount: 500 authorised_amount: 500 currency: EUR settled_amount: 500 settled_currency: EUR billing_address: country_code: US postcode: "94102" risk_level: low fees: [] payer: email: example.payer@example.com phone: "+447911123456" payment_method: type: card card_brand: visa funding: debit card_country_code: US card_bin: "424242" card_last_four: "4242" card_expiry: 12/35 cardholder_name: Example Customer checks: three_ds: eci: "05" state: verified version: 2 cvv_verification: not_processed address: n_a postcode: n_a cardholder: n_a fingerprint: aadDmPDArelhtk5QK3zqccaPi39zEDp6/uKuUsA9LHE= network_transaction_id: "1234567890123456" authorisation_code: "100000" arn: "12345678912345678912345" capture_deadline: 2025-11-28T15:34:50.513Z Req-Order-Capture-Min: summary: Capture with amount only value: amount: 100 Req-Order-Capture-Line-Items: summary: Capture with amount and line items value: amount: 770 line_items: - name: Example item 1 type: physical quantity: value: 2 unit: kg unit_price_amount: 100 total_amount: 170 external_id: external_id_123 discounts: - name: Discount 1 amount: 50 taxes: - name: 10% VAT amount: 20 - name: Example item 2 type: service quantity: value: 10 unit: pieces unit_price_amount: 100 total_amount: 600 external_id: external_id_456 discounts: - name: Discount 2 amount: 500 taxes: - name: 10% VAT amount: 100 Res-Order-Capture-Min: summary: Captured order (minimal) 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: [] payer: email: example.payer@example.com phone: "+447911123456" payment_method: type: revolut_pay_card card_brand: visa funding: debit card_country_code: US card_bin: "529999" card_last_four: "0368" card_expiry: 12/28 cardholder_name: Test Holder checks: three_ds: state: verified version: 2 enforce_challenge: automatic fingerprint: 1JAllfQY4POhBV8DaddAQ4LC5RbMP8LMLvUdJW4s5JY= network_transaction_id: "1234567890123456" Res-Order-Capture-Line-Items: summary: Captured order with line items 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: 770 currency: GBP refunded_amount: 0 outstanding_amount: 0 capture_mode: manual line_items: - name: Example item 1 type: physical quantity: value: 2 unit: kg unit_price_amount: 100 total_amount: 170 external_id: external_id_123 discounts: - name: Discount 1 amount: 50 taxes: - name: 10% VAT amount: 20 - name: Example item 2 type: service quantity: value: 10 unit: pieces unit_price_amount: 100 total_amount: 600 external_id: external_id_456 discounts: - name: Discount 2 amount: 500 taxes: - name: 10% VAT amount: 100 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: 770 currency: GBP settled_amount: 770 settled_currency: GBP billing_address: country_code: US postcode: "12345" risk_level: low fees: [] payer: email: example.payer@example.com phone: "+447911123456" payment_method: type: revolut_pay_card card_brand: visa funding: debit card_country_code: US card_bin: "529999" card_last_four: "0368" card_expiry: 12/28 cardholder_name: Test Holder checks: three_ds: state: verified version: 2 enforce_challenge: automatic fingerprint: 1JAllfQY4POhBV8DaddAQ4LC5RbMP8LMLvUdJW4s5JY= network_transaction_id: "1234567890123456" 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-v2: 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-Line-Items: description: Example order response with line items value: id: 66bcc998-4209-ac6e-96fe-2910b949c516 token: 0bcfcc1d-9ee9-4476-b36c-cf4abba2e45a type: payment state: cancelled created_at: 2024-08-14T15:13:28.814729Z updated_at: 2024-08-14T15:13:28.814729Z amount: 770 currency: GBP outstanding_amount: 770 capture_mode: automatic authorisation_type: final checkout_url: https://checkout.revolut.com/payment-link/0bcfcc1d-9ee9-4476-b36c-cf4abba2e45a enforce_challenge: automatic line_items: - name: Example item 1 unit_price_amount: 100 quantity: value: 2 unit: kg type: physical discounts: - name: Discount 1 amount: 50 taxes: - name: 10% VAT amount: 20 total_amount: 170 image_urls: - https://www.example.com/line-item-image1 - https://www.example.com/line-item-image2 description: First line item external_id: external_id_123 url: https://www.example.com - name: Example item 2 unit_price_amount: 100 quantity: value: 10 unit: pieces type: service discounts: - name: Discount 2 amount: 500 taxes: - name: 10% VAT amount: 100 total_amount: 600 image_urls: - https://www.example.com/line_item_image3 - https://www.example.com/line_item_image4 description: Second line item external_id: external_id_456 url: https://www.example.com Res-Order-Cancel-Shipping: summary: Example order response with shipping details value: id: 66c5e449-36d3-af78-a832-328150ddc6a3 token: b1145e3e-30c7-4dd6-b84c-680dccd39dde type: payment state: cancelled created_at: 2024-08-21T12:57:45.793605Z updated_at: 2024-08-21T12:57:45.793605Z amount: 770 currency: GBP outstanding_amount: 770 capture_mode: automatic authorisation_type: final checkout_url: https://checkout.revolut.com/payment-link/b1145e3e-30c7-4dd6-b84c-680dccd39dde shipping: address: street_line_1: Example Street 123 street_line_2: II/123 region: London city: London country_code: GB postcode: "123456" contact: name: Example Contact email: example.contact@example.com phone: "+441234567890" shipments: - shipping_company_name: Example Shipping Co. tracking_number: "123456789" estimated_delivery_date: 2024-12-03T10:15:30+02:00[Europe/Paris] tracking_url: https://www.example.com/tracking/123456789 enforce_challenge: automatic Res-Order-Cancel-Airline-v2: summary: Example cancelled 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: 2025-12-01T15:53:23.234913Z updated_at: 2025-12-01T16: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: airline: type: airline booking_id: unique-booking-id-12345 fulfillment_date: 2025-12-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: 2025-12-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: 2025-12-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: 2025-12-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: 2025-12-15T14: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: 2025-12-01T15:53:57.268142Z updated_at: 2025-12-01T16: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-v3: summary: Example cancelled order response with additional crypto transaction data value: id: 6516edb9-74af-ae47-829b-1475e807a8d7 token: 1e619c26-d954-4d45-94ab-aba1e407fcee type: payment state: cancelled created_at: 2025-12-01T15:31:05.746826Z updated_at: 2025-12-01T15:45:12.352147Z 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: crypto: type: crypto transactions: - id: 7b2a8ed4-5889-4c0c-a8cc-299aff1c881b status: cancelled recipient_wallet_id: 64a6f159-0a60-a446-880e-e449a1f62f7c seller: id: a13638ab-3e90-4b05-9f69-23abc655775b name: Ramp Provider Company Name website: https://example.com phone: "123456789" mcc: "6051" address: street_line_1: 456 Crypto Ave city: New York postcode: "10001" country_code: US 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-Cancel-Marketplace-v3: summary: Example cancelled 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: 2025-12-01T12:58:04.826974Z updated_at: 2025-12-01T13:15:22.145821Z 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: marketplace: type: marketplace seller: id: 123-45-67 name: Example Seller 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-v2: summary: Example cancelled 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-12-01T14:10:12.804901Z updated_at: 2025-12-01T14:15:33.625184Z 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: event: type: event booking_id: example_booking_123 events: - start_date: 2025-12-20T14:00:00Z end_date: 2025-12-20T17:00:00Z supplier: Example Supplier supplier_payment_date: 2025-12-19T14: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 transferable: false refundability: refundable enforce_challenge: automatic Res-Order-Cancel-Lodging-v2: summary: Example cancelled 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-12-01T14:25:06.099782Z updated_at: 2025-12-01T14:35:18.254973Z 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: lodging: type: lodging booking_id: example_booking_123 lodgings: - check_in_date: 2025-12-05T15:00:00Z check_out_date: 2025-12-10T11:00:00Z category: bed_and_breakfast supplier: id: example_supplier_123 name: Example Supplier payment_date: 2025-01-03T14:00:15Z 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 enforce_challenge: automatic Res-Order-Cancel-Multi-Industry: summary: Example cancelled order response with multiple industry types value: id: 6516ed0c-098f-aa19-80e5-9d92f52b35e0 token: 061f2c63-e36b-421e-9ece-5adfcd580886 type: payment state: cancelled created_at: 2025-12-01T15:28:12.114992Z updated_at: 2025-12-01T15:45:35.842761Z amount: 1500 currency: GBP outstanding_amount: 1500 capture_mode: manual authorisation_type: final description: Flight + Hotel Package checkout_url: https://checkout.revolut.com/payment-link/061f2c63-e36b-421e-9ece-5adfcd580886 industry_data: airline: type: airline booking_id: flight-booking-456 fulfillment_date: 2026-01-20T18:00:00Z ticket_type: flexible refundability: refundable passengers: - first_name: Example last_name: Customer journey_legs: - sequence: 1 departure_airport_code: LHR arrival_airport_code: BCN flight_number: "123" travel_date: 2026-01-15T08:00:00Z airline_name: Example Airlines airline_code: EX - sequence: 2 departure_airport_code: BCN arrival_airport_code: LHR flight_number: "456" travel_date: 2026-01-20T16:00:00Z airline_name: Example Airlines airline_code: EX booking_url: https://example.com/bookings/flight-456 lodging: type: lodging booking_id: hotel-booking-789 lodgings: - check_in_date: 2026-01-15T15:00:00Z check_out_date: 2026-01-20T11:00:00Z category: hotel supplier: id: example_supplier_123 name: Example Supplier payment_date: 2025-01-03T14:00:15Z booking_type: flexible refundability: refundable location: street_line_1: 123 Barcelona Street city: Barcelona country_code: ES postcode: "08001" guests: - first_name: Example last_name: Customer enforce_challenge: automatic customer: id: db186257-3031-4726-98ea-f2260ea115f0 email: example@example.com phone: "+441234567890" full_name: Example Customer Req-Refund-Min: summary: Refund order with minimal required parameters value: amount: 100 currency: GBP Req-Refund-Additional: summary: Refund order with additional parameters value: amount: 100 currency: GBP description: Example refund description merchant_order_data: reference: example_order_reference_123456 metadata: example_metadata_1: Example metadata value 1 example_metadata_2: Example metadata value 2 Res-Refund-Min: summary: Refund order response with minimal required parameters value: id: 6852e9a6-5cf0-ac65-8182-6a9c251011ce type: refund state: processing created_at: 2025-06-18T16:30:30.792962Z updated_at: 2025-06-18T16:30:30.954966Z amount: 100 currency: GBP outstanding_amount: 100 capture_mode: automatic authorisation_type: final payments: - id: 6852e9a6-ca77-a25d-b0be-83191db96e68 state: refund_validated created_at: 2025-06-18T16:30:30.821411Z updated_at: 2025-06-18T16:30:31.391153Z amount: 100 currency: GBP settled_amount: -100 settled_currency: GBP billing_address: country_code: GB postcode: E14 4HD risk_level: low fees: [] payer: email: example.payer@example.com phone: "+447911123456" payment_method: type: card fingerprint: 1JAllfQY4POhBV8DaddAQ4LC5RbMP8LMLvUdJW4s5JY= network_transaction_id: "1234567890123456" card_brand: visa funding: credit card_country_code: GB card_bin: "123456" card_last_four: "1234" card_expiry: 12/33 cardholder_name: Example Holder enforce_challenge: automatic related_order_id: 6852e963-d6a9-a5a4-9609-50b3addc5425 Res-Refund-Additional: summary: Refund order response with additional parameters value: id: 6852dd1f-32e1-a7ca-81c5-66e0dbc85122 type: refund state: processing created_at: 2025-06-18T15:37:03.410996Z updated_at: 2025-06-18T15:37:07.691537Z amount: 100 currency: GBP outstanding_amount: 0 capture_mode: automatic authorisation_type: final description: Example refund description metadata: example_metadata_1: Example metadata value 1 example_metadata_2: Example metadata value 2 payments: - id: 6852dd1f-25df-a855-9481-f5405a03da67 state: refund_validated created_at: 2025-06-18T15:37:03.557842Z updated_at: 2025-06-18T15:37:07.794313Z amount: 100 currency: GBP settled_amount: -100 settled_currency: GBP billing_address: street_line_1: 123 Example Street street_line_2: Example City 123456 city: SentinelFraudLow country_code: GB postcode: AB1 C23 risk_level: low fees: [] payer: email: example.payer@example.com phone: "+447911123456" payment_method: type: revolut_pay_account fingerprint: 1JAllfQY4POhBV8DaddAQ4LC5RbMP8LMLvUdJW4s5JY= enforce_challenge: automatic related_order_id: 6852dc49-b522-a7a2-89e0-09da07982e90 customer: id: 03e12eee-ea3c-4282-bb61-221517c47882 email: example.customer@example.com phone: "+441234567890" full_name: Example Customer date_of_birth: 1990-01-01 merchant_order_data: reference: example_order_reference_123456 Res-Customers-List: summary: List of customers value: next_page_token: 9e5d2caa-bb60-4b5b-b7cf-6345bbdff67e customers: - id: 9dfb8491-bfb0-4420-ad63-0fa7bdd3dffb full_name: First Customer email: first.customer@example.com created_at: 2020-06-24T12:12:56.596703Z updated_at: 2020-06-24T12:12:56.737082Z - id: 6c7c97a8-cfc1-4cf3-8b38-26a74fdf1fae full_name: Second Customer email: second.customer@example.com phone: "+441234567890" created_at: 2020-06-24T12:03:39.979397Z updated_at: 2020-06-25T10:03:39.134417Z Req-Customer-Creation-v2: summary: Create a customer value: full_name: Example Customer email: example.customer@example.com phone: "+441234567890" date_of_birth: 1990-01-01 Res-Customer-Created: summary: Customer value: id: 6c7c97a8-cfc1-4cf3-8b38-26a74fdf1fae full_name: Example Customer email: example.customer@example.com phone: "+441234567890" created_at: 2020-06-24T12:03:39.979397Z updated_at: 2020-06-24T12:03:39.979397Z Res-Customer-v3: summary: Customer value: id: 6c7c97a8-cfc1-4cf3-8b38-26a74fdf1fae full_name: Example Customer email: example.customer@example.com phone: "+441234567890" created_at: 2020-06-24T12:03:39.979397Z updated_at: 2020-06-25T10:03:39.134417Z payment_methods: - id: 648334a8-9546-a983-a81a-efc6d5bdd0be type: revolut_pay saved_for: merchant created_at: 2023-06-09T14:18:16.577888Z - id: edef3ba4-60a0-4df3-8f12-e5fc858c2420 type: card saved_for: customer created_at: 2023-03-24T14:15:22Z bin: "459765" last_four: "6578" expiry_month: 2 expiry_year: 2025 cardholder_name: Example Customer brand: visa funding: debit issuer: EXAMPLE ISSUER issuer_country: GB billing_address: street_line_1: 7 Westferry Circus street_line_2: Columbus Building postcode: E144HD city: London region: Greater London country_code: GB - id: 6a0fe961-a961-a8b6-ad17-ab2779165a82 type: sepa_direct_debit saved_for: merchant created_at: 2026-05-22T05:28:01.887482Z debtor_iban_last_four: "3273" debtor_name: John Doe mandate_reference: 69F1CB61BD99A32C8E20D7FB9E21E146 billing_address: street_line_1: Bank of England street_line_2: Threadneedle St postcode: EC2R 8AH city: London region: Greater London country_code: GB Req-Customer-Update-v2: summary: Update a customer value: email: updated.customer@example.com Res-Customer-Payment-Methods-List: summary: List of payment methods value: payment_methods: - id: 648334a8-9546-a983-a81a-efc6d5bdd0be type: revolut_pay saved_for: merchant created_at: 2023-06-09T14:18:16.577888Z - id: edef3ba4-60a0-4df3-8f12-e5fc858c2420 type: card saved_for: customer created_at: 2023-03-24T14:15:22Z bin: "459678" last_four: "6896" expiry_month: 3 expiry_year: 2025 cardholder_name: Example Customer brand: visa funding: debit issuer: EXAMPLE ISSUER issuer_country: GB billing_address: street_line_1: "7" street_line_2: Westferry Circus postcode: E144HD city: London region: Greater London country_code: GB - id: a04406c4-05be-498b-8207-cc1e02a9b3ca type: card saved_for: merchant created_at: 2023-03-24T14:15:22Z bin: "459885" last_four: "7653" expiry_month: 12 expiry_year: 2026 cardholder_name: Example Holder brand: mastercard funding: credit issuer: EXAMPLE ISSUER issuer_country: GB billing_address: street_line_1: Revolut street_line_2: 1 Canada Square postcode: EC2V 6DN city: London region: Greater London country_code: GB - id: 6a0fe961-a961-a8b6-ad17-ab2779165a82 type: sepa_direct_debit saved_for: merchant created_at: 2026-05-22T05:28:01.887482Z debtor_iban_last_four: "3273" debtor_name: John Doe mandate_reference: 69F1CB61BD99A32C8E20D7FB9E21E146 billing_address: street_line_1: Bank of England street_line_2: Threadneedle St postcode: EC2R 8AH city: London region: Greater London country_code: GB Res-Customer-Payment-Method: retrieved_card: summary: Retrieved card payment method value: id: edef3ba4-60a0-4df3-8f12-e5fc858c2420 type: card saved_for: customer created_at: 2023-03-24T14:15:22Z bin: "459678" last_four: "6896" expiry_month: 3 expiry_year: 2025 cardholder_name: Example Customer brand: visa funding: debit issuer: EXAMPLE ISSUER issuer_country: GB billing_address: street_line_1: "7" street_line_2: Westferry Circus postcode: E144HD city: London region: Greater London country_code: GB retrieved_revolut_pay: summary: Retrieved Revolut Pay payment method value: id: 648334a8-9546-a983-a81a-efc6d5bdd0be type: revolut_pay saved_for: merchant created_at: 2023-06-09T14:18:16.577888Z retrieved_sepa_direct_debit: summary: Retrieved SEPA Direct Debit payment method value: id: 6a0fe961-a961-a8b6-ad17-ab2779165a82 type: sepa_direct_debit saved_for: merchant created_at: 2026-05-22T05:28:01.887482Z debtor_iban_last_four: "3273" debtor_name: John Doe mandate_reference: 69F1CB61BD99A32C8E20D7FB9E21E146 billing_address: street_line_1: Bank of England street_line_2: Threadneedle St postcode: EC2R 8AH city: London region: Greater London country_code: GB Req-Payment-Method-Update: summary: Update a payment method value: saved_for: customer Res-Dispute-List: summary: List of disputes value: - id: ab934829-e4ba-4e7f-8a21-365cad85c763 state: under_review substate: arbitration created_at: 2024-06-13T12:06:18.732706Z updated_at: 2024-09-12T22:27:10.005680Z response_due_date: 2024-10-12T22:27:10.005625Z reason_code: "50" reason_description: Fraud amount: 50 currency: EUR payment: id: 6666f6c7-3898-a094-9c83-dc0152e0185c order_id: 6666f685-46a7-a7b9-9860-a28a4f3495a4 created_at: 2024-06-10T12:51:19.960490Z amount: 50 currency: EUR payment_method: type: revolut_pay_account - id: 340b85dc-da99-4c5f-9d47-37a45d52a455 state: lost substate: lost_expired created_at: 2024-09-11T21:20:05.659978Z updated_at: 2024-09-12T22:35:31.721921Z response_due_date: 2024-09-22T22:35:31.721860Z reason_code: "12.4" reason_description: Incorrect Account Number amount: 40 currency: EUR payment: id: 66e1fc66-7606-a7fb-b2e8-b48fb637783a order_id: 66e1fc4d-5cbe-a692-80aa-1cb912291d55 created_at: 2024-09-11T20:24:06.271746Z amount: 40 currency: EUR payment_method: type: card card_brand: visa card_last_four: "1234" - id: e9b5472b-7308-4aea-86a0-d4427bc04c24 state: lost substate: lost_pre_arbitration created_at: 2026-05-22T09:00:00Z updated_at: 2026-05-22T10:15:00Z response_due_date: 2030-12-15T00:00:00Z reason_code: OTHER reason_description: merchant_dispute amount: 91700 currency: GBP payment: id: 6a0f2bc4-2137-a1ad-9eb6-b34cf4ca6597 order_id: 2bcaf93a-aa87-4d3d-b5c6-62e06051cff2 created_at: 2026-05-21T15:59:00.451602Z amount: 1000 currency: GBP payment_method: type: sepa_direct_debit debtor_iban_last_four: "3273" debtor_name: John Doe mandate_reference: 69F1CB61BD99A32C8E20D7FB9E21E146 Res-Dispute-Card: summary: Dispute for a card payment value: id: fccc53e9-00e0-4847-9d54-6938e9cdd3ef state: lost substate: lost_accepted created_at: 2025-03-12T07:00:00.000000Z updated_at: 2025-03-13T10:00:00.000000Z response_due_date: 2025-03-15T12:00:00.000000Z reason_code: "50" reason_description: Fraud amount: 1500 currency: EUR payment: id: 67810850-4c48-a25d-8765-d03d36ca6719 order_id: 38bd1186-a276-4b14-91b4-5da886481f85 created_at: 2025-01-02T10:00:00Z arn: P58PC241502Q7800000000A amount: 3000 currency: EUR payment_method: type: card card_brand: visa card_last_four: "1234" Res-Dispute-Sepa-Direct-Debit: summary: Dispute for a SEPA Direct Debit payment value: id: 7a2d8f4b-1c3e-4a56-b789-0d1e2f3a4b5c state: needs_response substate: new created_at: 2026-05-22T09:00:00Z updated_at: 2026-05-22T09:00:00Z response_due_date: 2026-06-05T09:00:00Z reason_code: OTHER reason_description: merchant_dispute amount: 10000 currency: EUR payment: id: 6a0f2bc4-2137-a1ad-9eb6-b34cf4ca6597 order_id: 2bcaf93a-aa87-4d3d-b5c6-62e06051cff2 created_at: 2026-05-21T15:59:00.451602Z amount: 10000 currency: EUR payment_method: type: sepa_direct_debit debtor_iban_last_four: "3273" debtor_name: John Doe mandate_reference: 69F1CB61BD99A32C8E20D7FB9E21E146 Res-Dispute-Evidence: summary: Uploaded evidence value: id: 121ac27c-b00a-44d0-9120-efeeec7c912d Req-Dispute-Challenge-Min: summary: Minimal dispute challenge with reason and evidence value: reason: refund_already_issued evidences: - 121ac27c-b00a-44d0-9120-efeeec7c912d Req-Dispute-Challenge-With-Evidence: summary: Dispute challenge with reason, multiple evidences, and comment value: reason: product_already_delivered comment: The customer received the product on 2026-05-10 as confirmed by our delivery records. evidences: - 121ac27c-b00a-44d0-9120-efeeec7c912d - 0010e98d-0653-4dbe-8a4f-70cd5e9491f2 Res-Payment-Authentication-Challenge-Fingerprint: summary: Payment with 3DS fingerprint challenge value: id: d4aa447c-b9ef-4a0b-86ac-59bc4e8d590e order_id: b2da1805-94c3-4f66-8bae-4fc927d33990 state: authentication_challenge created_at: 2026-03-12T10:00:00.000000Z updated_at: 2026-03-12T10:00:05.000000Z token: 3f7a9b2c-1d4e-5f6a-7b8c-9d0e1f2a3b4c amount: 1000 currency: GBP settled_amount: 1000 settled_currency: GBP risk_level: low fees: [] payment_method: type: card card_brand: visa funding: credit card_country_code: GB card_bin: "411111" card_last_four: "1111" card_expiry: 12/28 cardholder_name: Example Customer authentication_challenge: type: three_ds_fingerprint fingerprint_html: PCFET0NUWVBFIGh0bWw+CjxodG1sPgo8Ym9keT4KCjwvYm9keT4KPC9odG1sPg== Res-Subscription-Plans-List: summary: List of subscription plans value: next_page_token: 9e5d2caa-bb60-4b5b-b7cf-6345bbdff67e subscription_plans: - id: 550e8400-e29b-41d4-a716-446655440000 name: Premium Plan with 14-days Trial state: active trial_duration: P14D created_at: 2025-06-05T21:00:00.036001Z updated_at: 2025-06-05T21:00:00.036001Z variations: - id: 550e8400-e29b-41d4-a716-446655440001 phases: - id: 550e8400-e29b-41d4-a716-446655440002 ordinal: 1 cycle_duration: P1Y amount: 99900 currency: GBP - id: f757b068-f287-43c8-8d05-9c073fecbe73 name: Enterprise Pro Plan state: active created_at: 2026-01-26T08:59:09.433527Z updated_at: 2026-01-26T08:59:09.433527Z variations: - id: f4e0a171-4f4e-484b-b0a2-22085059af65 phases: - id: 23319d04-4b23-4ae7-ba54-82112c752683 ordinal: 1 cycle_duration: P1M amount: 990 currency: GBP - id: 7cf47b0d-3da9-496b-a4e9-fbbe43c33ee3 phases: - id: feed2491-c895-4bfa-ba05-a3a088842d5c ordinal: 1 cycle_duration: P1Y amount: 9990 currency: GBP Req-Subscription-Plan-Simple: summary: Simple yearly and monthly plan value: name: Enterprise Pro Plan variations: - phases: - ordinal: 1 cycle_duration: P1Y amount: 99900 currency: GBP - phases: - ordinal: 1 cycle_duration: P1M amount: 9900 currency: GBP Req-Subscription-Plan-With-Trial-Duration: summary: Plan with trial duration value: name: Premium Plan with 14-day Trial trial_duration: P14D variations: - phases: - ordinal: 1 cycle_duration: P1M amount: 9900 currency: GBP Req-Subscription-Plan-Limited: summary: Plan that ends after 12 months value: name: 12-month Limited Plan variations: - phases: - ordinal: 1 cycle_duration: P1M cycle_count: 12 amount: 1000 currency: GBP Req-Subscription-Plan-Usage-Base: summary: Usage-based plan with tiered pricing value: name: API Usage Plan variations: - phases: - ordinal: 1 cycle_duration: P1M subscription_items: - name: API Calls type: usage currency: GBP unit: calls code: api_calls usage_aggregation_method: sum tiers: - upper_quantity_threshold: 1000 amount: 0 - upper_quantity_threshold: 10000 amount: 10 - amount: 5 Req-Subscription-Plan-Hybrid: summary: Hybrid plan with flat base fee and usage-based items value: name: Professional Plan variations: - phases: - ordinal: 1 cycle_duration: P1M subscription_items: - name: Base Subscription type: flat quantity: 1 amount: 2900 currency: GBP unit: subscription - name: API Calls type: usage currency: GBP unit: calls code: api_calls usage_aggregation_method: sum amount: 10 - name: Storage type: usage currency: GBP unit: gb code: storage_gb usage_aggregation_method: max package_size: 1 tiers: - upper_quantity_threshold: 10 amount: 0 - upper_quantity_threshold: 100 amount: 50 - amount: 30 Req-Subscription-Plan-Package: summary: Usage-based plan with block pricing (price per 1000 units) value: name: SMS Plan variations: - phases: - ordinal: 1 cycle_duration: P1M subscription_items: - name: SMS Messages type: usage currency: GBP unit: messages code: sms_messages usage_aggregation_method: sum package_size: 1000 amount: 500 Req-Subscription-Plan-With-Items: summary: Plan with flat and usage-based subscription items value: name: Professional Platform Plan variations: - phases: - ordinal: 1 cycle_duration: P1M amount: 4900 currency: GBP subscription_items: - type: flat name: Platform License unit: subscription quantity: 1 amount: 4900 currency: GBP - type: usage name: API Calls unit: call code: api_calls usage_aggregation_method: sum amount: 1 currency: GBP Res-Subscription-Plan-Simple: summary: Simple yearly and monthly plan value: id: f757b068-f287-43c8-8d05-9c073fecbe73 name: Enterprise Pro Plan state: active created_at: 2026-01-26T08:59:09.433527Z updated_at: 2026-01-26T08:59:09.433527Z variations: - id: f4e0a171-4f4e-484b-b0a2-22085059af65 phases: - id: 23319d04-4b23-4ae7-ba54-82112c752683 ordinal: 1 cycle_duration: P1M amount: 990 currency: GBP - id: 7cf47b0d-3da9-496b-a4e9-fbbe43c33ee3 phases: - id: feed2491-c895-4bfa-ba05-a3a088842d5c ordinal: 1 cycle_duration: P1Y amount: 9990 currency: GBP Res-Subscription-Plan-With-Trial-Duration: summary: Plan with trial duration value: id: 750e8400-e29b-41d4-a716-446655440010 name: Premium Plan with 14-day Trial trial_duration: P14D state: active created_at: 2025-06-04T21:00:00.036001Z updated_at: 2025-06-04T21:00:00.036001Z variations: - id: 850e8400-e29b-41d4-a716-446655440011 phases: - id: 950e8400-e29b-41d4-a716-446655440012 ordinal: 1 cycle_duration: P1M amount: 9900 currency: GBP Res-Subscription-Plan-Limited: summary: Plan that ends after 12 months value: id: 550e8400-e29b-41d4-a716-446655440003 name: 12-month Limited Plan state: active created_at: 2025-06-05T21:00:00.036001Z updated_at: 2025-06-05T21:00:00.036001Z variations: - id: 550e8400-e29b-41d4-a716-446655440004 phases: - id: 550e8400-e29b-41d4-a716-446655440005 ordinal: 1 cycle_duration: P1M cycle_count: 12 amount: 1000 currency: GBP Res-Subscription-Plan-Usage-Base: summary: Usage-based plan with tiered pricing value: id: 8d2c8872-9e8a-4b1a-827c-3f78e1234abc name: API Usage Plan state: active created_at: 2026-04-15T17:58:36.000Z updated_at: 2026-04-15T17:58:36.000Z variations: - id: a4e0a171-4f4e-484b-b0a2-22085059df99 phases: - id: ceed2491-c895-4bfa-ba05-a3a088842e11 ordinal: 1 cycle_duration: P1M subscription_items: - name: API Calls type: usage currency: GBP unit: calls code: api_calls usage_aggregation_method: sum tiers: - upper_quantity_threshold: 1000 amount: 0 - upper_quantity_threshold: 10000 amount: 10 - amount: 5 Res-Subscription-Plan-Hybrid: summary: Hybrid plan with flat base fee and usage-based items value: id: b22198c4-724d-4e9e-b9e3-827c3f78e456 name: Professional Plan state: active created_at: 2026-04-15T18:02:11.000Z updated_at: 2026-04-15T18:02:11.000Z variations: - id: d4e0a171-4f4e-484b-b0a2-22085059df77 phases: - id: ffeed491-c895-4bfa-ba05-a3a088842e22 ordinal: 1 cycle_duration: P1M subscription_items: - name: Base Subscription type: flat quantity: 1 amount: 2900 currency: GBP unit: subscription - name: API Calls type: usage currency: GBP unit: calls code: api_calls usage_aggregation_method: sum amount: 10 - name: Storage type: usage currency: GBP unit: gb code: storage_gb usage_aggregation_method: max package_size: 1 tiers: - upper_quantity_threshold: 10 amount: 0 - upper_quantity_threshold: 100 amount: 50 - amount: 30 Res-Subscription-Plan-Package: summary: Usage-based plan with block pricing (price per 1000 units) value: id: e33198c4-124d-4e9e-b9e3-827c3f78e789 name: SMS Plan state: active created_at: 2026-04-15T18:05:42.000Z updated_at: 2026-04-15T18:05:42.000Z variations: - id: c4e0a171-4f4e-484b-b0a2-22085059df44 phases: - id: ddeed491-c895-4bfa-ba05-a3a088842e33 ordinal: 1 cycle_duration: P1M subscription_items: - name: SMS Messages type: usage currency: GBP unit: messages code: sms_messages usage_aggregation_method: sum package_size: 1000 amount: 500 Res-Subscription-Plan-With-Items: summary: Plan with flat and usage-based subscription items value: id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 name: Professional Platform Plan state: active created_at: 2026-01-10T09:00:00.000000Z updated_at: 2026-01-10T09:00:00.000000Z variations: - id: b2c3d4e5-f6a7-8901-bcde-f12345678901 phases: - id: c3d4e5f6-a7b8-9012-cdef-123456789012 ordinal: 1 cycle_duration: P1M amount: 4900 currency: GBP subscription_items: - id: d4e5f6a7-b8c9-0123-defa-234567890123 type: flat name: Platform License unit: subscription quantity: 1 amount: 4900 currency: GBP - id: e5f6a7b8-c9d0-1234-efab-345678901234 type: usage name: API Calls unit: call code: api_calls usage_aggregation_method: sum amount: 1 currency: GBP Res-Subscriptions-List: summary: List of subscriptions value: next_page_token: 9e5d2caa-bb60-4b5b-b7cf-6345bbdff67e subscriptions: - id: 550e8400-e29b-41d4-a716-446655440000 external_reference: ext-ref-12345 state: active customer_id: 650e8400-e29b-41d4-a716-446655440001 plan_id: 750e8400-e29b-41d4-a716-446655440002 plan_variation_id: 850e8400-e29b-41d4-a716-446655440003 payment_method_type: automatic payment_method_id: 6689e244-8af7-4ada-9448-a91f02d4f192 created_at: 2025-06-05T21:00:00.036001Z updated_at: 2025-06-05T21:00:00.036001Z start_date: 2025-06-05T21:00:00.036001Z current_cycle_id: 950e8400-e29b-41d4-a716-446655440004 - id: 550e8400-e29b-41d4-a716-446655440010 state: pending customer_id: 650e8400-e29b-41d4-a716-446655440011 plan_id: 750e8400-e29b-41d4-a716-446655440012 plan_variation_id: 850e8400-e29b-41d4-a716-446655440013 payment_method_type: automatic created_at: 2025-06-04T21:00:00.036001Z updated_at: 2025-06-04T21:00:00.036001Z current_cycle_id: a31627fb-b037-4566-8d7b-f380c1f44653 Req-Subscription-Setup-Order: summary: Subscription with redirect URL value: plan_variation_id: 550e8400-e29b-41d4-a716-446655440000 customer_id: 650e8400-e29b-41d4-a716-446655440001 setup_order_redirect_url: https://example.com/subscription/setup/complete external_reference: ext-ref-12345 Req-Subscription-Setup-Order-No-URL: summary: Subscription without redirect URL value: plan_variation_id: 550e8400-e29b-41d4-a716-446655440000 customer_id: 650e8400-e29b-41d4-a716-446655440001 external_reference: ext-ref-12345 Req-Subscription-With-Trial: summary: Subscription with trial period overriding the trial duration from plan value: plan_variation_id: 550e8400-e29b-41d4-a716-446655440000 customer_id: 650e8400-e29b-41d4-a716-446655440001 payment_method_id: 6689e244-8af7-4ada-9448-a91f02d4f192 trial_duration: P14D external_reference: ext-ref-12345 Req-Subscription-Skip-Trial: summary: Subscription skipping trial predefined in plan value: plan_variation_id: 550e8400-e29b-41d4-a716-446655440000 customer_id: 650e8400-e29b-41d4-a716-446655440001 payment_method_id: 6689e244-8af7-4ada-9448-a91f02d4f192 trial_duration: P0D external_reference: ext-ref-12345 Res-Subscription-Setup-Order: summary: Subscription created with setup order value: id: 550e8400-e29b-41d4-a716-446655440000 external_reference: ext-ref-12345 state: pending customer_id: 650e8400-e29b-41d4-a716-446655440001 plan_id: 750e8400-e29b-41d4-a716-446655440002 plan_variation_id: 850e8400-e29b-41d4-a716-446655440003 payment_method_type: automatic created_at: 2025-06-05T21:00:00.036001Z updated_at: 2025-06-05T21:00:00.036001Z setup_order_id: a50e8400-e29b-41d4-a716-446655440005 current_cycle_id: a31627fb-b037-4566-8d7b-f380c1f44653 Res-Subscription-Setup-Order-No-URL: summary: Subscription created with setup order (no redirect URL) value: id: 550e8400-e29b-41d4-a716-446655440006 external_reference: ext-ref-12345 state: pending customer_id: 650e8400-e29b-41d4-a716-446655440001 plan_id: 750e8400-e29b-41d4-a716-446655440002 plan_variation_id: 850e8400-e29b-41d4-a716-446655440003 payment_method_type: automatic created_at: 2025-06-05T21:00:00.036001Z updated_at: 2025-06-05T21:00:00.036001Z setup_order_id: a50e8400-e29b-41d4-a716-446655440007 current_cycle_id: a31627fb-b037-4566-8d7b-f380c1f44654 Res-Subscription-Active: summary: Active subscription value: id: 550e8400-e29b-41d4-a716-446655440000 external_reference: ext-ref-12345 state: active customer_id: 650e8400-e29b-41d4-a716-446655440001 plan_id: 750e8400-e29b-41d4-a716-446655440002 plan_variation_id: 850e8400-e29b-41d4-a716-446655440003 payment_method_type: automatic payment_method_id: 6689e244-8af7-4ada-9448-a91f02d4f192 created_at: 2025-06-05T21:00:00.036001Z updated_at: 2025-06-05T21:00:00.036001Z start_date: 2025-06-05T21:00:00.036001Z current_cycle_id: 950e8400-e29b-41d4-a716-446655440004 trial_duration: P14D trial_end_date: 2025-06-19T21:00:00.036001Z Req-Subscription-Update: summary: Update subscription value: external_reference: ext-ref-12345 Req-Subscription-Change-Plan: summary: Schedule plan change at cycle end value: plan_variation_id: 850e8400-e29b-41d4-a716-446655440003 scheduled: at_cycle_end Req-Subscription-Change-Plan-With-Reason: summary: Schedule plan change with reason value: plan_variation_id: 850e8400-e29b-41d4-a716-446655440003 scheduled: at_cycle_end reason: customer_request Req-Subscription-Change-Plan-With-Phase: summary: Schedule plan change to a specific phase value: plan_variation_id: 850e8400-e29b-41d4-a716-446655440003 plan_variation_phase_id: 950e8400-e29b-41d4-a716-446655440004 scheduled: at_cycle_end Req-Subscription-Update-Renewal-Date: summary: Update renewal date value: renewal_date: 2026-07-01T00:00:00Z Res-Subscription-Cycles-List: summary: List of subscription cycles value: next_page_token: 9e5d2caa-bb60-4b5b-b7cf-6345bbdff67e cycles: - id: 550e8400-e29b-41d4-a716-446655440010 subscription_id: 650e8400-e29b-41d4-a716-446655440001 plan_variation_id: 750e8400-e29b-41d4-a716-446655440002 plan_variation_phase_id: 850e8400-e29b-41d4-a716-446655440003 number: 2 previous_cycle_id: 550e8400-e29b-41d4-a716-446655440000 state: active start_date: 2025-07-05T21:00:00.036001Z end_date: 2025-08-05T21:00:00.036001Z order_id: a50e8400-e29b-41d4-a716-446655440015 trial: false - id: 550e8400-e29b-41d4-a716-446655440000 subscription_id: 650e8400-e29b-41d4-a716-446655440001 plan_variation_id: 750e8400-e29b-41d4-a716-446655440002 number: 1 state: finished start_date: 2025-06-05T21:00:00.036001Z end_date: 2025-07-05T21:00:00.036001Z order_id: a50e8400-e29b-41d4-a716-446655440005 trial: true Res-Subscription-Cycle-Finished: summary: Finished subscription cycle value: id: 950e8400-e29b-41d4-a716-446655440004 subscription_id: 650e8400-e29b-41d4-a716-446655440001 plan_variation_id: 750e8400-e29b-41d4-a716-446655440002 plan_variation_phase_id: 850e8400-e29b-41d4-a716-446655440003 number: 1 state: finished start_date: 2025-06-05T21:00:00.036001Z end_date: 2025-07-05T21:00:00.036001Z order_id: b50e8400-e29b-41d4-a716-446655440006 trial: true Res-Usage-List: summary: Retrieve a list of usage records value: next_page_token: 9e5d2caa-bb60-4b5b-b7cf-6345bbdff67e subscription_usages: - id: 750e8400-e29b-41d4-a716-446655440000 subscription_id: 550e8400-e29b-41d4-a716-446655440000 subscription_cycle_id: 850e8400-e29b-41d4-a716-446655440000 subscription_item_code: api_calls usage_date: 2026-03-01T21:00:00Z quantity: 100 metadata: user_id: "12345" api_version: v2 created_at: 2026-03-01T21:05:00Z updated_at: 2026-03-01T21:05:00Z - id: bc903328-9f37-4d7a-8f56-02e5b7c76891 subscription_id: 550e8400-e29b-41d4-a716-446655440000 subscription_cycle_id: 850e8400-e29b-41d4-a716-446655440000 subscription_item_code: api_calls usage_date: 2026-03-01T22:15:00Z quantity: 50 metadata: user_id: "12345" api_version: v2 created_at: 2026-03-01T22:20:00Z updated_at: 2026-03-01T22:20:00Z Req-Subscription-Usage: summary: Report active license seats description: Reporting active seats used during a period value: subscription_id: 550e8400-e29b-41d4-a716-446655440000 subscription_item_code: active_seats usage_date: 2026-03-15T09:30:00Z quantity: 12 metadata: department: engineering update_type: onboarding Res-Subscription-Usage: summary: Successful usage record creation description: Returns the reported usages value: id: 750e8400-e29b-41d4-a716-446655440000 subscription_id: 550e8400-e29b-41d4-a716-446655440000 subscription_cycle_id: 850e8400-e29b-41d4-a716-446655440000 subscription_item_code: api_calls usage_date: 2026-03-01T21:00:00Z quantity: 100 metadata: user_id: "12345" api_version: v2 created_at: 2026-03-01T21:05:00Z updated_at: 2026-03-01T21:05:00Z Req-Subscription-Usage-Update-Quantity: summary: Update quantity value: quantity: 150 Req-Subscription-Usage-Update-Metadata: summary: Update metadata value: metadata: user_id: "67890" api_version: v3 Req-Subscription-Usage-Update: summary: Update both quantity and metadata value: quantity: 200 metadata: user_id: "54321" Res-Webhooks-List: summary: List of webhooks value: webhooks: - id: 6fc8db62-6489-4470-a9e0-84b462fe3908 url: https://revolut.com/webhooks events: - ORDER_COMPLETED - id: b466ab77-4932-4850-beb0-113bfc1166f8 url: https://business.revolut.com/webhooks events: - ORDER_COMPLETED - ORDER_AUTHORISED - id: c6b981f4-53b3-47d5-9b24-4f87af1160eb url: https://example.com/webhooks events: - ORDER_AUTHORISED - ORDER_COMPLETED Req-Webhook-Create: summary: Example webhook request value: url: https://example.com/webhooks events: - ORDER_COMPLETED - ORDER_AUTHORISED Res-Webhook-v2: summary: Webhook value: id: c6b981f4-53b3-47d5-9b24-4f87af1160eb url: https://example.com/webhooks events: - ORDER_AUTHORISED - ORDER_COMPLETED signing_secret: wsk_4jETWMz1g1b37gCONjNp84t2KSSIT7dK Req-Webhook-Update: summary: Update a webhook value: url: https://example.com/webhooks/updated events: - ORDER_COMPLETED - ORDER_AUTHORISED - ORDER_CANCELLED Req-Webhook-Rotate-Signing-Secret: summary: Webhook signing secret rotation request value: expiration_period: PT5H30M 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-a-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: {}