openapi: 3.1.1 info: title: Merchant API version: Legacy 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/Legacy#tag-orders) - [Customer management](/docs/api/merchant/Legacy#tag-customers) - [Payment management](/docs/api/merchant/Legacy#tag-payments) - [Reporting analytics](/docs/api/merchant/Legacy#tag-report-runs) - [Webhook management](/docs/api/merchant/Legacy#tag-webhooks) - [Location management](/docs/api/merchant/Legacy#tag-locations) ... and more. ### API versions :::warning We highly recommend using versioning in your API calls. If you don't provide a version header on the operations where it's required, you will receive an error response. ::: The Merchant API uses request header versioning. Where it is required you need to use the `Revolut-Api-Version` header parameter to specify an API version. Each request, where it is indicated in the API specification, must contain a version header in the following format: ``` 'Revolut-Api-Version: 2023-09-01' ``` :::info For more information, see: [API versions](/docs/guides/merchant/reference/versioning/api-versions) ::: ### Test the Merchant API You can test the Merchant API in Postman by forking this collection: [![View in Postman](https://run.pstmn.io/button.svg)](https://www.postman.com/revolut-api/workspace/revolut-developers/overview) contact: {} servers: - description: Production server (uses live data) url: https://merchant.revolut.com - description: Sandbox server (uses test data) url: https://sandbox-merchant.revolut.com security: - Api-Key: [] tags: - name: Orders description: >- The Orders resource in the Merchant API offers a comprehensive solution for managing the lifecycle of orders within your e-commerce or retail platform. Designed to streamline order processing, this resource encapsulates a suite of operations that allow for efficiently handling order management-related tasks. For more information about the order lifecycle, see: [Order and payment lifecycle](/docs/guides/merchant/reference/order-lifecycle). These operations are equipped to handle various order management scenarios, providing a robust interface for businesses to interact with their order data. To process a payment related to your customers' purchases, you need to create an `Order` object. Then you can use an order's unique `token` to process and accept payments via the Revolut Checkout Widget. :::warning The [Create an order endpoint](/docs/api/merchant#create-order) was updated to a new version and now returns `token` as the public identifier for the order. Previous integrations might still use the deprecated endpoint returning `public_id`. We strongly advise upgrading to the new [Create an order endpoint](/docs/api/merchant#create-order). ::: - name: Customers description: |- The Customers resource in the Merchant API is a pivotal tool for tracking and managing customer-related transactions within your e-commerce or retail platform. This resource provides a structured approach to customer management, enabling you to maintain a consistent record of customer transactions. A `Customer` object can be created using the [Create a customer](/docs/api/merchant#create-customer) endpoint and you can then retrieve, update and delete a customer using its `id`. `Customer` objects enable you to track multiple transactions in your system associated with the same customer in the Merchant API. You can save and store payment methods of a customer in the `payment_method` object, for more information, see: [Charge a customer's saved payment method](/docs/guides/merchant/optimise-checkout/save-payment-methods/charge-saved-payment-method). A merchant can store the details of the payment securely and group transactions from the same payment method in their system. A payment method is unique for each customer. For example, if the same card is used for a transaction by two different customers, two payment method objects are created linked to each customer. Similar principle applies when saving payment methods via Revolut Pay for merchant initiated transaction (MIT - useful for recurring payments). If a customer saves their details through Revolut Pay for MIT in separate sessions, each session will create a new payment method object linked to the customer. :::note You cannot create a payment method explicitly because they are generated as part of a payment. You can only retrieve, update or delete a payment method, or you can retrieve all payment methods of a customer. ::: - name: Payments description: >- Payment operations enable you to initiate payments, or track payment status transitions. You can use the ID of the payment to retrieve information about a specific payment. For more information about the payment lifecycle, see: [Order and payment lifecycle](/docs/guides/merchant/reference/order-lifecycle). - name: Report runs description: |- In addition to the CSV statements you can export via the [Revolut Business Dashboard](https://business.revolut.com/merchant/statement), you can generate custom CSV reports using the **Report runs** operations. Unlike the default statements, creating custom reports offers you more flexibility in determining what data you wish to incorporate. This allows you to have more control over your analytics. For more information about how to generate custom CSV reports, see: [Create CSV reports of transactions](/docs/guides/merchant/monitor-and-observe/reports-reconciliation). - name: Webhooks description: |- A `webhook` (also called a web callback) allows your system to receive an event from a different app immediately after it happens. For example, you can subscribe to a webhook when an order changes from `pending` to `completed` status. When the payment is cleared and the order is completed, Revolut servers send a notification to the URL of your choice. This is a more efficient way to know when an order is paid as opposed to trying to get the status of the order every few seconds. Many events that happen to a Revolut Merchant account are synchronous, which means they arrive instantly and have immediate results. For example, a successful request to create a customer immediately returns a `Customer` object. Such requests don't require webhooks. The Revolut Merchant API supports webhooks for events including `ORDER_COMPLETED` and `ORDER_AUTHORISED`. :::note Because we cannot guarantee the delivery order of the status (`events`), you might receive the status not in the expected order. Make sure that your implementation does not rely on the order that the events are being received in. ::: For example, for a completed order, you should receive the `ORDER_AUTHORISED` status first and then `ORDER_COMPLETED`. However, if the `ORDER_AUTHORISED` status isn't sent successfully at first, it's moved to the queue to be resent in the next few minutes. Before then, if the `ORDER_COMPLETED` status is sent successfully, you get `ORDER_COMPLETED` first and then `ORDER_AUTHORISED`. Check out our tutorial for [Using webhooks to keep track of the payment lifecycle](/docs/guides/merchant/monitor-and-observe/webhooks/using-webhooks). :::info For more information about the order and payment lifecycle, see: [Order and payment lifecycle](/docs/guides/merchant/reference/order-lifecycle). ::: - name: Locations description: >- The Locations API is designed to help merchants manage multiple points of sale, including both **online storefronts** and **physical stores**. Registering locations lets you differentiate and group your orders from different stores. You can also introduce custom business logic for each location, such as different inventory management, pricing, or shipping rules. To start using locations, follow the relevant use case for your business: ### Online locations 1. Register an online location using the [Create a location](/docs/api/merchant#create-location) endpoint, setting the `type` to `online`. 1. Configure your custom processes on your backend for each registered location (e.g., grouping orders, custom pricing, etc.). 1. Send the `location_id` parameter in the request body during [order creation](/docs/api/merchant#create-order) to assign the order to a specific location. ### Physical locations 1. Register a physical location using the [Create a location](/docs/api/merchant#create-location) endpoint, setting the `type` to `physical`. 1. In case of Revolut POS, our system handles order creation including `location_id` to associate the order with your location. ## Fast checkout for multiple storefronts Locations are particularly useful for tailoring the user experience on each of your online storefronts, especially when using features like [**Fast checkout**](/docs/guides/merchant/optimise-checkout/fast-checkout). For example, if you operate two online stores with different shipping rules, you can register two separate `online` locations. By then using the `location_id` to [register a distinct address validation endpoint](/docs/api/merchant#register-address-validation-endpoint) for each one, your backend can apply the correct shipping logic and pricing for the specific storefront a customer is buying from. - name: 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/1.0/orders: parameters: - $ref: "#/components/parameters/Authorization" post: summary: Create an order (Deprecated) operationId: createOrderDeprecated description: Create an `Order` object. deprecated: true requestBody: content: application/json: schema: $ref: "#/components/schemas/Order-Creation" examples: example_min_order: summary: Example order with minimal required parameters value: amount: 500 currency: GBP email: example.customer@email.com example_order_with_additional_params: summary: Example order with additional parameters value: amount: 500 currency: GBP capture_mode: MANUAL email: example.customer@email.com 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_uri: https://example.com/orders/12345 description: "" responses: "201": description: Order created content: application/json: schema: $ref: "#/components/schemas/Order" examples: created_order_min_params: summary: Order created with minimal required parameters value: id: 64a3f721-a5c8-aeee-bfb5-d5a984d32e9c public_id: 54933ff3-9fe5-49cd-8760-7d0e8c3ec198 type: PAYMENT state: PENDING created_at: 2023-07-04T10:40:33.069624Z updated_at: 2023-07-04T10:40:33.069624Z capture_mode: AUTOMATIC customer_id: 51918dc4-c02c-49e4-9b8b-3f08c8b01248 email: example.customer@email.com order_amount: value: 500 currency: GBP order_outstanding_amount: value: 500 currency: GBP metadata: {} checkout_url: https://business.revolut.com/payment-link/h2B9Dow-wZhUkz_zn-VJzQ created_order_additional_params: summary: Order created with additional parameters value: id: 64a3f606-3fb8-a2ab-970e-4cafdb62e04c public_id: c8c6b05a-6a4f-463e-a2a7-44e1a0c77e18 type: PAYMENT state: PENDING created_at: 2023-07-04T10:35:50.542458Z updated_at: 2023-07-04T10:35:50.542458Z description: Example product capture_mode: MANUAL customer_id: 51918dc4-c02c-49e4-9b8b-3f08c8b01248 email: example.customer@email.com order_amount: value: 500 currency: GBP order_outstanding_amount: value: 500 currency: GBP shipping_address: street_line_1: 7 Westferry Circus city: London country_code: GB postcode: E14 4HD metadata: product_type: Example checkout_url: https://business.revolut.com/payment-link/oqdE4aDHfhjIxrBaak9GPg merchant_order_uri: https://example.com/orders/12345 "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/Error" examples: example-1: value: errorId: 94b27660-fdda-49ec-8b85-cd46a068ade0 timestamp: 1601296792533 headers: {} "401": description: Unauthorized "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/Error" security: - Api-Key: [] tags: - Orders get: summary: Retrieve an order list (Deprecated) operationId: retrieveOrderListDeprecated description: >- Retrieve all the orders that you've created. You can also use the query parameters for: | Filtering | Pagination | | --------- | ---------- | | Filter the orders that you want to retrieve, for example, only retrieve the orders that have a specific email.

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

