---
api: 'Merchant API'
---
# Create an order
Create an `Order` object.
Creating orders is one of the basic operations of the Merchant API. Most of the other operations are related to creating orders. Furthermore, the payment methods merchants can use to take payments for their orders are also built on order creation.
To learn more about how you can accept payments, see:
- [Revolut Pay](/docs/guides/merchant/accept-payments/online-payments/revolut-pay/introduction)
- [Card payments](/docs/guides/merchant/accept-payments/online-payments/card-payments/introduction)
- [Apple Pay and Google Pay](/docs/guides/merchant/accept-payments/online-payments/apple-pay-google-pay/introduction)
- [Pay by Bank](/docs/guides/merchant/accept-payments/online-payments/pay-by-bank/introduction)
- [Revolut Checkout](/docs/guides/merchant/accept-payments/online-payments/revolut-checkout/introduction)
- [Hosted Checkout Page](/docs/guides/merchant/accept-payments/online-payments/hosted-checkout-page/introduction)
### Pre-authorisation and incremental authorisation
Orders can be created with `authorisation_type: pre_authorisation` to enable incremental authorisation. This allows you to increase the authorised amount after the initial authorisation.
**Requirements:**
- `capture_mode` must be set to `manual`
- `authorisation_type` must be set to `pre_authorisation`
**Payment method support:**
Pre-authorisation orders support card, Apple Pay, and Google Pay only — enforced at the API level and on the hosted checkout page. Revolut Pay account-to-account (A2A) payments, Pay by Bank, and SEPA Direct Debit are not supported for pre-authorisation orders.
**`cancel_authorised_after`:**
For pre-authorisation orders, `cancel_authorised_after` can be set to a maximum of 30 days (`P30D`). For final authorisation orders, the 7-day maximum (`P7D`) still applies. If omitted, only `capture_deadline` governs expiry.
**Example use cases:**
- Hotels: authorise deposit, then increment for room service and minibar
- Car rentals: authorise deposit, then increment for damages or fuel
:::info
For more information, see:
- [Pre-authorisation guide](/docs/guides/merchant/operations/capture-and-settlement/advanced-authorisation/pre-authorisation)
- [Incremental authorisation guide](/docs/guides/merchant/operations/capture-and-settlement/advanced-authorisation/incremental-authorisation)
- [Increment authorisation endpoint](/docs/api/merchant#increment-authorisation)
:::
Industry-specific requirements
If you operate in any of the industries listed below, sharing industry-specific data is mandatory. Not providing the necessary information will result in further scrutiny from Revolut and/or the imposition of risk mitigation actions.
| Industry | Related fields |
| ------- | --------------- |
| Retail merchants | `line_items`, `shipping` |
| Airlines | `industry_data` with `type: airline` |
| Car rentals | `industry_data` with `type: car_rental` |
| Hotels & accommodation | `industry_data` with `type: lodging` |
| Travel agencies (OTAs) | `industry_data` with `type: airline` and `industry_data` with `type: lodging` |
| Crypto merchants | `industry_data` with `type: crypto` |
| Event ticket sellers | `industry_data` with `type: event` |
| Marketplace merchants | `industry_data` with `type: marketplace` |
## Endpoint
POST `/api/orders`
## Request body
### Attributes
- `amount` (integer)
The order total expressed in minor currency units, according to the [ISO 4217 standard](https://en.wikipedia.org/wiki/ISO_4217). For example, `7034` in `EUR` corresponds to €70.34.
:::info
- Conversion between major and minor units varies by currency. For instance, `100` minor units equal £1.00 in `GBP`, whereas in `ISK` they represent 100 units. For more details, see the [ISO 4217 standard](https://en.wikipedia.org/wiki/ISO_4217).
- If `line_items` are provided, the order `amount` must equal the sum of all line items' `total_amount`.
- For card payments with a non-zero amount, the order `amount` must be at least **$0.005** (or equivalent in different currencies, calculated using Revolut's exchange rate on the payment date). Otherwise, card payments can't be performed.
:::
- `currency` (string)
[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` (string, optional)
[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/).
:::
- `description` (string, optional)
The description of the order.
- `customer` (object, optional)
Object containing information about a customer.
If you have it, we strongly advise providing at least either `id`, `phone`, or `email`.
Using the [Customers operations](/docs/api/merchant#tag-customers), you can manage customer instances.
The following behaviours apply to different use cases:
| Use case | API behavior |
| -------- | ------------ |
| Existing customer | If `id` was provided, we ignore other customer details and associate the customer with the order.
If either `email`, `phone`, or `full_name` was provided (without an existing customer's `id`), we always create a new customer, irrespective of another, existing customer object having the same details. |
| New customer | If either `email`, `phone`, or `full_name` was provided, we create a new customer, irrespective of another customer object having the same details.
If `id` of a non-existent customer was provided, we return a `404` error, irrespective of other details provided. |
:::note
To avoid unintentional duplication of customer records, search for an existing customer by email or phone using the [List customers](/docs/api/merchant#retrieve-a-customer-list) endpoint first, then provide `customer.id` in the order.
:::
- `customer.id` (string, optional)
Permanent ID of a customer used to retrieve, update, delete a customer. This ID can also be used to link customer to an order.
:::note
If you provide the customer's ID during order creation, no other customer data is required, they will be parsed automatically from the referenced customer object.
:::
- `customer.full_name` (string, optional)
The full name of the customer.
- `customer.phone` (string, optional)
The phone number of the customer in [E.164 format](https://en.wikipedia.org/wiki/E.164).
- `customer.email` (string, optional)
The email address of the customer.
- `customer.date_of_birth` (string, optional)
The birth date of the customer.
- `enforce_challenge` (enum, optional)
The enforce challenge mode. `automatic` is used by default.
| Parameter value | Description |
| --------------- | ----------- |
| `automatic` | The payments created for an order will have challenge requirement calculated by our fraud mechanisms. Not all payments will trigger a 3DS challenge. |
| `forced` | The payments created for an order will always require a 3DS challenge. Currently only supported for card payments. |
Possible enum values:
- `automatic`
- `forced`
- `line_items` (array of object, optional)
An array of line items included in the order. Each line item represents an individual product or service, along with its quantity, price, taxes, and discounts.
:::info
Required for merchants collecting payment for one or multiple products/services in one transaction. Omitting this information may trigger additional scrutiny and risk mitigation actions by Revolut.
:::
- `line_items[].name` (string)
Name of the line item.
- `line_items[].type` (enum)
Type of the line item.
Possible enum values:
- `physical`
- `service`
- `line_items[].quantity` (object)
Object representing the quantity details of a line item, including the amount and its associated unit of measurement.
- `line_items[].quantity.value` (number)
The number of units of the line item.
- `line_items[].quantity.unit` (string, optional)
The measurement unit for the quantity, such as `cm`, or `kg`.
- `line_items[].unit_price_amount` (integer)
The unit price of the line item.
- `line_items[].total_amount` (integer)
The total amount to be paid for the line item, including taxes and discounts.
- `line_items[].external_id` (string, optional)
Unique identifier of line item in the merchant's system.
- `line_items[].discounts` (array of object, optional)
A list of discounts applied to the line item. Each discount should be subtracted from the total amount payable for the item.
- `line_items[].discounts[].name` (string)
The specific name or label of the discount applied to the line item.
- `line_items[].discounts[].amount` (integer)
The monetary value of the discount.
- `line_items[].taxes` (array of object, optional)
A list of taxes applied to the line item. Each tax should be added to the total amount payable for the item.
- `line_items[].taxes[].name` (string)
The specific name or designation of the tax applied to the line item.
- `line_items[].taxes[].amount` (integer)
The monetary value of the tax in minor currency units (e.g., cents for EUR).
- `line_items[].image_urls` (array of string, optional)
A list of URLs pointing to images related to the line item. These images can provide visual details or representations of the item.
- `line_items[].description` (string, optional)
Description of the line item.
- `line_items[].url` (string, optional)
An HTTP/HTTPS URL that links to more information about the line item, such as a product page or details.
:::warning
Restrictions:
- Must be a valid URI as defined by [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986)
- URI scheme is required and must be either `http` or `https`
- URI host is required and cannot be `localhost` or an IP address
- Max length: `2000`
- Reserved or invalid characters must be percent-encoded (for example, use `%20` instead of a space)
:::
- `shipping` (object, optional)
Details about the shipping related to the order, including address, contact information, and individual shipments.
:::info
Required for merchants shipping physical goods. Omitting this information may trigger additional scrutiny and risk mitigation actions by Revolut.
:::
- `shipping.address` (object, optional)
Details of a physical address.
- `shipping.address.street_line_1` (string)
Primary address line.
- `shipping.address.street_line_2` (string, optional)
Secondary address line, such as floor and apartment number.
- `shipping.address.region` (string, optional)
State or province of the address.
- `shipping.address.city` (string)
City of the address.
- `shipping.address.country_code` (string)
ISO 2-letter country code.
- `shipping.address.postcode` (string)
Postal code of the address.
- `shipping.contact` (object, optional)
Contact details for someone responsible for the shipment.
:::warning
At least `email` or `phone` is required.
:::
- `shipping.contact.name` (string, optional)
Full name of the contact person.
- `shipping.contact.email` (string, optional)
Email address of the contact person.
- `shipping.contact.phone` (string, optional)
Phone number of the contact person.
- `shipping.shipments` (array of object, optional)
List of individual shipment details.
- `shipping.shipments[].shipping_company_name` (string)
Name of the company handling the shipment.
- `shipping.shipments[].tracking_number` (string)
Unique tracking number for the shipment.
- `shipping.shipments[].estimated_delivery_date` (string, optional)
Estimated delivery date and time for the shipment.
The time should also include the customer's timezone.
- `shipping.shipments[].tracking_url` (string, optional)
An HTTP/HTTPS URL where the shipment can be tracked.
:::warning
Restrictions:
- Must be a valid URI as defined by [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986)
- URI scheme is required and must be either `http` or `https`
- URI host is required and cannot be `localhost` or an IP address
- Max length: `2000`
- Reserved or invalid characters must be percent-encoded (for example, use `%20` instead of a space)
:::
- `capture_mode` (enum, optional)
The capture mode of the order. `automatic` is used by default.
| Parameter value | Description |
| --------------- | ----------- |
| `automatic` | The order is captured automatically after payment authorisation. |
| `manual` | The order is not captured automatically. You must manually capture the order later. |
:::info
For more information, see [Capture an order](/docs/api/merchant#capture-an-order).
:::
Possible enum values:
- `automatic`
- `manual`
- `authorisation_type` (enum, optional)
The type of authorisation for the order. Used with manual capture mode. If omitted, `final` is used by default.
### Pre-authorisation
Pre-authorisation allows you to reserve funds on a customer's card without immediately capturing them. This is useful for scenarios like:
- Hotel bookings where the final amount may vary
- Car rentals where additional charges may apply
- Deposits that need to be held temporarily
| Parameter value | Description |
| --------------- | ----------- |
| `final` | Standard authorisation for immediate or near-immediate capture. |
| `pre_authorisation` | Reserve funds for later capture, used with manual capture mode. |
:::note
Pre-authorisation must be used with `capture_mode: manual`. For more information, see [Capture an order](/docs/api/merchant#capture-an-order).
:::
Possible enum values:
- `final`
- `pre_authorisation`
- `cancel_authorised_after` (string, optional)
Automatic cancellation period for uncaptured orders, specified in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
After this period, the authorised payment is automatically cancelled and the order is cancelled.
Maximum period depends on the order's `authorisation_type`:
- `pre_authorisation`: 30 days = `P30D`
- `final`: 7 days = `P7D`
:::note
The following limitations apply:
- Cannot be a negative value.
- Cannot be updated if the new value is less than or equal to the elapsed time since authorisation.
**Failing scenario:**
- Original value: 7 days
- Time since authorisation: 3 days
- Update value: 2 days
In this scenario, an error is returned.
**Successful scenario:**
- Original value: 7 days
- Time since authorisation: 3 days
- Update value: 4 days
In this scenario, the parameter can be updated.
- Cannot be updated if cancellation is ≤ 30 minutes away.
**Failing scenario:**
- Original value: 12 hours
- Time since authorisation: 11 hours 40 minutes
In this scenario, an error is returned.
**Successful scenario:**
- Original value: 12 hours
- Time since authorisation: 11 hours 20 minutes
In this scenario, the parameter can be updated.
:::
- `expire_pending_after` (string, optional)
Automatic expiration period for pending orders, specified in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
Orders in `pending` state will be automatically failed if they stay unpaid for longer than the period specified.
When the order expires, it transitions to the `failed` state and an `ORDER_FAILED` webhook event is triggered.
:::note
- This field can only be set during order creation and cannot be updated afterward.
- Must be between `PT1M` (1 minute) and `PT720H` (30 days).
- Cannot be a negative value.
:::
- `location_id` (string, optional)
Unique ID representing the location where merchants sells products.
:::info
For more information, see: [Locations](/docs/api/merchant#tag-locations).
:::
- `metadata` (object, optional)
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}$`
:::
- `industry_data` (object, optional)
Object containing industry-specific information associated with the order.
You can provide data for one or multiple industries in a single order.
:::info
In the following cases, industry-specific info is required. Omitting this information may trigger additional scrutiny and risk mitigation actions by the Revolut risk team.
| Transaction type | Required for |
| ---------------- | ----------- |
| `airline` | Airlines and Online Travel Agencies (OTAs). |
| `car_rental` | Car Rental Merchants and Online Travel Agencies (OTAs). |
| `crypto` | Crypto merchants. |
| `marketplace` | Marketplace merchants. |
| `event` | Event ticket sellers. |
| `lodging` | Lodging providers. |
:::
- `industry_data.airline` (object, optional)
Object containing additional information about an airline booking associated with the order.
Use this object to provide required data to enable **Revolut Flight Alerts**. This feature allows users to receive real-time flight updates such as check-in reminders, boarding alerts, and notifications for cancellations or delays in the Revolut app.
To enable **Revolut Flight Alerts** functionalities in the Revolut app, the following fields are **required** on order creation or update, before capturing the order:
```
tickets_purchase,
journey_legs,
booking_url
```
:::note
These are the specific data field requirements for merchants who must provide airline data. Note that these requirements can be extended on a case by case basis as decided by Revolut.
| Required for airline/charter merchants | Required for OTA merchants |
| -------------------------------------- | -------------------------- |
| - `booking_id`
- `fulfillment_date`
- `passengers[].first_name`
- `passengers[].last_name`
- `journey_legs[].pnr`
- `journey_legs[].sequence`
- `journey_legs[].flight_number`
- `journey_legs[].travel_date`
- `journey_legs[].airline_code`
- `journey_legs[].departure_airport_code`
- `journey_legs[].arrival_airport_code`
| - `booking_id`
- `fulfillment_date`
- `passengers[].first_name`
- `passengers[].last_name`
- `journey_legs[].pnr`
- `journey_legs[].arrival_airport_code`
|
:::
- `industry_data.airline.booking_id` (string)
A unique identifier provided by the merchant associated with the order.
This `booking_id` is used to reference and correlate booking information with the Merchant API and the merchant's internal system.
- `industry_data.airline.fulfillment_date` (string, optional)
The UTC date and time of the final journey leg.
:::warning
The following limitations apply:
- When creating or updating an order, `fulfillment_date` cannot be set to a date in the past.
- When updating an order, if the current `fulfillment_date` value is already in the past, it cannot be modified. The date must remain as is to maintain data integrity for completed transactions.
:::
- `industry_data.airline.tickets_purchase` (boolean, optional)
Flag indicating whether the order includes actual ticket purchases. Set to `true` if the order contains ticket purchases, and `false` if it does not (e.g., it **only** contains seat reservations, or baggage upgrades).
:::info
This field is required for activating **Revolut Flight Alerts** functionalities within the Revolut app.
Provide the info on order creation or update, before capturing the order.
:::
- `industry_data.airline.ticket_type` (enum, optional)
The type of the ticket.
| Parameter value | Description |
| --------------- | ----------- |
| `fixed` | Non-modifiable once confirmed. |
| `flexible` | Allows modifications or cancellations under specified conditions. |
Possible enum values:
- `fixed`
- `flexible`
- `industry_data.airline.crs_code` (string, optional)
The code of the Computer Reservation System (CRS) used to make the booking and purchase the ticket.
- `industry_data.airline.ticket_change_indicator` (enum, optional)
Parameter indicating whether this order is related to a new ticket reservation or a modification of an existing one.
Possible enum values:
- `new`
- `modification`
- `industry_data.airline.refundability` (enum, optional)
Parameter indicating whether the booking is refundable, partially refundable, or not refundable.
Possible enum values:
- `refundable`
- `non_refundable`
- `partially_refundable`
- `industry_data.airline.passengers` (array of object, optional)
Array containing information of passengers associated with the booking.
- `industry_data.airline.passengers[].first_name` (string)
Passenger's first name.
- `industry_data.airline.passengers[].last_name` (string)
Passenger's last name.
- `industry_data.airline.journey_legs` (array of object, optional)
Array containing information of journey legs associated with the booking.
:::info
This field is required for activating **Revolut Flight Alerts** functionalities within the Revolut app.
This information is used to compile a tracking widget that provides real-time updates on flight status and sends notifications, such as a check-in reminders, boarding alerts, and notifications for cancellations or delays.
To enable the widget the following fields are required on order creation or update, before capturing the order:
```
sequence,
departure_airport_code,
arrival_airport_code,
flight_number,
travel_date,
airline_name,
airline_code,
```
:::
- `industry_data.airline.journey_legs[].sequence` (integer)
Sequence of the journey legs. Increment by 1 for each flight included in the ticket.
For example: For a `FRA > LHR > DUB > LHR > FRA` journey the sequence will be assigned as:
- `FRA > LHR`: 1
- `LHR > DUB`: 2
- `DUB > LHR`: 3
- `LHR > FRA`: 4
- `industry_data.airline.journey_legs[].departure_airport_code` (string)
The [IATA](https://www.iata.org/en/services/codes) 3-letter airport code for the departure airport.
- `industry_data.airline.journey_legs[].arrival_airport_code` (string)
The [IATA](https://www.iata.org/en/services/codes) 3-letter airport code for the arrival airport.
- `industry_data.airline.journey_legs[].flight_number` (string, optional)
The flight identifier, without airline code.
- `industry_data.airline.journey_legs[].fare_base_code` (string, optional)
The fare base code for the given journey leg.
- `industry_data.airline.journey_legs[].travel_date` (string)
The UTC date and time of the flight departure for the given journey leg.
- `industry_data.airline.journey_legs[].airline_name` (string)
The name of the airline associated with the journey leg.
- `industry_data.airline.journey_legs[].airline_code` (string)
The IATA 2-letter accounting code identifying the airline associated with the journey leg.
- `industry_data.airline.journey_legs[].pnr` (string, optional)
The Passenger Name Record (PNR) for the journey leg issued by the airline.
PNR is a unique identifier for the booking, acting as a digital certificate allowing passengers to retrieve or manage their booking details.
:::warning
This is a required field for OTAs.
:::
- `industry_data.airline.booking_url` (string, optional)
URL to the online portal for managing the airline booking, which includes check-in functionality. This URL may be a personalised, pre-populated check-in link specific to the user or a generic link, and it is essential for enabling direct access to booking details within the Revolut app.
:::info
This field is required for activating **Revolut Flight Alerts** functionalities within the Revolut app.
Provide the info on order creation or update, before capturing the order.
:::
:::warning
Restrictions:
- Must be a valid URI as defined by [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986)
- URI scheme is required and must be either `http` or `https`
- URI host is required and cannot be `localhost` or an IP address
- Max length: `2000`
- Reserved or invalid characters must be percent-encoded (for example, use `%20` instead of a space)
:::
- `industry_data.car_rental` (object, optional)
Object containing additional information about a car rental booking associated with the order.
:::info
These are the specific data field requirements for merchants offering car rental. Note that these requirements can be extended on a case by case basis as decided by Revolut.
```
booking_id
drop_off_date
refundability
```
:::
- `industry_data.car_rental.booking_id` (string)
A unique identifier provided by the merchant associated with the order.
This `booking_id` is used to reference and correlate booking information with the Merchant API and the merchant's internal system.
- `industry_data.car_rental.pick_up_date` (string, optional)
The UTC date and time of the pick-up.
- `industry_data.car_rental.pick_up_location` (object, optional)
Object containing address details.
- `industry_data.car_rental.pick_up_location.street_line_1` (string, optional)
Street line 1 information.
- `industry_data.car_rental.pick_up_location.street_line_2` (string, optional)
Street line 2 information.
- `industry_data.car_rental.pick_up_location.region` (string, optional)
The region associated with the address.
- `industry_data.car_rental.pick_up_location.city` (string, optional)
The city associated with the address.
- `industry_data.car_rental.pick_up_location.country_code` (string)
The 2-letter country code of the country associated with the address.
- `industry_data.car_rental.pick_up_location.postcode` (string)
The postcode associated with the address.
- `industry_data.car_rental.drop_off_date` (string)
The UTC date and time of the drop-off.
- `industry_data.car_rental.drop_off_location` (object, optional)
Object containing address details.
- `industry_data.car_rental.drop_off_location.street_line_1` (string, optional)
Street line 1 information.
- `industry_data.car_rental.drop_off_location.street_line_2` (string, optional)
Street line 2 information.
- `industry_data.car_rental.drop_off_location.region` (string, optional)
The region associated with the address.
- `industry_data.car_rental.drop_off_location.city` (string, optional)
The city associated with the address.
- `industry_data.car_rental.drop_off_location.country_code` (string)
The 2-letter country code of the country associated with the address.
- `industry_data.car_rental.drop_off_location.postcode` (string)
The postcode associated with the address.
- `industry_data.car_rental.refundability` (enum, optional)
Parameter indicating whether the booking is refundable, partially refundable, or not refundable.
Possible enum values:
- `refundable`
- `non_refundable`
- `partially_refundable`
- `industry_data.car_rental.distance_limit` (object, optional)
Object containing distance limit information.
- `industry_data.car_rental.distance_limit.limit` (integer, optional)
The maximum distance allowed.
- `industry_data.car_rental.distance_limit.unit` (enum, optional)
The unit of distance.
Possible enum values:
- `miles`
- `km`
- `industry_data.car_rental.distance_limit.additional_distance_cost` (object, optional)
Cost for exceeding the distance limit.
- `industry_data.car_rental.distance_limit.additional_distance_cost.amount` (integer, optional)
The amount of the cost in minor currency units. For example, enter `7034` for €70.34.
- `industry_data.car_rental.distance_limit.additional_distance_cost.currency` (string, optional)
[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/).
:::
- `industry_data.crypto` (object, optional)
Object containing information about crypto transactions associated with the order.
:::info
Processing crypto on-ramp transactions with Revolut has additional compliance requirements. Please reach out to your account executive for additional details.
**Required data fields for crypto services:**
```
transactions[].id
transactions[].status
transactions[].recipient_wallet_id
seller.id
seller.name
seller.website
seller.phone
seller.address
seller.mcc
customer.full_name
customer.date_of_birth
```
Note that these requirements can be extended on a case by case basis as decided by Revolut.
:::
- `industry_data.crypto.transactions` (array of object)
Array of crypto transaction data associated with the order.
- `industry_data.crypto.transactions[].id` (string)
The public transaction hash of the crypto transaction.
- `industry_data.crypto.transactions[].status` (enum)
The status of the crypto transaction.
Possible enum values:
- `pending`
- `failed`
- `cancelled`
- `completed`
- `industry_data.crypto.transactions[].recipient_wallet_id` (string, optional)
The wallet ID of the recipient.
:::note
At least one of the parameters: `recipient_user_id` or `recipient_wallet_id` is required.
:::
- `industry_data.crypto.transactions[].recipient_user_id` (string, optional)
The user ID of the recipient.
:::note
At least one of the parameters: `recipient_user_id` or `recipient_wallet_id` is required.
:::
- `industry_data.crypto.seller` (object, optional)
Information about the crypto conversion affiliate.
This should be provided when a customer completes a payment on a subseller's website rather than directly on the merchant's website, providing insight into the type of business conducted by the subseller.
:::note
This needs to be provided only by crypto on-ramp providers for payments they are processing for conversion affiliates.
For their own payments, `seller` can be omitted.
:::
- `industry_data.crypto.seller.mcc` (string)
A string representing the four-digit [Merchant Category Code (MCC)](https://en.wikipedia.org/wiki/Merchant_category_code) of the conversion affiliate.
- `industry_data.crypto.seller.id` (string)
The ID of the seller in the merchant's internal system.
- `industry_data.crypto.seller.name` (string)
The business or legal name of the seller.
- `industry_data.crypto.seller.website` (string)
The URL of the website of the seller.
:::warning
Restrictions:
- Must be a valid URI as defined by [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986)
- URI scheme is required and must be either `http` or `https`
- URI host is required and cannot be `localhost` or an IP address
- Max length: `255`
- Reserved or invalid characters must be percent-encoded (for example, use `%20` instead of a space)
:::
- `industry_data.crypto.seller.phone` (string)
The phone number of the seller.
- `industry_data.crypto.seller.address` (object)
Details of a physical address.
- `industry_data.crypto.seller.address.street_line_1` (string)
Primary address line.
- `industry_data.crypto.seller.address.street_line_2` (string, optional)
Secondary address line, such as floor and apartment number.
- `industry_data.crypto.seller.address.region` (string, optional)
State or province of the address.
- `industry_data.crypto.seller.address.city` (string)
City of the address.
- `industry_data.crypto.seller.address.country_code` (string)
ISO 2-letter country code.
- `industry_data.crypto.seller.address.country_subdivision_code` (string, optional)
The subdivision code represents the state, province, or region within the country, following the [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2) standard. This code uniquely identifies subdivisions within a country.
For example, for London in the United Kingdom, use `GB-LND`.
:::warning
The parameter is required for countries listed on the [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2) page.
:::
- `industry_data.crypto.seller.address.postcode` (string)
Postal code of the address.
- `industry_data.marketplace` (object, optional)
This object is required by Mastercard and Visa for merchants operating as marketplaces under the Merchant Category Code (MCC) `5262`. The marketplace object ensures compliance with the card schemes' regulations by providing detailed information about the seller involved in the transaction.
:::info
These are the specific data field requirements for merchants who must provide marketplace data.
```
seller.id
seller.name
seller.website
seller.phone
seller.address
```
:::
- `industry_data.marketplace.seller` (object)
Information about the subseller on the marketplace platform.
- `industry_data.marketplace.seller.id` (string)
The ID of the seller in the merchant's internal system.
- `industry_data.marketplace.seller.name` (string)
The business or legal name of the seller.
- `industry_data.marketplace.seller.website` (string)
The URL of the website of the seller.
:::warning
Restrictions:
- Must be a valid URI as defined by [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986)
- URI scheme is required and must be either `http` or `https`
- URI host is required and cannot be `localhost` or an IP address
- Max length: `255`
- Reserved or invalid characters must be percent-encoded (for example, use `%20` instead of a space)
:::
- `industry_data.marketplace.seller.phone` (string)
The phone number of the seller.
- `industry_data.marketplace.seller.address` (object)
Details of a physical address.
- `industry_data.marketplace.seller.address.street_line_1` (string)
Primary address line.
- `industry_data.marketplace.seller.address.street_line_2` (string, optional)
Secondary address line, such as floor and apartment number.
- `industry_data.marketplace.seller.address.region` (string, optional)
State or province of the address.
- `industry_data.marketplace.seller.address.city` (string)
City of the address.
- `industry_data.marketplace.seller.address.country_code` (string)
ISO 2-letter country code.
- `industry_data.marketplace.seller.address.country_subdivision_code` (string, optional)
The subdivision code represents the state, province, or region within the country, following the [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2) standard. This code uniquely identifies subdivisions within a country.
For example, for London in the United Kingdom, use `GB-LND`.
:::warning
The parameter is required for countries listed on the [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2) page.
:::
- `industry_data.marketplace.seller.address.postcode` (string)
Postal code of the address.
- `industry_data.event` (object, optional)
Object containing booking information for a list of event tickets associated with the order.
:::info
These are the specific data field requirements for merchants who must provide event data. Note that these requirements can be extended on a case by case basis as decided by Revolut.
```
booking_id
events[].start_date
events[].end_date
events[].supplier
events[].tickets[].id
```
:::
- `industry_data.event.booking_id` (string)
A unique identifier provided by the merchant associated with the order.
This `booking_id` is used to reference and correlate booking information with the Merchant API and the merchant's internal system.
- `industry_data.event.events` (array of object, optional)
A list of events associated with the booking.
- `industry_data.event.events[].start_date` (string, optional)
[ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date and time when the event starts.
- `industry_data.event.events[].end_date` (string, optional)
[ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date and time when the event ends.
- `industry_data.event.events[].supplier` (string, optional)
Legal name of the ticket vendor/event organiser.
- `industry_data.event.events[].supplier_payment_date` (string, optional)
[ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date and time when the funds are released to merchants.
- `industry_data.event.events[].name` (string, optional)
The name of the event.
- `industry_data.event.events[].location` (object, optional)
The address of the event location.
- `industry_data.event.events[].location.street_line_1` (string)
Primary address line.
- `industry_data.event.events[].location.street_line_2` (string, optional)
Secondary address line, such as floor and apartment number.
- `industry_data.event.events[].location.region` (string, optional)
State or province of the address.
- `industry_data.event.events[].location.city` (string)
City of the address.
- `industry_data.event.events[].location.country_code` (string)
ISO 2-letter country code.
- `industry_data.event.events[].location.postcode` (string)
Postal code of the address.
- `industry_data.event.events[].category` (enum, optional)
The type of the event.
Possible enum values:
- `concert`
- `conference`
- `convention`
- `exhibition`
- `festival`
- `party`
- `performance`
- `other`
- `industry_data.event.events[].market` (enum, optional)
Indicates the relationship between the ticket vendor and the event organiser.
| Parameter value | Description |
| --------------- | ----------- |
| `primary` | The merchant is the organiser and primary distributor of the tickets. |
| `secondary` | The merchant is a reseller, only distributing the tickets. |
Possible enum values:
- `primary`
- `secondary`
- `industry_data.event.events[].tickets` (array of object, optional)
A list of tickets associated with the booking.
- `industry_data.event.events[].tickets[].id` (string)
A unique identifier provided by the merchant associated with the ticket.
- `industry_data.event.events[].tickets[].transferable` (boolean, optional)
Indicates whether the ticket is transferable to another buyer.
- `industry_data.event.events[].tickets[].refundability` (enum, optional)
Parameter indicating whether the booking is refundable, partially refundable, or not refundable.
Possible enum values:
- `refundable`
- `non_refundable`
- `partially_refundable`
- `industry_data.lodging` (object, optional)
Object containing details of a lodging booking.
:::info
These are the specific data field requirements for merchants who must provide lodging data. Note that these requirements can be extended on a case by case basis as decided by Revolut.
```
booking_id
lodgings[].check_in_date
lodgings[].check_out_date
lodgings[].supplier.payment_date
```
:::
- `industry_data.lodging.booking_id` (string)
A unique identifier provided by the merchant associated with the order.
This `booking_id` is used to reference and correlate booking information with the Merchant API and the merchant's internal system.
- `industry_data.lodging.lodgings` (array of object, optional)
List of lodging entries associated with this booking.
- `industry_data.lodging.lodgings[].check_in_date` (string, optional)
[ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date and time of the check-in.
- `industry_data.lodging.lodgings[].check_out_date` (string, optional)
[ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date and time of the check-out.
- `industry_data.lodging.lodgings[].category` (enum, optional)
The type of the accommodation associated with the booking.
Possible enum values:
- `bed_and_breakfast`
- `hostel`
- `hotel`
- `short_term_rental`
- `other`
- `industry_data.lodging.lodgings[].supplier` (object, optional)
Object containing supplier information about the lodging provider.
- `industry_data.lodging.lodgings[].supplier.id` (string, optional)
Unique identifier of the lodging supplier.
- `industry_data.lodging.lodgings[].supplier.name` (string, optional)
Legal name of the lodging supplier.
- `industry_data.lodging.lodgings[].supplier.payment_date` (string, optional)
[ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date and time when the funds are released to merchants.
- `industry_data.lodging.lodgings[].booking_type` (enum, optional)
Indicates whether the booking terms are fixed or flexible.
| Parameter value | Description |
| --------------- | ----------- |
| `fixed` | Non-modifiable once confirmed. |
| `flexible` | Allows modifications or cancellations under specified conditions.
Possible enum values:
- `fixed`
- `flexible`
- `industry_data.lodging.lodgings[].refundability` (enum, optional)
Parameter indicating whether the booking is refundable, partially refundable, or not refundable.
Possible enum values:
- `refundable`
- `non_refundable`
- `partially_refundable`
- `industry_data.lodging.lodgings[].location` (object, optional)
Address of the accommodation.
- `industry_data.lodging.lodgings[].location.street_line_1` (string)
Primary address line.
- `industry_data.lodging.lodgings[].location.street_line_2` (string, optional)
Secondary address line, such as floor and apartment number.
- `industry_data.lodging.lodgings[].location.region` (string, optional)
State or province of the address.
- `industry_data.lodging.lodgings[].location.city` (string)
City of the address.
- `industry_data.lodging.lodgings[].location.country_code` (string)
ISO 2-letter country code.
- `industry_data.lodging.lodgings[].location.postcode` (string)
Postal code of the address.
- `industry_data.lodging.lodgings[].guests` (array of object, optional)
List of guests associated with the booking.
- `industry_data.lodging.lodgings[].guests[].first_name` (string)
Guest's first name.
- `industry_data.lodging.lodgings[].guests[].last_name` (string)
Guest's last name.
- `merchant_order_data` (object, optional)
Object for providing additional information stored in the merchant's order management system.
- `merchant_order_data.url` (string, optional)
The URL of the order stored in the merchant's order management system.
This URL will be included in the order confirmation email for payments made via Revolut Pay. If specified, this URL will override the default link to the merchant's **Business website** configured in the Revolut Business account.
:::warning
Restrictions:
- Must be a valid URI as defined by [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986)
- URI scheme is required and must be either `http` or `https`
- URI host is required and cannot be `localhost` or an IP address
- Max length: `2000`
- Reserved or invalid characters must be percent-encoded (for example, use `%20` instead of a space)
:::
- `merchant_order_data.reference` (string, optional)
Merchant order ID for external reference.
Use this field to set the ID that your own system can use to easily track orders.
- `upcoming_payment_data` (object, optional)
Object containing information about upcoming payments associated with the order.
- `upcoming_payment_data.date` (string)
The date and time in [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601) when the upcoming payment is scheduled to be executed.
- `upcoming_payment_data.payment_method_id` (string)
The unique ID of the customer's payment method used to complete the scheduled payment.
:::info
For more information about operations related to customer's payment methods, see:
- [Retrieve payment method list of a customer](/docs/api/merchant#retrieve-payment-method-list-of-a-customer)
- [Retrieve a customer's payment method](/docs/api/merchant#retrieve-a-customer-s-payment-method)
- [Update a customer's payment method](/docs/api/merchant#update-a-customer-s-payment-method)
- [Delete a customer's payment method](/docs/api/merchant#delete-a-customer-s-payment-method)
:::
- `redirect_url` (string, optional)
The URL your customer will be redirected to after a successful payment on the hosted checkout page (`checkout_url` parameter's value of the order).
:::warning
Restrictions:
- Must be a valid URI as defined by [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986)
- URI scheme is required and must be either `http` or `https`
- URI host is required and cannot be `localhost` or an IP address
- Max length: `2000`
- Reserved or invalid characters must be percent-encoded (for example, use `%20` instead of a space)
:::
:::info
For more information on how to use the `redirect_url`, see: [Custom redirection via the API](/docs/guides/merchant/accept-payments/online-payments/hosted-checkout-page/api#custom-post-payment-redirection-optional)
:::
- `statement_descriptor_suffix` (string, optional)
You can set a dynamic statement descriptor for your orders by providing a custom suffix.
A statement descriptor is the text shown on cardholders' bank or card statements, helping them recognise a transaction or merchant. This field can be used to send extra information with the statement descriptor for card transactions.
The complete descriptor is built using the following format: `{base}*{suffix}`, where:
- **`{base}`** is the existing descriptor configured in the Revolut Business dashboard (**Settings > Business account > Merchant profile > Statement descriptor**).
- **`{suffix}`** is defined by the `statement_descriptor_suffix` field.
:::note
- If the combined descriptor's length (base + suffix) exceeds the character limits of card scheme providers, the final value will be truncated. For example if the limit is 22 characters, the base descriptor is `"base"` and the suffix is `"testdescriptorsuffix"`, the final descriptor becomes `"base*testdescriptorsuf"`.
- The final statement descriptor shown on a cardholder's statement may vary by issuing bank, as some banks apply their own custom formatting or truncation rules.
:::
## Returns
### 201
Order created
#### Response attributes
- `id` (string, optional)
Permanent order ID used to retrieve, capture, cancel, or refund an order after authorization.
- `token` (string, optional)
Temporary ID for the order, which expires when the payment is authorised.
The order `token` is used for [token-based initialisation](/docs/sdks/merchant-web-sdk/initialisation/token-based), and is returned by the `createOrder` callback in the following payment methods:
- [Embedded Checkout](/docs/sdks/merchant-web-sdk/payment-methods/embedded-checkout#embeddedcheckout options-interface)
- [Revolut Pay](/docs/sdks/merchant-web-sdk/payment-methods/revolut-pay#widgetpaymentsrevolutpayoptions)
- [Apple Pay and Google Pay](/docs/sdks/merchant-web-sdk/payment-methods/apple-pay-google-pay#paymentrequestoptions-interface)
- [Pay by Bank](/docs/sdks/merchant-web-sdk/payment-methods/pay-by-bank#paybybankoptions-interface)
- `type` (enum, optional)
The type of the order.
Possible enum values:
- `payment`
- `payment_request`
- `refund`
- `chargeback`
- `chargeback_reversal`
- `credit_reimbursement`
- `state` (enum, optional)
The state of the order in its lifecycle.
| State | Description |
|-------|-------------|
| `pending` | Order created, awaiting payment |
| `processing` | Payment is being processed |
| `authorised` | Payment authorised but not yet captured (for manual capture) |
| `completed` | Payment successfully captured and settled |
| `cancelled` | Order was cancelled |
| `failed` | Payment failed |
For more information, see: [Order and payment lifecycle](/docs/guides/merchant/reference/order-lifecycle)
Possible enum values:
- `pending`
- `processing`
- `authorised`
- `completed`
- `cancelled`
- `failed`
- `created_at` (string, optional)
The date and time the order was created.
- `updated_at` (string, optional)
The date and time the order was last updated.
- `description` (string, optional)
The description of the order.
- `capture_mode` (enum, optional)
The capture mode of the order. `automatic` is used by default.
| Parameter value | Description |
| --------------- | ----------- |
| `automatic` | The order is captured automatically after payment authorisation. |
| `manual` | The order is not captured automatically. You must manually capture the order later. |
:::info
For more information, see [Capture an order](/docs/api/merchant#capture-an-order).
:::
Possible enum values:
- `automatic`
- `manual`
- `authorisation_type` (enum, optional)
The type of authorisation for the order. Used with manual capture mode. If omitted, `final` is used by default.
### Pre-authorisation
Pre-authorisation allows you to reserve funds on a customer's card without immediately capturing them. This is useful for scenarios like:
- Hotel bookings where the final amount may vary
- Car rentals where additional charges may apply
- Deposits that need to be held temporarily
| Parameter value | Description |
| --------------- | ----------- |
| `final` | Standard authorisation for immediate or near-immediate capture. |
| `pre_authorisation` | Reserve funds for later capture, used with manual capture mode. |
:::note
Pre-authorisation must be used with `capture_mode: manual`. For more information, see [Capture an order](/docs/api/merchant#capture-an-order).
:::
Possible enum values:
- `final`
- `pre_authorisation`
- `cancel_authorised_after` (string, optional)
Automatic cancellation period for uncaptured orders, specified in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
After this period, the authorised payment is automatically cancelled and the order is cancelled. Maximum: 7 days = `P7D`.
:::note
The following limitations apply:
- Cannot be a negative value.
- Cannot be updated if the new value is less than or equal to the elapsed time since authorisation.
**Failing scenario:**
- Original value: 7 days
- Time since authorisation: 3 days
- Update value: 2 days
In this scenario, an error is returned.
**Successful scenario:**
- Original value: 7 days
- Time since authorisation: 3 days
- Update value: 4 days
In this scenario, the parameter can be updated.
- Cannot be updated if cancellation is ≤ 30 minutes away.
**Failing scenario:**
- Original value: 12 hours
- Time since authorisation: 11 hours 40 minutes
In this scenario, an error is returned.
**Successful scenario:**
- Original value: 12 hours
- Time since authorisation: 11 hours 20 minutes
In this scenario, the parameter can be updated.
:::
- `amount` (integer, optional)
The order total expressed in minor currency units, according to the [ISO 4217 standard](https://en.wikipedia.org/wiki/ISO_4217). For example, `7034` in `EUR` corresponds to €70.34.
:::info
- Conversion between major and minor units varies by currency. For instance, `100` minor units equal £1.00 in `GBP`, whereas in `ISK` they represent 100 units. For more details, see the [ISO 4217 standard](https://en.wikipedia.org/wiki/ISO_4217).
- If `line_items` are provided, the order `amount` must equal the sum of all line items' `total_amount`.
- For card payments with a non-zero amount, the order `amount` must be at least **$0.005** (or equivalent in different currencies, calculated using Revolut's exchange rate on the payment date). Otherwise, card payments can't be performed.
:::
- `outstanding_amount` (integer, optional)
The amount not yet paid for a given order (in minor currency units). For example, `7034` represents €70.34.
The value in this field may differ from `amount` if there are partial payments associated with the order.
- `refunded_amount` (integer, optional)
The amount that was refunded from the order (in minor currency units). For example, `7034` represents €70.34.
This applies to orders that have been refunded (i.e., orders of type `payment` that have a related `refund` order).
- `currency` (string, optional)
[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` (string, optional)
[ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code in upper case.
If `settlement_currency` is different from the value of `currency`, the money will be exchanged when the amount is settled to your merchant account. In case of a refund or chargeback, the money will be exchanged to the order's initial `currency`.
If `settlement_currency` is not specified, this value is taken from `currency`.
:::info
For more information about the supported currencies, see: [Help Center](https://help.revolut.com/business/help/merchant-accounts/payments/in-which-currencies-can-i-accept-payments/).
:::
- `customer` (object, optional)
Object containing information about a customer.
If you have it, we strongly advise providing at least either `id`, `phone`, or `email`.
Using the [Customers operations](/docs/api/merchant#tag-customers), you can manage customer instances.
The following behaviours apply to different use cases:
| Use case | API behavior |
| -------- | ------------ |
| Existing customer | If `id` was provided, we ignore other customer details and associate the customer with the order.
If either `email`, `phone`, or `full_name` was provided (without an existing customer's `id`), we always create a new customer, irrespective of another, existing customer object having the same details. |
| New customer | If either `email`, `phone`, or `full_name` was provided, we create a new customer, irrespective of another customer object having the same details.
If `id` of a non-existent customer was provided, we return a `404` error, irrespective of other details provided. |
:::note
To avoid unintentional duplication of customer records, search for an existing customer by email or phone using the [List customers](/docs/api/merchant#retrieve-a-customer-list) endpoint first, then provide `customer.id` in the order.
:::
- `customer.id` (string, optional)
Permanent ID of a customer used to retrieve, update, delete a customer. This ID can also be used to link customer to an order.
:::note
If you provide the customer's ID during order creation, no other customer data is required, they will be parsed automatically from the referenced customer object.
:::
- `customer.full_name` (string, optional)
The full name of the customer.
- `customer.phone` (string, optional)
The phone number of the customer in [E.164 format](https://en.wikipedia.org/wiki/E.164).
- `customer.email` (string, optional)
The email address of the customer.
- `customer.date_of_birth` (string, optional)
The birth date of the customer.
- `payments` (array of object, optional)
The details of all the payments that have been made towards this order (successful or unsuccessful).
- `payments[].id` (string)
The ID of the payment.
- `payments[].state` (enum)
The status of the payment.
Possible enum values:
- `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`
- `payments[].decline_reason` (enum, optional)
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).
Possible enum values:
- `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`
- `payments[].bank_message` (string, optional)
The reason for a `failed` or `declined` payment, sent by the financial institution processing the payment.
- `payments[].created_at` (string)
The date and time the payment was created.
- `payments[].updated_at` (string)
The date and time the payment was last updated.
- `payments[].token` (string, optional)
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.
- `payments[].amount` (integer)
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.
:::
- `payments[].authorised_amount` (integer, optional)
The currently authorised amount for this payment (in minor units).
For pre-authorised payments with incremental authorization:
- Initially equals the `amount` field
- Remains unchanged during increment processing
- Updates to new amount upon successful increment
- Remains at original amount if increment is declined
For standard payments, this field may not be present or will equal the `amount` field.
- `payments[].currency` (string, optional)
[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/).
:::
- `payments[].settled_amount` (integer, optional)
The amount of the settled payment (minor currency unit). For example, `7034` stands for €70.34.
- `payments[].settled_currency` (string, optional)
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/).
:::
- `payments[].payment_method` (object, optional)
The details of the payment method used to make the payment.
- `payments[].authentication_challenge` (object, optional)
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`.
- `payments[].billing_address` (object, optional)
Object containing address details.
- `payments[].billing_address.street_line_1` (string, optional)
Street line 1 information.
- `payments[].billing_address.street_line_2` (string, optional)
Street line 2 information.
- `payments[].billing_address.region` (string, optional)
The region associated with the address.
- `payments[].billing_address.city` (string, optional)
The city associated with the address.
- `payments[].billing_address.country_code` (string)
The 2-letter country code of the country associated with the address.
- `payments[].billing_address.postcode` (string)
The postcode associated with the address.
- `payments[].risk_level` (enum, optional)
The risk level of the card.
If the risk level is `high`, the payment might be declined.
Possible enum values:
- `low`
- `high`
- `payments[].fees` (array of object, optional)
The details of the order fee.
- `payments[].fees[].type` (enum, optional)
The type of the order fee.
Possible enum values:
- `fx`
- `acquiring`
- `payments[].fees[].amount` (integer, optional)
The amount of the payment fee (minor currency unit). For example, enter `7034` for €70.34 in the field.
- `payments[].fees[].currency` (string, optional)
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/).
:::
- `payments[].payer` (object, optional)
The person who made the payment. This object is present when an email or phone number is provided during the payment flow.
Capturing payer details lets you identify exactly who authorised the charge, reach the right person for receipts or refund queries, and support compliance or fraud-review workflows where the paying identity matters.
- `payments[].payer.email` (string, optional)
The email of the person who made the payment.
- `payments[].payer.phone` (string, optional)
The phone number of the payer in [E.164 format](https://en.wikipedia.org/wiki/E.164).
- `incremental_authorisations` (array of object, optional)
History of incremental authorisation attempts for this order.
Only present for orders with `authorisation_type: pre_authorisation`.
Contains all increment attempts in chronological order.
- `incremental_authorisations[].new_amount` (integer, optional)
The new total amount requested in this increment (in minor units).
- `incremental_authorisations[].old_amount` (integer, optional)
The previously authorised amount before this increment (in minor units).
- `incremental_authorisations[].state` (enum, optional)
The state of this incremental authorization attempt.
| State | Description |
|-------|-------------|
| `pending` | Increment registered in system, not yet submitted to card network |
| `processing` | Increment is being processed by card network |
| `authorised` | Increment was successfully authorised |
| `declined` | Increment was declined by card issuer |
| `failed` | Increment failed due to technical error (not an issuer decline) |
Possible enum values:
- `pending`
- `processing`
- `authorised`
- `declined`
- `failed`
- `incremental_authorisations[].reference` (string, optional)
External reference for this incremental authorisation.
:::tip
Use your internal charge or invoice ID. This reference is returned in webhooks for easy matching to your system.
:::
- `incremental_authorisations[].line_items` (array of object, optional)
Line items associated with this increment (if provided).
:::note
If the increment is successful, these line items will override the existing order line items.
:::
- `incremental_authorisations[].line_items[].name` (string)
Name of the line item.
- `incremental_authorisations[].line_items[].type` (enum)
Type of the line item.
Possible enum values:
- `physical`
- `service`
- `incremental_authorisations[].line_items[].quantity` (object)
Object representing the quantity details of a line item, including the amount and its associated unit of measurement.
- `incremental_authorisations[].line_items[].quantity.value` (number)
The number of units of the line item.
- `incremental_authorisations[].line_items[].quantity.unit` (string, optional)
The measurement unit for the quantity, such as `cm`, or `kg`.
- `incremental_authorisations[].line_items[].unit_price_amount` (integer)
The unit price of the line item.
- `incremental_authorisations[].line_items[].total_amount` (integer)
The total amount to be paid for the line item, including taxes and discounts.
- `incremental_authorisations[].line_items[].external_id` (string, optional)
Unique identifier of line item in the merchant's system.
- `incremental_authorisations[].line_items[].discounts` (array of object, optional)
A list of discounts applied to the line item. Each discount should be subtracted from the total amount payable for the item.
- `incremental_authorisations[].line_items[].discounts[].name` (string)
The specific name or label of the discount applied to the line item.
- `incremental_authorisations[].line_items[].discounts[].amount` (integer)
The monetary value of the discount.
- `incremental_authorisations[].line_items[].taxes` (array of object, optional)
A list of taxes applied to the line item. Each tax should be added to the total amount payable for the item.
- `incremental_authorisations[].line_items[].taxes[].name` (string)
The specific name or designation of the tax applied to the line item.
- `incremental_authorisations[].line_items[].taxes[].amount` (integer)
The monetary value of the tax in minor currency units (e.g., cents for EUR).
- `incremental_authorisations[].line_items[].image_urls` (array of string, optional)
A list of URLs pointing to images related to the line item. These images can provide visual details or representations of the item.
- `incremental_authorisations[].line_items[].description` (string, optional)
Description of the line item.
- `incremental_authorisations[].line_items[].url` (string, optional)
An HTTP/HTTPS URL that links to more information about the line item, such as a product page or details.
:::warning
Restrictions:
- Must be a valid URI as defined by [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986)
- URI scheme is required and must be either `http` or `https`
- URI host is required and cannot be `localhost` or an IP address
- Max length: `2000`
- Reserved or invalid characters must be percent-encoded (for example, use `%20` instead of a space)
:::
- `incremental_authorisations[].reason` (string, optional)
Reason why increment was declined or failed.
:::note
Only present when `state` is `declined` or `failed`.
:::
- `location_id` (string, optional)
Unique ID representing the location where merchants sells products.
:::info
For more information, see: [Locations](/docs/api/merchant#tag-locations).
:::
- `metadata` (object, optional)
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}$`
:::
- `industry_data` (object, optional)
Object containing industry-specific information associated with the order.
You can provide data for one or multiple industries in a single order.
:::info
In the following cases, industry-specific info is required. Omitting this information may trigger additional scrutiny and risk mitigation actions by the Revolut risk team.
| Transaction type | Required for |
| ---------------- | ----------- |
| `airline` | Airlines and Online Travel Agencies (OTAs). |
| `car_rental` | Car Rental Merchants and Online Travel Agencies (OTAs). |
| `crypto` | Crypto merchants. |
| `marketplace` | Marketplace merchants. |
| `event` | Event ticket sellers. |
| `lodging` | Lodging providers. |
:::
- `industry_data.airline` (object, optional)
Object containing additional information about an airline booking associated with the order.
Use this object to provide required data to enable **Revolut Flight Alerts**. This feature allows users to receive real-time flight updates such as check-in reminders, boarding alerts, and notifications for cancellations or delays in the Revolut app.
To enable **Revolut Flight Alerts** functionalities in the Revolut app, the following fields are **required** on order creation or update, before capturing the order:
```
tickets_purchase,
journey_legs,
booking_url
```
:::note
These are the specific data field requirements for merchants who must provide airline data. Note that these requirements can be extended on a case by case basis as decided by Revolut.
| Required for airline/charter merchants | Required for OTA merchants |
| -------------------------------------- | -------------------------- |
| - `booking_id`
- `fulfillment_date`
- `passengers[].first_name`
- `passengers[].last_name`
- `journey_legs[].pnr`
- `journey_legs[].sequence`
- `journey_legs[].flight_number`
- `journey_legs[].travel_date`
- `journey_legs[].airline_code`
- `journey_legs[].departure_airport_code`
- `journey_legs[].arrival_airport_code`
| - `booking_id`
- `fulfillment_date`
- `passengers[].first_name`
- `passengers[].last_name`
- `journey_legs[].pnr`
- `journey_legs[].arrival_airport_code`
|
:::
- `industry_data.airline.booking_id` (string)
A unique identifier provided by the merchant associated with the order.
This `booking_id` is used to reference and correlate booking information with the Merchant API and the merchant's internal system.
- `industry_data.airline.fulfillment_date` (string, optional)
The UTC date and time of the final journey leg.
:::warning
The following limitations apply:
- When creating or updating an order, `fulfillment_date` cannot be set to a date in the past.
- When updating an order, if the current `fulfillment_date` value is already in the past, it cannot be modified. The date must remain as is to maintain data integrity for completed transactions.
:::
- `industry_data.airline.tickets_purchase` (boolean, optional)
Flag indicating whether the order includes actual ticket purchases. Set to `true` if the order contains ticket purchases, and `false` if it does not (e.g., it **only** contains seat reservations, or baggage upgrades).
:::info
This field is required for activating **Revolut Flight Alerts** functionalities within the Revolut app.
Provide the info on order creation or update, before capturing the order.
:::
- `industry_data.airline.ticket_type` (enum, optional)
The type of the ticket.
| Parameter value | Description |
| --------------- | ----------- |
| `fixed` | Non-modifiable once confirmed. |
| `flexible` | Allows modifications or cancellations under specified conditions. |
Possible enum values:
- `fixed`
- `flexible`
- `industry_data.airline.crs_code` (string, optional)
The code of the Computer Reservation System (CRS) used to make the booking and purchase the ticket.
- `industry_data.airline.ticket_change_indicator` (enum, optional)
Parameter indicating whether this order is related to a new ticket reservation or a modification of an existing one.
Possible enum values:
- `new`
- `modification`
- `industry_data.airline.refundability` (enum, optional)
Parameter indicating whether the booking is refundable, partially refundable, or not refundable.
Possible enum values:
- `refundable`
- `non_refundable`
- `partially_refundable`
- `industry_data.airline.passengers` (array of object, optional)
Array containing information of passengers associated with the booking.
- `industry_data.airline.passengers[].first_name` (string)
Passenger's first name.
- `industry_data.airline.passengers[].last_name` (string)
Passenger's last name.
- `industry_data.airline.journey_legs` (array of object, optional)
Array containing information of journey legs associated with the booking.
:::info
This field is required for activating **Revolut Flight Alerts** functionalities within the Revolut app.
This information is used to compile a tracking widget that provides real-time updates on flight status and sends notifications, such as a check-in reminders, boarding alerts, and notifications for cancellations or delays.
To enable the widget the following fields are required on order creation or update, before capturing the order:
```
sequence,
departure_airport_code,
arrival_airport_code,
flight_number,
travel_date,
airline_name,
airline_code,
```
:::
- `industry_data.airline.journey_legs[].sequence` (integer)
Sequence of the journey legs. Increment by 1 for each flight included in the ticket.
For example: For a `FRA > LHR > DUB > LHR > FRA` journey the sequence will be assigned as:
- `FRA > LHR`: 1
- `LHR > DUB`: 2
- `DUB > LHR`: 3
- `LHR > FRA`: 4
- `industry_data.airline.journey_legs[].departure_airport_code` (string)
The [IATA](https://www.iata.org/en/services/codes) 3-letter airport code for the departure airport.
- `industry_data.airline.journey_legs[].arrival_airport_code` (string)
The [IATA](https://www.iata.org/en/services/codes) 3-letter airport code for the arrival airport.
- `industry_data.airline.journey_legs[].flight_number` (string, optional)
The flight identifier, without airline code.
- `industry_data.airline.journey_legs[].fare_base_code` (string, optional)
The fare base code for the given journey leg.
- `industry_data.airline.journey_legs[].travel_date` (string)
The UTC date and time of the flight departure for the given journey leg.
- `industry_data.airline.journey_legs[].airline_name` (string)
The name of the airline associated with the journey leg.
- `industry_data.airline.journey_legs[].airline_code` (string)
The IATA 2-letter accounting code identifying the airline associated with the journey leg.
- `industry_data.airline.journey_legs[].pnr` (string, optional)
The Passenger Name Record (PNR) for the journey leg issued by the airline.
PNR is a unique identifier for the booking, acting as a digital certificate allowing passengers to retrieve or manage their booking details.
:::warning
This is a required field for OTAs.
:::
- `industry_data.airline.booking_url` (string, optional)
URL to the online portal for managing the airline booking, which includes check-in functionality. This URL may be a personalised, pre-populated check-in link specific to the user or a generic link, and it is essential for enabling direct access to booking details within the Revolut app.
:::info
This field is required for activating **Revolut Flight Alerts** functionalities within the Revolut app.
Provide the info on order creation or update, before capturing the order.
:::
:::warning
Restrictions:
- Must be a valid URI as defined by [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986)
- URI scheme is required and must be either `http` or `https`
- URI host is required and cannot be `localhost` or an IP address
- Max length: `2000`
- Reserved or invalid characters must be percent-encoded (for example, use `%20` instead of a space)
:::
- `industry_data.car_rental` (object, optional)
Object containing additional information about a car rental booking associated with the order.
:::info
These are the specific data field requirements for merchants offering car rental. Note that these requirements can be extended on a case by case basis as decided by Revolut.
```
booking_id
drop_off_date
refundability
```
:::
- `industry_data.car_rental.booking_id` (string)
A unique identifier provided by the merchant associated with the order.
This `booking_id` is used to reference and correlate booking information with the Merchant API and the merchant's internal system.
- `industry_data.car_rental.pick_up_date` (string, optional)
The UTC date and time of the pick-up.
- `industry_data.car_rental.pick_up_location` (object, optional)
Object containing address details.
- `industry_data.car_rental.pick_up_location.street_line_1` (string, optional)
Street line 1 information.
- `industry_data.car_rental.pick_up_location.street_line_2` (string, optional)
Street line 2 information.
- `industry_data.car_rental.pick_up_location.region` (string, optional)
The region associated with the address.
- `industry_data.car_rental.pick_up_location.city` (string, optional)
The city associated with the address.
- `industry_data.car_rental.pick_up_location.country_code` (string)
The 2-letter country code of the country associated with the address.
- `industry_data.car_rental.pick_up_location.postcode` (string)
The postcode associated with the address.
- `industry_data.car_rental.drop_off_date` (string)
The UTC date and time of the drop-off.
- `industry_data.car_rental.drop_off_location` (object, optional)
Object containing address details.
- `industry_data.car_rental.drop_off_location.street_line_1` (string, optional)
Street line 1 information.
- `industry_data.car_rental.drop_off_location.street_line_2` (string, optional)
Street line 2 information.
- `industry_data.car_rental.drop_off_location.region` (string, optional)
The region associated with the address.
- `industry_data.car_rental.drop_off_location.city` (string, optional)
The city associated with the address.
- `industry_data.car_rental.drop_off_location.country_code` (string)
The 2-letter country code of the country associated with the address.
- `industry_data.car_rental.drop_off_location.postcode` (string)
The postcode associated with the address.
- `industry_data.car_rental.refundability` (enum, optional)
Parameter indicating whether the booking is refundable, partially refundable, or not refundable.
Possible enum values:
- `refundable`
- `non_refundable`
- `partially_refundable`
- `industry_data.car_rental.distance_limit` (object, optional)
Object containing distance limit information.
- `industry_data.car_rental.distance_limit.limit` (integer, optional)
The maximum distance allowed.
- `industry_data.car_rental.distance_limit.unit` (enum, optional)
The unit of distance.
Possible enum values:
- `miles`
- `km`
- `industry_data.car_rental.distance_limit.additional_distance_cost` (object, optional)
Cost for exceeding the distance limit.
- `industry_data.car_rental.distance_limit.additional_distance_cost.amount` (integer, optional)
The amount of the cost in minor currency units. For example, enter `7034` for €70.34.
- `industry_data.car_rental.distance_limit.additional_distance_cost.currency` (string, optional)
[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/).
:::
- `industry_data.crypto` (object, optional)
Object containing information about crypto transactions associated with the order.
:::info
Processing crypto on-ramp transactions with Revolut has additional compliance requirements. Please reach out to your account executive for additional details.
**Required data fields for crypto services:**
```
transactions[].id
transactions[].status
transactions[].recipient_wallet_id
seller.id
seller.name
seller.website
seller.phone
seller.address
seller.mcc
customer.full_name
customer.date_of_birth
```
Note that these requirements can be extended on a case by case basis as decided by Revolut.
:::
- `industry_data.crypto.transactions` (array of object)
Array of crypto transaction data associated with the order.
- `industry_data.crypto.transactions[].id` (string)
The public transaction hash of the crypto transaction.
- `industry_data.crypto.transactions[].status` (enum)
The status of the crypto transaction.
Possible enum values:
- `pending`
- `failed`
- `cancelled`
- `completed`
- `industry_data.crypto.transactions[].recipient_wallet_id` (string, optional)
The wallet ID of the recipient.
:::note
At least one of the parameters: `recipient_user_id` or `recipient_wallet_id` is required.
:::
- `industry_data.crypto.transactions[].recipient_user_id` (string, optional)
The user ID of the recipient.
:::note
At least one of the parameters: `recipient_user_id` or `recipient_wallet_id` is required.
:::
- `industry_data.crypto.seller` (object, optional)
Information about the crypto conversion affiliate.
This should be provided when a customer completes a payment on a subseller's website rather than directly on the merchant's website, providing insight into the type of business conducted by the subseller.
:::note
This needs to be provided only by crypto on-ramp providers for payments they are processing for conversion affiliates.
For their own payments, `seller` can be omitted.
:::
- `industry_data.crypto.seller.mcc` (string)
A string representing the four-digit [Merchant Category Code (MCC)](https://en.wikipedia.org/wiki/Merchant_category_code) of the conversion affiliate.
- `industry_data.crypto.seller.id` (string)
The ID of the seller in the merchant's internal system.
- `industry_data.crypto.seller.name` (string)
The business or legal name of the seller.
- `industry_data.crypto.seller.website` (string)
The URL of the website of the seller.
:::warning
Restrictions:
- Must be a valid URI as defined by [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986)
- URI scheme is required and must be either `http` or `https`
- URI host is required and cannot be `localhost` or an IP address
- Max length: `255`
- Reserved or invalid characters must be percent-encoded (for example, use `%20` instead of a space)
:::
- `industry_data.crypto.seller.phone` (string)
The phone number of the seller.
- `industry_data.crypto.seller.address` (object)
Details of a physical address.
- `industry_data.crypto.seller.address.street_line_1` (string)
Primary address line.
- `industry_data.crypto.seller.address.street_line_2` (string, optional)
Secondary address line, such as floor and apartment number.
- `industry_data.crypto.seller.address.region` (string, optional)
State or province of the address.
- `industry_data.crypto.seller.address.city` (string)
City of the address.
- `industry_data.crypto.seller.address.country_code` (string)
ISO 2-letter country code.
- `industry_data.crypto.seller.address.country_subdivision_code` (string, optional)
The subdivision code represents the state, province, or region within the country, following the [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2) standard. This code uniquely identifies subdivisions within a country.
For example, for London in the United Kingdom, use `GB-LND`.
:::warning
The parameter is required for countries listed on the [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2) page.
:::
- `industry_data.crypto.seller.address.postcode` (string)
Postal code of the address.
- `industry_data.marketplace` (object, optional)
This object is required by Mastercard and Visa for merchants operating as marketplaces under the Merchant Category Code (MCC) `5262`. The marketplace object ensures compliance with the card schemes' regulations by providing detailed information about the seller involved in the transaction.
:::info
These are the specific data field requirements for merchants who must provide marketplace data.
```
seller.id
seller.name
seller.website
seller.phone
seller.address
```
:::
- `industry_data.marketplace.seller` (object)
Information about the subseller on the marketplace platform.
- `industry_data.marketplace.seller.id` (string)
The ID of the seller in the merchant's internal system.
- `industry_data.marketplace.seller.name` (string)
The business or legal name of the seller.
- `industry_data.marketplace.seller.website` (string)
The URL of the website of the seller.
:::warning
Restrictions:
- Must be a valid URI as defined by [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986)
- URI scheme is required and must be either `http` or `https`
- URI host is required and cannot be `localhost` or an IP address
- Max length: `255`
- Reserved or invalid characters must be percent-encoded (for example, use `%20` instead of a space)
:::
- `industry_data.marketplace.seller.phone` (string)
The phone number of the seller.
- `industry_data.marketplace.seller.address` (object)
Details of a physical address.
- `industry_data.marketplace.seller.address.street_line_1` (string)
Primary address line.
- `industry_data.marketplace.seller.address.street_line_2` (string, optional)
Secondary address line, such as floor and apartment number.
- `industry_data.marketplace.seller.address.region` (string, optional)
State or province of the address.
- `industry_data.marketplace.seller.address.city` (string)
City of the address.
- `industry_data.marketplace.seller.address.country_code` (string)
ISO 2-letter country code.
- `industry_data.marketplace.seller.address.country_subdivision_code` (string, optional)
The subdivision code represents the state, province, or region within the country, following the [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2) standard. This code uniquely identifies subdivisions within a country.
For example, for London in the United Kingdom, use `GB-LND`.
:::warning
The parameter is required for countries listed on the [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2) page.
:::
- `industry_data.marketplace.seller.address.postcode` (string)
Postal code of the address.
- `industry_data.event` (object, optional)
Object containing booking information for a list of event tickets associated with the order.
:::info
These are the specific data field requirements for merchants who must provide event data. Note that these requirements can be extended on a case by case basis as decided by Revolut.
```
booking_id
events[].start_date
events[].end_date
events[].supplier
events[].tickets[].id
```
:::
- `industry_data.event.booking_id` (string)
A unique identifier provided by the merchant associated with the order.
This `booking_id` is used to reference and correlate booking information with the Merchant API and the merchant's internal system.
- `industry_data.event.events` (array of object, optional)
A list of events associated with the booking.
- `industry_data.event.events[].start_date` (string, optional)
[ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date and time when the event starts.
- `industry_data.event.events[].end_date` (string, optional)
[ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date and time when the event ends.
- `industry_data.event.events[].supplier` (string, optional)
Legal name of the ticket vendor/event organiser.
- `industry_data.event.events[].supplier_payment_date` (string, optional)
[ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date and time when the funds are released to merchants.
- `industry_data.event.events[].name` (string, optional)
The name of the event.
- `industry_data.event.events[].location` (object, optional)
The address of the event location.
- `industry_data.event.events[].location.street_line_1` (string)
Primary address line.
- `industry_data.event.events[].location.street_line_2` (string, optional)
Secondary address line, such as floor and apartment number.
- `industry_data.event.events[].location.region` (string, optional)
State or province of the address.
- `industry_data.event.events[].location.city` (string)
City of the address.
- `industry_data.event.events[].location.country_code` (string)
ISO 2-letter country code.
- `industry_data.event.events[].location.postcode` (string)
Postal code of the address.
- `industry_data.event.events[].category` (enum, optional)
The type of the event.
Possible enum values:
- `concert`
- `conference`
- `convention`
- `exhibition`
- `festival`
- `party`
- `performance`
- `other`
- `industry_data.event.events[].market` (enum, optional)
Indicates the relationship between the ticket vendor and the event organiser.
| Parameter value | Description |
| --------------- | ----------- |
| `primary` | The merchant is the organiser and primary distributor of the tickets. |
| `secondary` | The merchant is a reseller, only distributing the tickets. |
Possible enum values:
- `primary`
- `secondary`
- `industry_data.event.events[].tickets` (array of object, optional)
A list of tickets associated with the booking.
- `industry_data.event.events[].tickets[].id` (string)
A unique identifier provided by the merchant associated with the ticket.
- `industry_data.event.events[].tickets[].transferable` (boolean, optional)
Indicates whether the ticket is transferable to another buyer.
- `industry_data.event.events[].tickets[].refundability` (enum, optional)
Parameter indicating whether the booking is refundable, partially refundable, or not refundable.
Possible enum values:
- `refundable`
- `non_refundable`
- `partially_refundable`
- `industry_data.lodging` (object, optional)
Object containing details of a lodging booking.
:::info
These are the specific data field requirements for merchants who must provide lodging data. Note that these requirements can be extended on a case by case basis as decided by Revolut.
```
booking_id
lodgings[].check_in_date
lodgings[].check_out_date
lodgings[].supplier.payment_date
```
:::
- `industry_data.lodging.booking_id` (string)
A unique identifier provided by the merchant associated with the order.
This `booking_id` is used to reference and correlate booking information with the Merchant API and the merchant's internal system.
- `industry_data.lodging.lodgings` (array of object, optional)
List of lodging entries associated with this booking.
- `industry_data.lodging.lodgings[].check_in_date` (string, optional)
[ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date and time of the check-in.
- `industry_data.lodging.lodgings[].check_out_date` (string, optional)
[ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date and time of the check-out.
- `industry_data.lodging.lodgings[].category` (enum, optional)
The type of the accommodation associated with the booking.
Possible enum values:
- `bed_and_breakfast`
- `hostel`
- `hotel`
- `short_term_rental`
- `other`
- `industry_data.lodging.lodgings[].supplier` (object, optional)
Object containing supplier information about the lodging provider.
- `industry_data.lodging.lodgings[].supplier.id` (string, optional)
Unique identifier of the lodging supplier.
- `industry_data.lodging.lodgings[].supplier.name` (string, optional)
Legal name of the lodging supplier.
- `industry_data.lodging.lodgings[].supplier.payment_date` (string, optional)
[ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date and time when the funds are released to merchants.
- `industry_data.lodging.lodgings[].booking_type` (enum, optional)
Indicates whether the booking terms are fixed or flexible.
| Parameter value | Description |
| --------------- | ----------- |
| `fixed` | Non-modifiable once confirmed. |
| `flexible` | Allows modifications or cancellations under specified conditions.
Possible enum values:
- `fixed`
- `flexible`
- `industry_data.lodging.lodgings[].refundability` (enum, optional)
Parameter indicating whether the booking is refundable, partially refundable, or not refundable.
Possible enum values:
- `refundable`
- `non_refundable`
- `partially_refundable`
- `industry_data.lodging.lodgings[].location` (object, optional)
Address of the accommodation.
- `industry_data.lodging.lodgings[].location.street_line_1` (string)
Primary address line.
- `industry_data.lodging.lodgings[].location.street_line_2` (string, optional)
Secondary address line, such as floor and apartment number.
- `industry_data.lodging.lodgings[].location.region` (string, optional)
State or province of the address.
- `industry_data.lodging.lodgings[].location.city` (string)
City of the address.
- `industry_data.lodging.lodgings[].location.country_code` (string)
ISO 2-letter country code.
- `industry_data.lodging.lodgings[].location.postcode` (string)
Postal code of the address.
- `industry_data.lodging.lodgings[].guests` (array of object, optional)
List of guests associated with the booking.
- `industry_data.lodging.lodgings[].guests[].first_name` (string)
Guest's first name.
- `industry_data.lodging.lodgings[].guests[].last_name` (string)
Guest's last name.
- `merchant_order_data` (object, optional)
Object for providing additional information stored in the merchant's order management system.
- `merchant_order_data.url` (string, optional)
The URL of the order stored in the merchant's order management system.
This URL will be included in the order confirmation email for payments made via Revolut Pay. If specified, this URL will override the default link to the merchant's **Business website** configured in the Revolut Business account.
:::warning
Restrictions:
- Must be a valid URI as defined by [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986)
- URI scheme is required and must be either `http` or `https`
- URI host is required and cannot be `localhost` or an IP address
- Max length: `2000`
- Reserved or invalid characters must be percent-encoded (for example, use `%20` instead of a space)
:::
- `merchant_order_data.reference` (string, optional)
Merchant order ID for external reference.
Use this field to set the ID that your own system can use to easily track orders.
- `upcoming_payment_data` (object, optional)
Object containing information about upcoming payments associated with the order.
- `upcoming_payment_data.date` (string)
The date and time in [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601) when the upcoming payment is scheduled to be executed.
- `upcoming_payment_data.payment_method_id` (string)
The unique ID of the customer's payment method used to complete the scheduled payment.
:::info
For more information about operations related to customer's payment methods, see:
- [Retrieve payment method list of a customer](/docs/api/merchant#retrieve-payment-method-list-of-a-customer)
- [Retrieve a customer's payment method](/docs/api/merchant#retrieve-a-customer-s-payment-method)
- [Update a customer's payment method](/docs/api/merchant#update-a-customer-s-payment-method)
- [Delete a customer's payment method](/docs/api/merchant#delete-a-customer-s-payment-method)
:::
- `checkout_url` (string, optional)
Link to a checkout page hosted by Revolut.
- `redirect_url` (string, optional)
The URL your customer will be redirected to after a successful payment on the hosted checkout page (`checkout_url` parameter's value of the order).
:::warning
Restrictions:
- Must be a valid URI as defined by [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986)
- URI scheme is required and must be either `http` or `https`
- URI host is required and cannot be `localhost` or an IP address
- Max length: `2000`
- Reserved or invalid characters must be percent-encoded (for example, use `%20` instead of a space)
:::
:::info
For more information on how to use the `redirect_url`, see: [Custom redirection via the API](/docs/guides/merchant/accept-payments/online-payments/hosted-checkout-page/api#custom-post-payment-redirection-optional)
:::
- `shipping` (object, optional)
Details about the shipping related to the order, including address, contact information, and individual shipments.
:::info
Required for merchants shipping physical goods. Omitting this information may trigger additional scrutiny and risk mitigation actions by Revolut.
:::
- `shipping.address` (object, optional)
Details of a physical address.
- `shipping.address.street_line_1` (string)
Primary address line.
- `shipping.address.street_line_2` (string, optional)
Secondary address line, such as floor and apartment number.
- `shipping.address.region` (string, optional)
State or province of the address.
- `shipping.address.city` (string)
City of the address.
- `shipping.address.country_code` (string)
ISO 2-letter country code.
- `shipping.address.postcode` (string)
Postal code of the address.
- `shipping.contact` (object, optional)
Contact details for someone responsible for the shipment.
:::warning
At least `email` or `phone` is required.
:::
- `shipping.contact.name` (string, optional)
Full name of the contact person.
- `shipping.contact.email` (string, optional)
Email address of the contact person.
- `shipping.contact.phone` (string, optional)
Phone number of the contact person.
- `shipping.shipments` (array of object, optional)
List of individual shipment details.
- `shipping.shipments[].shipping_company_name` (string)
Name of the company handling the shipment.
- `shipping.shipments[].tracking_number` (string)
Unique tracking number for the shipment.
- `shipping.shipments[].estimated_delivery_date` (string, optional)
Estimated delivery date and time for the shipment.
The time should also include the customer's timezone.
- `shipping.shipments[].tracking_url` (string, optional)
An HTTP/HTTPS URL where the shipment can be tracked.
:::warning
Restrictions:
- Must be a valid URI as defined by [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986)
- URI scheme is required and must be either `http` or `https`
- URI host is required and cannot be `localhost` or an IP address
- Max length: `2000`
- Reserved or invalid characters must be percent-encoded (for example, use `%20` instead of a space)
:::
- `enforce_challenge` (enum, optional)
The enforce challenge mode. `automatic` is used by default.
| Parameter value | Description |
| --------------- | ----------- |
| `automatic` | The payments created for an order will have challenge requirement calculated by our fraud mechanisms. Not all payments will trigger a 3DS challenge. |
| `forced` | The payments created for an order will always require a 3DS challenge. Currently only supported for card payments. |
Possible enum values:
- `automatic`
- `forced`
- `line_items` (array of object, optional)
An array of line items included in the order. Each line item represents an individual product or service, along with its quantity, price, taxes, and discounts.
:::info
Required for merchants collecting payment for one or multiple products/services in one transaction. Omitting this information may trigger additional scrutiny and risk mitigation actions by Revolut.
:::
- `line_items[].name` (string)
Name of the line item.
- `line_items[].type` (enum)
Type of the line item.
Possible enum values:
- `physical`
- `service`
- `line_items[].quantity` (object)
Object representing the quantity details of a line item, including the amount and its associated unit of measurement.
- `line_items[].quantity.value` (number)
The number of units of the line item.
- `line_items[].quantity.unit` (string, optional)
The measurement unit for the quantity, such as `cm`, or `kg`.
- `line_items[].unit_price_amount` (integer)
The unit price of the line item.
- `line_items[].total_amount` (integer)
The total amount to be paid for the line item, including taxes and discounts.
- `line_items[].external_id` (string, optional)
Unique identifier of line item in the merchant's system.
- `line_items[].discounts` (array of object, optional)
A list of discounts applied to the line item. Each discount should be subtracted from the total amount payable for the item.
- `line_items[].discounts[].name` (string)
The specific name or label of the discount applied to the line item.
- `line_items[].discounts[].amount` (integer)
The monetary value of the discount.
- `line_items[].taxes` (array of object, optional)
A list of taxes applied to the line item. Each tax should be added to the total amount payable for the item.
- `line_items[].taxes[].name` (string)
The specific name or designation of the tax applied to the line item.
- `line_items[].taxes[].amount` (integer)
The monetary value of the tax in minor currency units (e.g., cents for EUR).
- `line_items[].image_urls` (array of string, optional)
A list of URLs pointing to images related to the line item. These images can provide visual details or representations of the item.
- `line_items[].description` (string, optional)
Description of the line item.
- `line_items[].url` (string, optional)
An HTTP/HTTPS URL that links to more information about the line item, such as a product page or details.
:::warning
Restrictions:
- Must be a valid URI as defined by [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986)
- URI scheme is required and must be either `http` or `https`
- URI host is required and cannot be `localhost` or an IP address
- Max length: `2000`
- Reserved or invalid characters must be percent-encoded (for example, use `%20` instead of a space)
:::
- `statement_descriptor_suffix` (string, optional)
You can set a dynamic statement descriptor for your orders by providing a custom suffix.
A statement descriptor is the text shown on cardholders' bank or card statements, helping them recognise a transaction or merchant. This field can be used to send extra information with the statement descriptor for card transactions.
The complete descriptor is built using the following format: `{base}*{suffix}`, where:
- **`{base}`** is the existing descriptor configured in the Revolut Business dashboard (**Settings > Business account > Merchant profile > Statement descriptor**).
- **`{suffix}`** is defined by the `statement_descriptor_suffix` field.
:::note
- If the combined descriptor's length (base + suffix) exceeds the character limits of card scheme providers, the final value will be truncated. For example if the limit is 22 characters, the base descriptor is `"base"` and the suffix is `"testdescriptorsuffix"`, the final descriptor becomes `"base*testdescriptorsuf"`.
- The final statement descriptor shown on a cardholder's statement may vary by issuing bank, as some banks apply their own custom formatting or truncation rules.
:::
- `related_order_id` (string, optional)
The unique ID of the original order that was refunded and this refund is associated with. You can use this ID to get more information about the related order using the [Retrieve an order](/docs/api/merchant#retrieve-an-order) operation.
:::note
This field is only returned for orders with `type: refund`.
:::
## Error responses
| HTTP status code | Description |
| --- | --- |
| 400 | Bad Request |
| 401 | Unauthorized |
| 404 | Not Found |