---
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 building on order creation.
To learn more about how you can accept payments, see:
- [Revolut Pay](/docs/guides/merchant/accept-payments/online-payments/revolut-pay/introduction)
- [Card payments](/docs/guides/merchant/accept-payments/online-payments/card-payments/introduction)
- [Apple Pay and Google Pay](/docs/guides/merchant/accept-payments/online-payments/apple-pay-google-pay/introduction)
- [Pay by Bank](/docs/guides/merchant/accept-payments/online-payments/pay-by-bank/introduction)
- [Revolut Checkout](/docs/guides/merchant/accept-payments/online-payments/revolut-checkout/introduction)
- [Hosted Checkout Page](/docs/guides/merchant/accept-payments/online-payments/hosted-checkout-page/introduction)
Industry-specific requirements
If you operate in any of the industries listed below, sharing industry-specific data is mandatory. Not providing the necessary information will result in further scrutiny from Revolut and/or the imposition of risk mitigation actions.
| Industry | Related fields |
| ------- | --------------- |
| Airlines | `industry_data` with `type: airline` |
| Car rentals | `industry_data` with `type: car_rental` |
| Hotels & accommodation | `industry_data` with `type: lodging` |
| Travel agencies (OTAs) | `industry_data` with `type: airline` or `industry_data` with `type: lodging` |
| Crypto merchants | `industry_data` with `type: crypto`; `customer.full_name`, `customer.date_of_birth` |
| Financial institutions | `customer.full_name`, `customer.date_of_birth` |
| Stored value / Wallets | `customer.full_name`, `customer.date_of_birth` |
| Event ticket sellers | `industry_data` with `type: event` |
| Marketplace merchants | `industry_data` with `type: marketplace` |
## 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).
:::
- `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-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.
- `shipping_address` (object, optional)
Object containing address details.
- `shipping_address.street_line_1` (string, optional)
Street line 1 information.
- `shipping_address.street_line_2` (string, optional)
Street line 2 information.
- `shipping_address.region` (string, optional)
The region associated with the address.
- `shipping_address.city` (string, optional)
The city associated with the address.
- `shipping_address.country_code` (string)
The 2-letter country code of the country associated with the address.
- `shipping_address.postcode` (string)
The postcode associated with the address.
- `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`
- `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-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-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.
:::
- `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.
:::info
In the following cases, industry-specific info is required. Omitting this information may trigger additional scrutiny and risk mitigation actions by the Revolut risk team.
| Transaction type | Required for |
| ---------------- | ----------- |
| `airline` | Airlines and Online Travel Agencies (OTAs). |
| `crypto` | Crypto merchants. |
| `marketplace` | Marketplace merchants. |
| `event` | Event ticket sellers. |
| `lodging` | Lodging providers and OTAs. |
:::
- `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)
- [Retrieve a customer's payment method](/docs/api/merchant#retrieve-payment-method)
- [Update a customer's payment method](/docs/api/merchant#update-payment-method)
- [Delete a customer's payment method](/docs/api/merchant#delete-payment-method)
:::
- `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#embedded-checkout-options-interface)
- [Revolut Pay](/docs/sdks/merchant-web-sdk/payment-methods/revolut-pay#widget-payments-revolut-pay-options)
- [Apple Pay and Google Pay](/docs/sdks/merchant-web-sdk/payment-methods/apple-pay-google-pay#payment-request-options-interface)
- [Pay by Bank](/docs/sdks/merchant-web-sdk/payment-methods/pay-by-bank#pay-by-bank-options-interface)
- `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-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-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).
:::
- `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-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.
- `shipping_address` (object, optional)
Object containing address details.
- `shipping_address.street_line_1` (string, optional)
Street line 1 information.
- `shipping_address.street_line_2` (string, optional)
Street line 2 information.
- `shipping_address.region` (string, optional)
The region associated with the address.
- `shipping_address.city` (string, optional)
The city associated with the address.
- `shipping_address.country_code` (string)
The 2-letter country code of the country associated with the address.
- `shipping_address.postcode` (string)
The postcode associated with the address.
- `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).
- `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.
:::info
In the following cases, industry-specific info is required. Omitting this information may trigger additional scrutiny and risk mitigation actions by the Revolut risk team.
| Transaction type | Required for |
| ---------------- | ----------- |
| `airline` | Airlines and Online Travel Agencies (OTAs). |
| `crypto` | Crypto merchants. |
| `marketplace` | Marketplace merchants. |
| `event` | Event ticket sellers. |
| `lodging` | Lodging providers and OTAs. |
:::
- `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)
- [Retrieve a customer's payment method](/docs/api/merchant#retrieve-payment-method)
- [Update a customer's payment method](/docs/api/merchant#update-payment-method)
- [Delete a customer's payment method](/docs/api/merchant#delete-payment-method)
:::
- `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)
:::
- `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`
- `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.
:::
## Error responses
| HTTP status code | Description |
| --- | --- |
| 400 | Bad Request |
| 401 | Unauthorized |
| 404 | Not Found |