Retrieve an order
Retrieve the details of an order that has been created. Provide the unique order ID, and the corresponding order information is returned.
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 account: Access the Revolut Business log in page and enter your credentials.
- Navigate to Merchant API settings: Once logged in, access the Merchant API settings page by clicking in the top right corner, then selecting APIs > Merchant API. Here you can access your Production API keys (Public, Secret) specific to your Merchant account.
- Get API keys: If you're visiting this page for the first time, you'll need to generate your Production API Secret key, click the
Generatebutton.
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
The ID of the Order object.
Example: "Bearer sk_1234567890ABCdefGHIjklMNOpqrSTUvwxYZ_1234567890-Ab_cdeFGHijkLMNopq"
This parameter accepts the Merchant API Secret key to authorise requests coming from the merchant's backend.
It ensures that ensures that each request is authenticated and authorised by verifying the secret key. The secret key should be included in all request headers as a Bearer token.
For more information, see: Authorization
Possible values: [2023-09-01, 2024-05-01, 2024-09-01]
Example: "2024-09-01"
The version of the Merchant API, specified in YYYY-MM-DD format.
If not specified, you will receive an error.
For more information about API versioning, see: API versions.
Response
Order retrieved
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 createOrder callback on the Revolut Pay widget and Apple Pay and Google Pay widget.
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.
For more information about the order lifecycle, see: Order and payment lifecycle.
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.
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.
The order total expressed in minor currency units, according to the ISO 4217 standard. For example, 7034 in EUR corresponds to €70.34.
- Conversion between major and minor units varies by currency. For instance,
100minor units equal £1.00 inGBP, whereas inISKthey represent 100 units. For more details, see the ISO 4217 standard. - If
line_itemsare provided, the orderamountmust equal the sum of all line items'total_amount. - For card payments with a non-zero amount, the order
amountmust 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.
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.
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).
ISO 4217 currency code in upper case.
For more information about the supported currencies, see: Help Center.
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.
For more information about the supported currencies, see: Help Center.
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 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. |
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 length: >= 2 characters
The customer's full name.
The customer's phone number.
The customer's email address.
If you wish to save a customer's payment method using any of the available payment methods on the Revolut Checkout Widget (Revolut Pay, Card payments), you need to meet one of the following requirements:
- Have a customer object with
emailand assign it to the order by providingcustomer.id - Create a new customer with
customer.emailduring order creation - Pass the
emailin the configuration of the Revolut Checkout Widget
For more information, see: Charge a customer's saved payment method.
The birth date of the customer.
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: [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]
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 order total expressed in minor currency units, according to the ISO 4217 standard. For example, 7034 in EUR corresponds to €70.34.
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.
ISO 4217 currency code in upper case.
For more information about the supported currencies, see: Help Center.
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.
For more information about the supported currencies, see: Help Center.
The details of the payment method used to make the payment.
Object containing details of a card used via Apple Pay.
ID of the saved payment method.
The id parameter is only returned when the payment method is saved.
Possible values: [apple_pay, card, google_pay, revolut_pay_card, revolut_pay_account]
The type of payment method used to pay for the order.
Available values:
Payment method type | Description |
|---|---|
apple_pay | The customer paid the order using Apple Pay. |
card | The customer paid the order using their credit or debit card. |
google_pay | The customer paid the order using Google Pay. |
revolut_pay_card | The customer paid the order via Revolut Pay using their credit or debit card. |
revolut_pay_account | The customer paid the order via Revolut Pay using their Revolut account. |
Possible values: [visa, mastercard, american_express]
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 length: >= 6 characters and <= 6 characters
The BIN of the card.
Possible length: >= 4 characters and <= 4 characters
The last four digits of the card number.
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 3D Secure check. Only for orders with successful payments.
Not returned for Apple Pay and Google Pay payments.
The Electronic Commerce Indicator (ECI) value corresponds to the authentication result and indicates the level of security used when the payment information was provided.
Possible values: [verified, failed, challenge]
The result of 3D Secure check.
The 3D 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.
Possible length: >= 44 characters and <= 44 characters
A unique identifier for a payment method, always 44 characters long. This fingerprint can be used to uniquely identify various payment methods.
Fingerprint generation
| Payment method | Description |
|---|---|
| All payment methods | A fingerprint is generated for all payment methods, including cards, Revolut Pay (card, account-to-account payments), Apple Pay, and Google Pay. |
| Cards (Revolut Pay & Card Gateway) | For cards, the fingerprint is based on the PAN. Cards processed via Revolut Pay and our card gateway will share the same fingerprint. Renewed cards (new expiry/CVV) retain the same fingerprint for efficient blocking. |
| Apple Pay & Google Pay | Since Apple Pay and Google Pay provide us Device PANs (DPAN), the fingerprint is based on the DPAN provided by Apple/Google, not the connected card's PAN. This means that a new DPAN (and fingerprint) is generated for cards in case they are re-added to the customer's digital wallet, or added to different devices. |
Detecting duplicate payment methods
Fingerprints are a valuable tool for detecting duplicate payment methods by identifying if a payment method has been seen before. This capability, in turn, helps in preventing various types of misuse (e.g., exploitation of free trials, or association with known problematic accounts, which can be a form of fraud). To effectively use fingerprints for this purpose, you will need to create and maintain your own lists (e.g., blocklists of known problematic fingerprints, allowlists for trusted customers, or tracking frequently used fingerprints).
The ideal way to utilise fingerprints is by combining them with a manual capture process. While automatic capture with subsequent refunds for problematic payments is possible, manual capture based on fingerprint validation is recommended.
During your manual capture workflow, after a payment was authorised:
- Check the fingerprint status by comparing it against your maintained lists and internal business rules.
- If you decide to proceed with the payment (e.g., the fingerprint is not on a blocklist, or matches a trusted customer's previous payment method): Capture the order.
- If you decide not to proceed with the payment (e.g., the fingerprint matches a known fraudulent fingerprint, or exhibits suspicious patterns): Cancel the order.
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.
Information about the 3DS 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 length: <= 100 characters
Street line 1 information.
Possible length: <= 100 characters
Street line 2 information.
Possible length: <= 100 characters
The region associated with the address.
Possible length: <= 100 characters
The city associated with the address.
Possible length: <= 2 characters
The 2-letter country code of the country associated with the address.
Possible length: <= 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.
For more information about the supported currencies, see: Help Center.
Unique ID representing the location where merchants sells products.
Currently, only online locations are supported.
For more information, see: Locations.
Possible number of items: <= 50 items
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.
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. |
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
Possible values: [airline, crypto, event, lodging, marketplace]
Type of the industry-specific data object, determining what additional data is expected.
Available types:
| Object type | Description |
|---|---|
airline | Object containing information about a specific airline ticket purchase. |
crypto | Object containing information about crypto transactions associated with the order. |
marketplace | 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 subseller involved in the transaction. |
event | Object containing information about event ticket bookings associated with the order. |
lodging | Object containing information about lodging bookings associated with the order. |
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.
The UTC date and time of the final journey leg.
The following limitations apply:
- When creating or updating an order,
fulfillment_datecannot be set to a date in the past. - When updating an order, if the current
fulfillment_datevalue is already in the past, it cannot be modified. The date must remain as is to maintain data integrity for completed transactions.
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).
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.
Possible values: [fixed, flexible]
The type of the ticket.
| Parameter value | Description |
|---|---|
fixed | Non-modifiable once confirmed. |
flexible | Allows modifications or cancellations under specified conditions. |
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.
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,
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 length: <= 2000 characters
Pattern: Value must match regular expression ^https?:\/{2}.+/gi
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.
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.
Domain cannot be localhost or IP address.
Object for providing additional information stored in the merchant's order management system.
Possible length: <= 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.
Object containing information about upcoming payments associated with the order.
The date and time in ISO 8601 format when the upcoming payment is scheduled to be executed.
The unique ID of the customer's payment method used to complete the scheduled payment.
For more information about operations related to customer's payment methods, see:
Link to a checkout page hosted by Revolut.
Pattern: Value must match regular expression ^https:\/{2}.+/gi
The URL your customer will be redirected to after completing a payment on the hosted checkout page (checkout_url parameter's value of the order).
For more information on how to use the redirect_url, see: Custom redirection via the API
Details about the shipping related to the order, including address, contact information, and individual shipments.
Required for retail merchants. Omitting this information may trigger additional scrutiny and risk mitigation actions by the Revolut risk team.
Details of a physical address.
Possible length: <= 100 characters
Primary address line.
Possible length: <= 100 characters
Secondary address line, such as floor and apartment number.
Possible length: <= 100 characters
State or province of the address.
Possible length: <= 100 characters
City of the address.
Possible length: >= 2 characters and <= 2 characters
Pattern: Value must match regular expression ^[A-Z]{2}$
ISO 2-letter country code.
Possible length: <= 100 characters
Postal code of the address.
Contact details for someone responsible for the shipment.
At least email or phone is required.
Possible length: <= 250 characters
Full name of the contact person.
Email address of the contact person.
Phone number of the contact person.
Possible number of items: <= 50 items
List of individual shipment details.
Possible length: <= 250 characters
Name of the company handling the shipment.
Possible length: <= 500 characters
Unique tracking number for the shipment.
Estimated delivery date and time for the shipment. The time should also include the customer's timezone.
Possible length: <= 2000 characters
An HTTP/HTTPS URL where the shipment can be tracked.
Restrictions:
- Max length:
2000 - Only valid
http://orhttps://domains are accepted - Domain cannot be
localhostor IP 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 number of items: <= 250 items
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.
Required for retail merchants. Omitting this information may trigger additional scrutiny and risk mitigation actions by the Revolut risk team.
Possible length: <= 250 characters
Name of the line item.
Possible values: [physical, service]
Type of the line item.
Object representing the quantity details of a line item, including the amount and its associated unit of measurement.
The number of units of the line item.
Possible length: <= 100 characters
The measurement unit for the quantity, such as cm, or kg.
The unit price of the line item.
The total amount to be paid for the line item, including taxes and discounts.
Possible length: <= 250 characters
Unique identifier of line item in the merchant's system.
Possible number of items: <= 50 items
A list of discounts applied to the line item. Each discount should be subtracted from the total amount payable for the item.
Possible length: <= 100 characters
The specific name or label of the discount applied to the line item.
The monetary value of the discount.
Possible number of items: <= 50 items
A list of taxes applied to the line item. Each tax should be added to the total amount payable for the item.
Possible length: <= 100 characters
The specific name or designation of the tax applied to the line item.
The monetary value of the tax in minor currency units (e.g., cents for EUR).
Possible number of items: <= 50 items
A list of URLs pointing to images related to the line item. These images can provide visual details or representations of the item.
Possible length: <= 1024 characters
Description of the line item.
Possible length: <= 2000 characters
An HTTP/HTTPS URL that links to more information about the line item, such as a product page or details.
Restrictions:
- Max length:
2000 - Only valid
http://orhttps://domains are accepted - Domain cannot be
localhostor IP address
Possible length: non-empty and <= 19 characters
Pattern: Value must match regular expression ^[^*\n\r\\]+$
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 thestatement_descriptor_suffixfield.
- 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.