Skip to main content

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 MethodTransaction FlowsTransaction Types
Revolut Pay (RevolutPay)payment.jsDebit, Preauthorize, Capture, Void, Refund, Register, Deregister

Connector Setup​

FieldDescription
Public API KeyYour Revolut Business merchant account's public API key — used client-side to initialise the widget.
Secret API KeyYour Revolut Business merchant account's secret API key — used for all server-to-server Merchant API calls.
Webhook Signing SecretFilled in automatically once you activate the webhook — see Webhooks below. Do not set this manually.
Test modeSwitches the connector between the Revolut sandbox and production environments.

Optional per-connector settings:

OptionDescription
IndustryOnly 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) ordersUsed 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.

note

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>
note

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​

OptionRequiredTypeDescription
currencyyesstring3-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).
totalAmountyesnumberOrder 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.
vaultnobooleanPassed through to Revolut as savePaymentMethodForMerchant. See Saved payment methods. Defaults to false.
buttonStylenoobjectPassed through unmodified to Revolut's revolutPay.mount() — see Revolut's own Revolut Pay button guidelines.
customernoobjectPassed through unmodified. Pre-fills the customer's details inside the widget to speed up checkout.
validatenofunctionPassed through unmodified. A function Revolut calls to validate the order client-side before the payment is initiated.
localenostringPassed through to RevolutCheckout.payments(). Overrides the widget's language/locale.
note

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​

HandlerCalled withNotes
completeHandlerorderId (Revolut order id)Fires when the widget reports a successful payment.
errorHandlererrorFires on a widget-reported or SDK-level error.
canceledHandlerevent ({ dropOffState })Fires when the customer abandons the payment inside the widget.
note

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:

  1. Your frontend renders the button and calls createRevolutOrder.
  2. createRevolutOrder calls your backend, which calls our /debit or /preauthorize.
  3. The adapter creates the order via the Merchant API (capture_mode: automatic for Debit, manual for Preauthorize) and the transaction is persisted immediately, in a pending state.
  4. The API response carries extraData.revolutPublicId (the order's token). Your backend returns it to the frontend, and createRevolutOrder resolves with it.
  5. The widget uses that token to let the customer complete the payment.
  6. Revolut sends a webhook (ORDER_COMPLETED for Debit, ORDER_AUTHORISED for 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 / preauthorize with withRegister: true — a normal charge that also saves the payment method at the same time.
note

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:

FieldValue
referenceUuidThe transaction UUID of the original register (or debit/preauthorize with withRegister: true) call.
transactionIndicatorRECURRING 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.

note

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 parameterRevolut parameterTypeDescription
amountamountrequired stringConverted to minor units. Always 0 for Register.
currencycurrencyrequired stringFor Register, taken from extraData.currency, falling back to the connector's configured default.
descriptiondescriptionoptional string
customer.firstName, customer.lastNamecustomer.full_nameoptional stringCombined into one field. Omitted entirely if a saved customer id is being reused (see below).
customer.emailcustomer.emailoptional string
customer.billingPhonecustomer.phoneoptional string
customer.birthDatecustomer.date_of_birthoptional string
YYYY-MM-DD
customer.shippingAddress1/2, customer.shippingCity, customer.shippingState, customer.shippingCountry, customer.shippingPostcodeshipping.address.*optionalSent only when street line 1, city, country, and postcode are all present.
customer.shippingFirstName/LastName, customer.email, customer.shippingPhoneshipping.contact.*optionalOnly sent alongside a complete shipping.address.
referenceUuidcustomer.id (implicit)optional stringWhen 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 arraySee Line items. Not applicable to Register.
extraData.enforceChallengeenforce_challengeoptional string
one of: [ automatic, forced ]
forced requires a 3DS challenge on every payment for this order. Defaults to Revolut's own fraud-based decision.
extraData.expirePendingAfterexpire_pending_afteroptional string
ISO 8601 duration
Automatically fails the order if it's still unpaid after this period.
extraData.locationIdlocation_idoptional stringRevolut location id.
extraData.statementDescriptorSuffixstatement_descriptor_suffixoptional stringAppended to the cardholder's statement descriptor.
withRegistern/aoptional boolean
Debit, Preauthorize only
Also saves the payment method during this charge — see Saved payment methods.

Request mapping — Capture​

Gateway parameterRevolut parameterTypeDescription
amountamountrequired stringMinor units. For a capture lower than the authorised amount, Revolut voids the uncaptured remainder.
items[]line_items[]optional arrayOverwrites the order's original line items. See Line items.

Request mapping — Refund​

Gateway parameterRevolut parameterTypeDescription
amountamountrequired string
currencycurrencyrequired stringMust match the original order's currency.
descriptiondescriptionoptional string

Response mapping​

Gateway parameterRevolut parameterDescriptionTransaction types
extraData.revolutPublicIdtokenThe 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.walletOwnerpayer.emailThe 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 indicatorEffect
RECURRING, CARDONFILE_MERCHANTCombined with referenceUuid or Customer Profile Token, charges a previously saved payment method directly — see Saved payment methods.
any other value, or omittedNormal interactive widget flow.

Line items​

FieldRequiredDescription
nameyes
quantityyes
priceyesUnit price.
currencyyes
descriptionno
identificationnoSent as external_id.
l2l3Data.typenophysical or service. Anything else (or omitted) defaults to physical.
l2l3Data.taxAmountnoAdded on top of the item's total.
l2l3Data.discountnoSubtracted 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.