Merchant API
Capture an order
api
post
/api/orders/{order_id}/capture

Capture an order

This endpoint is used to capture the funds of an existing, uncaptured order. When the payment for an order is authorised, you can capture the order to send it to the processing stage.

info

For more information about the order and payment lifecycle, see: Order and payment lifecycle.

Capture modes​

When you create an order, you can choose one of the following capture modes:

Capture modeDescription
automaticThe order is captured automatically after payment authorisation. No further actions are needed.
manualThe order is not captured automatically and stays in authorised state. You must manually capture the order using the steps outlined below.
caution

Uncaptured orders remain in authorised state for 7 days. If not captured within this period, the funds are returned to the customer's original payment method.

Manual capture​

To capture an order manually, use one of the following methods:

Web UIMerchant API
  1. Log in to your Revolut Business portal.
  2. Navigate to the Merchant tab on the dashboard, and click the See all button in the Transactions section.
  3. Select an uncaptured payment, and click Capture.
Use the /capture endpoint.
info

For more information about manually capturing an order, see: Authorise an amount to capture later.

Partial capture​

You have the option to capture only a fraction of the full amount. In such cases, the uncaptured portion of the amount will be voided.

caution

The following limitations apply to manual captures:

  • It's not possible to capture an amount multiple times
  • Captured amount can't exceed the authorised amount
  • On Web UI, only capturing full amount is possible
  • 0 amount captures are not allowed
  • For partial captures, you can only resend the request with the initial amount

Idempotency and repeated requests​

The capture operation is idempotent. This means that an order can only be captured once. If you send a capture request more than once:

  • The first valid request captures the order and moves it to the processing stage.
  • Any subsequent capture requests for the same order will not recapture the funds. Instead, these requests will behave like a Retrieve an order request. The response will provide the current state of the order as if you queried it using the order retrieval endpoint.
info

Utilising the idempotent nature of this endpoint helps maintain data consistency and prevents duplicate processing of the same order.

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):

  1. Log in to your Revolut Business portal.
  2. On the top left corner, click your account name, click APIs then select Merchant API.
  3. 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.

Merchant API - Settings

note

Use these keys only for the production environment. For the Revolut Business Sandbox environment, use the sandbox API keys.

SSL​

note

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​

note

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​

Path Parameters
Path Parameters

The ID of the Order object.

Header Parameters
Header Parameters

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.

info

For more information, see: Authorization

Possible values: [2023-09-01, 2024-05-01, 2024-09-01]

The version of the Merchant API, specified in YYYY-MM-DD format.

If not specified, you will receive an error.

info

For more information about API versioning, see: API versions.

Request body
Body object

Specify an amount to capture, in minor currency units. The amount must not exceed the authorised amount.

If order has been previously captured, the amount must be equal to the initially captured amount. Uncaptured amount will be voided.

If not provided, it defaults to the authorised amount (full capture will be executed).

Response​

Order captured

Response body
Body object

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.

info

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 valueDescription
automaticThe order is captured automatically after payment authorisation.
manualThe order is not captured automatically. You must manually capture the order later.
info

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.

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.

The total amount of the order in minor currency units. For example, 7034 represents €70.34.

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.

info

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.

info

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 caseAPI behavior
Existing customerIf 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 customerIf 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.

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.

Possible values: >= 2 characters

The customer's full name.

The customer's phone number.

The customer's email address.

note

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 email and assign it to the order by providing customer.id
  • Create a new customer with customer.email during order creation
  • Pass the email in the configuration of the Revolut Checkout Widget

For more information, see: Charge a customer's saved payment method.

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, unknown_card, invalid_card, do_not_honour, invalid_email, restricted_card, expired_card, insufficient_funds, rejected_by_customer, cardholder_name_missing, 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 total amount of the order in minor currency units. For example, 7034 represents €70.34.

ISO 4217 currency code in upper case.

info

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.

info

For more information about the supported currencies, see: Help Center.

The details of the payment method used to make the payment.

ID of the saved payment method.

note

The id parameter is only returned when the payment method is saved.

Possible values: [apple_pay, apple_tap_to_pay, card, cash, google_pay, revolut_pay_card, revolut_pay_account]

The type of payment method used to pay for the order.

Available values:

Payment method typeDescription
apple_payThe customer paid the order using Apple Pay.
apple_tap_to_payThe customer paid the order via Apple Tap to Pay.
cardThe customer paid the order using their credit or debit card.
cashThe customer paid the order using cash via the Revolut POS app.
google_payThe customer paid the order using Google Pay.
revolut_pay_cardThe customer paid the order via Revolut Pay using their credit or debit card.
revolut_pay_accountThe 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 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 3D Secure check. Only for orders with successful 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 valueDescription
matchCVV matches the card's CVV
not_matchCVV does not match the card's CVV
incorrectCVV format is incorrect for this type of card
not_processedCVV 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.

info

For more information about the supported currencies, see: Help Center.

Unique ID representing the location where merchants sells products.

note

Currently, only online locations are supported.

info

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.

caution

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.

info

In the following cases, industry-specific info is required:

Transaction typeRequired for
airlineAirlines and Online Travel Agencies (OTAs).
cryptoCrypto merchants.
marketplaceMarketplace merchants.

Possible values: [airline, crypto, marketplace]

Type of the industry-specific data object, determining what additional data is expected.

Available types:

Object typeDescription
airlineObject containing information about a specific airline ticket purchase.
cryptoObject containing information about crypto transactions associated with the order.
marketplaceThis 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.

Unique ID of the travel reservation associated with the order.

The UTC date and time of the final journey leg.

caution

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.

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: 1
  • LHR > DUB: 2
  • DUB > LHR: 3
  • LHR > 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

URL to the online portal for managing the airline booking. This link allows the customer to perform actions such as selecting seats, adding baggage, or making other changes to their reservation.

caution

Restrictions:

  • Max length: 2000
  • Only valid http:// or https:// domains are accepted
  • Domain cannot be localhost or IP address

Object for providing additional information stored in the merchant's order management system.

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.

caution

Restrictions:

  • Max length of url string: 2000
  • Only valid http:// or https:// domains are accepted
  • Domain cannot be localhost or 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.

info

For more information about operations related to customer's payment methods, see:

Link to a checkout page hosted by Revolut.

Possible values: 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).

info

For more information on how to use the redirect_url, see: Custom redirection via the API

Possible values: [automatic, forced]

Default value: automatic

The enforce challenge mode. automatic is used by default.

Parameter valueDescription
automaticThe payments created for an order will have challenge requirement calculated by our fraud mechanisms. Not all payments will trigger a 3DS challenge.
forcedThe payments created for an order will always require a 3DS challenge. Currently only supported for card payments.
Was this page helpful?
Loading...