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:
Authorization
Each Merchant API request must contain an authorization header in the following format to make a call:
'Authorization: Bearer <yourSecretApiKey>'
Before you start, ensure that you've successfully applied for a Merchant Account in your Revolut Business Account.
The Public key is on the same path in your Revolut Business account as the Secret key. There are two different functions for each:
- Public key should be provided with payment methods at checkout
- Secret key is used as a part of the authorization header for all server calls, e.g., creating order
Complete the following steps to generate the Production API keys (Secret, Public):
- Log in to your Revolut Business portal.
- On the top left corner, click your account name, click APIs then select Merchant API.
- Under the Production API Secret key and Production API Public key sections you will find the API keys needed. If it's your first time on this page, you will need to click the Generate button to create your unique API keys.
You can also use this link to directly open the Merchant API page.
Use these keys only for the production environment. For the Revolut Business Sandbox environment, use the sandbox API keys.
SSL
This authentication protocol is used exclusively when using Fast checkout.
Connection over HTTPS is using SSL authentication. For successful authentication, your system's certificate should be issued by a Public Certificate Authority (PCA) and your system should trust Revolut's public certificate.
Revolut-Pay-Payload-Signature
This authentication protocol is used exclusively when using Fast checkout.
Data integrity and authorship will be verified using a payload-based signature. The response of a successful URL registration for address validation (see: Register address validation for Fast checkout) will contain a secret signing key.
The signing key will be used by Revolut to compute a Hash-based Message Authentication Code (HMAC) payload signature whenever the registered URL is called, which should be verified by your backend.
Request
Possible values: [2023-09-01]
The version of the Merchant API, specified in YYYY-MM-DD format.
If not specified, you will receive an error.
Current version: 2023-09-01
For more information about API versioning, see: API versions.
The amount of the order (minor currency unit). For example, enter 7034 for €70.34 in the field.
ISO 4217 currency code in upper case.
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.
The description of the order.
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, 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 id with the order.If email was provided, we try to find the customer by email. We ignore other details in this case. |
| New customer | If email is provided and no match is found, a new customer instance is created with the data provided and appended to the order. |
Permanent ID of a customer used to retrieve, update, delete a customer. This ID can also be used to link customer to an order.
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.
Possible values: >= 2 characters
The customer's full name.
If full_name is not specified, this value is taken from the cardholder_name the first time a payment is made.
The customer's phone number.
The customer's email address.
Object containing address details.
Possible values: <= 100 characters
Street line 1 information.
Possible values: <= 100 characters
Street line 2 information.
Possible values: <= 100 characters
The region associated with the address.
Possible values: <= 100 characters
The city associated with the address.
Possible values: <= 2 characters
The 2-letter country code of the country associated with the address.
Possible values: <= 100 characters
The postcode associated with the address.
Possible values: [automatic, forced]
Default value: automatic
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 values: [automatic, manual]
Default value: automatic
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. |
For more information, see Capture an order.
Automatic cancellation period for uncaptured orders, specified in ISO 8601 format.
Orders in authorised state will be automatically cancelled if they stay uncaptured for longer than the period specified. Maximum: 7 days = P7D.
Cannot be a negative value.
Unique ID representing the location where merchants sells products.
Currently, only online locations are supported.
For more information, see: Locations.
Possible values: <= 50
Additional information to track your orders in your system, by providing custom metadata using "<key>" : "<value>" pairs.
Restrictions:
- Max number of items:
50 - Max length of metadata values:
500 - Format of metadata keys:
^[a-zA-Z][a-zA-Z\\d_]{0,39}$
Object containing industry-specific information associated with the order.
Possible values: [airline, crypto]
Type of the industry-specific data object, determining what further data is expected for a particular order.
Available types:
airlinecrypto
Unique ID of the travel reservation associated with the order.
The UTC date and time of the final journey leg.
Possible values: [flexible, fixed]
The type of the ticket.
The code of the Computer Reservation System (CRS) used to make the booking and purchase the ticket.
Possible values: [new, modification]
Parameter indicating whether this order is related to a new ticket reservation or a modification of an existing one.
Possible values: [refundable, non_refundable, partially_refundable]
Parameter indicating whether the ticket is refundable, partially refundable, or not refundable.
Array containing information of passengers associated with the booking.
Passenger's first name.
Passenger's last name.
Array containing information of journey legs associated with the booking.
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: 1LHR > DUB: 2DUB > LHR: 3LHR > FRA: 4
The IATA 3-letter airport code for the departure airport.
The IATA 3-letter airport code for the arrival airport.
The flight identifier, without airline code.
The fare base code for the given journey leg.
The UTC date and time of the flight departure for the given journey leg.
The name of the airline associated with the journey leg.
The IATA 2-letter accounting code identifying the airline associated with the journey leg.
Possible values: <= 2000 characters
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.
Restrictions:
- Max length of
urlstring:2000 - Only valid
http://orhttps://domains are accepted - Domain cannot be
localhostor IP address
Merchant order ID for external reference.
Use this field to set the ID that your own system can use to easily track orders.
Response
Order created
Permanent order ID used to retrieve, capture, cancel, or refund an order after authorization.
Temporary ID for the order, which expires when the payment is authorised.
The order token is used to initialise the Revolut Checkout widget, and to be returned by the Revolut Pay widget's createOrder callback.
Possible values: [payment, payment_request, refund, chargeback, chargeback_reversal, credit_reimbursement]
The type of the order.
Possible values: [pending, processing, authorised, completed, cancelled, failed]
The state of the order.
The date and time the order was created.
The date and time the order was last updated.
The description of the order.
Possible values: [automatic, manual]
Default value: automatic
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. |
For more information, see Capture an order.
Automatic cancellation period for uncaptured orders, specified in ISO 8601 format.
Orders in authorised state will be automatically cancelled if they stay uncaptured for longer than the period specified. Maximum: 7 days = P7D.
Cannot be a negative value.
The amount of the order (minor currency unit). For example, enter 7034 for €70.34 in the field.
The amount of the order (minor currency unit) that is outstanding. For example, enter 7034 for €70.34 in the field.
The amount of the refunded order (minor currency unit). For example, enter 7034 for €70.34 in the field.
ISO 4217 currency code in upper case.
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.
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, 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 id with the order.If email was provided, we try to find the customer by email. We ignore other details in this case. |
| New customer | If email is provided and no match is found, a new customer instance is created with the data provided and appended to the order. |
Permanent ID of a customer used to retrieve, update, delete a customer. This ID can also be used to link customer to an order.
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.
Possible values: >= 2 characters
The customer's full name.
If full_name is not specified, this value is taken from the cardholder_name the first time a payment is made.
The customer's phone number.
The customer's email address.
Object containing address details.
Possible values: <= 100 characters
Street line 1 information.
Possible values: <= 100 characters
Street line 2 information.
Possible values: <= 100 characters
The region associated with the address.
Possible values: <= 100 characters
The city associated with the address.
Possible values: <= 2 characters
The 2-letter country code of the country associated with the address.
Possible values: <= 100 characters
The postcode associated with the address.
The details of all the payments that have been made towards this order (successful or unsuccessful).
The ID of the payment.
Possible 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]
The status of the payment.
Possible values: [high_risk, cardholder_name_missing, unknown_card, unknown_card, pick_up_card, invalid_card, invalid_card, expired_card, do_not_honour, invalid_email, invalid_email, invalid_amount, restricted_card, restricted_card, expired_card, insufficient_funds, rejected_by_customer, rejected_by_customer, cardholder_name_missing, withdrawal_limit_exceeded, withdrawal_limit_exceeded, pick_up_card, 3ds_challenge_failed_manually, invalid_amount, transaction_not_allowed_for_cardholder, issuer_not_available, invalid_expiry, invalid_cvv, invalid_pin, invalid_phone, invalid_address, invalid_country, invalid_merchant, customer_challenge_failed, customer_challenge_abandoned, customer_name_mismatch, technical_error]
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.
The reason for a failed or declined payment, sent by the financial institution processing the payment.
The date and time the payment was created.
The date and time the payment was last updated.
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.
The amount of the order (minor currency unit). For example, 7034 stands for €70.34.
ISO 4217 currency code in upper case.
The amount of the settled payment (minor currency unit). For example, 7034 stands for €70.34.
The currency of the settled payment. ISO 4217 currency code in upper case.
The details of the payment method used to make the payment.
ID of the saved payment method.
The id parameter is only returned when the payment method is saved.
Possible values: [card, revolut_pay_card, revolut_pay_account]
The type of payment method used to pay for the order.
Available values:
Payment method type | Description |
|---|---|
card | The customer paid the order using their credit or debit card. |
revolut_pay_card | The customer paid the order via Revolut Pay using their credit or debit card. |
revolut_pay_account | The customer paid the order via Revolut Pay using their Revolut account. |
Possible values: [visa, mastercard]
The type of the card.
Possible values: [credit, debit, prepaid]
The type of card funding.
The 2-letter country code of the country where the card was issued.
Possible values: >= 6 characters and <= 6 characters
The BIN of the card.
Possible values: >= 4 characters and <= 4 characters
The last four digits of the card.
The expiry date of the card in the format of MM/YY.
The name of the cardholder.
The details of the check for card payment. Only for orders with successful payments.
The details of the 3-D Secure check. Only for orders with successful payments.
Possible values: [verified, failed, challenge]
The result of 3-D Secure check.
The 3-D Secure version.
Possible values: [match, not_match, incorrect, not_processed]
The result of CVV verification.
| Parameter value | Description |
|---|---|
match | CVV matches the card's CVV |
not_match | CVV does not match the card's CVV |
incorrect | CVV format is incorrect for this type of card |
not_processed | CVV verification was not performed |
Possible values: [match, not_match, n_a, invalid]
The result of address verification.
Possible values: [match, not_match, n_a, invalid]
The result of postcode verification.
Possible values: [match, not_match, n_a, invalid]
The result of cardholder verification.
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.
Only returned if the payment's state is authentication_challenge.
Possible values: [three_ds, three_ds_fingerprint]
Type of the authentication challenge the payment triggers.
The URL of the authentication challenge.
Object containing address details.
Possible values: <= 100 characters
Street line 1 information.
Possible values: <= 100 characters
Street line 2 information.
Possible values: <= 100 characters
The region associated with the address.
Possible values: <= 100 characters
The city associated with the address.
Possible values: <= 2 characters
The 2-letter country code of the country associated with the address.
Possible values: <= 100 characters
The postcode associated with the address.
Possible values: [low, high]
The risk level of the card.
If the risk level is high, the payment might be declined.
The details of the order fee.
Possible values: [fx, acquiring]
The type of the order fee.
The amount of the payment fee (minor currency unit). For example, enter 7034 for €70.34 in the field.
The currency of the payment fee. ISO 4217 currency code in upper case.
Unique ID representing the location where merchants sells products.
Currently, only online locations are supported.
For more information, see: Locations.
Possible values: <= 50
Additional information to track your orders in your system, by providing custom metadata using "<key>" : "<value>" pairs.
Restrictions:
- Max number of items:
50 - Max length of metadata values:
500 - Format of metadata keys:
^[a-zA-Z][a-zA-Z\\d_]{0,39}$
Object containing industry-specific information associated with the order.
Possible values: [airline, crypto]
Type of the industry-specific data object, determining what further data is expected for a particular order.
Available types:
airlinecrypto
Unique ID of the travel reservation associated with the order.
The UTC date and time of the final journey leg.
Possible values: [flexible, fixed]
The type of the ticket.
The code of the Computer Reservation System (CRS) used to make the booking and purchase the ticket.
Possible values: [new, modification]
Parameter indicating whether this order is related to a new ticket reservation or a modification of an existing one.
Possible values: [refundable, non_refundable, partially_refundable]
Parameter indicating whether the ticket is refundable, partially refundable, or not refundable.
Array containing information of passengers associated with the booking.
Passenger's first name.
Passenger's last name.
Array containing information of journey legs associated with the booking.
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: 1LHR > DUB: 2DUB > LHR: 3LHR > FRA: 4
The IATA 3-letter airport code for the departure airport.
The IATA 3-letter airport code for the arrival airport.
The flight identifier, without airline code.
The fare base code for the given journey leg.
The UTC date and time of the flight departure for the given journey leg.
The name of the airline associated with the journey leg.
The IATA 2-letter accounting code identifying the airline associated with the journey leg.
Possible values: <= 2000 characters
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.
Restrictions:
- Max length of
urlstring:2000 - Only valid
http://orhttps://domains are accepted - Domain cannot be
localhostor IP address
Merchant order ID for external reference.
Use this field to set the ID that your own system can use to easily track orders.
Link to a checkout page hosted by Revolut.