Merchant API

Retrieve payment details

api

get

/api/payments/{payment_id}

Retrieve payment details

Retrieve information about a specific payment, based on the payment's ID.

Use this endpoint to track a payment's lifecycle, for example:

When you develop a 1-click checkout process
When you build a subscription management system

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 Generate button.

SSL

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

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

Header Parameters

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.

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

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

Response

Payment details

Response body

Body object

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.

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.

Object containing details of a card used via Apple Pay.

ID of the saved payment method.

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.

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.

Object containing address details.