Parameters used for pagination:
| The response contains an array of simplified `Order` objects. To get the full details of an `Order` object, use the [Retrieve an order](/docs/api/merchant#retrieve-order) endpoint. deprecated: true parameters: - schema: type: integer default: 100 minimum: 1 maximum: 1000 in: query name: limit description: The maximum number of orders returned per page. Used for **pagination**. - schema: type: string format: date-time in: query name: created_before description: >- Retrieve orders with a `created_date` < `created_before`. Used for **pagination**. Use the `created_date` of the last order returned in the previous response to get to the next page. The default value is the current date and time you are calling the endpoint. - schema: type: string format: date-time in: query name: from_created_date description: >- Retrieve all orders with a `created_date` ≥ `from_created_date`. Used for **filtering**. Use the [ISO date format](https://en.wikipedia.org/wiki/ISO_8601): `yyyy-MM-ddTHH:mm:ss[.SSSSSS]Z`. For example, `2021-02-10T16:59:50.886826Z`. - schema: type: string format: date-time in: query name: to_created_date description: >- Retrieve all orders with a `created_date` ≤ `to_created_date`. Used for **filtering**. Use the [ISO date format](https://en.wikipedia.org/wiki/ISO_8601): `yyyy-MM-ddTHH:mm:ss[.SSSSSS]Z`. For example, `2021-02-10T16:59:50.886826Z`. - schema: type: string format: uuid in: query name: customer_id description: Retrieve all orders that have this `customer_id` associated to them. Used for **filtering**. - schema: type: string format: email in: query name: email description: >- Retrieve all orders that have this `email` associated to them. Used for **filtering**. This parameter is case sensitive. - schema: type: string in: query name: merchant_order_ext_ref description: >- Merchant order ID for external reference. Use this field to filter and retrieve all the orders that have this ID. Used for **filtering**. This parameter is case sensitive. - schema: type: array items: type: string enum: - PENDING - PROCESSING - AUTHORISED - COMPLETED - CANCELLED - FAILED style: form explode: true in: query name: state description: |- Retrieve all orders with specific states. You can pass several states. Used for **filtering**. If multiple states are selected, for example `AUTHORISED` and `COMPLETED`, orders with either of the selected values are returned. See this example of such a request URL: ```curl https://merchant.revolut.com/api/1.0/orders?state=AUTHORISED&state=COMPLETED ``` The parameter is case sensitive. responses: "200": description: OK content: application/json: schema: type: array items: $ref: "#/components/schemas/Simplified-Order" examples: list_of_orders: summary: List of orders value: - id: f0d685f4-07ab-4eff-ba80-5811303c607d type: PAYMENT state: PENDING created_at: 2021-02-10T18:17:37.959383Z updated_at: 2021-02-10T18:17:37.959383Z order_amount: value: 35000 currency: GBP order_outstanding_amount: value: 35000 currency: GBP - id: feca684a-b9ea-4033-9bc4-b9e6ac12ada6 type: PAYMENT state: COMPLETED created_at: 2021-02-10T16:59:23.642673Z updated_at: 2021-02-10T16:59:50.886826Z completed_at: 2021-02-10T16:59:50.886826Z settlement_currency: USD email: sally.gibson@lloydsbank.co.uk order_amount: value: 1000 currency: GBP order_outstanding_amount: value: 0 currency: GBP - id: f3c5e3f1-f73a-4853-a9e3-b0261301c66a type: PAYMENT state: COMPLETED created_at: 2021-02-10T16:58:47.507560Z updated_at: 2021-02-10T16:59:52.847017Z completed_at: 2021-02-10T16:59:52.847017Z description: URBAN 'Panther' Watch by José Almeida capture_mode: AUTOMATIC merchant_order_ext_ref: testorder123 customer_id: 31345442-3d03-4c4b-8354-3bdaf0ca9600 email: someothermail@gmail.com order_amount: value: 777 currency: GBP order_outstanding_amount: value: 0 currency: GBP "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/Error" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/Error" security: - Api-Key: [] tags: - Orders /api/1.0/orders/{order_id}: parameters: - $ref: "#/components/parameters/Authorization" - $ref: "#/components/parameters/Order-Id" get: summary: Retrieve an order (Deprecated) operationId: retrieveOrderDeprecated description: Retrieve the details of an order that has been created. Provide the unique order ID, and the corresponding order information is returned. deprecated: true responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/Order" examples: retrieved_order: summary: Retrieved order value: id: 7c97ce7e-a7e4-4ff9-b3ca-9f988b0ba5e0 public_id: fecaafa0-c230-44e9-a24e-7005e82e03f8 type: PAYMENT state: COMPLETED created_at: 2021-01-14T18:37:06.055371Z updated_at: 2021-01-14T18:38:04.115204Z completed_at: 2021-01-14T18:38:39.476986Z description: Testing Orders capture_mode: MANUAL settlement_currency: EUR merchant_order_ext_ref: testorder123 customer_id: 56db1367-2494-4a35-8254-c23929f8e5e1 email: test@revolut.com phone: "+447123456789" order_amount: value: 50 currency: GBP order_outstanding_amount: value: 0 currency: GBP refunded_amount: value: 30 currency: GBP shipping_address: street_line_1: 7 Westferry Circus street_line_2: Revolut city: London country_code: GB postcode: E14 4HD payments: - id: 7c97ce7e-a7e4-4ff9-b3ca-absgdjwuio12 state: COMPLETED created_at: 2021-01-14T18:37:48.069092Z updated_at: 2021-01-14T18:38:39.476986Z token: 3cba558e-f465-4688-b5c4-94673508ece5 amount: value: 50 currency: GBP settled_amount: value: 67 currency: EUR payment_method: type: CARD card: card_brand: VISA funding: CREDIT card_country: GB card_bin: "459664" card_last_four: "6376" card_expiry: 03/2025 cardholder_name: John Doe checks: three_ds: state: VERIFIED version: 2 cvv_verification: MATCH address: NOT_MATCH postcode: MATCH cardholder: N_A billing_address: street_line_1: 7 Westferry Circus street_line_2: Revolut city: London country_code: GB postcode: E14 4HD risk_level: LOW fees: - type: ACQUIRING amount: value: 5 currency: GBP related: - id: 8af43efa-0d0c-4267-9abc-72679bc56859 type: REFUND state: COMPLETED amount: value: 30 currency: GBP "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/Error" examples: example-1: value: errorId: 94b27660-fdda-49ec-8b85-cd46a068ade0 timestamp: 1601296792533 "401": description: Unauthorized "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/Error" security: - Api-Key: [] tags: - Orders patch: summary: Update an order (Deprecated) operationId: updateOrderDeprecated description: >- Update the details of an order. You can update the details of an order based on the state of the order: - `PENDING` state: You can use all the following parameters to update the order. - `AUTHORISED` or `COMPLETED` state: You can update only the `merchant_order_ext_ref`, `description`, `metadata` and `shipping_address` parameters. - `PROCESSING` state: You cannot update the order. deprecated: true requestBody: content: application/json: schema: $ref: "#/components/schemas/Order-Update" examples: example_order: summary: Example order value: amount: 100 currency: EUR merchant_order_ext_ref: "#2234" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/Order" examples: updated_order: summary: Updated order value: id: 5fd927ba-6f73-4a01-8e2b-fcd37fb629c5 public_id: 94a11217-6319-4d34-8dae-a2b80b953adb type: PAYMENT state: PENDING created_at: 2020-10-15T07:46:40.648108Z updated_at: 2020-10-15T07:46:40.648108Z order_amount: value: 100 currency: EUR merchant_order_ext_ref: "#2234" email: johndoe001@gmail.com checkout_url: https://business.revolut.com/payment-link/uLHGQVGNx_ZRDV14z5VFIA "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/Error" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/Error" security: - Api-Key: [] tags: - Orders /api/1.0/orders/{order_id}/capture: parameters: - $ref: "#/components/parameters/Authorization" - $ref: "#/components/parameters/Order-Id" post: summary: Capture an order (Deprecated) operationId: captureOrderDeprecated description: >- Capture the funds of an existing, uncaptured order. When the payment for an order is authorised, the order is captured and sent to the processing stage. When you create an order, you can choose one of the following capture modes: - `AUTOMATIC`: The order is captured automatically after payment authorisation, so you don't need to take any action then. - `MANUAL`: The order is not captured automatically and stays in `AUTHORISED` state. You must manually capture the order later using one of the following methods: - Web UI: Complete the following steps: 1. Log in to your Revolut Business portal. 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**. - Endpoint: Use the `/capture` endpoint. Optionally, you can send a fraction of the full amount in the capture request to do a partial capture. You can only capture an order once. The amount that isn't captured will be voided. :::note Orders stay uncaptured for 7 days. After this period, the funds are returned to the customer's original payment method. ::: requestBody: content: application/json: schema: type: object properties: amount: type: integer description: >- Specify an amount to capture. This amount must be less than the amount that was originally captured. The remaining amount in the order will be voided and can't be captured. examples: default: value: amount: 100 responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/Order" examples: captured_order: summary: Captured order value: id: 7c97ce7e-a7e4-4ff9-b3ca-9f988b0ba5e0 public_id: fecaafa0-c230-44e9-a24e-7005e82e03f8 type: PAYMENT state: COMPLETED created_at: 2021-01-14T18:37:06.055371Z updated_at: 2021-01-14T18:38:04.115204Z completed_at: 2021-01-14T18:38:39.476986Z description: Testing Orders capture_mode: MANUAL settlement_currency: EUR merchant_order_ext_ref: testorder123 customer_id: 56db1367-2494-4a35-8254-c23929f8e5e1 email: test@revolut.com phone: "+447123456789" order_amount: value: 50 currency: GBP order_outstanding_amount: value: 0 currency: GBP shipping_address: street_line_1: 7 Westferry Circus street_line_2: Revolut city: London country_code: GB postcode: E14 4HD payments: - id: 7c97ce7e-a7e4-4ff9-b3ca-absgdjwuio12 state: COMPLETED created_at: 2021-01-14T18:37:48.069092Z updated_at: 2021-01-14T18:38:39.476986Z amount: value: 50 currency: GBP settled_amount: value: 67 currency: EUR payment_method: type: CARD card: card_brand: VISA funding: CREDIT card_country: GB card_bin: "459664" card_last_four: "6376" card_expiry: 03/2025 cardholder_name: John Doe checks: cvv_verification: MATCH address: NOT_MATCH postcode: MATCH cardholder: N_A billing_address: street_line_1: 7 Westferry Circus street_line_2: Revolut city: London country_code: GB postcode: E14 4HD risk_level: LOW fees: - type: ACQUIRING amount: value: 5 currency: GBP "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/Error" examples: example-1: value: errorId: 94b27660-fdda-49ec-8b85-cd46a068ade0 timestamp: 1601296792533 "401": description: Unauthorized "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/Error" security: - Api-Key: [] tags: - Orders /api/1.0/orders/{order_id}/cancel: parameters: - $ref: "#/components/parameters/Authorization" - $ref: "#/components/parameters/Order-Id" post: summary: Cancel an order (Deprecated) operationId: cancelOrderDeprecated description: >- Cancel an existing uncaptured order. You can only cancel an order that is in one of the following states: - In the `AUTHORISED` state, which means that the `capture_mode` of an order is set to `MANUAL` and the customer has made a successful payment. - In the `PENDING` state, which means that it doesn't have any successful payment associated with it. :::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" examples: cancelled_order: summary: Cancelled order value: id: 7c97ce7e-a7e4-4ff9-b3ca-9f988b0ba5e0 public_id: fecaafa0-c230-44e9-a24e-7005e82e03f8 type: PAYMENT state: CANCELLED created_at: 2021-01-14T18:37:06.055371Z updated_at: 2021-01-14T18:38:04.115204Z completed_at: 2021-01-14T18:38:39.476986Z description: Testing Orders capture_mode: MANUAL settlement_currency: EUR merchant_order_ext_ref: testorder123 customer_id: 56db1367-2494-4a35-8254-c23929f8e5e1 email: test@revolut.com phone: "+447123456789" order_amount: value: 50 currency: GBP order_outstanding_amount: value: 0 currency: GBP shipping_address: street_line_1: 7 Westferry Circus street_line_2: Revolut city: London country_code: GB postcode: E14 4HD payments: - id: 7c97ce7e-a7e4-4ff9-b3ca-absgdjwuio12 state: CANCELLED created_at: 2021-01-14T18:37:48.069092Z updated_at: 2021-01-14T18:38:39.476986Z amount: value: 50 currency: GBP payment_method: type: CARD card: card_brand: VISA funding: CREDIT card_country: GB card_bin: "459664" card_last_four: "6376" card_expiry: 03/2025 cardholder_name: John Doe checks: cvv_verification: MATCH address: NOT_MATCH postcode: MATCH cardholder: N_A billing_address: street_line_1: 7 Westferry Circus street_line_2: Revolut city: London country_code: GB postcode: E14 4HD risk_level: LOW "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/Error" examples: example-1: value: errorId: 94b27660-fdda-49ec-8b85-cd46a068ade0 timestamp: 1601296792533 "401": description: Unauthorized "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/Error" security: - Api-Key: [] tags: - Orders /api/1.0/orders/{order_id}/refund: parameters: - $ref: "#/components/parameters/Authorization" - $ref: "#/components/parameters/Idempotency-Key" - $ref: "#/components/parameters/Order-Id" post: summary: Refund an order (Deprecated) operationId: refundOrderDeprecated description: >- Issue a refund for a completed order. This operation allows for either a full or partial refund, which will be processed back to the customer's original payment method. ## Operation details - The refund operation generates a new order with `type: REFUND`. This new order represents a full or partial refund of the original amount paid. - Refunds can only be initiated for orders that are in the `COMPLETED` state. Orders in any other state are not eligible for refunds to ensure transaction integrity and to prevent errors. :::note - Ensure that the order to be refunded is confirmed as `COMPLETED` before attempting a refund operation. - Consider using the `Idempotency-Key` header to make the refund operation idempotent, preventing duplicate refund processing in cases of multiple submissions. ::: requestBody: content: application/json: schema: $ref: "#/components/schemas/Order-Refund" examples: default: value: amount: 40 description: Refund for damaged goods responses: "201": description: OK content: application/json: schema: $ref: "#/components/schemas/Order" examples: refund_example: summary: Refund example value: id: 6a1353a8-3054-40ee-ab39-97a11e4c5f2a type: REFUND state: COMPLETED created_at: 2020-05-12T14:23:11.046526Z updated_at: 2020-05-12T14:23:11.046526Z completed_at: 2020-05-12T14:23:11.046526Z order_amount: value: 40 currency: GBP email: customer@gmail.com full_name: Example Customer related: - id: 4695b666-45d0-4f15-ad10-e66a84c914bf type: PAYMENT amount: value: 100 currency: GBP "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/Error" "401": description: Unauthorized "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/Error" "422": description: Insufficient funds content: application/json: schema: type: object properties: errorId: type: string description: The ID of the error. You can share this ID with Revolut support for troubleshooting. timestamp: type: integer description: The date and time the error happened. code: type: integer examples: example-1: value: errorId: 94b27660-fdda-49ec-8b85-cd46a068ade0 timestamp: 1601296792533 code: 1026 security: - Api-Key: [] tags: - Orders /api/orders/{order_id}/payments: parameters: - $ref: "#/components/parameters/Authorization" - $ref: "#/components/parameters/Order-Id" post: summary: Pay for an order operationId: payOrder description: |- Initiate a payment to pay full amount for an order using a customer's saved payment method. :::note The `/orders/{order_id}/confirm` endpoint has been deprecated. It will be only supported for already existing implementations. ::: :::warning This endpoint is part of a new API, pay attention to the different endpoint URL. ::: For more information about how to save and charge payment methods, see: [Charge a customer's saved payment method](/docs/guides/merchant/optimise-checkout/save-payment-methods/charge-saved-payment-method). The following table shows who can initiate payments on saved payment methods (`initiator` parameter), depending on if the payment method was saved for the customer or the merchant (`savedPaymentMethodFor` parameter): | | `savePaymentMethodFor: customer` | `savePaymentMethodFor: merchant` | | ------------------------- | -------------------------------- | -------------------------------- | | **`initiator: customer`** | Allowed | Allowed | | **`initiator: merchant`** | Not allowed | Allowed | :::note Using this endpoint, only merchant initiated payments are supported with Revolut Pay. ::: For more information about customers' payment methods, see the [Retrieve payment method list of a customer](/docs/api/merchant#retrieve-payment-method-list) operation. requestBody: content: application/json: schema: $ref: "#/components/schemas/Saved-Payment-Method" examples: saved_card_customer: summary: Saved card (customer initiator) value: saved_payment_method: type: card id: 2b83c23a-650e-40c3-8989-00ee24478738 initiator: customer environment: type: browser time_zone_utc_offset: 180 color_depth: 48 screen_width: 1920 screen_height: 1080 java_enabled: true challenge_window_width: 640 browser_url: https://business.revolut.com saved_card_merchant: summary: Saved card (merchant initiator) value: saved_payment_method: type: card id: 2b83c23a-650e-40c3-8989-00ee24478738 initiator: merchant revolut_pay: summary: Saved Revolut Pay (merchant initiator) value: saved_payment_method: type: revolut_pay id: 2b83c23a-650e-40c3-8989-00ee24478738 initiator: merchant responses: "200": description: Payment initiated content: application/json: schema: $ref: "#/components/schemas/Payment-Retrieval" examples: successful_payment_card: summary: Payment authorised (card) value: id: 63c55e04-4208-a43d-9c96-eaee848ffbaf order_id: 63c55df6-1461-a886-b90f-f49d3c370253 payment_method: type: card id: 2b83c23a-650e-40c3-8989-00ee24478738 brand: mastercard_credit last_four: "1234" state: authorisation_passed successful_payment_revolut_pay_account: summary: Payment authorised (Revolut Pay - Revolut account) value: id: 63c55e04-4208-a43d-9c96-eaee848ffbaf order_id: 63c55df6-1461-a886-b90f-f49d3c370253 payment_method: type: revolut_pay subtype: revolut_account id: 2b83c23a-650e-40c3-8989-00ee24478738 state: authorisation_passed successful_payment_revolut_pay_card: summary: Payment authorised (Revolut Pay - card) value: id: 63c55e04-4208-a43d-9c96-eaee848ffbaf order_id: 63c55df6-1461-a886-b90f-f49d3c370253 payment_method: type: revolut_pay subtype: card id: 2b83c23a-650e-40c3-8989-00ee24478738 brand: visa last_four: "1234" state: authorisation_passed three_ds: summary: Saved card payment (3DS challenge) value: id: 5e96b328-4054-41ed-b089-595ccc4d0870 order_id: a16718e0-077a-4942-89bc-23ac17a2e14c payment_method: type: card id: 2b83c23a-650e-40c3-8989-00ee24478738 brand: mastercard_credit last_four: "1234" state: authentication_challenge authentication_challenge: type: three_ds acs_url: https://example.com three_ds_fingerprint: summary: Saved card payment (3DS fingerprint challenge) value: id: 5e96b328-4054-41ed-b089-595ccc4d0870 order_id: a16718e0-077a-4942-89bc-23ac17a2e14c payment_method: type: card id: 2b83c23a-650e-40c3-8989-00ee24478738 brand: mastercard_credit last_four: "1234" state: authentication_challenge authentication_challenge: type: three_ds_fingerprint fingerprint_url: https://example.com fingerprint_data: string "400": description: Bad Request content: application/json: schema: type: object properties: errorId: type: string description: |- The ID of the error. You can share this ID with Revolut support for troubleshooting. timestamp: type: integer description: The date and time the error happened. examples: example-1: value: errorId: 94b27660-fdda-49ec-8b85-cd46a068ade0 timestamp: 1601296792533 "401": description: Unauthorized "404": description: Not Found content: application/json: schema: type: object properties: errorId: type: string description: |- The ID of the error. You can share this ID with Revolut support for troubleshooting. timestamp: type: integer description: The date and time the error happened. code: type: integer examples: example-1: value: errorId: 94b27660-fdda-49ec-8b85-cd46a068ade0 timestamp: 1601296792533 code: 1024 security: - Api-Key: [] tags: - Orders - Payments get: summary: Retrieve payment list of an order operationId: retrievePaymentList description: >- Retrieve a list of payments for a specific order, based on the order's ID. :::note This endpoint is part of a new API, pay attention to the different endpoint URL. ::: Use this endpoint to retrieve payment details for saved payment methods to make merchant and customer initiated transactions. For more information, see: - [Speed up customer checkout by using saved card details](/docs/guides/merchant/optimise-checkout/save-payment-methods/checkout-with-saved-card) - [Manage subscriptions](/docs/guides/merchant/optimise-checkout/save-payment-methods/subscription-management) responses: "200": description: List of payments content: application/json: schema: type: array items: $ref: "#/components/schemas/Payment-Retrieval" examples: payment_list: summary: List of payments (failed card attempt, SEPA Direct Debit retry) value: - id: 63dd0e4a-42c4-a1a6-ab2c-6ac9d255ca4b token: 294358bf-3818-49b2-aacc-7ca971f52695 order_id: 63dd0e3f-7b84-ab5c-927c-1a06f7c9583a state: declined amount: 100 currency: EUR payment_method: type: card card_brand: visa funding: credit card_last_four: "1234" - id: 649adc44-3e86-a832-879c-2f6d0255dd4c token: 8061e645-35e0-42bb-8318-603abaeab7b7 order_id: 63dd0e3f-7b84-ab5c-927c-1a06f7c9583a state: declined amount: 100 currency: EUR decline_reason: insufficient_funds payment_method: type: revolut_pay subtype: revolut_account - id: 663387f1-1c2e-a295-b143-9f1fb1eec175 token: 663387f1-c91e-a464-908a-1cc4548ebc6a order_id: 63dd0e3f-7b84-ab5c-927c-1a06f7c9583a state: pending amount: 100 currency: EUR payment_method: type: sepa_direct_debit debtor_iban_last_four: "1234" debtor_name: John Doe mandate_reference: A1B2C3D4E5F6A1B2C3D4E5F6A1B2C3D4 "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/Error-v2" examples: default: value: code: bad_request message: Could not parse JSON timestamp: 1720528890647 "401": description: Unauthenticated content: application/json: schema: $ref: "#/components/schemas/Error-v2" examples: default: value: code: unauthenticated message: Authentication failed timestamp: 1720528890647 "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/Error-v2" examples: - code: not_found message: Order with id b8883ab5-964a-4329-aa44-4d3c76cf3f54 was not found timestamp: 1720528890647 security: - Api-Key: [] tags: - Orders - Payments /api/1.0/customers: parameters: - $ref: "#/components/parameters/Authorization" post: summary: Create a customer (Deprecated) deprecated: true operationId: createCustomerDeprecated description: |- Create a `customer` that has the information in the body of the request. :::note If you wish to save a customer's payment details using any of the available payment methods on the Revolut Checkout Widget ([Revolut Pay](/docs/guides/merchant/accept-payments/online-payments/revolut-pay/introduction), [Card payments](/docs/guides/merchant/accept-payments/online-payments/card-payments/introduction)), you need to meet one of the following requirements: - Have a customer object with `email` and assign it to the order by providing `customer.id` - Create a new customer with, at least, `customer.email` during [order creation](/docs/api/merchant#create-order) For more information, see: [Charge a customer's saved payment method](/docs/guides/merchant/optimise-checkout/save-payment-methods/charge-saved-payment-method). ::: requestBody: content: application/json: schema: $ref: "#/components/schemas/Customer-Creation" examples: default: value: full_name: Example Customer business_name: Example Business email: example.customer@example.com phone: "+441234567890" date_of_birth: 1990-01-01 responses: "201": description: Created content: application/json: schema: $ref: "#/components/schemas/Customer" examples: created_customer: summary: Created customer value: id: 6c7c97a8-cfc1-4cf3-8b38-26a74fdf1fae full_name: Example Customer business_name: Example Business email: example.customer@example.com phone: "+441234567890" date_of_birth: 1990-01-01 created_at: 2020-06-24T12:03:39.979397Z updated_at: 2020-06-24T12:03:39.979397Z "400": description: Bad Request content: application/json: schema: description: "" type: object properties: errorId: type: string description: |- The ID of the error. You can share this ID with Revolut support for troubleshooting. timestamp: type: number description: The date and time the error happened. code: type: number description: "`1018` - The customer already exists." required: - errorId - timestamp examples: Error: value: errorId: 5226f800-e9be-4b74-ae61-6c7b71c913b5 timestamp: 1593439990599 code: 1018 "401": description: Unauthorized security: - Api-Key: [] tags: - Customers get: summary: Retrieve a customer list (Deprecated) deprecated: true operationId: retrieveAllCustomersDeprecated description: Get a list of all your `customers`. parameters: - schema: type: integer default: 100 minimum: 1 maximum: 100 in: query name: limit description: The maximum number of customers returned per page. Used for **pagination**. - schema: type: integer default: 0 minimum: 0 in: query name: page description: A zero-based page index for the paginated results, used in conjunction with `limit`. responses: "200": description: OK content: application/json: schema: type: array items: $ref: "#/components/schemas/Customer" examples: list_of_customers: summary: List of customers value: - id: 9dfb8491-bfb0-4420-ad63-0fa7bdd3dffb full_name: First Customer email: first.customer@example.com date_of_birth: 1990-01-01 created_at: 2020-06-24T12:12:56.596703Z updated_at: 2020-06-24T12:12:56.737082Z - id: 6c7c97a8-cfc1-4cf3-8b38-26a74fdf1fae full_name: Second Customer business_name: Second Business email: second.customer@example.com phone: "+441234567890" created_at: 2020-06-24T12:03:39.979397Z updated_at: 2020-06-25T10:03:39.134417Z - id: 014f0ad6-c45b-4d7d-83c6-80eea94fceac full_name: Third Customer email: third.customer@example.com phone: "+441234567890" created_at: 2020-06-23T14:13:08.262336Z updated_at: 2020-06-24T10:47:11.173027Z "401": description: Unauthorized security: - Api-Key: [] tags: - Customers /api/1.0/customers/{customer_id}: parameters: - $ref: "#/components/parameters/Authorization" - $ref: "#/components/parameters/Customer-Id" get: summary: Retrieve a customer (Deprecated) deprecated: true operationId: retrieveCustomerDeprecated description: Get the information about a specific `customer`, based on its ID. responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/Customer-With-Payment-Method" examples: retrieved_customer: summary: Retrieved customer value: id: 6c7c97a8-cfc1-4cf3-8b38-26a74fdf1fae full_name: Example Customer business_name: Example Business email: example.customer@example.com phone: "+441234567890" date_of_birth: 1990-01-01 created_at: 2020-06-24T12:03:39.979397Z updated_at: 2020-06-25T10:03:39.134417Z payment_methods: - id: 648334a8-9546-a983-a81a-efc6d5bdd0be type: REVOLUT_PAY saved_for: MERCHANT method_details: created_at: 2023-06-09T14:18:16.577888Z - id: edef3ba4-60a0-4df3-8f12-e5fc858c2420 type: CARD saved_for: CUSTOMER method_details: bin: "459765" last4: "6578" expiry_month: 2 expiry_year: 2025 cardholder_name: Example Customer brand: VISA funding: DEBIT issuer: EXAMPLE ISSUER issuer_country: GB billing_address: street_line_1: 7, Westferry Circus street_line_2: Columbus Building postcode: E144HD city: London region: Greater London country_code: GB created_at: 2023-03-24T14:15:22Z "401": description: Unauthorized "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/Error" security: - Api-Key: [] tags: - Customers patch: summary: Update a customer (Deprecated) deprecated: true operationId: updateCustomerDeprecated description: Update the attributes of a specific `customer`. requestBody: content: application/json: schema: $ref: "#/components/schemas/Customer-Update" examples: default: value: email: example.business@example.com responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/Customer" examples: updated_customer: summary: Updated customer value: id: 6c7c97a8-cfc1-4cf3-8b38-26a74fdf1fae full_name: Example Customer business_name: Example Business email: example.business@example.com phone: "+441234567890" date_of_birth: 1990-01-01 created_at: 2020-06-24T12:03:39.979397Z updated_at: 2020-06-25T10:03:39.134417Z "400": description: Bad Request content: application/json: schema: type: object properties: errorId: type: string description: |- The ID of the error. You can share this ID with Revolut support for troubleshooting. timestamp: type: integer description: The date and time the error happened. examples: example-1: value: errorId: 94b27660-fdda-49ec-8b85-cd46a068ade0 timestamp: 1601296792533 "401": description: Unauthorized "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/Error" security: - Api-Key: [] tags: - Customers delete: summary: Delete a customer (Deprecated) deprecated: true operationId: deleteCustomerDeprecated description: Delete the profile of a specific `customer`. responses: "204": description: No Content "401": description: Unauthorized "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/Error" security: - Api-Key: [] tags: - Customers /api/1.0/customers/{customer_id}/payment-methods: parameters: - $ref: "#/components/parameters/Authorization" - $ref: "#/components/parameters/Customer-Id" get: summary: Retrieve all payment methods of a customer (Deprecated) deprecated: true operationId: retrieveAllPaymentMethodsDeprecated description: >- Retrieve all the payment methods for a specific customer. This can be useful in the following example cases: - To show what information is stored for the customer. - To try a different payment method if the first payment method fails when a recurring transaction occurs. parameters: - name: only_merchant in: query schema: type: boolean default: false description: >- If `only_merchant` is set to `true`, you retrieve the payment methods that were saved for the merchant (`saved_for: "MERCHANT"`). To use this parameter insert it at the end of the request URL. See this example for a request URL in Production environment: ```curl https://merchant.revolut.com/api/1.0/customers/{customer_id}/payment-methods?only_merchant=true ``` required: false responses: "200": description: OK content: application/json: schema: type: array items: $ref: "#/components/schemas/Customer-Payment-Method" examples: list_of_payment_methods: summary: List of payment methods value: - id: 648334a8-9546-a983-a81a-efc6d5bdd0be type: REVOLUT_PAY saved_for: MERCHANT method_details: created_at: 2023-06-09T14:18:16.577888Z - id: edef3ba4-60a0-4df3-8f12-e5fc858c2420 type: CARD saved_for: CUSTOMER method_details: bin: "459678" last4: "6896" expiry_month: 3 expiry_year: 2025 cardholder_name: Example Customer brand: VISA funding: DEBIT issuer: EXAMPLE ISSUER issuer_country: GB billing_address: street_line_1: "7" street_line_2: Westferry Circus postcode: E144HD city: London region: Greater London country_code: GB created_at: 2023-03-24T14:15:22Z - id: a04406c4-05be-498b-8207-cc1e02a9b3ca type: CARD saved_for: MERCHANT method_details: bin: "459885" last4: "7653" expiry_month: 12 expiry_year: 2021 cardholder_name: Example Holder brand: MASTERCARD funding: CREDIT issuer: EXAMPLE ISSUER issuer_country: GB billing_address: street_line_1: Revolut street_line_2: 1 Canada Square postcode: EC2V 6DN city: London region: Greater London country_code: GB created_at: 2023-03-24T14:15:22Z list_of_only_merchant_payment_methods: summary: List of payment methods (only_merchant=true) value: - id: 624baa72-0a30-4ee3-9870-d7172912704c type: CARD saved_for: MERCHANT method_details: bin: "492942" last4: "5709" expiry_month: 12 expiry_year: 2025 cardholder_name: Example Customer billing_address: street_line_1: "7" street_line_2: Westferry Circus postcode: E144HD city: London region: Greater London country_code: GB created_at: 2023-03-24T14:15:22Z - id: b92b7413-8764-4f8e-855d-d9b6986af2d9 type: CARD saved_for: MERCHANT method_details: bin: "528143" last4: "7653" expiry_month: 12 expiry_year: 2025 cardholder_name: Example Holder billing_address: street_line_1: Revolut street_line_2: 1 Canada Square postcode: EC2V 6DN city: London region: Greater London country_code: GB created_at: 2023-03-24T14:15:22Z "401": description: Unauthorized "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/Error" security: - Api-Key: [] tags: - Customers /api/1.0/customers/{customer_id}/payment-methods/{payment_method_id}: parameters: - $ref: "#/components/parameters/Authorization" - $ref: "#/components/parameters/Customer-Id" - $ref: "#/components/parameters/Payment-Method-Id" get: summary: Retrieve a customer's payment method (Deprecated) deprecated: true operationId: retrievePaymentMethodDeprecated description: Retrieve the information of a specific payment method that is saved. responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/Customer-Payment-Method" examples: retrieved_payment_method: summary: Retrieved payment method value: id: edef3ba4-60a0-4df3-8f12-e5fc858c2420 type: CARD saved_for: CUSTOMER method_details: bin: "459678" last4: "6896" expiry_month: 3 expiry_year: 2025 cardholder_name: Example Customer brand: VISA funding: DEBIT issuer: EXAMPLE ISSUER issuer_country: GB billing_address: street_line_1: "7" street_line_2: Westferry Circus postcode: E144HD city: London region: Greater London country_code: GB created_at: 2023-03-24T14:15:22Z "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/Error" security: - Api-Key: [] tags: - Customers patch: summary: Update a customer's payment method (Deprecated) deprecated: true operationId: updatePaymentMethodDeprecated description: >- When you use this request to update a customer's payment method, the payment method can't be used for merchant initiated transactions (MIT) any more. This payment method can be used only when the customer is on the checkout page. For more information about the limitations introduced by this parameter, see: - [Pay for an order](/docs/api/merchant#pay-order) - [Charge a customer's saved payment method](/docs/guides/merchant/optimise-checkout/save-payment-methods/charge-saved-payment-method) requestBody: content: application/json: schema: type: object properties: saved_for: type: string description: >- Update the value of `saved_for` from `MERCHANT` to `CUSTOMER`. This indicates that the updated payment method can't be used for merchant initiated transactions (MIT) any more. enum: - CUSTOMER required: - saved_for examples: example_request: summary: Example request value: saved_for: CUSTOMER application/xml: schema: type: object properties: {} responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/Customer-Payment-Method" examples: updated_payment_method: summary: Updated payment method value: id: edef3ba4-60a0-4df3-8f12-e5fc858c2420 type: CARD saved_for: CUSTOMER method_details: bin: "459678" last4: "6896" expiry_month: 3 expiry_year: 2025 cardholder_name: John Doe brand: VISA funding: DEBIT issuer: EXAMPLE ISSUER issuer_country: GB billing_address: street_line_1: "7" street_line_2: Westferry Circus postcode: E144HD city: London region: Greater London country_code: GB created_at: 2023-03-24T14:15:22Z "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/Error" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/Error" security: - Api-Key: [] tags: - Customers delete: summary: Delete a customer's payment method (Deprecated) deprecated: true operationId: deletePaymentMethodDeprecated description: >- Delete a specific payment method. The payment method is completely deleted from the customer payment methods. To reuse the payment method that is deleted, direct your customer to the checkout page and save the card details again. responses: "204": description: No Content "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/Error" security: - Api-Key: [] tags: - Customers /api/payments/{payment_id}: parameters: - $ref: "#/components/parameters/Authorization" - $ref: "#/components/parameters/Payment-Id" get: summary: Retrieve payment details operationId: retrievePaymentDetails description: >- Retrieve information about a specific payment, based on the payment's ID. Use this endpoint to track a payment's lifecycle, for example: - When you develop a [1-click checkout process](/docs/guides/merchant/optimise-checkout/save-payment-methods/checkout-with-saved-card) - When you build a [subscription management system](/docs/guides/merchant/optimise-checkout/save-payment-methods/subscription-management) responses: "200": description: Payment details content: application/json: schema: $ref: "#/components/schemas/Payment-Retrieval" examples: revolut_pay_saved: summary: Payment completed via Revolut Pay (saved details) value: id: 64905d4b-a205-aac3-a5ef-dab978b1b7ee order_id: 64905d0f-3f95-a2ac-91ea-57c77f9dbe69 state: completed payment_method: type: revolut_pay subtype: revolut_account id: 648334a8-9546-a983-a81a-efc6d5bdd0be revolut_pay_not_saved: summary: Payment completed via Revolut Pay (not saved details) value: id: 64905d4b-a205-aac3-a5ef-dab978b1b7ee order_id: 64905d0f-3f95-a2ac-91ea-57c77f9dbe69 state: completed payment_method: type: revolut_pay subtype: revolut_account card_payment_saved: summary: Payment completed via card (saved details) value: id: 63dd0e4a-42c4-a1a6-ab2c-6ac9d255ca4b order_id: 63dd0e3f-7b84-ab5c-927c-1a06f7c9583a state: completed payment_method: type: card brand: visa last_four: "1234" id: 64a28499-05c5-af30-bbf9-9c1b028e00b8 card_payment_not_saved: summary: Payment completed via card (not saved details) value: id: 63dd0e4a-42c4-a1a6-ab2c-6ac9d255ca4b order_id: 63dd0e3f-7b84-ab5c-927c-1a06f7c9583a state: completed payment_method: type: card brand: visa last_four: "1234" "400": description: Bad Request content: application/json: schema: type: object properties: errorId: type: string description: |- The ID of the error. You can share this ID with Revolut support for troubleshooting. timestamp: type: integer description: The date and time the error happened. examples: example-1: value: errorId: 94b27660-fdda-49ec-8b85-cd46a068ade0 timestamp: 1601296792533 "401": description: Unauthorized "404": description: Not Found content: application/json: schema: type: object properties: errorId: type: string description: |- The ID of the error. You can share this ID with Revolut support for troubleshooting. timestamp: type: integer description: The date and time the error happened. code: type: integer examples: example-1: value: errorId: 94b27660-fdda-49ec-8b85-cd46a068ade0 timestamp: 1601296792533 code: 1024 security: - Api-Key: [] tags: - Payments /api/report-runs: parameters: - $ref: "#/components/parameters/Authorization" post: summary: Create a new report run operationId: createReportRun description: >- Start generating a new report of the relevant transactions, and receive `report_run_id`. After generation is done, use the link in `file_url` to download the report. Use the [Retrieve report run details](/docs/api/merchant#retrieve-report-run-details) operation to check the status of the report run. Use the table below to choose the right report type for your use case: | Report type | What it covers | Required filter | | ----------- | -------------- | --------------- | | `custom_report` | Settled and processing transactions with configurable columns | `from`, `to` | | `settlement_report` | Predefined settled transaction view | `from`, `to` | | `payout_statement_report` | All transactions contributing to a specific payout | `filter.payout_id` | | `icpp_fee_breakdown_report` | IC++ fees per transaction for a specific IC++ charge | `filter.icpp_charge_id` | | `payments_report` | All payments including failed and declined ones | `from`, `to` | requestBody: content: application/json: schema: discriminator: propertyName: type mapping: settlement_report: "#/components/schemas/Report-Run-Settlement-Report" custom_report: "#/components/schemas/Report-Run-Custom-Report" payout_statement_report: "#/components/schemas/Report-Run-Payout-Report" icpp_fee_breakdown_report: "#/components/schemas/Report-Run-Icpp-Report" payments_report: "#/components/schemas/Report-Run-Payments-Report" oneOf: - $ref: "#/components/schemas/Report-Run-Settlement-Report" - $ref: "#/components/schemas/Report-Run-Custom-Report" - $ref: "#/components/schemas/Report-Run-Payout-Report" - $ref: "#/components/schemas/Report-Run-Icpp-Report" - $ref: "#/components/schemas/Report-Run-Payments-Report" examples: custom_report: summary: Custom report value: filter: from: 2020-01-01T00:00:00Z to: 2020-01-02T00:00:00Z entity_types: - payment entity_states: - completed - processing format: csv type: custom_report options: timezone: Europe/London columns: - transaction_id - amount - currency - metadata.custom_attribute settlement_report: summary: Settlement report value: filter: from: 2020-01-01T00:00:00Z to: 2020-01-02T00:00:00Z entity_types: - payment format: csv type: settlement_report payout_statement_report: summary: Payout statement report value: filter: payout_id: a830020e-090c-4717-836d-37941a27ad12 format: csv type: payout_statement_report icpp_fee_breakdown_report: summary: IC++ fee breakdown report value: filter: icpp_charge_id: 41d6c699-744a-4994-91c0-9227539c587f format: csv type: icpp_fee_breakdown_report payments_report: summary: Payments report value: filter: from: 2020-01-01T00:00:00Z to: 2020-01-02T00:00:00Z entity_states: - completed - failed - declined format: csv type: payments_report responses: "201": description: Report run created, report started generating content: application/json: schema: $ref: "#/components/schemas/Report-Run-Details" examples: report_run_processing: summary: Report run processing value: report_run_id: d6f6ef64-f668-4e64-8967-1cdf8afb2561 status: processing report_run_completed: summary: Report run completed value: report_run_id: d6f6ef64-f668-4e64-8967-1cdf8afb2561 status: completed file_url: https://merchant.revolut.com/api/report-runs/d6f6ef64-f668-4e64-8967-1cdf8afb2561/file "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/Report-Run-Error" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/Report-Run-Error" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/Report-Run-Error" security: - Api-Key: [] tags: - Report runs /api/report-runs/{report_run_id}: parameters: - $ref: "#/components/parameters/Authorization" - $ref: "#/components/parameters/Report-Run-Id" get: summary: Retrieve report run details operationId: retrieveReportRunDetails description: >- Retrieve details of a report run, based on the `report_run_id`. Use this method to check the status of a report run. If a report run's `status` is `completed`, the report file can be downloaded using the `file_url`. responses: "200": description: Report run found content: application/json: schema: $ref: "#/components/schemas/Report-Run-Details" examples: report_run_processing: summary: Report run processing value: report_run_id: d6f6ef64-f668-4e64-8967-1cdf8afb2561 status: processing report_run_completed: summary: Report run completed value: report_run_id: d6f6ef64-f668-4e64-8967-1cdf8afb2561 status: completed file_url: https://merchant.revolut.com/api/report-runs/d6f6ef64-f668-4e64-8967-1cdf8afb2561/file "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/Report-Run-Error" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/Report-Run-Error" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/Report-Run-Error" security: - Api-Key: [] tags: - Report runs /api/report-runs/{report_run_id}/file: parameters: - $ref: "#/components/parameters/Authorization" - $ref: "#/components/parameters/Report-Run-Id" get: summary: Download report file operationId: downloadReportFile description: Use this endpoint to download the generated report file. responses: "200": description: OK content: text/csv: schema: type: string description: CSV-formatted text representing the generated report file. examples: custom-report: summary: Custom CSV report example value: |- transaction_id,order_id,payment_method,amount,currency,state,updated_date 649ae37f-99ca-a7db-a4fb-5924af14ad7c,649ae35c-2558-adea-bf98-3a7156a764e7,PAY_WITH_REVOLUT,0.05,GBP,COMPLETED,2023-06-28T13:30:46.07498Z 649ae3de-e945-af9f-98c8-1d6172e350b5,649ae3ab-3998-ab2b-ad95-41b48346be69,PAY_WITH_REVOLUT,0.05,GBP,COMPLETED,2023-06-28T13:30:46.075569Z 649ae48b-37f6-a097-9cb0-4fc2a89d9e5a,649ae479-d7e8-a139-993b-bf75865c5059,PAY_WITH_REVOLUT,0.05,GBP,COMPLETED,2023-06-28T13:38:46.084289Z 649af325-0695-ac77-8868-ab421510a964,649af29d-be4a-a854-b872-3ececa585e0a,PAY_WITH_REVOLUT,0.05,GBP,COMPLETED,2023-06-28T14:34:56.894573Z 649af3a5-efbd-af7e-8c95-022bbdb91f1b,649af383-670d-a390-b22c-799a00892645,PAY_WITH_REVOLUT,0.05,GBP,COMPLETED,2023-06-28T14:42:56.903122Z 649ab540-352a-ac19-866f-47189c00d1a2,649ab53e-53ba-a398-88e1-78cf5bd9d348,PAY_WITH_REVOLUT,0.50,GBP,COMPLETED,2023-06-28T10:14:18.000566Z payout_statement_report: summary: Payout statement CSV report example value: |- created_date,completed_date,payout_affected_date,affected_payout_amount,transaction_id,order_id,merchant_order_reference,type,related_payout_id,related_icpp_charge_id,transaction_amount,transaction_currency,billing_amount,billing_currency,state,original_transaction_id,original_transaction_amount,original_transaction_currency,original_order_id,original_merchant_order_reference,fee_amount,fee_currency,settlement_amount,settlement_currency 2024-04-10T17:34:15.928757Z,2024-04-11T17:35:03.281106Z,2024-04-11T17:35:03.281106Z,true,6616cd97-3d8a-a1df-99c6-1417fc9e1997,6616cd60-ba44-a55a-81f3-91b4edb2a5c1,,Payment,,,10000.00,GBP,10000.00,GBP,COMPLETED,6616cd97-3d8a-a1df-99c6-1417fc9e1997,10000.00,GBP,6616cd60-ba44-a55a-81f3-91b4edb2a5c1,,-100.00,GBP,9900.00,GBP 2024-04-10T17:38:08.94564Z,2024-04-11T17:38:58.500128Z,2024-04-11T17:38:58.500128Z,true,6616ce80-2cee-a314-b494-b3ff64d77e14,6616cdbf-5674-a095-bbc9-4349ea767dd1,,Payment,,,10000.00,GBP,10000.00,GBP,COMPLETED,6616ce80-2cee-a314-b494-b3ff64d77e14,10000.00,GBP,6616cdbf-5674-a095-bbc9-4349ea767dd1,,-100.00,GBP,9900.00,GBP 2024-04-10T17:42:23.260097Z,2024-04-11T17:42:58.497249Z,2024-04-11T17:42:58.497249Z,true,6616cf7f-aa77-a577-9051-fe526e109b82,6616cf1b-dfa8-aeac-b736-36e851d83376,,Payment,,,10000.00,GBP,10000.00,GBP,COMPLETED,6616cf7f-aa77-a577-9051-fe526e109b82,10000.00,GBP,6616cf1b-dfa8-aeac-b736-36e851d83376,,-100.00,GBP,9900.00,GBP payments_report: summary: Payments CSV report example value: |- payment_id,type,description,original_payment_id,order_id,state,reason,amount,currency,surcharge_amount,tip_amount,refunded_amount,created_date,merchant_order_ext_ref,payment_method,location_id,customer_id,customer_card_number,customer_card_country,customer_card_brand,customer_card_type,customer_card_category,customer_email,fee_amount,fee_currency a1b2c3d4-0001-0000-0000-000000000001,PAYMENT,Payment from customer,,o1b2c3d4-0001-0000-0000-000000000001,COMPLETED,,120,GBP,,0,0,2026-02-01T09:10:05.375Z,ORD-001,CARD,,cust-0001-0000-0000-000000000001,533325******3223,GB,VISA,DEBIT,consumer,customer@example.com,3.56,GBP a1b2c3d4-0002-0000-0000-000000000002,PAYMENT,Payment from customer,,o1b2c3d4-0002-0000-0000-000000000002,COMPLETED,,10,GBP,,0,0,2026-02-01T14:35:00.699Z,,PAY_WITH_REVOLUT,,,,,,,customer2@example.com,0.30,GBP a1b2c3d4-0003-0000-0000-000000000003,PAYMENT,Payment from customer,,o1b2c3d4-0003-0000-0000-000000000003,FAILED,Insufficient Funds,15,GBP,,0,0,2026-02-02T20:45:01.255Z,,CARD,,cust-0001-0000-0000-000000000001,533325******3223,GB,MASTERCARD_DEBIT,PREPAID,consumer,customer@example.com,, "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/Report-Run-Error" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/Report-Run-Error" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/Report-Run-Error" security: - Api-Key: [] tags: - Report runs /api/1.0/webhooks: parameters: - $ref: "#/components/parameters/Authorization" post: summary: Create a webhook (Deprecated) deprecated: true operationId: createWebhookDeprecated description: >- Set up a webhook URL so that the Merchant API can push event notifications to the specified URL. :::warning Merchants can register a **maximum of 10 webhook URLs**. If you attempt to register more than 10, the API will return a `422 - Unprocessable Content` error. Ensure your webhook registrations are necessary and within the allowed limit. ::: requestBody: content: application/json: schema: $ref: "#/components/schemas/Webhook-Creation" examples: example_webhook_request: summary: Example webhook request value: url: https://example.com/webhooks events: - ORDER_COMPLETED - ORDER_AUTHORISED responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/Webhook-With-Signing-Secret" examples: created_webhook: summary: Created webhook value: id: c6b981f4-53b3-47d5-9b24-4f87af1160eb url: https://example.com/webhooks events: - ORDER_AUTHORISED - ORDER_COMPLETED signing_secret: wsk_4jETWMz1g1b37gCONjNp84t2KSSIT7dK "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/Error" "401": description: Unauthorized callbacks: Send webhook event: $ref: "#/components/callbacks/Webhook-Event" security: - Api-Key: [] tags: - Webhooks get: summary: Retrieve a webhook list (Deprecated) deprecated: true operationId: retrieveAllWebhooksDeprecated description: Get a list of webhooks that you are currently subscribed to. responses: "200": description: OK content: application/json: schema: type: array items: $ref: "#/components/schemas/Webhook" examples: list_of_webhooks: summary: List of webhooks value: - id: 6fc8db62-6489-4470-a9e0-84b462fe3908 url: https://revolut.com/webhooks events: - ORDER_COMPLETED - id: b466ab77-4932-4850-beb0-113bfc1166f8 url: https://business.revolut.com/webhooks events: - ORDER_COMPLETED - ORDER_AUTHORISED - id: 4a31c8a3-8037-4260-a09e-090475d37025 url: https://developer.revolut.com/webhooks events: - ORDER_AUTHORISED - id: 5d815041-5753-46bc-aebc-315fe99f30aa url: https://example.com/webhooks events: - ORDER_COMPLETED - ORDER_AUTHORISED "401": description: Unauthorized security: - Api-Key: [] tags: - Webhooks /api/1.0/webhooks/{webhook_id}: parameters: - $ref: "#/components/parameters/Authorization" - $ref: "#/components/parameters/Webhook-Id" get: summary: Retrieve a webhook (Deprecated) deprecated: true operationId: retrieveWebhookDeprecated description: Get the details of a specific webhook. responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/Webhook-With-Signing-Secret" examples: retrieved_webhook: summary: Retrieved webhook value: id: c6b981f4-53b3-47d5-9b24-4f87af1160eb url: https://example.com/webhooks events: - ORDER_AUTHORISED - ORDER_COMPLETED signing_secret: wsk_4jETWMz1g1b37gCONjNp84t2KSSIT7dK "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/Error" security: - Api-Key: [] tags: - Webhooks put: summary: Update a webhook (Deprecated) deprecated: true operationId: updateWebhookDeprecated description: Update the details of a specific webhook. requestBody: content: application/json: schema: $ref: "#/components/schemas/Webhook-Creation" examples: webhook_update_request: summary: Webhook update request value: url: http://business.revolut.com events: - ORDER_COMPLETED responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/Webhook" examples: updated_webhook: summary: Updated webhook value: id: c6b981f4-53b3-47d5-9b24-4f87af1160eb url: http://business.revolut.com events: - ORDER_COMPLETED "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/Error" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/Error" security: - Api-Key: [] tags: - Webhooks delete: summary: Delete a webhook (Deprecated) deprecated: true operationId: deleteWebhookDeprecated description: Delete a webhook so that events are not sent to the specified URL any more. responses: "204": description: No Content "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/Error" security: - Api-Key: [] tags: - Webhooks /api/1.0/webhooks/{webhook_id}/rotate-signing-secret: parameters: - $ref: "#/components/parameters/Authorization" - $ref: "#/components/parameters/Webhook-Id" post: summary: Rotate a webhook signing secret (Deprecated) deprecated: true operationId: rotateWebhookSigningSecretDeprecated description: |- Rotate the `signing secret` for a specific webhook. For more information, see [Tutorials: Verify the payload signature](/docs/guides/merchant/monitor-and-observe/webhooks/verify-the-payload-signature). requestBody: content: application/json: schema: type: object properties: expiration_period: type: string format: duration description: >- The expiration period of the signing secret in the [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601#Durations). If defined, when the signing secret is rotated, it continues to be valid until the expiration period passes. Otherwise, it is invalidated immediately. Maximum expiration period is 7 days. examples: - PT5H30M examples: webhook_signing_secret_rotate_request: summary: Webhook signing secret rotation request value: expiration_period: PT5H30M responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/Webhook-With-Signing-Secret" examples: updated_webhook: summary: Updated webhook value: id: c6b981f4-53b3-47d5-9b24-4f87af1160eb url: http://business.revolut.com events: - ORDER_COMPLETED signing_secret: wsk_4jETWMz1g1b37gCONjNp84t2KSSIT6aG "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/Error" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/Error" security: - Api-Key: [] tags: - Webhooks /api/apple-pay/domains/register: parameters: - $ref: "#/components/parameters/Authorization" post: summary: Register domain for Apple Pay operationId: registerDomainApplePay description: |- Register your website's domain to accept payments via Apple Pay. Before you call this endpoint, make sure that you have completed the following steps: 1. Download the latest [domain validation file](https://assets.revolut.com/api-docs/merchant-api/files/apple-developer-merchantid-domain-association). 1. Upload the domain validation file to your website in the following folder `/.well-known/`. For example, if your website is `example.com`, the file should be available on `example.com/.well-known/apple-developer-merchantid-domain-association`, where `apple-developer-merchantid-domain-association` indicates the name of the file. requestBody: content: application/json: schema: type: object properties: domain: type: string description: Domain name of your website without the scheme (i.e. without `http://` or `https://`). examples: - revolut.com required: - domain examples: example_request: summary: Example domain registration request for Apple Pay value: domain: revolut.com responses: "204": description: Domain registered successfully "400": description: Bad Request content: application/json: schema: type: object properties: code: type: string description: >- An identifier that can be used to determine what went wrong. Error codes are not globally unique, but uniqueness is guaranteed within endpoints. message: type: string description: Human readable text describing what went wrong. required: - code examples: error_message: summary: Error message value: code: validation message: Exactly one value must be supplied for client_id security: - Api-Key: [] tags: - Apple Pay merchant registration /api/apple-pay/domains/unregister: parameters: - $ref: "#/components/parameters/Authorization" - $ref: "#/components/parameters/Revolut-Api-Version-Optional" post: summary: Unregister domain for Apple Pay operationId: unregisterDomainApplePay description: "Unregister your website from Apple Pay's registered domains. " requestBody: content: application/json: schema: type: object properties: domain: type: string description: Domain name of your website without the scheme (i.e. without `http://` or `https://`). examples: - revolut.com reason: type: string description: A short explanation why you remove the domain. maxLength: 1024 required: - domain - reason examples: example_request: summary: Example domain registration request for Apple Pay value: domain: revolut.com reason: Unregister due to domain change. responses: "204": description: Domain ungistered successfully "400": description: Bad Request content: application/json: schema: type: object properties: code: type: string description: >- An identifier that can be used to determine what went wrong. Error codes are not globally unique, but uniqueness is guaranteed within endpoints. message: type: string description: Human readable text describing what went wrong. required: - code examples: error_message: summary: Error message value: code: validation message: Exactly one value must be supplied for client_id security: - Api-Key: [] tags: - Apple Pay merchant registration /api/synchronous-webhooks: parameters: - $ref: "#/components/parameters/Authorization" post: summary: Register address validation endpoint for Fast checkout operationId: registerAddressValidationEndpoint description: >- Use this endpoint to register a URL where Revolut can send shipping address(es) from a Revolut Pay customer for validation during the [Fast checkout process](/docs/guides/merchant/optimise-checkout/fast-checkout). Revolut Pay can support Fast checkout for delivering goods. Once your customer selects a shipping address, Revolut needs to validate if the merchant (or their shipping partner) delivers to the address provided. This is done by contacting the merchant's backend and asking for such validation and information. In order for your backend to support Fast checkout, you need to: 1. Register an URL to handle address validation 1. Validate the shipping address sent to your backend 1. Respond with a JSON object containing the result of the validation Additionally, Revolut Pay can support multiple webhooks if you have multiple stores. For more information, see: - [Manage multiple stores with Fast checkout](/docs/guides/merchant/optimise-checkout/fast-checkout#manage-multiple-stores-with-fast-checkout) - [Merchant API: Locations](/docs/api/merchant#tag-locations) :::note To set up a webhook for tracking order completion, failure, error, etc. events, use the [Webhooks endpoints](/docs/api/merchant#tag-webhooks). ::: requestBody: content: application/json: schema: $ref: "#/components/schemas/Synchronous-Webhook-Creation" examples: create_webhook: summary: Create synchronous webhook value: event_type: fast_checkout.validate_address url: https://backend.example.com/webhooks/validate-address create_webhook_with_location_id: summary: Create synchronous webhook with location ID value: event_type: fast_checkout.validate_address url: https://backend.example.com/webhooks/validate-address location_id: 8d9a7125-805f-40f3-a405-bc89765db996 responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/Synchronous-Webhook" examples: example_without_location: summary: Synchronous webhook response value: id: f6abc4df-eb48-417c-8e75-f7c6d7ad394f signing_key: swsk_y5z3LEHYZ9ndote3qegzWD6uL4t1lfp1 url: https://backend.example.com/webhooks/validate-address event_type: fast_checkout.validate_address example_with_location: summary: Synchronous webhook response with location ID value: id: f6abc4df-eb48-417c-8e75-f7c6d7ad394f signing_key: swsk_y5z3LEHYZ9ndote3qegzWD6uL4t1lfp1 url: https://backend.example.com/webhooks/validate-address event_type: fast_checkout.validate_address location_id: b0ebede4-5cbc-4951-977f-70329faa8769 "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/Error" "401": description: Unauthorized security: - Api-Key: [] tags: - Other get: summary: Retrieve a synchronous webhook list operationId: retrieveSynchronousWebhookList description: >- Retrieve a list of synchronous webhook objects. You can use this endpoint to see your different address validation endpoints registered to different locations. :::info For more information about locations, see: [Merchant API: Locations](/docs/api/merchant#tag-locations). ::: responses: "200": description: Synchronous webhook list returned content: application/json: schema: type: array items: $ref: "#/components/schemas/Synchronous-Webhook" examples: example_without_location: summary: List of synchronous webhooks value: - id: f6abc4df-eb48-417c-8e75-f7c6d7ad394f signing_key: swsk_y5z3LEHYZ9ndote3qegzWD6uL4t1lfp1 url: https://example.com/webhooks/validate-address event_type: fast_checkout.validate_address - id: 5c08dcc1-cd60-4b7d-a255-e42d24d7365c signing_key: swsk_VsuFcq6FIpa9gOWUu0n2WxiCbsDHIJlN url: https://groceries.example.com/webhooks/validate-address event_type: fast_checkout.validate_address location_id: b0ebede4-5cbc-4951-977f-70329faa8769 - id: dbebe6f8-4c47-4176-a94f-576d76e1d0b6 signing_key: swsk_0TKYlzoakBgGGVvojCiRRqInMD1ufLZn url: https://clothes.example.com/webhooks/validate-address event_type: fast_checkout.validate_address location_id: 6ebd3d2b-7a51-42e4-84f4-3c513621edd3 "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/Error" "401": description: Unauthorized security: - Api-Key: [] tags: - Other /api/synchronous-webhooks/{synchronous_webhook_id}: parameters: - $ref: "#/components/parameters/Authorization" - $ref: "#/components/parameters/Synchronous-Webhook-Id" delete: summary: Delete a synchronous webhook operationId: deleteSynchronousWebhook description: Delete a specific synchronous webhook registration, based on its ID. responses: "204": description: Synchronous webhook deleted "401": description: Unauthorized "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/Error" security: - Api-Key: [] tags: - Other /api/locations: parameters: - $ref: "#/components/parameters/Authorization" post: summary: Create a location operationId: createLocation description: Create a `Location` object. Supports `online` and `physical` location types. requestBody: content: application/json: schema: $ref: "#/components/schemas/Location-Creation" examples: example_online_location: $ref: "#/components/examples/Req-Location-Online" example_physical_location: $ref: "#/components/examples/Req-Location-Physical" responses: "201": description: Location created content: application/json: schema: $ref: "#/components/schemas/Location" examples: example_online_location: $ref: "#/components/examples/Res-Location-Online" example_physical_location: $ref: "#/components/examples/Res-Location-Physical" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/Error" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/Error" security: - Api-Key: [] tags: - Locations get: summary: Retrieve location list operationId: retrieveLocationList description: >- Retrieve a list of locations registered for the merchant. :::note [Default behavior] Without the `type` query parameter, this endpoint returns only **online** locations by default. To retrieve physical locations, you must explicitly specify `type=physical` in the query parameters. ::: parameters: - $ref: "#/components/parameters/Location-Type" responses: "200": description: OK content: application/json: schema: type: array items: $ref: "#/components/schemas/Location" examples: list_of_locations: summary: Location list value: - id: 8d9a7125-805f-40f3-a405-bc89765db996 name: Grocery website type: online details: domain: groceries.example.com - id: 066223df-d5a8-42f0-b3ce-688c7a76f9a8 name: Cars website type: online details: domain: cars.example.com - id: 299050a4-cc7a-44b0-8b2b-7cd1e335ef38 name: Example Street Store type: physical details: address: street_line_1: 123 Example Street city: Example city postcode: "12345" country_code: GB geo_location: lat: 12.3456 lon: -12.3456 opening_hours: monday: - from: 09:00 to: 15:00 - from: 16:00 to: 18:00 tuesday: - from: 10:00 to: 13:00 - from: 16:00 to: 18:00 "401": description: Unauthorized security: - Api-Key: [] tags: - Locations /api/locations/{location_id}: parameters: - $ref: "#/components/parameters/Authorization" - $ref: "#/components/parameters/Location-Id" get: summary: Retrieve a location operationId: retrieveLocation description: Retrieve details of a specific location, based on its ID. responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/Location" examples: example_online_location: $ref: "#/components/examples/Res-Location-Online" example_physical_location: $ref: "#/components/examples/Res-Location-Physical" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/Error" security: - Api-Key: [] tags: - Locations patch: summary: Update a location operationId: updateLocation description: >- Update details of a specific location, based on its ID. Only the fields provided in the request will be updated. Any omitted fields will retain their current values. :::note The value of the location's `type` parameter cannot be updated. ::: requestBody: content: application/json: schema: $ref: "#/components/schemas/Location-Update" examples: online_location: summary: Online location example value: name: Cars website - Name update details: domain: cars.example.com physical_location: summary: Physical location example value: name: Example Street Store details: opening_hours: monday: - from: 10:00 to: 18:00 wednesday: - from: 11:00 to: 18:00 responses: "200": description: Location updated content: application/json: schema: $ref: "#/components/schemas/Location" examples: online_location: summary: Online location example value: id: 8d9a7125-805f-40f3-a405-bc89765db996 name: Cars website - Name update type: online details: domain: cars.example.com physical_location: summary: Physical location example value: name: Example Street Store type: physical details: address: null street_line_1: 123 Example Street city: Example city postcode: "12345" country_code: GB geo_location: lat: 12.3456 lon: -12.3456 opening_hours: monday: - from: 10:00 to: 18:00 tuesday: - from: 10:00 to: 13:00 - from: 16:00 to: 18:00 wednesday: - from: 11:00 to: 18:00 "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/Error" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/Error" security: - Api-Key: [] tags: - Locations delete: summary: Delete a location operationId: deleteLocation description: Delete a specific location, based on its ID. responses: "204": description: Location deleted "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/Error" security: - Api-Key: [] tags: - Locations components: securitySchemes: Api-Key: type: apiKey in: header name: Authorization description: >- Each Merchant API request must contain an authorization header in the following format: ``` 'Authorization: Bearer ' ``` To use this API, you need to generate API keys from your Revolut Business account. The Secret key is used in the authorization header for all server calls, while the Public key is provided with payment methods at checkout. :::info For detailed instructions on generating your API keys, see: [Generate API keys](/docs/guides/merchant/get-started). ::: SSL: type: http scheme: SSL description: >- :::note This authentication protocol is used exclusively when using [Fast checkout](/docs/guides/merchant/optimise-checkout/fast-checkout). ::: Connection over HTTPS is using SSL authentication. For successful authentication, your system's certificate should be issued by a Public Certificate Authority (PCA) and your system should trust Revolut's public certificate. Payload-Signature: type: apiKey in: header name: Revolut-Pay-Payload-Signature description: >- :::note This authentication protocol is used exclusively when using [Fast checkout](/docs/guides/merchant/optimise-checkout/fast-checkout). ::: Data integrity and authorship will be verified using a payload-based signature. The response of a successful URL registration for address validation (see: [Register address validation for Fast checkout](/docs/api/merchant#register-address-validation-endpoint)) will contain a secret signing key. The signing key will be used by Revolut to compute a Hash-based Message Authentication Code (HMAC) payload signature whenever the registered URL is called, which should be verified by your backend. parameters: Authorization: name: Authorization in: header schema: type: string format: Bearer examples: - Bearer sk_1234567890ABCdefGHIjklMNOpqrSTUvwxYZ_1234567890-Ab_cdeFGHijkLMNopq required: true description: >- This parameter accepts the [Merchant API Secret key](https://business.revolut.com/settings/merchant-api) to authorise requests coming from the merchant's backend. It ensures that ensures that each request is authenticated and authorised by verifying the secret key. The secret key should be included in all request headers as a `Bearer` token. :::info For more information, see: [Generate API keys](/docs/guides/merchant/get-started) ::: 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. Idempotency-Key: name: Idempotency-Key in: header schema: type: string required: false description: >- The `Idempotency-Key` ensures that requests are processed only once, preventing multiple executions of the same operation due to retries or duplicate requests. This header is optional and can accept any unique string value the merchant uses. A recommended practice is to use a unique identifier from your system (such as the entity's ID or a request UUID) as the idempotency key. This facilitates tracking and managing requests effectively. Customer-Id: name: customer_id in: path schema: type: string format: uuid description: A UUID string, typically used to identify resources. required: true description: The ID of the `Customer` object. Payment-Method-Id: name: payment_method_id in: path schema: type: string format: uuid description: A UUID string, typically used to identify resources. required: true description: The ID of the payment method. Payment-Id: name: payment_id in: path schema: type: string format: uuid description: A UUID string, typically used to identify resources. required: true description: The ID of the `Payment` object. 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. 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 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. schemas: Address: title: Address type: object properties: street_line_1: type: string description: Street line 1 information. street_line_2: type: string description: Street line 2 information. region: type: string description: The region associated with the address. city: type: string description: The city associated with the address. country_code: type: string description: The country associated with the address. postcode: type: string description: The postcode associated with the address. required: - country_code - postcode Simplified-Order: title: Simplified-Order type: object properties: id: type: string description: Permanent order ID used to retrieve, capture, cancel, or refund an order after authorisation. type: type: string description: The type of the order. enum: - PAYMENT - REFUND - CHARGEBACK state: type: string description: >- The state of the order. :::info For more information about the order lifecycle, see: [Order and payment lifecycle](/docs/guides/merchant/reference/order-lifecycle). ::: enum: - PENDING - PROCESSING - AUTHORISED - COMPLETED - CANCELLED - FAILED created_at: type: string description: The date and time the order was created. format: date-time updated_at: type: string description: The date and time the order was last updated. format: date-time completed_at: type: string description: The date and time the order was completed. format: date-time description: type: string description: The description of the order. capture_mode: type: string description: >- The capture mode of the order. `AUTOMATIC` is used by default. - `AUTOMATIC`: The order is captured automatically after payment authorisation. - `MANUAL`: The order is not captured automatically. You must manually capture the order later. For more information, see [Capture an order](/docs/api/merchant#capture-order). settlement_currency: type: string description: |- [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code in upper case. All payments made towards this order are settled in this currency. :::info For more information about the supported currencies, see: [Help Center](https://help.revolut.com/business/help/merchant-accounts/payments/in-which-currencies-can-i-accept-payments/). ::: merchant_order_ext_ref: type: string description: >- Merchant order ID for external reference. Use this field to set the ID that your own system can use to easily track orders. customer_id: type: string description: The ID of the [customer](/docs/api/merchant#tag-customers) associated with this order. email: type: string description: The email of the customer. format: email phone: type: string description: The phone number of the customer. order_amount: type: object description: The amount and currency of the order. required: - value - currency properties: value: type: integer description: The amount of the order (minor currency unit). For example, enter `7034` for €70.34 in the field. currency: type: string description: |- The currency of the order. [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code in upper case. :::info For more information about the supported currencies, see: [Help Center](https://help.revolut.com/business/help/merchant-accounts/payments/in-which-currencies-can-i-accept-payments/). ::: order_outstanding_amount: type: object description: The amount and currency outstanding to be paid for this order. properties: value: type: integer description: The amount of the order (minor currency unit) that is outstanding. For example, enter `7034` for €70.34 in the field. currency: type: string description: |- The currency of the amount that is outstanding. [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code in upper case. :::info For more information about the supported currencies, see: [Help Center](https://help.revolut.com/business/help/merchant-accounts/payments/in-which-currencies-can-i-accept-payments/). ::: shipping_address: $ref: "#/components/schemas/Address" required: - id - type - state - created_at - updated_at - order_amount description: The `Order` object returned when you retrieve a list of orders. Error: title: Error type: object properties: errorId: type: string description: The ID of the error. You can share this ID with Revolut support for troubleshooting. timestamp: type: integer description: The date and time the error happened. required: - errorId - timestamp Order-Amount: type: integer description: >- The order total expressed in minor currency units, according to the [ISO 4217 standard](https://en.wikipedia.org/wiki/ISO_4217). For example, `7034` in `EUR` corresponds to €70.34. :::info Conversion between major and minor units varies by currency. For instance, `100` minor units equal £1.00 in `GBP`, whereas in `ISK` they represent 100 units. For more details, see the [ISO 4217 standard](https://en.wikipedia.org/wiki/ISO_4217). ::: Capture-Mode: type: string description: >- The capture mode of the order. `AUTOMATIC` is used by default. - `AUTOMATIC`: The order is captured automatically after payment authorisation. - `MANUAL`: The order is not captured automatically. You must manually capture the order later. For more information, see [Capture an order](/docs/api/merchant#capture-order). enum: - AUTOMATIC - MANUAL 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-Description: type: string description: The description of the order. Currency: type: string format: ISO 4217 minLength: 3 maxLength: 3 description: |- [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code in upper case. :::info For more information about the supported currencies, see: [Help Center](https://help.revolut.com/business/help/merchant-accounts/payments/in-which-currencies-can-i-accept-payments/). ::: Settlement-Currency: type: string description: |- [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code in upper case. If `settlement_currency` is different from the value of `currency`, the money will be exchanged when the amount is settled to your merchant account. In case of a refund or chargeback, the money will be exchanged to the order's initial `currency`. If `settlement_currency` is not specified, this value is taken from `currency`. :::info For more information about the supported currencies, see: [Help Center](https://help.revolut.com/business/help/merchant-accounts/payments/in-which-currencies-can-i-accept-payments/). ::: Enforce-Challenge: type: string description: >- The enforce challenge mode. `AUTOMATIC` is used by default. - `AUTOMATIC`: The payments created for an order, will have challenge requirement calculated by our fraud mechanisms and might not require it. - `FORCED`: The payments created for an order will require a challenge. Currently only supported for card payments and forces 3DS challenge. enum: - AUTOMATIC - FORCED 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 Merchant-Order-Uri: type: string format: uri pattern: ^https?:\/{2}.+/gi maxLength: 2000 description: >- The URI of the order stored in the merchant's order management system. This URI will be included in the order confirmation email for payments made via Revolut Pay. If specified, this URI will override the default link to the merchant's **Business website** configured in the Revolut Business account. :::warning Restrictions: - Must be a valid URI as defined by [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986) - URI scheme is required and must be either `http` or `https` - URI host is required and cannot be `localhost` or an IP address - Max length: `2000` - Reserved or invalid characters must be percent-encoded (for example, use `%20` instead of a space) ::: Order-Creation: type: object properties: amount: $ref: "#/components/schemas/Order-Amount" capture_mode: $ref: "#/components/schemas/Capture-Mode" merchant_order_ext_ref: $ref: "#/components/schemas/Merchant-Order-External-Reference" email: type: string description: The email of the customer. format: email description: $ref: "#/components/schemas/Order-Description" currency: $ref: "#/components/schemas/Currency" settlement_currency: $ref: "#/components/schemas/Settlement-Currency" customer_id: type: string description: >- ID of the [customer](/docs/api/merchant#tag-customers) that is associated with this order. When you specify a `customer_id`, the email associated with the customer ID overrides the value of the `email` field. shipping_address: $ref: "#/components/schemas/Address" enforce_challenge: $ref: "#/components/schemas/Enforce-Challenge" metadata: $ref: "#/components/schemas/Metadata" merchant_order_uri: $ref: "#/components/schemas/Merchant-Order-Uri" required: - amount - currency Order-Id: type: string format: uuid description: Permanent order ID used to retrieve, capture, cancel, or refund an order after authorization. Payment-Method: title: Payment-Method type: object description: The details of the payment method used to make the payment. properties: id: type: string description: The ID of the payment method. This value is present only if the payment method was previously saved. format: uuid type: type: string description: The type of the payment. enum: - CARD - REVOLUT card: type: object description: The details of the card. Only present for payments with `payment_method.type` = `CARD`. properties: card_brand: type: string description: The type of the card. enum: - VISA - MASTERCARD funding: type: string description: The type of card funding. enum: - CREDIT - DEBIT - PREPAID card_country: type: string description: The country where the card was issued. card_bin: type: string description: The BIN of the card. minLength: 6 maxLength: 6 card_last_four: type: string description: The last four digits of the card. minLength: 4 maxLength: 4 card_expiry: type: string description: The expiry date of the card in the format of MM/YY. cardholder_name: type: string description: The name of the cardholder. checks: type: object description: The details of the check for card payment. Only for orders with successful payments. properties: three_ds: type: object description: The details of the 3D Secure check. Only for orders with successful payments. properties: state: type: string description: The result of 3D Secure check. enum: - VERIFIED - FAILED - CHALLENGE version: type: integer description: The 3D Secure version. cvv_verification: type: string description: >- The result of CVV verification. | Verification result | Description | | ------------------- | ----------- | | `MATCH` | Provided CVV matches the card's CVV | | `NOT_MATCH` | Provided CVV does not match the card's CVV | | `INCORRECT` | Provided CVV format is incorrect for this type of card | | `NOT_PROCESSED` | CVV verification was not performed | enum: - MATCH - NOT_MATCH - INCORRECT - NOT_PROCESSED address: type: string description: The result of address verification. enum: - MATCH - NOT_MATCH - N_A - INVALID postcode: type: string description: The result of postcode verification. enum: - MATCH - NOT_MATCH - N_A - INVALID cardholder: type: string description: The result of cardholder verification. enum: - MATCH - NOT_MATCH - N_A - INVALID Payment: title: Payment type: object description: "" properties: id: type: string description: The ID of the payment. state: type: string description: The state of the payment. enum: - PROCESSING - AUTHORISED - CAPTURED - COMPLETED - FAILED - DECLINED - CANCELLED failure_reason: type: string description: |- The reason for a `FAILED` or `DECLINED` payment. A failed or declined payment can result from multiple reasons. To learn more, check our [decline reasons](/docs/guides/merchant/reference/error-codes/decline-reasons). enum: - do_not_honour - 3ds_challenge_abandoned - 3ds_challenge_failed - 3ds_challenge_failed_manually - insufficient_funds - transaction_not_allowed_for_cardholder - high_risk - cardholder_name_missing - unknown_card - invalid_card - invalid_email - restricted_card - expired_card - rejected_by_customer - withdrawal_limit_exceeded - pick_up_card - invalid_amount created_at: type: string description: The date and time the payment was created. format: date-time updated_at: type: string description: The date and time the payment was last updated. format: date-time token: type: string description: |- Temporary token of the payment used to fetch the reward offer during checkout and link user registrations to the given offers. The token is only valid for a limited time. amount: type: object description: The amount and currency of the payment. required: - value - currency properties: value: type: integer description: >- The amount of the payment (minor currency unit). For example, enter `7034` for €70.34 in the field. currency: type: string description: |- The currency of the payment. [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code in upper case. :::info For more information about the supported currencies, see: [Help Center](https://help.revolut.com/business/help/merchant-accounts/payments/in-which-currencies-can-i-accept-payments/). ::: settled_amount: type: object description: The amount and currency of the settled payment. properties: value: type: integer description: >- The amount of the settled payment (minor currency unit). For example, enter `7034` for €70.34 in the field. currency: type: string description: |- The currency of the settled payment. [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code in upper case. :::info For more information about the supported currencies, see: [Help Center](https://help.revolut.com/business/help/merchant-accounts/payments/in-which-currencies-can-i-accept-payments/). ::: payment_method: $ref: "#/components/schemas/Payment-Method" billing_address: $ref: "#/components/schemas/Address" risk_level: type: string description: |- The risk level of the card. If the risk level is `HIGH`, the payment might be declined. enum: - LOW - HIGH fees: type: array description: The details of the order fee. items: type: object properties: type: type: string description: The type of the order fee. enum: - FX - ACQUIRING amount: type: object description: The amount and currency of the payment fee. properties: value: type: integer description: |- The amount of the payment fee (minor currency unit). For example, enter `7034` for €70.34 in the field. currency: type: string description: |- The currency of the payment fee. [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code in upper case. :::info For more information about the supported currencies, see: [Help Center](https://help.revolut.com/business/help/merchant-accounts/payments/in-which-currencies-can-i-accept-payments/). ::: required: - id - state - created_at - updated_at - amount Order-Related: title: Order-Related type: object properties: id: type: string description: The ID of the related order. You can use this ID to get more information about the related order using the [Retrieve an order](/docs/api/merchant#retrieve-order) operation. type: type: string description: The type of the related order. enum: - PAYMENT - REFUND - CHARGEBACK state: type: string description: The state of the related order. enum: - PENDING - PROCESSING - AUTHORISED - COMPLETED - CANCELLED - FAILED amount: type: object description: The amount and currency of the related order. properties: value: $ref: "#/components/schemas/Order-Amount" currency: $ref: "#/components/schemas/Currency" Checkout-Url: type: string description: Link to a checkout page hosted by Revolut. format: uri Order: title: Order type: object description: >- An Order object helps you through the process of accepting payments from your customers. Create an order for every customer session or while an order is being created in your own system. Then, the order goes through multiple states using the [Revolut Checkout Widget](/docs/sdks/merchant-web-sdk/install-widget) to collect payments from your customers. properties: id: $ref: "#/components/schemas/Order-Id" public_id: type: string description: |- Temporary ID for the order. It expires when the payment is authorized. type: type: string description: The type of the order. enum: - PAYMENT - REFUND - CHARGEBACK state: type: string description: >- The state of the order. :::info For more information about the order lifecycle, see: [Order and payment lifecycle](/docs/guides/merchant/reference/order-lifecycle). ::: enum: - PENDING - PROCESSING - AUTHORISED - COMPLETED - CANCELLED - FAILED created_at: type: string description: The date and time the order was created. format: date-time updated_at: type: string description: The date and time the order was last updated. format: date-time completed_at: type: string description: The date and time the order was completed. format: date-time description: $ref: "#/components/schemas/Order-Description" capture_mode: $ref: "#/components/schemas/Capture-Mode" settlement_currency: $ref: "#/components/schemas/Settlement-Currency" merchant_order_ext_ref: $ref: "#/components/schemas/Merchant-Order-External-Reference" customer_id: type: string description: The ID of the [customer](/docs/api/merchant#tag-customers) associated with this order. email: type: string description: The email of the customer. format: email phone: type: string description: The phone number of the customer. full_name: type: string description: The customer's full name. order_amount: type: object description: The amount and currency of the order. required: - value - currency properties: value: $ref: "#/components/schemas/Order-Amount" currency: $ref: "#/components/schemas/Currency" order_outstanding_amount: type: object description: The amount and currency outstanding to be paid for this order. properties: value: type: integer description: The amount of the order (minor currency unit) that is outstanding. For example, enter `7034` for €70.34 in the field. currency: type: string description: |- The currency of the amount that is outstanding. [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code in upper case. :::info For more information about the supported currencies, see: [Help Center](https://help.revolut.com/business/help/merchant-accounts/payments/in-which-currencies-can-i-accept-payments/). ::: refunded_amount: type: object description: The amount and currency of the refunded order. properties: value: type: integer description: The amount of the refunded order (minor currency unit). For example, enter `7034` for €70.34 in the field. currency: type: string description: |- The currency of the refunded order. [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code in upper case. :::info For more information about the supported currencies, see: [Help Center](https://help.revolut.com/business/help/merchant-accounts/payments/in-which-currencies-can-i-accept-payments/). ::: shipping_address: $ref: "#/components/schemas/Address" payments: type: array description: The details of all the payment attempts that have been made towards this order (successful or unsuccessful). items: $ref: "#/components/schemas/Payment" related: type: array description: The details of related orders. You can use the ID of the related order to [Retrieve the order information](/docs/api/merchant#retrieve-order). items: $ref: "#/components/schemas/Order-Related" metadata: $ref: "#/components/schemas/Metadata" checkout_url: $ref: "#/components/schemas/Checkout-Url" merchant_order_uri: $ref: "#/components/schemas/Merchant-Order-Uri" required: - id - type - state - created_at - updated_at - order_amount Order-Update: type: object properties: amount: $ref: "#/components/schemas/Order-Amount" currency: $ref: "#/components/schemas/Currency" merchant_order_ext_ref: $ref: "#/components/schemas/Merchant-Order-External-Reference" description: $ref: "#/components/schemas/Order-Description" email: type: string description: The email of the customer. customer_id: type: string description: The ID of the customer. capture_mode: $ref: "#/components/schemas/Capture-Mode" settlement_currency: type: string description: |- Settlement 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/). ::: shipping_address: $ref: "#/components/schemas/Address" metadata: $ref: "#/components/schemas/Metadata" enforce_challenge: $ref: "#/components/schemas/Enforce-Challenge" Order-Refund: type: object properties: amount: type: integer description: >- The amount of the refund (minor currency unit). For example, enter `7034` for €70.34 in the field. This amount can't exceed the remaining amount of the original order. To get the refundable amount, subtract the `value` of the `refunded_amount` from the `value` of the `order_amount` in the original order. See [Retrieve an order](/docs/api/merchant#retrieve-order). description: type: string description: The description of the refund. merchant_order_ext_ref: $ref: "#/components/schemas/Merchant-Order-External-Reference" metadata: $ref: "#/components/schemas/Metadata" required: - amount Payment-Id: type: string format: uuid description: The ID of the payment. RPay-Account: properties: type: type: string enum: - card - revolut_pay description: The type of payment method used to pay for the order. subtype: type: string enum: - revolut_account - card description: Indicates whether the customer used their card or Revolut account via Revolut Pay. id: type: string format: uuid description: |- ID of the saved payment method. :::note The `id` parameter is only returned if the payment method is saved. ::: required: - type - subtype RPay-Card: properties: type: type: string enum: - card - revolut_pay description: The type of payment method used to pay for the order. subtype: type: string enum: - revolut_account - card description: Indicates whether the customer used their card or Revolut account via Revolut Pay. id: type: string format: uuid description: |- ID of the saved payment method. :::note The `id` parameter is only returned if the payment method is saved. ::: brand: type: string description: The type of the card. last_four: type: string description: The last four digits of the card number. required: - type - subtype Revolut-Pay: discriminator: propertyName: subtype mapping: revolut_pay_account: "#/components/schemas/RPay-Account" revolut_pay_card: "#/components/schemas/RPay-Card" oneOf: - $ref: "#/components/schemas/RPay-Account" - $ref: "#/components/schemas/RPay-Card" Card-For-Payment-Details: properties: type: type: string enum: - card - revolut_pay description: The type of payment method used to pay for the order. brand: type: string description: The type of the card. last_four: type: string description: The last four digits of the card number. id: type: string format: uuid description: |- ID of the saved payment method. :::note The `id` parameter is only returned if the payment method is saved. ::: required: - type Payment-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. | Sepa-Direct-Debit-Debtor-Iban-Last-Four: type: string description: The last four digits of the debtor's IBAN. minLength: 4 maxLength: 4 Sepa-Direct-Debit-Debtor-Name: type: string description: The full name of the debtor as provided in the mandate. Sepa-Direct-Debit-Mandate-Reference: type: string description: The unique mandate reference generated by Revolut. Include this in pre-debit notifications sent to your customers. Sepa-Direct-Debit: type: object description: |- Object containing details of a SEPA Direct Debit payment. :::info For more information, see: [SEPA Direct Debit server-to-server integration](/docs/guides/merchant/payment-methods/sepa-direct-debit/server-to-server) ::: properties: id: type: string format: uuid description: >- ID of the saved payment method. :::note The `id` parameter is only returned when the payment method is saved for the merchant. ::: type: $ref: "#/components/schemas/Payment-Method-Type" debtor_iban_last_four: $ref: "#/components/schemas/Sepa-Direct-Debit-Debtor-Iban-Last-Four" debtor_name: $ref: "#/components/schemas/Sepa-Direct-Debit-Debtor-Name" mandate_reference: $ref: "#/components/schemas/Sepa-Direct-Debit-Mandate-Reference" required: - type Payment-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-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 Authentication-Challenge-Type: type: string enum: - three_ds - three_ds_fingerprint description: Type of the authentication challenge the payment triggers. Three-Ds: title: three_ds type: object description: Information about the 3DS challenge. properties: type: $ref: "#/components/schemas/Authentication-Challenge-Type" acs_url: type: string format: url description: The URL of the authentication challenge. required: - type - acs_url Three-Ds-Fingerprint: title: three_ds_fingerprint type: object description: Information about the 3DS fingerprint challenge. properties: type: $ref: "#/components/schemas/Authentication-Challenge-Type" fingerprint_url: type: string format: url description: The URL of the fingerprint. (Used only internally by Revolut.) fingerprint_data: type: string format: JSON description: >- Data about the fingerprint used for authentication. (Used only internally by Revolut.) required: - type - fingerprint_url - fingerprint_data Authentication-Challenge: type: object description: >- Details about the authentication challenge that should be performed to complete the authentication process. For more information about Revolut's 3DS solution, see: [3D Secure overview](/docs/guides/merchant/reference/3d-secure). Only returned if the payment's state is `authentication_challenge`. discriminator: propertyName: type mapping: three_ds: "#/components/schemas/Three-Ds" three_ds_fingerprint: "#/components/schemas/Three-Ds-Fingerprint" oneOf: - $ref: "#/components/schemas/Three-Ds" - $ref: "#/components/schemas/Three-Ds-Fingerprint" Payment-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 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. 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 Date-Of-Birth: type: string format: date description: The birth date of the customer. Customer: title: Customer type: object description: "" properties: id: type: string description: Permanent customer ID used to retrieve, update, and delete a customer. full_name: type: string description: The full name of the customer. business_name: type: string description: The name of the customer's business. phone: type: string description: The phone number of the customer in [E.164 format](https://en.wikipedia.org/wiki/E.164). created_at: type: string description: The date and time the customer was created. format: date-time updated_at: type: string description: The data and time the customer was last updated. format: date-time email: type: string description: The email address of the customer. format: email date_of_birth: $ref: "#/components/schemas/Date-Of-Birth" required: - id - created_at - updated_at - email Customer-Creation: type: object properties: full_name: type: string description: The full name of the customer. business_name: type: string description: The name of the customer's business. email: type: string description: The email address of the customer. format: email phone: type: string description: The phone number of the customer in [E.164 format](https://en.wikipedia.org/wiki/E.164). date_of_birth: $ref: "#/components/schemas/Date-Of-Birth" required: - email Customer-Payment-Method: title: Payment method object type: object description: "" properties: id: type: string format: uuid description: The ID of the payment method. type: type: string enum: - CARD - REVOLUT_PAY description: >- The type of the payment method. :::note Only merchant initiated transactions are supported for saved `REVOLUT_PAY` payment methods. ::: saved_for: type: string enum: - CUSTOMER - MERCHANT description: >- Indicates in which case this saved payment method can be used for payments. - `CUSTOMER`: This payment method can be used only when the customer is on the checkout page. - `MERCHANT`: This payment method can be used without the customer being on the checkout page, and the merchant can initiate transactions, for example, to take payments for recurring transactions. method_details: type: object description: The details of the payment method. properties: bin: type: string maxLength: 6 minLength: 6 description: The BIN of the payment card. last4: type: string maxLength: 4 minLength: 4 description: The last four digits of the payment card. expiry_month: type: number description: The expiry month of the payment card. expiry_year: type: number description: The expiry year of the payment card. cardholder_name: type: string description: The name of the cardholder. billing_address: type: object description: The billing address of the payment method. properties: street_line_1: type: string minLength: 1 description: Street line 1 information. street_line_2: type: string minLength: 1 description: Street line 2 information. postcode: type: string minLength: 1 description: The postcode associated with the address. city: type: string minLength: 1 description: The city associated with the address. region: type: string minLength: 1 description: The region associated with the address. country_code: type: string minLength: 1 description: The country associated with the address. brand: type: string description: The brand of the payment card. enum: - VISA - MASTERCARD - MAESTRO funding: type: string enum: - DEBIT - CREDIT - PREPAID - DEFERRED_DEBIT - CHARGE description: The funding type of the payment card. issuer: type: string description: The issuer of the payment card. issuer_country: type: string description: Two-letter country code of the country where the payment card was issued. created_at: type: string description: The date and time the payment card was added. format: date-time required: - id Customer-With-Payment-Method: title: Customer object with Payment Method object type: object properties: id: type: string description: Permanent customer ID used to retrieve, update, and delete a customer. full_name: type: string description: The full name of the customer. business_name: type: string description: The name of the customer's business. phone: type: string description: The phone number of the customer in [E.164 format](https://en.wikipedia.org/wiki/E.164). created_at: type: string description: The date and time the customer was created. format: date-time updated_at: type: string description: The data and time the customer was last updated. format: date-time email: type: string description: The email address of the customer. format: email date_of_birth: $ref: "#/components/schemas/Date-Of-Birth" payment_methods: type: array uniqueItems: false description: All the payment methods for this customer. items: $ref: "#/components/schemas/Customer-Payment-Method" required: - id - created_at - updated_at - email Customer-Update: type: object properties: full_name: type: string description: The full name of the customer. business_name: type: string description: The name of the customer's business. email: type: string description: >- The email address of the customer. :::note This value must be unique for each customer for one merchant. If the email address matches an existing customer, an error is returned. ::: format: email phone: type: string description: The phone number of the customer in [E.164 format](https://en.wikipedia.org/wiki/E.164). date_of_birth: $ref: "#/components/schemas/Date-Of-Birth" Report-Run-From: type: string format: date-time description: >- This parameter specifies the start boundary for filtering transaction data in the report based on an order's `payments.created_at` parameter. It accepts ETC/UTC date and time in [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601) and includes all transactions created on or after this timestamp. Combined with the `to` parameter, this determines the report's timeframe, including all transactions between the two values. For example, by setting the `from` parameter to `2021-01-01T00:00:00Z`, the report will include transactions created from the first second of January 1, 2021, UTC, and onwards. Report-Run-To: type: string format: date-time description: >- This parameter specifies the end boundary for filtering transaction data in the report based on an order's `payments.created_at` parameter. It accepts ETC/UTC date and time in [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601) and includes all transactions created before this timestamp (exclusive). Combined with the `from` parameter, this determines the timeframe for the report, including all transactions between the two values. For example, setting the `to` parameter to `2021-12-31T23:59:59Z` will include all transactions in the report created up to, but not including, the last second of December 31, 2021, UTC. Report-Run-Entity-Types: type: array items: type: string enum: - payment - refund - dispute description: Select transactions by type to be included in the report. Report-Run-Entity-States: type: array items: type: string enum: - completed - processing - cancelled - reverted description: >- Select transactions by state to be included in the report. If not provided, only `completed` transactions will be included in the report. Report-Run-Currency: type: string description: |- Select transactions with specific currencies to include in the report. Provide [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code in upper case. :::info For more information about the supported currencies, see: [Help Center](https://help.revolut.com/business/help/merchant-accounts/payments/in-which-currencies-can-i-accept-payments/). ::: minLength: 3 maxLength: 3 examples: - GBP Report-Run-Location-Id: type: string format: uuid description: >- Select transactions by location ID to be included in the report. :::info For more information, see: [Locations](/docs/api/merchant#tag-locations). ::: Report-Run-Filter: type: object description: Filtering parameters to be applied to the report. properties: from: $ref: "#/components/schemas/Report-Run-From" to: $ref: "#/components/schemas/Report-Run-To" entity_types: $ref: "#/components/schemas/Report-Run-Entity-Types" entity_states: $ref: "#/components/schemas/Report-Run-Entity-States" currency: $ref: "#/components/schemas/Report-Run-Currency" location_id: $ref: "#/components/schemas/Report-Run-Location-Id" required: - from - to Report-Run-Format: type: string enum: - csv description: Format of the generated report file. examples: - csv Report-Run-Type: type: string description: >- Type of the report. Possible values: | Type of report | Description | | -------------- | ----------- | | `settlement_report` | Settlement report is a report including transactions settled to the user account. This parameter sets the predefined `options` and list of represented columns. | | `custom_report` | Custom reports require users to define `options`. | | `payout_statement_report` | Payout statement Reports provide a detailed breakdown of all transactions contributing to a specific payout amount. It requires the additional parameter `filter.payout_id`, which should be obtained from the payout ID retrieved via the [payout list endpoint](/docs/api/merchant#retrieve-payout-list) or from [webhook events](/docs/api/merchant#create-webhook). | | `icpp_fee_breakdown_report` | IC++ fee breakdown reports provide a detailed breakdown of fees for each IC++ transaction related to a payout. It requires the additional parameter `filter.icpp_charge_id`, which should be obtained from the `related_icpp_charge_id` column in the Payout statement report. A separate report should be generated for each IC++ transaction. | | `payments_report` | Payments report provides details of all payments associated with a Merchant account, including failed and declined payments. Supports filtering by `from` and `to` creation timestamps, and optionally by `entity_states`. | enum: - settlement_report - custom_report - payout_statement_report - icpp_fee_breakdown_report - payments_report examples: - settlement_report Report-Run-Options: type: object description: Further options to customize the report. properties: timezone: type: string description: >- Defaults to `ETC/UTC`. Defines the output timezone for all timestamps displayed in the report. Has no effect on `from` or `to` parameters. examples: - Europe/London columns: type: array items: type: string description: >- Names of the columns to be included in the report. If the `columns` parameter is not defined in the request, all available columns will be included in the report. An empty array will return an error. If you created orders using the `metadata` object, you can include them in the report by adding them with `metadata.` prefix. For example: `metadata.custom_attribute`. Available columns: | Column name | Description | | ----------- | ----------- | | `transaction_id` | Unique identifier of the transaction related to an order. | | `order_id` | Unique identifier of the order. | | `started_date` | Date and time the transaction was created. | | `updated_date` | Date and time the transaction was last updated. | | `completed_date` | Date and time the transaction was completed. | | `type` | Type of the order. | | `state` | State of the order. | | `description` | Description of the order. | | `merchant_order_ext_ref` | Merchant's order identifier for external reference. | | `customer_id` | Unique identifier of the customer related to an order. | | `amount` | Total amount of the order. | | `currency` | The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code that represents the currency of the order. | | `settlement_amount` | Total amount settled on the merchant's account. | | `settlement_currency` | The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code that represents the currency of the settled amount. | | `fee_amount` | Total amount of extra fees applied to the order. | | `fee_currency` | The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code that represents the currency of extra fees. | | `processing_fee_amount` | Total amount of processing fees applied to the order. | | `processing_fee_currency` | The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code that represents the currency of processing fees. | | `payment_method` | Type of the payment method the customer used to pay for the order. | | `browser_url` | The URL where the customer initiated the payment. | | `related_icpp_charge_id` | Unique identifier of the IC++ charge related to the transaction. **This column is only available in the `payout_statement_report`.** | | `location_id` | Unique identifier of the location related to the transaction. **This column is only available in `settlement_report` and `custom_report`.** | examples: - - transaction_id - amount - metadata.custom_attribute Report-Run-Settlement-Report: title: Settlement report type: object description: A settlement report contains all the query information for generating reports of settled transactions associated with a Merchant account. properties: filter: $ref: "#/components/schemas/Report-Run-Filter" format: $ref: "#/components/schemas/Report-Run-Format" type: $ref: "#/components/schemas/Report-Run-Type" options: $ref: "#/components/schemas/Report-Run-Options" required: - filter - format - type Report-Run-Custom-Report: title: Custom report type: object description: A custom report contains all the query information for generating reports of selected transactions associated with a Merchant account. properties: filter: $ref: "#/components/schemas/Report-Run-Filter" format: $ref: "#/components/schemas/Report-Run-Format" type: $ref: "#/components/schemas/Report-Run-Type" options: $ref: "#/components/schemas/Report-Run-Options" required: - filter - format - type Payout-Id: type: string format: uuid description: Permanent payout ID used for payouts operations. Report-Run-Payout-Filter: type: object description: Filtering parameters to be applied to the report. properties: payout_id: $ref: "#/components/schemas/Payout-Id" required: - payout_id Report-Run-Payout-Report: title: Payout settlement report type: object description: A payout settlement report contains all the query information for generating reports of a selected payout associated with a Merchant account. properties: filter: $ref: "#/components/schemas/Report-Run-Payout-Filter" format: $ref: "#/components/schemas/Report-Run-Format" type: $ref: "#/components/schemas/Report-Run-Type" options: $ref: "#/components/schemas/Report-Run-Options" required: - filter - format - type Icpp-Charge-Id: type: string format: uuid description: >- Permanent ID of of the IC++ fee related to a payout transaction. This ID can be obtained from the `related_icpp_charge_id` column of a payout statement report. Report-Run-Icpp-Filter: type: object description: Filtering parameters to be applied to the report. properties: icpp_charge_id: $ref: "#/components/schemas/Icpp-Charge-Id" required: - icpp_charge_id Report-Run-Icpp-Report: title: IC++ fee breakdown report type: object description: A IC++ fee breakdown report contains all the query information for generating reports of fees for each IC++ transaction related to a payout. properties: filter: $ref: "#/components/schemas/Report-Run-Icpp-Filter" format: $ref: "#/components/schemas/Report-Run-Format" type: $ref: "#/components/schemas/Report-Run-Type" options: $ref: "#/components/schemas/Report-Run-Options" required: - filter - format - type Report-Run-Payments-Entity-States: type: array items: type: string enum: - completed - failed - declined - cancelled description: |- Select payments by state to be included in the report. If not provided, payments in all states will be included in the report. Report-Run-Payments-Filter: type: object description: Filtering parameters to be applied to the report. properties: from: $ref: "#/components/schemas/Report-Run-From" to: $ref: "#/components/schemas/Report-Run-To" entity_states: $ref: "#/components/schemas/Report-Run-Payments-Entity-States" required: - from - to Report-Run-Payments-Options: type: object description: Further options to customize the report. properties: timezone: type: string description: >- Defaults to `ETC/UTC`. Defines the output timezone for all timestamps displayed in the report. Has no effect on `from` or `to` parameters. examples: - Europe/London columns: type: array items: type: string description: >- Names of the columns to be included in the report. If the `columns` parameter is not defined in the request, all available columns will be included in the report. An empty array will return an error. Available columns: | Column name | Description | | ----------- | ----------- | | `payment_id` | Unique identifier of the payment. | | `type` | Type of the payment, for example: `PAYMENT` or `REFUND`. | | `description` | Description of the payment. | | `original_payment_id` | For refunds, the unique identifier of the original payment. | | `order_id` | Unique identifier of the order associated with the payment. | | `state` | State of the payment, for example: `COMPLETED`, `FAILED`, or `DECLINED`. | | `reason` | Reason for a failed or declined payment, for example: `Insufficient Funds`. | | `amount` | Total amount of the payment. | | `currency` | The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code of the payment. | | `surcharge_amount` | Surcharge amount applied to the payment, if any. | | `tip_amount` | Tip amount included in the payment, if any. | | `refunded_amount` | Amount refunded for the payment. | | `created_date` | Date and time the payment was created. | | `merchant_order_ext_ref` | Merchant's order identifier for external reference. | | `payment_method` | Payment method used, for example: `CARD` or `PAY_WITH_REVOLUT`. | | `location_id` | Unique identifier of the location where the payment was made. | | `customer_id` | Unique identifier of the customer. | | `customer_card_number` | Masked card number used for the payment. | | `customer_card_country` | Country of the card used for the payment, as an [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) code. | | `customer_card_brand` | Card brand used for the payment, for example: `VISA` or `MASTERCARD_DEBIT`. | | `customer_card_type` | Card funding type, for example: `DEBIT` or `PREPAID`. | | `customer_card_category` | Card category, for example: `consumer` or `business`. | | `customer_email` | Email address of the customer. | | `fee_amount` | Total fee amount charged for the payment. | | `fee_currency` | The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code of the fee. | examples: - - payment_id - type - state - amount - currency Report-Run-Payments-Report: title: Payments report type: object description: A payments report contains all the query information for generating reports of payments associated with a Merchant account, including failed and declined payments. properties: filter: $ref: "#/components/schemas/Report-Run-Payments-Filter" format: $ref: "#/components/schemas/Report-Run-Format" type: $ref: "#/components/schemas/Report-Run-Type" options: $ref: "#/components/schemas/Report-Run-Payments-Options" required: - filter - format - type Report-Run-Details: title: ReportRunDetails type: object description: The `ReportRunDetails` object contains all information associated with a specific report run, identified by the `report_run_id`. properties: report_run_id: type: string format: uuid description: Unique ID used for accessing report details. Use this to check report generation status. status: type: string description: Current status of the report run. enum: - processing - completed - failed - expired file_url: type: string description: Use this link to download report file. Not available, until `status` is `completed`. required: - report_run_id - status Report-Run-Error: title: Report run error type: object properties: code: type: string description: >- An identifier that can be used to determine what went wrong. Error codes are not globally unique, but uniqueness is guaranteed within endpoints. message: type: string description: Some human readable text describing what went wrong. timestamp: type: integer description: The date and time the error happened. required: - code - message - timestamp Webhook-Id: type: string format: uuid description: The ID of the webhook. Webhook-Url: type: string format: uri pattern: ^https?:\/{2}.+/gi maxLength: 2000 description: >- Your webhook's URL to which event notifications will be sent. Must be a valid HTTP or HTTPS URL, capable of receiving `POST` requests. :::warning Restrictions: - Must be a valid URI as defined by [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986) - URI scheme is required and must be either `http` or `https` - URI host is required and cannot be `localhost` or an IP address - Max length: `2000` - Reserved or invalid characters must be percent-encoded (for example, use `%20` instead of a space) ::: Webhook-Events: type: array description: >- List of event types that the webhook is configured to listen to. Each event is related to status changes of a specific object in the Merchant API: | Object | Event types | | --------- | ----------- | | `Order` |
  • `ORDER_COMPLETED`
  • `ORDER_AUTHORISED`
  • `ORDER_CANCELLED`
  • `ORDER_FAILED`
  • `ORDER_INCREMENTAL_AUTHORISATION_AUTHORISED`
  • `ORDER_INCREMENTAL_AUTHORISATION_DECLINED`
  • `ORDER_INCREMENTAL_AUTHORISATION_FAILED`
| | `Payment` |
  • `ORDER_PAYMENT_AUTHENTICATION_CHALLENGED`
  • `ORDER_PAYMENT_AUTHENTICATED`
  • `ORDER_PAYMENT_DECLINED`
  • `ORDER_PAYMENT_FAILED`
| | `Subscription` |
  • `SUBSCRIPTION_INITIATED`
  • `SUBSCRIPTION_FINISHED`
  • `SUBSCRIPTION_CANCELLED`
  • `SUBSCRIPTION_OVERDUE`
| | `Payout` |
  • `PAYOUT_INITIATED`
  • `PAYOUT_COMPLETED`
  • `PAYOUT_FAILED`
| | `Dispute` |
  • `DISPUTE_ACTION_REQUIRED`
  • `DISPUTE_UNDER_REVIEW`
  • `DISPUTE_WON`
  • `DISPUTE_LOST`
| items: type: string description: The available event types your can listen to. enum: - ORDER_COMPLETED - ORDER_AUTHORISED - ORDER_CANCELLED - ORDER_FAILED - ORDER_INCREMENTAL_AUTHORISATION_AUTHORISED - ORDER_INCREMENTAL_AUTHORISATION_DECLINED - ORDER_INCREMENTAL_AUTHORISATION_FAILED - ORDER_PAYMENT_AUTHENTICATION_CHALLENGED - ORDER_PAYMENT_AUTHENTICATED - ORDER_PAYMENT_DECLINED - ORDER_PAYMENT_FAILED - SUBSCRIPTION_INITIATED - SUBSCRIPTION_FINISHED - SUBSCRIPTION_CANCELLED - SUBSCRIPTION_OVERDUE - PAYOUT_INITIATED - PAYOUT_COMPLETED - PAYOUT_FAILED - DISPUTE_ACTION_REQUIRED - DISPUTE_UNDER_REVIEW - DISPUTE_WON - DISPUTE_LOST minItems: 1 Webhook: title: Webhook type: object description: >- A `webhook` (also called a web callback) allows your system to receive an event from a different app immediately after it happens. For example, you can subscribe to a webhook when an order changes from Pending to Completed. When the payment is cleared and the order is completed, Revolut servers will send a notification to the URL of your choice. This is a much more efficient way to know when an order is paid as opposed to trying to get the status of the order every few seconds. Many events that happen to a Revolut Merchant account are synchronous, which means that they arrive instantly and have immediate results. For example, a successful request to create a customer immediately returns a Customer object. Such requests don't require webhooks. The Revolut Merchant API supports webhooks for events such as `ORDER_COMPLETED` and `ORDER_AUTHORISED`. properties: id: $ref: "#/components/schemas/Webhook-Id" url: $ref: "#/components/schemas/Webhook-Url" events: $ref: "#/components/schemas/Webhook-Events" required: - id Webhook-Creation: title: Webhook schema for creation and update operations type: object properties: url: $ref: "#/components/schemas/Webhook-Url" events: $ref: "#/components/schemas/Webhook-Events" required: - url - events Webhook-Signing-Secret: type: string description: The signing secret for the webhook. Use it to verify the signature for the webhook request's payload. Webhook-With-Signing-Secret: title: Webhook with signing secret type: object properties: id: $ref: "#/components/schemas/Webhook-Id" url: $ref: "#/components/schemas/Webhook-Url" events: $ref: "#/components/schemas/Webhook-Events" signing_secret: $ref: "#/components/schemas/Webhook-Signing-Secret" required: - id - signing_secret Webhook-Callback-Event: type: string enum: - ORDER_COMPLETED - ORDER_AUTHORISED - ORDER_CANCELLED - ORDER_FAILED - ORDER_INCREMENTAL_AUTHORISATION_AUTHORISED - ORDER_INCREMENTAL_AUTHORISATION_DECLINED - ORDER_INCREMENTAL_AUTHORISATION_FAILED - ORDER_PAYMENT_AUTHENTICATION_CHALLENGED - ORDER_PAYMENT_AUTHENTICATED - ORDER_PAYMENT_DECLINED - ORDER_PAYMENT_FAILED - SUBSCRIPTION_INITIATED - SUBSCRIPTION_FINISHED - SUBSCRIPTION_CANCELLED - SUBSCRIPTION_OVERDUE - PAYOUT_INITIATED - PAYOUT_COMPLETED - PAYOUT_FAILED - DISPUTE_ACTION_REQUIRED - DISPUTE_UNDER_REVIEW - DISPUTE_WON - DISPUTE_LOST description: >- The event type of the webhook notification that's sent by Revolut to your webhook URL. Each event is related to status changes of a specific object in the Merchant API: | Object | Event types | | --------- | ----------- | | `Order` |
  • `ORDER_COMPLETED`
  • `ORDER_AUTHORISED`
  • `ORDER_CANCELLED`
  • `ORDER_FAILED`
  • `ORDER_INCREMENTAL_AUTHORISATION_AUTHORISED`
  • `ORDER_INCREMENTAL_AUTHORISATION_DECLINED`
  • `ORDER_INCREMENTAL_AUTHORISATION_FAILED`
| | `Payment` |
  • `ORDER_PAYMENT_AUTHENTICATION_CHALLENGED`
  • `ORDER_PAYMENT_AUTHENTICATED`
  • `ORDER_PAYMENT_DECLINED`
  • `ORDER_PAYMENT_FAILED`
| | `Subscription` |
  • `SUBSCRIPTION_INITIATED`
  • `SUBSCRIPTION_FINISHED`
  • `SUBSCRIPTION_CANCELLED`
  • `SUBSCRIPTION_OVERDUE`
| | `Payout` |
  • `PAYOUT_INITIATED`
  • `PAYOUT_COMPLETED`
  • `PAYOUT_FAILED`
| | `Dispute` |
  • `DISPUTE_ACTION_REQUIRED`
  • `DISPUTE_UNDER_REVIEW`
  • `DISPUTE_WON`
  • `DISPUTE_LOST`
| Webhook-Order-Event: type: object properties: event: $ref: "#/components/schemas/Webhook-Callback-Event" order_id: type: string format: uuid description: The ID of the order the event is related to. merchant_order_ext_ref: type: string description: |- The information sent during order creation in the `merchant_order_data.reference` field. incremental_authorisation_ext_reference: type: string description: The reference sent in the `reference` field of the [Increment authorisation](/docs/api/merchant#increment-authorisation) request. Only present for incremental authorisation events. required: - event - order_id Webhook-Subscription-Event: type: object properties: event: $ref: "#/components/schemas/Webhook-Callback-Event" subscription_id: type: string format: uuid description: The ID of the subscription the event is related to. external_reference: type: string description: The information sent in the `external_reference` field of the [Create a subscription](/docs/api/merchant#create-subscription) request. required: - event - subscription_id Webhook-Payout-Event: type: object properties: event: $ref: "#/components/schemas/Webhook-Callback-Event" payout_id: type: string format: uuid description: The ID of the payout the event is related to. required: - event - payout_id Webhook-Dispute-Event: type: object properties: event: $ref: "#/components/schemas/Webhook-Callback-Event" dispute_id: type: string format: uuid description: The ID of the dispute the event is related to. required: - event - dispute_id 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). ::: Synchronous-Webhook: title: SynchronousWebhook type: object properties: id: type: string format: uuid description: The ID of the synchronous webhook object. signing_key: type: string pattern: ^swsk_[a-zA-Z0-9]{32}$ description: "A randomly generated signing key, which can be used by merchants to authenticate requests from Revolut by verifying the signature. For more information, see: [Verify the payload signature](/docs/guides/merchant/monitor-and-observe/webhooks/verif\ y-the-payload-signature)." url: type: string format: uri pattern: ^https:\/{2}.+/gi maxLength: 2000 description: >- The valid URL of the endpoint, that uses HTTPS URL schema. Revolut sends the shipping address of the customer to this URL for validation. :::warning Restrictions: - Must be a valid URI as defined by [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986) - URI scheme is required and must be `https` - URI host is required and cannot be `localhost` or an IP address - Max length: `2000` - Reserved or invalid characters must be percent-encoded (for example, use `%20` instead of a space) ::: event_type: type: string enum: - fast_checkout.validate_address description: >- Type of event this synchronous webhook is configured for. :::note At the moment, synchronous webhooks only support address validation events. ::: location_id: $ref: "#/components/schemas/Location-Id" required: - id - signing_key - url - event_type Synchronous-Webhook-Creation: title: SynchronousWebhookCreation type: object description: >- The `SynchronousWebhook` object allows merchants to register endpoints on their backend for receiving predefined event types. Currently, only address validation events are available. In addition, merchants can specify locations representing their online stores, enabling them to set up different webhooks for different stores. properties: event_type: type: string enum: - fast_checkout.validate_address description: >- Type of event this synchronous webhook is configured for. :::note At the moment, synchronous webhooks only support address validation events. ::: url: type: string format: uri pattern: ^https:\/{2}.+/gi maxLength: 2000 description: >- The valid URL of the endpoint, that uses HTTPS URL schema. Revolut sends the shipping address of the customer to this URL for validation. :::warning Restrictions: - Must be a valid URI as defined by [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986) - URI scheme is required and must be `https` - URI host is required and cannot be `localhost` or an IP address - Max length: `2000` - Reserved or invalid characters must be percent-encoded (for example, use `%20` instead of a space) ::: location_id: $ref: "#/components/schemas/Location-Id" required: - event_type - url Location-Name: type: string description: |- Name of the location. :::warning The `name` parameter's value must be unique across all locations. ::: Location-Type: type: string description: |- Type of the location. | Value | Description | | ----- | ----------- | | `online` | Represents an online store. | | `physical` | Represents a physical point of sale. | enum: - online - physical Location-Online-Details: type: object description: Additional details of the location. properties: domain: type: string description: |- Domain address of the location. Required for online locations. :::warning The `domain` parameter's value must be unique across all locations. ::: required: - domain Location-Online: type: object properties: id: $ref: "#/components/schemas/Location-Id" name: $ref: "#/components/schemas/Location-Name" type: $ref: "#/components/schemas/Location-Type" details: $ref: "#/components/schemas/Location-Online-Details" required: - id - name - type - details Address-v3: type: object description: Details of a physical address. properties: street_line_1: type: string description: Primary address line. maxLength: 100 street_line_2: type: string description: Secondary address line, such as floor and apartment number. maxLength: 100 region: type: string description: State or province of the address. maxLength: 100 city: type: string description: City of the address. maxLength: 100 country_code: type: string pattern: ^[A-Z]{2}$ description: ISO 2-letter country code. minLength: 2 maxLength: 2 postcode: type: string description: Postal code of the address. maxLength: 100 required: - street_line_1 - city - country_code - postcode Geo-Location: type: object description: Coordinates of the location. properties: lat: type: number format: double description: The latitude of the location, in decimal degrees. minimum: -90 maximum: 90 lon: type: number format: double description: To longitude of the location, in decimal degrees. minimum: -180 maximum: 180 required: - lat - lon Day-Opening-Hours: type: array description: |- A list of one or more time intervals for a single day. A day can have multiple intervals (e.g., closing for a lunch break). items: type: object properties: from: type: string format: time description: >- The local time when the interval begins. :::note The format is `hh:mm[:ss]`; seconds are optional and must be `00` if provided. ::: examples: - 09:00:00 to: type: string format: time description: >- The local time when the interval ends. :::note The format is `hh:mm[:ss]`; seconds are optional and must be `00` if provided. ::: examples: - 18:00:00 required: - from - to Opening-Hours: type: object description: |- An object containing the opening hours for each day of the week. A day can have multiple intervals (e.g., closing for a lunch break). properties: monday: description: Opening hours for Monday. $ref: "#/components/schemas/Day-Opening-Hours" tuesday: description: Opening hours for Tuesday. $ref: "#/components/schemas/Day-Opening-Hours" wednesday: description: Opening hours for Wednesday. $ref: "#/components/schemas/Day-Opening-Hours" thursday: description: Opening hours for Thursday. $ref: "#/components/schemas/Day-Opening-Hours" friday: description: Opening hours for Friday. $ref: "#/components/schemas/Day-Opening-Hours" saturday: description: Opening hours for Saturday. $ref: "#/components/schemas/Day-Opening-Hours" sunday: description: Opening hours for Sunday. $ref: "#/components/schemas/Day-Opening-Hours" Location-Physical-Details: type: object description: Additional details of the location. properties: address: $ref: "#/components/schemas/Address-v3" geo_location: $ref: "#/components/schemas/Geo-Location" opening_hours: $ref: "#/components/schemas/Opening-Hours" required: - address - geo_location - opening_hours Location-Physical: title: Location type: object properties: id: $ref: "#/components/schemas/Location-Id" name: $ref: "#/components/schemas/Location-Name" type: $ref: "#/components/schemas/Location-Type" details: $ref: "#/components/schemas/Location-Physical-Details" required: - id - name - type - details Location: title: Location type: object description: Location object represents merchant locations depending on type. oneOf: - $ref: "#/components/schemas/Location-Online" - $ref: "#/components/schemas/Location-Physical" discriminator: propertyName: type mapping: online: "#/components/schemas/Location-Online" physical: "#/components/schemas/Location-Physical" Location-Creation-Online: type: object properties: name: $ref: "#/components/schemas/Location-Name" type: $ref: "#/components/schemas/Location-Type" details: $ref: "#/components/schemas/Location-Online-Details" required: - name - type - details Location-Creation-Physical: type: object properties: name: $ref: "#/components/schemas/Location-Name" type: $ref: "#/components/schemas/Location-Type" details: $ref: "#/components/schemas/Location-Physical-Details" required: - name - type - details Location-Creation: type: object description: Request body for creating a location. The structure of the `details` object depends on the `type` of the location. oneOf: - $ref: "#/components/schemas/Location-Creation-Online" - $ref: "#/components/schemas/Location-Creation-Physical" discriminator: propertyName: type mapping: online: "#/components/schemas/Location-Creation-Online" physical: "#/components/schemas/Location-Creation-Physical" Location-Update-Online: type: object properties: name: $ref: "#/components/schemas/Location-Name" details: $ref: "#/components/schemas/Location-Online-Details" Location-Update-Physical: title: Location type: object description: Location object represents merchant locations depending on type. oneOf: - $ref: "#/components/schemas/Location-Online" - $ref: "#/components/schemas/Location-Physical" discriminator: propertyName: type mapping: online: "#/components/schemas/Location-Online" physical: "#/components/schemas/Location-Physical" Location-Update: type: object description: Request body for updating a location. The structure of the `details` object depends on the `type` of the location. oneOf: - $ref: "#/components/schemas/Location-Update-Online" - $ref: "#/components/schemas/Location-Update-Physical" discriminator: propertyName: type mapping: online: "#/components/schemas/Location-Update-Online" physical: "#/components/schemas/Location-Update-Physical" callbacks: Webhook-Event: "{$request.body#/url}": post: summary: Send webhook event to webhook URL description: |- The following webhook event payload is sent as a HTTP POST request to the URL registered as the merchant's webhook server via the [Create a webhook](/docs/api/merchant#create-webhook) operation. The delivery of the webhook events happen asynchronously, based on the events you subscribed to. :::info For more information, see: [Use webhooks to track order and payment lifecycle](/docs/guides/merchant/monitor-and-observe/webhooks/using-webhooks). ::: ### IP allowlisting To ensure secure delivery of webhook events, please allowlist the following IP addresses from which the events originate: **Production webhook IPs:** - `35.246.21.235` - `34.89.70.170` **Sandbox webhook IPs:** - `35.242.130.242` - `35.242.162.241` parameters: - name: Revolut-Request-Timestamp in: header required: true schema: type: string description: |- The [UNIX timestamp](https://www.unixtimestamp.com/) of the date and time when the webhook event was sent from Revolut. Used to verify the webhook event payload was actually sent by Revolut. :::info For more information, see: [Verify payload signature](/docs/guides/merchant/monitor-and-observe/webhooks/verify-the-payload-signature) ::: - name: Revolut-Signature in: header required: true schema: type: string description: |- The payload signature computed by Revolut using a Hash-based Message Authentication Code (HMAC). Used to verify the webhook event payload was actually sent by Revolut. :::info For more information, see: [Verify payload signature](/docs/guides/merchant/monitor-and-observe/webhooks/verify-the-payload-signature) ::: requestBody: required: true content: application/json: schema: discriminator: propertyName: event mapping: Order or payment event: "#/components/schemas/Webhook-Order-Event" Subscription: "#/components/schemas/Webhook-Subscription-Event" Payout event: "#/components/schemas/Webhook-Payout-Event" Dispute event: "#/components/schemas/Webhook-Dispute-Event" oneOf: - $ref: "#/components/schemas/Webhook-Order-Event" - $ref: "#/components/schemas/Webhook-Subscription-Event" - $ref: "#/components/schemas/Webhook-Payout-Event" - $ref: "#/components/schemas/Webhook-Dispute-Event" examples: order_event: summary: Webhook event related to an order or payment value: event: ORDER_COMPLETED order_id: 6634c172-3398-ac93-aee9-50de0282e3ac merchant_order_ext_ref: "Example reference #123" subscription_event: summary: Webhook event related to a subscription value: event: SUBSCRIPTION_INITIATED subscription_id: 550e8400-e29b-41d4-a716-446655440000 external_reference: ext-ref-12345 incremental_auth_authorised: summary: Webhook event for successful incremental authorisation value: event: ORDER_INCREMENTAL_AUTHORISATION_AUTHORISED order_id: 6634c172-3398-ac93-aee9-50de0282e3ac incremental_authorisation_ext_reference: CHG-67890 incremental_auth_declined: summary: Webhook event for declined incremental authorisation value: event: ORDER_INCREMENTAL_AUTHORISATION_DECLINED order_id: 6634c172-3398-ac93-aee9-50de0282e3ac incremental_authorisation_ext_reference: CHG-67891 incremental_auth_failed: summary: Webhook event for failed incremental authorisation value: event: ORDER_INCREMENTAL_AUTHORISATION_FAILED order_id: 6634c172-3398-ac93-aee9-50de0282e3ac incremental_authorisation_ext_reference: CHG-67892 payout_event: summary: Webhook event related to a payout value: event: PAYOUT_COMPLETED payout_id: 6634c172-3398-ac93-aee9-50de0282e3ac dispute_event: summary: Webhook event related to a dispute value: event: DISPUTE_ACTION_REQUIRED dispute_id: ab934829-e4ba-4e7f-8a21-365cad85c763 responses: "204": description: >- If the webhook event was delivered successfully, we recommend to respond with a `204` code. :::info You can respond to and acknowledge the delivery of a webhook event by any HTTP response code between `200-399`. ::: 4XX: description: If the webhook event delivery times out or the delivery of the events fails, you can respond with any HTTP `4XX` code. In this case, Revolut will retry sending the webhook event 3 more times, each with a 10-minute delay. examples: 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 x-ext-urls: {}