Revolut
This page provides an overview of the payments methods provided by the Revolut adapter in the IXOPAY platform. It also includes a full list of all configuration options available to you when integrating Revolut within your payments landscape, as well as an overview of the parameters required when submitting a transaction via IXOPAY's API.
Revolut Pay lets your customers pay with their card or their Revolut account balance through a widget rendered directly on your checkout page (desktop web only — see Miscellaneous). The widget is powered by Revolut's own Checkout SDK and integrated through payment.js.
Payment Methods
| Payment Method | Transaction Flows | Transaction Types |
|---|---|---|
Revolut Pay (RevolutPay) | payment.js | Debit, Preauthorize, Capture, Void, Refund, Register, Deregister |
Connector Setup
| Field | Description |
|---|---|
| Public API Key | Your Revolut Business merchant account's public API key — used client-side to initialise the widget. |
| Secret API Key | Your Revolut Business merchant account's secret API key — used for all server-to-server Merchant API calls. |
| Webhook Signing Secret | Filled in automatically once you activate the webhook — see Webhooks below. Do not set this manually. |
| Test mode | Switches the connector between the Revolut sandbox and production environments. |
Optional per-connector settings:
| Option | Description |
|---|---|
| Industry | Only set this if your business is in one of Revolut's regulated industry verticals (Airline, Car Rental, Crypto, Marketplace, Event Ticketing, Lodging). See Industry-specific data. |
| Default currency for Register (vault-only) orders | Used for a plain register call (no amount of its own) when extraData.currency isn't supplied on the transaction. Not used for Debit/Preauthorize, which always use the transaction's own currency. |
Webhooks
Revolut has no self-service way for you to register a webhook against this connector, so the gateway manages it for you. Once your API keys are saved, open this connector's Additional Config panel and click Activate Webhook. This registers a webhook with Revolut for the postback URL of this project and writes the returned signing secret into the Webhook Signing Secret field automatically — there is nothing to copy manually, and no signing secret to generate on your end.
An active webhook is required for this connector to work at all. Every transaction is finalized by the corresponding webhook event — see Order creation and payment lifecycle. Only use Deactivate Webhook if asked to, or if you are disabling the connector entirely.
Integration Guide
payment.js
Revolut Pay is rendered as a button inside a container element you provide. This is handled by the payment.js integration.
1. Embed payment.js in your page:
<script data-main="payment-js" src="https://gateway.ixopay.com/js/integrated/payment.1.3.min.js"></script>
The data-main="payment-js" attribute is required.
2. Add a container element for the button:
<div id="revolut-pay-button"></div>
3. Initialize the widget:
<script>
var paymentJs = new PaymentJs('1.3');
var completeHandler = function (orderId) {
// UI feedback only — do not fulfill the order here. See "Order creation and payment lifecycle".
};
var errorHandler = function (error) {
// Handle a widget-reported error.
};
var canceledHandler = function (event) {
// The customer closed the widget or abandoned the payment before completing it.
};
// Called by the widget when the customer clicks the button. Must call your own backend,
// which in turn calls our /debit, /preauthorize, or /register, and resolve with the
// extraData.revolutPublicId returned in that response.
var createRevolutOrder = function () {
return fetch('{MY_BACKEND_ENDPOINT}', { method: 'POST' })
.then(function (res) { return res.json(); })
.then(function (data) { return data.extraData.revolutPublicId; });
};
var revolutPayOptions = {
currency: 'EUR',
totalAmount: 1000, // minor units, e.g. cents — must match the amount sent to /debit or /preauthorize
vault: false // set to true to also save the payment method — see "Saved payment methods" below
};
paymentJs.initRevolutPay(
'public-integration-key', // the connector token of this project
'revolut-pay-button',
completeHandler,
errorHandler,
canceledHandler,
revolutPayOptions,
createRevolutOrder
);
</script>
revolutPayOptions
| Option | Required | Type | Description |
|---|---|---|---|
currency | yes | string | 3-letter ISO 4217 currency code. Must match the currency of the /debit or /preauthorize call that produced the order (or extraData.currency / the connector's default currency for a register). |
totalAmount | yes | number | Order total in minor units, for display only — the amount actually charged is the one sent to /debit//preauthorize/register. May be 0 for a register (vault-only) order. |
vault | no | boolean | Passed through to Revolut as savePaymentMethodForMerchant. See Saved payment methods. Defaults to false. |
buttonStyle | no | object | Passed through unmodified to Revolut's revolutPay.mount() — see Revolut's own Revolut Pay button guidelines. |
customer | no | object | Passed through unmodified. Pre-fills the customer's details inside the widget to speed up checkout. |
validate | no | function | Passed through unmodified. A function Revolut calls to validate the order client-side before the payment is initiated. |
locale | no | string | Passed through to RevolutCheckout.payments(). Overrides the widget's language/locale. |
buttonStyle, customer, validate, and locale are forwarded to Revolut's Checkout SDK as-is — the
gateway does not inspect or transform them. Refer to Revolut's own
Revolut Pay SDK reference
for their exact shape.
Handlers
| Handler | Called with | Notes |
|---|---|---|
completeHandler | orderId (Revolut order id) | Fires when the widget reports a successful payment. |
errorHandler | error | Fires on a widget-reported or SDK-level error. |
canceledHandler | event ({ dropOffState }) | Fires when the customer abandons the payment inside the widget. |
Revolut explicitly documents that delivery of these widget events is not guaranteed — ad blockers, poor connectivity, or the customer closing the tab can all prevent them from firing. Use them only for UI feedback (e.g. showing a spinner or a "payment cancelled" message). The transaction's real, final outcome is always delivered through your status postback once our webhook processes the corresponding Revolut event — see the next section.
Order creation and payment lifecycle
Unlike a typical redirect-based APM, the customer's approval inside the widget is itself the payment —
there is no separate "prepare" call. Because of that, the Revolut order is created as part of the /debit
or /preauthorize call itself, in this order:
- Your frontend renders the button and calls
createRevolutOrder. createRevolutOrdercalls your backend, which calls our/debitor/preauthorize.- The adapter creates the order via the Merchant API (
capture_mode: automaticfor Debit,manualfor Preauthorize) and the transaction is persisted immediately, in a pending state. - The API response carries
extraData.revolutPublicId(the order'stoken). Your backend returns it to the frontend, andcreateRevolutOrderresolves with it. - The widget uses that token to let the customer complete the payment.
- Revolut sends a webhook (
ORDER_COMPLETEDfor Debit,ORDER_AUTHORISEDfor Preauthorize) once the payment actually settles. This is what finalizes the transaction and triggers your status postback.
A transaction therefore exists (in a pending state) from the moment the widget is clicked, even if the customer never completes the payment — it is finalized or expired independently of anything that happens in the browser.
Saved payment methods (Register, recurring charges, and Deregister)
Revolut Pay has no dedicated "save card" endpoint of its own — saving a payment method happens as a side
effect of an order, driven by the widget's vault option (savePaymentMethodForMerchant).
Saving a payment method
There are two ways to save a payment method for later reuse:
register— a zero-amount vault-only order. Use this when you want to save a payment method without charging the customer anything right away.debit/preauthorizewithwithRegister: true— a normal charge that also saves the payment method at the same time.
To actually save the payment method, you must also supply a customer object (at minimum email or
firstName/lastName) on that same transaction — Revolut only saves a payment method against a customer
record. Setting vault: true / withRegister: true alone, with no customer data, will not save anything.
Charging a saved payment method
To charge a saved payment method later without presenting the widget again (e.g. a subscription renewal),
send a normal debit or preauthorize with:
| Field | Value |
|---|---|
referenceUuid | The transaction UUID of the original register (or debit/preauthorize with withRegister: true) call. |
transactionIndicator | RECURRING or CARDONFILE_MERCHANT |
No revolutPublicId / widget interaction is needed for this call — it either fails immediately (e.g. a
decline) or resolves via the same pending postback as any other transaction. The gateway automatically
resolves the saved payment method id and the Revolut customer id from the referenced transaction; you do not
need to look up or resend either of them yourself.
Both referenceUuid/ Customer Profile Token and transactionIndicator are required together. If either is missing, the call is
treated as a normal, interactive order instead — it will succeed, but it presents a fresh widget flow rather
than charging the saved payment method.
Removing a saved payment method (Deregister)
Call deregister with referenceUuid set to the transaction UUID of the original register /
debit/preauthorize-with-registration call whose saved payment method you want to remove. As with
charging a saved payment method, the payment method id and Revolut customer id are resolved automatically
from the referenced transaction.
Mapping to Revolut
Request mapping — Debit, Preauthorize, Register
| Gateway parameter | Revolut parameter | Type | Description |
|---|---|---|---|
amount | amount | required string | Converted to minor units. Always 0 for Register. |
currency | currency | required string | For Register, taken from extraData.currency, falling back to the connector's configured default. |
description | description | optional string | |
customer.firstName, customer.lastName | customer.full_name | optional string | Combined into one field. Omitted entirely if a saved customer id is being reused (see below). |
customer.email | customer.email | optional string | |
customer.billingPhone | customer.phone | optional string | |
customer.birthDate | customer.date_of_birth | optional stringYYYY-MM-DD | |
customer.shippingAddress1/2, customer.shippingCity, customer.shippingState, customer.shippingCountry, customer.shippingPostcode | shipping.address.* | optional | Sent only when street line 1, city, country, and postcode are all present. |
customer.shippingFirstName/LastName, customer.email, customer.shippingPhone | shipping.contact.* | optional | Only sent alongside a complete shipping.address. |
referenceUuid | customer.id (implicit) | optional string | When this references a transaction with a saved Revolut customer, that customer.id is sent instead of rebuilding customer from scratch — see Saved payment methods. Not applicable to Register. |
items[] | line_items[] | optional array | See Line items. Not applicable to Register. |
extraData.enforceChallenge | enforce_challenge | optional stringone of: [ automatic, forced ] | forced requires a 3DS challenge on every payment for this order. Defaults to Revolut's own fraud-based decision. |
extraData.expirePendingAfter | expire_pending_after | optional stringISO 8601 duration | Automatically fails the order if it's still unpaid after this period. |
extraData.locationId | location_id | optional string | Revolut location id. |
extraData.statementDescriptorSuffix | statement_descriptor_suffix | optional string | Appended to the cardholder's statement descriptor. |
withRegister | n/a | optional booleanDebit, Preauthorize only | Also saves the payment method during this charge — see Saved payment methods. |
Request mapping — Capture
| Gateway parameter | Revolut parameter | Type | Description |
|---|---|---|---|
amount | amount | required string | Minor units. For a capture lower than the authorised amount, Revolut voids the uncaptured remainder. |
items[] | line_items[] | optional array | Overwrites the order's original line items. See Line items. |
Request mapping — Refund
| Gateway parameter | Revolut parameter | Type | Description |
|---|---|---|---|
amount | amount | required string | |
currency | currency | required string | Must match the original order's currency. |
description | description | optional string |
Response mapping
| Gateway parameter | Revolut parameter | Description | Transaction types |
|---|---|---|---|
extraData.revolutPublicId | token | The order's public token — pass it back from createRevolutOrder to mount the widget. | Debit, Preauthorize, Register (not returned for a saved-payment-method charge — there's no widget to mount) |
returnData.walletOwner | payer.email | The customer's Revolut account email, present once the order completes if a payment method was saved. | Debit, Preauthorize, Register (when saving a payment method) |
Transaction indicators
| Gateway transaction indicator | Effect |
|---|---|
RECURRING, CARDONFILE_MERCHANT | Combined with referenceUuid or Customer Profile Token, charges a previously saved payment method directly — see Saved payment methods. |
| any other value, or omitted | Normal interactive widget flow. |
Line items
| Field | Required | Description |
|---|---|---|
name | yes | |
quantity | yes | |
price | yes | Unit price. |
currency | yes | |
description | no | |
identification | no | Sent as external_id. |
l2l3Data.type | no | physical or service. Anything else (or omitted) defaults to physical. |
l2l3Data.taxAmount | no | Added on top of the item's total. |
l2l3Data.discount | no | Subtracted from the item's total. |
Industry-specific data
Set the connector-level Industry option to one of Airline, Car Rental, Crypto, Marketplace, Event
Ticketing, or Lodging to unlock that industry's fields. Each field is supplied as a flat extraData key on
the transaction (e.g. extraData.bookingId); the gateway nests them under industry_data.<industry> in the
request sent to Revolut. Fields that are themselves a list of objects (e.g. passengers, journeyLegs,
seller, events, lodgings, tickets, guests) must be supplied as a JSON-encoded string, since
extraData values can only ever be flat strings.
Refer to Revolut's own Create an order
reference for the exact industry_data schema per industry; the gateway's extraData keys mirror it
field-for-field (camelCase instead of snake_case — e.g. extraData.pickUpDate → pick_up_date).
Error codes
HTTP-level failures (invalid request, authentication, rate limiting, maintenance, etc.) and payment-level decline reasons are both mapped to the gateway's standard error codes, preserving Revolut's own error message/code as the adapter error message/code for troubleshooting. See Revolut's error reference and decline reasons reference for the full list of underlying Revolut codes.
Testing
While operating the Revolut connector in test mode, use the sandbox test cards from Revolut's own Test cards reference to exercise different outcomes (declines, 3DS challenges, etc.). A full end-to-end test exercises both the widget (button renders, completes/cancels as expected) and the webhook (the transaction actually reaches its final status after the widget reports success).
Miscellaneous
- Desktop web only. The widget is mounted as a popup; no mobile redirect URLs are configured, so a mobile browser checkout without the Revolut app installed is not a supported flow.
- Widget events (
completeHandler/errorHandler/canceledHandler) are UI feedback only — see Order creation and payment lifecycle. Always drive fulfillment from your status postback.