{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/api-evangelist/revolut/main/json-schema/revolut-payment-retrieval-v3-schema.json", "title": "Payment-Retrieval-v3", "description": "Represents a payment for an order.\n\nFor pre-authorised payments, the `authorised_amount` field tracks the currently authorised amount, which may differ from `amount` during incremental authorisation processing.", "x-generated": "2026-10-12", "x-method": "derived", "x-generator": "derive-json-schema.py", "x-source": "openapi/revolut-payments-api-openapi.yml#/components/schemas/Payment-Retrieval-v3", "type": "object", "properties": { "order_id": { "type": "string", "format": "uuid", "description": "The ID of the associated order." }, "id": { "$ref": "#/$defs/Payment-Id" }, "state": { "$ref": "#/$defs/Payment-State-v2" }, "decline_reason": { "$ref": "#/$defs/Decline-Reason-v2" }, "bank_message": { "$ref": "#/$defs/Bank-Message" }, "created_at": { "$ref": "#/$defs/Payment-Created" }, "updated_at": { "$ref": "#/$defs/Payment-Updated" }, "token": { "$ref": "#/$defs/Payment-Token" }, "amount": { "$ref": "#/$defs/Payment-Amount" }, "authorised_amount": { "$ref": "#/$defs/Payment-Authorised-Amount" }, "currency": { "$ref": "#/$defs/Currency" }, "settled_amount": { "$ref": "#/$defs/Payment-Settled-Amount" }, "settled_currency": { "$ref": "#/$defs/Payment-Settled-Currency" }, "payment_method": { "$ref": "#/$defs/Payment-Method-v2" }, "authentication_challenge": { "$ref": "#/$defs/Authentication-Challenge-v2" }, "billing_address": { "$ref": "#/$defs/Address-v2" }, "risk_level": { "$ref": "#/$defs/Payment-Risk-Level" }, "fees": { "$ref": "#/$defs/Fees" }, "payer": { "$ref": "#/$defs/Payer" } }, "required": [ "id", "state", "created_at", "updated_at", "amount" ], "$defs": { "Address-v2": { "type": "object", "description": "Object containing address details.", "properties": { "street_line_1": { "type": "string", "description": "Street line 1 information.", "maxLength": 100 }, "street_line_2": { "type": "string", "description": "Street line 2 information.", "maxLength": 100 }, "region": { "type": "string", "description": "The region associated with the address.", "maxLength": 100 }, "city": { "type": "string", "description": "The city associated with the address.", "maxLength": 100 }, "country_code": { "type": "string", "description": "The 2-letter country code of the country associated with the address.", "maxLength": 2 }, "postcode": { "type": "string", "description": "The postcode associated with the address.", "maxLength": 100 } }, "required": [ "country_code", "postcode" ] }, "Apple-Pay": { "type": "object", "description": "Object containing details of a card used via Apple Pay.", "properties": { "id": { "type": "string", "format": "uuid", "description": "ID of the saved payment method.\n\n:::note\nThe `id` parameter is only returned when the payment method is saved.\n:::" }, "type": { "$ref": "#/$defs/Payment-Method-Type" }, "card_brand": { "type": "string", "description": "The type of the card.", "enum": [ "visa", "mastercard", "american_express" ] }, "funding": { "type": "string", "description": "The type of card funding.", "enum": [ "credit", "debit", "prepaid" ] }, "card_country_code": { "type": "string", "description": "The 2-letter country code of the country where the card was issued." }, "card_bin": { "type": "string", "description": "The BIN of the card.", "minLength": 6, "maxLength": 6 }, "card_last_four": { "type": "string", "description": "The last four digits of the card number.", "minLength": 4, "maxLength": 4 }, "card_expiry": { "type": "string", "format": "MM/YY", "description": "The expiry date of the card in the format of MM/YY." }, "cardholder_name": { "type": "string", "description": "The name of the cardholder." }, "checks": { "$ref": "#/$defs/Card-Checks-v2" }, "authorisation_code": { "$ref": "#/$defs/Authorisation-Code" }, "arn": { "$ref": "#/$defs/Arn" }, "capture_deadline": { "$ref": "#/$defs/Capture-Deadline" }, "terminal_hardware_id": { "$ref": "#/$defs/Terminal-Hardware-Id" }, "fingerprint": { "$ref": "#/$defs/Fingerprint" }, "network_transaction_id": { "$ref": "#/$defs/Network-Transaction-Id" } }, "required": [ "type" ] }, "Arn": { "type": "string", "description": "Acquirer Reference Number (ARN) of the payment.\n\n:::note\nOnly returned for refund payments made by a card.\n:::", "minLength": 23, "maxLength": 23 }, "Authentication-Challenge-Type": { "type": "string", "enum": [ "three_ds", "three_ds_fingerprint" ], "description": "Type of the authentication challenge the payment triggers." }, "Authentication-Challenge-v2": { "type": "object", "description": "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](https://developer.revolut.com/docs/guides/merchant/reference/3d-secure).\n\nOnly returned if the payment's state is `authentication_challenge`.", "oneOf": [ { "$ref": "#/$defs/Three-Ds" }, { "$ref": "#/$defs/Three-Ds-Fingerprint-v2" } ] }, "Authorisation-Code": { "type": "string", "description": "The authorisation code (or auth code) is a short, alphanumeric code returned by the cardholder's issuing bank to the merchant's terminal or payment gateway.\n\nIt serves as confirmation that the transaction has been approved and funds are available.", "pattern": "^[a-zA-Z0-9]{2,6}$", "minLength": 2, "maxLength": 6 }, "Bank-Message": { "type": "string", "description": "The reason for a `failed` or `declined` payment, sent by the financial institution processing the payment." }, "Capture-Deadline": { "type": "string", "format": "date-time", "description": "The date and time by which the payment must be captured.\n\nAfter this deadline, the authorised funds may be automatically released by the card issuer." }, "Card": { "type": "object", "description": "Object containing details of the card used for the payment.", "properties": { "id": { "type": "string", "format": "uuid", "description": "ID of the saved payment method.\n\n:::note\nThe `id` parameter is only returned when the payment method is saved.\n:::" }, "type": { "$ref": "#/$defs/Payment-Method-Type" }, "card_brand": { "type": "string", "description": "The type of the card.", "enum": [ "visa", "mastercard", "american_express" ] }, "funding": { "type": "string", "description": "The type of card funding.", "enum": [ "credit", "debit", "prepaid" ] }, "card_country_code": { "type": "string", "description": "The 2-letter country code of the country where the card was issued." }, "card_bin": { "type": "string", "description": "The BIN of the card.", "minLength": 6, "maxLength": 6 }, "card_last_four": { "type": "string", "description": "The last four digits of the card number.", "minLength": 4, "maxLength": 4 }, "card_expiry": { "type": "string", "format": "MM/YY", "description": "The expiry date of the card in the format of MM/YY." }, "cardholder_name": { "type": "string", "description": "The name of the cardholder." }, "checks": { "$ref": "#/$defs/Card-Checks-v2" }, "authorisation_code": { "$ref": "#/$defs/Authorisation-Code" }, "arn": { "$ref": "#/$defs/Arn" }, "capture_deadline": { "$ref": "#/$defs/Capture-Deadline" }, "terminal_hardware_id": { "$ref": "#/$defs/Terminal-Hardware-Id" }, "fingerprint": { "$ref": "#/$defs/Fingerprint" }, "network_transaction_id": { "$ref": "#/$defs/Network-Transaction-Id" } }, "required": [ "type" ] }, "Card-Checks-v2": { "type": "object", "description": "The details of the check for card payment. Only for orders with successful payments.", "properties": { "three_ds": { "type": "object", "description": "The details of the 3D Secure check. Only for orders with successful payments.\n\n:::note\nNot returned for Apple Pay and Google Pay payments.\n:::", "properties": { "eci": { "type": "string", "description": "The Electronic Commerce Indicator (ECI) value corresponds to the authentication result and indicates the level of security used when the payment information was provided." }, "state": { "type": "string", "description": "The result of 3D Secure check.", "enum": [ "verified", "failed", "challenge" ] }, "version": { "type": "integer", "description": "The 3D Secure version." } } }, "cvv_verification": { "type": "string", "description": "The result of CVV verification.\n\n| Parameter value | Description |\n| ----- | ----------- |\n| `match` | CVV matches the card's CVV |\n| `not_match` | CVV does not match the card's CVV |\n| `incorrect` | CVV format is incorrect for this type of card |\n| `not_processed` | CVV verification was not performed |", "enum": [ "match", "not_match", "incorrect", "not_processed" ] }, "address": { "type": "string", "description": "The result of address verification.", "enum": [ "match", "not_match", "n_a", "invalid" ] }, "postcode": { "type": "string", "description": "The result of postcode verification.", "enum": [ "match", "not_match", "n_a", "invalid" ] }, "cardholder": { "type": "string", "description": "The result of cardholder verification.", "enum": [ "match", "not_match", "n_a", "invalid" ] } } }, "Currency": { "type": "string", "format": "ISO 4217", "minLength": 3, "maxLength": 3, "description": "[ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code in upper case.\n\n:::info\nFor 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/).\n:::" }, "Decline-Reason-v2": { "type": "string", "description": "The reason for a `failed` or `declined` payment.\n\nA failed or declined payment can result from multiple reasons. To learn more, check our [failure reasons](https://developer.revolut.com/docs/guides/merchant/reference/error-codes/decline-reasons).", "enum": [ "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" ] }, "Email": { "type": "string", "format": "email", "description": "The email address of the customer." }, "Fee": { "type": "object", "properties": { "type": { "type": "string", "description": "The type of the order fee.", "enum": [ "fx", "acquiring" ] }, "amount": { "type": "integer", "description": "The amount of the payment fee (minor currency unit). For example, enter `7034` for €70.34 in the field." }, "currency": { "type": "string", "description": "The currency of the payment fee. [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code in upper case.\n\n:::info\nFor 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/).\n:::" } } }, "Fees": { "type": "array", "description": "The details of the order fee.", "items": { "$ref": "#/$defs/Fee" } }, "Fingerprint": { "type": "string", "minLength": 44, "maxLength": 44, "description": "A unique identifier for a payment method, always 44 characters long. This fingerprint can be used to uniquely identify various payment methods.\n\n#### Fingerprint generation\n\n| Payment method | Description |\n| -------- | ----------- |\n| **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. |\n| **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. |\n| **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. |\n\n#### Detecting duplicate payment methods\n\nFingerprints 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). \n\nThe 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.\n\nDuring your manual capture workflow, after a payment was authorised:\n \n - Check the fingerprint status by comparing it against your maintained lists and internal business rules.\n - 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](https://developer.revolut.com/docs/api/merchant#capture-order).\n - 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](https://developer.revolut.com/docs/api/merchant#cancel-order)." }, "Google-Pay": { "type": "object", "description": "Object containing details of a card used via Google Pay.", "properties": { "id": { "type": "string", "format": "uuid", "description": "ID of the saved payment method.\n\n:::note\nThe `id` parameter is only returned when the payment method is saved.\n:::" }, "type": { "$ref": "#/$defs/Payment-Method-Type" }, "card_brand": { "type": "string", "description": "The type of the card.", "enum": [ "visa", "mastercard", "american_express" ] }, "funding": { "type": "string", "description": "The type of card funding.", "enum": [ "credit", "debit", "prepaid" ] }, "card_country_code": { "type": "string", "description": "The 2-letter country code of the country where the card was issued." }, "card_bin": { "type": "string", "description": "The BIN of the card.", "minLength": 6, "maxLength": 6 }, "card_last_four": { "type": "string", "description": "The last four digits of the card number.", "minLength": 4, "maxLength": 4 }, "card_expiry": { "type": "string", "format": "MM/YY", "description": "The expiry date of the card in the format of MM/YY." }, "cardholder_name": { "type": "string", "description": "The name of the cardholder." }, "checks": { "$ref": "#/$defs/Card-Checks-v2" }, "authorisation_code": { "$ref": "#/$defs/Authorisation-Code" }, "arn": { "$ref": "#/$defs/Arn" }, "capture_deadline": { "$ref": "#/$defs/Capture-Deadline" }, "terminal_hardware_id": { "$ref": "#/$defs/Terminal-Hardware-Id" }, "fingerprint": { "$ref": "#/$defs/Fingerprint" }, "network_transaction_id": { "$ref": "#/$defs/Network-Transaction-Id" } }, "required": [ "type" ] }, "Network-Transaction-Id": { "type": "string", "description": "The Network Transaction ID (NTI) is a unique identifier assigned by the card scheme (e.g., Visa or Mastercard) to a card transaction.\n\nIt can be used to trace the transaction across the payment network, link recurring or instalment payments to the original authorisation, and support dispute resolution." }, "Payer": { "title": "Payer", "type": "object", "description": "The person who made the payment. This object is present when an email or phone number is provided during the payment flow.\n\nCapturing 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.", "properties": { "email": { "$ref": "#/$defs/Email", "description": "The email of the person who made the payment." }, "phone": { "$ref": "#/$defs/Phone", "description": "The phone number of the payer in [E.164 format](https://en.wikipedia.org/wiki/E.164)." } } }, "Payment-Amount": { "type": "integer", "format": "int64", "minimum": 0, "description": "The payment amount in minor units (e.g., cents). The value of this field depends on the payment type and state.\n\n| Payment type | State | Amount value |\n|--------------|-------|--------------|\n| Standard payment | Any | Total payment amount |\n| Pre-authorised payment | `authorisation_started` | New amount being authorised (during increment processing) |\n| Pre-authorised payment | `authorised` | Currently authorised amount (equals `authorised_amount`) |\n\n:::info\nFor pre-authorised payments, see the `authorised_amount` field for tracking the currently authorised amount separately.\n:::" }, "Payment-Authorised-Amount": { "type": "integer", "description": "The currently authorised amount for this payment (in minor units).\n\nFor pre-authorised payments with incremental authorization:\n- Initially equals the `amount` field\n- Remains unchanged during increment processing\n- Updates to new amount upon successful increment\n- Remains at original amount if increment is declined\n\nFor standard payments, this field may not be present or will equal the `amount` field." }, "Payment-Created": { "type": "string", "format": "date-time", "description": "The date and time the payment was created." }, "Payment-Id": { "type": "string", "format": "uuid", "description": "The ID of the payment." }, "Payment-Method-Type": { "type": "string", "enum": [ "apple_pay", "card", "google_pay", "revolut_pay_card", "revolut_pay_account", "sepa_direct_debit" ], "description": "The type of payment method used to pay for the order.\n\nAvailable values:\n\n| Payment method `type` | Description |\n| --------------------- | ----------- |\n| `apple_pay` | The customer paid the order using Apple Pay. |\n| `card` | The customer paid the order using their credit or debit card. |\n| `google_pay` | The customer paid the order using Google Pay. |\n| `revolut_pay_card` | The customer paid the order via Revolut Pay using their credit or debit card. |\n| `revolut_pay_account` | The customer paid the order via Revolut Pay using their Revolut account. |\n| `sepa_direct_debit` | The customer paid the order using SEPA Direct Debit. |" }, "Payment-Method-v2": { "type": "object", "description": "The details of the payment method used to make the payment.", "oneOf": [ { "$ref": "#/$defs/Apple-Pay" }, { "$ref": "#/$defs/Card" }, { "$ref": "#/$defs/Google-Pay" }, { "$ref": "#/$defs/Revolut-Pay-Card" }, { "$ref": "#/$defs/Revolut-Pay-Account" }, { "$ref": "#/$defs/Sepa-Direct-Debit" } ] }, "Payment-Risk-Level": { "type": "string", "description": "The risk level of the card.\n\nIf the risk level is `high`, the payment might be declined.", "enum": [ "low", "high" ] }, "Payment-Settled-Amount": { "type": "integer", "description": "The amount of the settled payment (minor currency unit). For example, `7034` stands for €70.34." }, "Payment-Settled-Currency": { "type": "string", "description": "The currency of the settled payment. [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code in upper case.\n\n:::info\nFor 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/).\n:::" }, "Payment-State-v2": { "type": "string", "description": "The status of the payment.", "enum": [ "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" ] }, "Payment-Token": { "type": "string", "format": "uuid", "description": "Temporary token of the payment used to fetch the reward offer during checkout and link user registrations to the given offers. \n\nThe token is only valid for a limited time." }, "Payment-Updated": { "type": "string", "format": "date-time", "description": "The date and time the payment was last updated." }, "Phone": { "type": "string", "description": "The phone number of the customer in [E.164 format](https://en.wikipedia.org/wiki/E.164)." }, "Revolut-Pay-Account": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "ID of the saved payment method.\n\n:::note\nThe `id` parameter is only returned when the payment method is saved.\n:::" }, "type": { "$ref": "#/$defs/Payment-Method-Type" }, "fingerprint": { "$ref": "#/$defs/Fingerprint" } }, "required": [ "type" ] }, "Revolut-Pay-Card": { "type": "object", "description": "Object containing details of a card used via Revolut Pay.", "properties": { "id": { "type": "string", "format": "uuid", "description": "ID of the saved payment method.\n\n:::note\nThe `id` parameter is only returned when the payment method is saved.\n:::" }, "type": { "$ref": "#/$defs/Payment-Method-Type" }, "card_brand": { "type": "string", "description": "The type of the card.", "enum": [ "visa", "mastercard", "american_express" ] }, "funding": { "type": "string", "description": "The type of card funding.", "enum": [ "credit", "debit", "prepaid" ] }, "card_country_code": { "type": "string", "description": "The 2-letter country code of the country where the card was issued." }, "card_bin": { "type": "string", "description": "The BIN of the card.", "minLength": 6, "maxLength": 6 }, "card_last_four": { "type": "string", "description": "The last four digits of the card number.", "minLength": 4, "maxLength": 4 }, "card_expiry": { "type": "string", "format": "MM/YY", "description": "The expiry date of the card in the format of MM/YY." }, "cardholder_name": { "type": "string", "description": "The name of the cardholder." }, "checks": { "$ref": "#/$defs/Card-Checks-v2" }, "authorisation_code": { "$ref": "#/$defs/Authorisation-Code" }, "arn": { "$ref": "#/$defs/Arn" }, "capture_deadline": { "$ref": "#/$defs/Capture-Deadline" }, "terminal_hardware_id": { "$ref": "#/$defs/Terminal-Hardware-Id" }, "fingerprint": { "$ref": "#/$defs/Fingerprint" }, "network_transaction_id": { "$ref": "#/$defs/Network-Transaction-Id" } }, "required": [ "type" ] }, "Sepa-Direct-Debit": { "type": "object", "description": "Object containing details of a SEPA Direct Debit payment.\n\n:::info\nFor more information, see: [SEPA Direct Debit server-to-server integration](https://developer.revolut.com/docs/guides/merchant/accept-payments/payment-methods/sepa-direct-debit/server-to-server)\n:::", "properties": { "id": { "type": "string", "format": "uuid", "description": "ID of the saved payment method.\n\n:::note\nThe `id` parameter is only returned when the payment method is saved for the merchant.\n:::" }, "type": { "$ref": "#/$defs/Payment-Method-Type" }, "debtor_iban_last_four": { "$ref": "#/$defs/Sepa-Direct-Debit-Debtor-Iban-Last-Four" }, "debtor_name": { "$ref": "#/$defs/Sepa-Direct-Debit-Debtor-Name" }, "mandate_reference": { "$ref": "#/$defs/Sepa-Direct-Debit-Mandate-Reference" } }, "required": [ "type" ] }, "Sepa-Direct-Debit-Debtor-Iban-Last-Four": { "type": "string", "description": "The last four digits of the debtor's IBAN.", "minLength": 4, "maxLength": 4 }, "Sepa-Direct-Debit-Debtor-Name": { "type": "string", "description": "The full name of the debtor as provided in the mandate." }, "Sepa-Direct-Debit-Mandate-Reference": { "type": "string", "description": "The unique mandate reference generated by Revolut. Include this in pre-debit notifications sent to your customers." }, "Terminal-Hardware-Id": { "type": "string", "description": "The hardware identifier of the Revolut Terminal device used to process the payment.\n\n:::note\nOnly present for card-present transactions processed via Revolut Terminal.\n:::" }, "Three-Ds": { "title": "three_ds", "type": "object", "description": "Information about the 3DS challenge.", "properties": { "type": { "$ref": "#/$defs/Authentication-Challenge-Type" }, "acs_url": { "type": "string", "format": "url", "description": "The URL of the authentication challenge." } }, "required": [ "type", "acs_url" ] }, "Three-Ds-Fingerprint-v2": { "title": "three_ds_fingerprint", "type": "object", "description": "Information about the 3DS fingerprint challenge.", "properties": { "type": { "$ref": "#/$defs/Authentication-Challenge-Type" }, "fingerprint_html": { "type": "string", "format": "byte", "description": "Base64-encoded HTML string for the 3DS fingerprint challenge. This HTML is fully\nconstructed by Revolut — no modifications are needed.\n\nDecode this value using a `base64` decoder and render the resulting HTML in your\nfront-end application. Revolut automatically moves the payment to the full 3DS\nchallenge if the fingerprint is not handled within 15 seconds." } }, "required": [ "type", "fingerprint_html" ] } } }