To enable JavaScript:

Merchant Web SDKs

Payments.revolutPay

doc

Payments.revolutPay

The revolutPay module provides a method to mount and manage the Revolut Pay button, which enables customers to pay with their Revolut account or saved cards.

Module signature

type PaymentsModuleRevolutPayInstance = {
  mount: (
    target: string | HTMLElement | null,
    options: WidgetPaymentsRevolutPayOptions
  ) => void
  on: <T extends RevolutPayEvents['type']>(
    event: T,
    callback: (payload: RevolutPayEventPayload<T>) => void
  ) => void
  destroy: () => void
}

The revolutPay object, returned from the parent payments() instance, exposes the following methods:

Method	Description	Signature
`mount()`	Renders the Revolut Pay button into a target DOM element and configures it.	`(target: string \| HTMLElement \| null, options: WidgetPaymentsRevolutPayOptions) => void`
`on()`	Attaches a listener to Revolut Pay events.	`<T extends RevolutPayEvents['type']>(event: T, callback: (payload: RevolutPayEventPayload<T>) => void) => void`
`destroy()`	Removes the Revolut Pay button and cleans up all associated event listeners.	`() => void`

Method details

`mount(target, options)`

This method renders the Revolut Pay button.

revolutPay.mount: (
  target: string | HTMLElement | null,
  options: WidgetPaymentsRevolutPayOptions
) => void

Parameter	Description	Type	Required
`target`	The DOM element or CSS selector where the button should be rendered (e.g., `document.getElementById('container')`).	`string \| HTMLElement \| null`	Yes
`options`	An object to configure the button's behavior, appearance, and payment details.	`WidgetPaymentsRevolutPayOptions`	Yes

`WidgetPaymentsRevolutPayOptions`

This object configures the payment session.

type WidgetPaymentsRevolutPayOptions = {
  currency: string;
  totalAmount: number;
  createOrder: () => Promise<{ publicId: string }>;
  customer?: CustomerDetails;
  buttonStyle?: ButtonStyleOptions;
  requestShipping?: boolean;
  savePaymentMethodForMerchant?: boolean;
  redirectUrls?: {
    success: string;
    failure: string;
    cancel: string;
  };
  mobileRedirectUrls?: {
    success: string;
    failure: string;
    cancel: string;
  };
  validate?: () => Promise<boolean> | boolean;
  lineItems?: RevolutPayLineItem[];
};

Parameter	Description	Type	Required
`currency`	3-letter ISO 4217 currency code for the payment. info For more information about the supported currencies, see: Help Center.	`string`	Yes
`totalAmount`	The total amount to be paid, in the currency's smallest denomination (e.g., cents).	`number`	Yes
`createOrder`	An async function that calls your backend to create an order in the Merchant API and returns the `publicId` (order `token`).	`() => Promise<{ publicId: string }>`	Yes
`customer`	Pre-fills customer details in the payment pop-up.	`CustomerDetails`	No
`buttonStyle`	Customises the appearance of the Revolut Pay button.	`ButtonStyleOptions`	No
`requestShipping`	If `true`, collects the shipping address and delivery method from the customer via the Revolut Pay flow. Default: `false` note Your backend must support Fast checkout for this functionality to work, for more information see: Fast checkout guide	`boolean`	No
`savePaymentMethodForMerchant`	If `true`, the customer's payment method is saved for future merchant-initiated payments (e.g., subscriptions). Default: `false`.	`boolean`	No
`redirectUrls`	An object with URLs for redirecting the user after payment completion. Use this for a redirect-based flow. See the integration guide for details.	`Object`	No
`mobileRedirectUrls`	Same as `redirectUrls`, but specifically for mobile devices. Can be used to combine event listening on desktop with redirects on mobile.	`Object`	No
`validate`	An optional async function that runs before payment. Return `true` to proceed or throw an error to display a message and cancel.	`() => Promise<boolean> \| boolean`	No
`lineItems`	An array of objects detailing the items in the customer's cart.	`RevolutPayLineItem[]`	No

`CustomerDetails` object

Use this object to pre-fill known customer information in the payment flow.

interface CustomerDetails {
  name?: string;
  email?: string;
  phone?: string;
  dateOfBirth?: {
    day: number;
    month: number;
    year: number;
  }
  billingAddress?: Address;
  shippingAddress?: Address;
}

Parameter	Description	Type	Required
`name`	The customer's full name.	`string`	No
`email`	The customer's email address.	`string`	No
`phone`	The customer's phone number, including country code (e.g., `+44...`).	`string`	No
`dateOfBirth`	An object containing the customer's date of birth.	`Object`	No
`billingAddress`	The customer's billing address.	`Address`	No
`shippingAddress`	The customer's shipping address.	`Address`	No

`Address` object

interface Address {
  countryCode: CountryCode;
  postcode: string;
  region?: string;
  city?: string;
  streetLine1?: string;
  streetLine2?: string;
};

Parameter	Description	Type	Required
`countryCode`	2-letter ISO 3166-1 alpha-2 country code.	`CountryCode`	Yes
`postcode`	The postal code or ZIP code.	`string`	Yes
`region`	The state, province, or region.	`string`	No
`city`	The city or town.	`string`	No
`streetLine1`	The primary street address line.	`string`	No
`streetLine2`	The secondary street address line (e.g., apartment, suite).	`string`	No

`ButtonStyleOptions` object

This object allows you to customise the appearance of the Revolut Pay button.

type ButtonStyleOptions = {
  height?: string;
  size?: 'large' | 'small';
  radius?: 'none' | 'small' | 'large' | 'round';
  variant?: 'dark' | 'light' | 'light-outlined';
  action?: 'donate' | 'pay' | 'subscribe' | 'buy';
  cashback?: boolean;
  cashbackCurrency?: RevolutPayButtonCashbackCurrency;
};

Property	Description	Type	Required
`height`	The CSS height of the button (e.g., `'48px'`).	`string`	No
`size`	`large` for a full-width button, `small` for an inline-sized button.	`'large' \| 'small'`	No
`radius`	The border-radius of the button.	`'none' \| 'small' \| 'large' \| 'round'`	No
`variant`	The color theme of the button.	`'dark' \| 'light' \| 'light-outlined'`	No
`action`	The call-to-action text displayed on the button.	`'donate' \| 'pay' \| 'subscribe' \| 'buy'`	No
`cashback`	If `true`, may display rewards information on the button.	`boolean`	No
`cashbackCurrency`	3-letter currency code for the rewards text.	`string`	No

`RevolutPayButtonCashbackCurrency` type

The available currencies for the rewards text:

type RevolutPayButtonCashbackCurrency =
  | 'AED'
  | 'AUD'
  | 'BGN'
  | 'CAD'
  | 'CHF'
  | 'CZK'
  | 'DKK'
  | 'EUR'
  | 'GBP'
  | 'HKD'
  | 'HUF'
  | 'ILS'
  | 'JPY'
  | 'MXN'
  | 'NOK'
  | 'NZD'
  | 'PLN'
  | 'QAR'
  | 'RON'
  | 'RUB'
  | 'SAR'
  | 'SEK'
  | 'SGD'
  | 'THB'
  | 'TRY'
  | 'USD'
  | 'ZAR'

`RevolutPayLineItem` object

This object represents a single item in the customer's cart.

type RevolutPayLineItem = {
  name: string;
  totalAmount: string;
  unitPriceAmount: string;
  quantity?: {
    value: number;
    unit: 'PIECES';
  };
  type?: 
    | 'TAX'
    | 'GIFT'
    | 'MISC'
    | 'REFUND'
    | 'CHARGE'
    | 'SERVICE'
    | 'PHYSICAL'
    | 'ADJUSTMENT';
  productId?: string;
  productUrl?: string;
  description?: string;
  taxes?: { 
    name: string;
    amount: string;
    type?: 'INCLUDED'
  }[];
  imageUrls?: string[];
  totalTaxAmount?: string;
  totalDiscountAmount?: string;
  discounts?: { 
    name: string;
    type?: 'FIXED';
    totalAmount?: number;
    appliedAmount?: number
  }[];
  metadata?: Record<string, string>;
};

Property	Description	Type	Required
`name`	The display name of the item.	`string`	Yes
`totalAmount`	The total price for this line item (unit price * quantity).	`string`	Yes
`unitPriceAmount`	The price of a single unit of this item.	`string`	Yes
`quantity`	An object specifying the number of units.	`Object`	No
`type`	The classification of the line item.	`string`	No
`productId`	Your internal product identifier.	`string`	No
`productUrl`	A URL pointing to the product page.	`string`	No
`description`	A brief description of the item.	`string`	No
`taxes`	An array of tax objects applied to this item.	`Object[]`	No
`imageUrls`	An array of URLs for product images.	`string[]`	No
`totalTaxAmount`	The total tax amount for this line item.	`string`	No
`totalDiscountAmount`	The total discount amount for this line item.	`string`	No
`discounts`	An array of discount objects applied to this item.	`Object[]`	No
`metadata`	A key-value map for any additional data.	`Object`	No

`on(event, callback)`

This method listens for events happening during the payment lifecycle.

revolutPay.on: <T extends RevolutPayEvents['type']>(
  event: T,
  callback: (payload: RevolutPayEventPayload<T>) => void
) => void

The SDK uses TypeScript generics to provide strong type-safety for events. When you specify an event name (e.g., 'payment'), the payload object in the callback function is automatically typed with the correct shape for that specific event, preventing errors.

Parameter	Description	Type	Required
`event`	The name of the event to listen for. Currently, only `'payment'` is supported.	`'payment' \| 'click'`	Yes
`callback`	A function that will be executed when the event is triggered. It receives a `payload` object with event details.	`function`	Yes

Supported events

The .on() method can listen for the following events:

'payment': Fired when the payment flow completes, either with a success, failure, or cancellation.
'click': Fired immediately when the user clicks the Revolut Pay button. The payload for this event is null.

Event: `'payment'`

The complete type definition for all possible payment events is as follows:

type RevolutPayEvents =
  | {
      type: 'payment';
      payload:
        | { type: 'success'; orderId: string };
        | { type: 'error'; error: RevolutCheckoutError; orderId: string };
        | {
            type: 'cancel';
            dropOffState: RevolutPayDropOffState;
            orderId?: string;
          };
    };
  | { type: 'click'; payload: null };

When listening for the payment event, the payload object passed to your callback will have one of the following shapes:

`payload.type`	`payload` description	`payload` shape
`success`	The payment was completed successfully. The payload includes the `orderId`.	`{ type: 'success', orderId: string }`
`error`	An error occurred during payment. The payload includes the `orderId` and an `error` object.	`{ type: 'error', error: RevolutCheckoutError, orderId: string }`
`cancel`	The user cancelled the payment flow. The `dropOffState` indicates where in the flow the cancellation occurred. See RevolutPayDropOffState.	`{ type: 'cancel', dropOffState: RevolutPayDropOffState, orderId?: string }`

`RevolutPayDropOffState` type

This type indicates the specific step in the payment flow where the user cancelled.

type RevolutPayDropOffState =
  | 'enter_otp'
  | 'payment_summary'
  | 'load_session_data'
  | 'enter_card_details'
  | 'verify_user_details'
  | 'enter_personal_details'
  | 'enter_shipping_details'
  | 'revolut_app_push_challenge'

Handling redirects

You can handle the payment result in one of two ways:

Event listening with mobile redirects: Use the .on() method to handle payment outcomes in your client-side code. This is the standard approach for desktop. For mobile, you should also provide mobileRedirectUrls to handle cases where a redirect is required after the payment is completed.
Redirects only: Use the redirectUrls option. This will disable the .on() event handler entirely and redirect the user to a new URL on both desktop and mobile.

When a user is redirected, Revolut Pay appends the order's public ID (token) as a query parameter named _rp_oid to the URL.

For a success URL of https://example.com/success, the final URL will be: https://example.com/success?_rp_oid=fe34dbd3-3fa9-4d4c-8987-3f7735ba3cdf

You can fetch this ID from your redirect page using one of two methods:

Using URLSearchParams:

const searchParams = new URLSearchParams(window.location.search);
const revolutPublicOrderId = searchParams.get('_rp_oid');

Using the SDK's helper function (available from v1.1.3):

import { getRevolutPayOrderIdURLParam } from '@revolut/checkout';

const revolutPublicOrderId = getRevolutPayOrderIdURLParam();

Example usage

Here is a minimal example of how to mount the Revolut Pay button and listen for payment events.

my-page.html
<!-- Add a container for the button in your HTML -->
<div id="revolut-pay-container"></div>

my-page.js
import RevolutCheckout from '@revolut/checkout'

async function initializeRevolutPay() {
  const { revolutPay } = await RevolutCheckout.payments({
    publicToken: '<YOUR_PUBLIC_API_KEY>',
    locale: 'en',
  })

  const paymentOptions = {
    currency: 'GBP',
    totalAmount: 2000, // £20.00
    createOrder: async () => {
      // Replace with your server-side call to create an order in the Merchant API
      const response = await fetch('/api/create-revolut-order');
      const order = await response.json()
      return { publicId: order.token }
    },
  }

  revolutPay.mount('#revolut-pay-container', paymentOptions)

  revolutPay.on('payment', (event) => {
    switch (event.type) {
      case 'success':
        console.log('Payment successful! Order ID:', event.orderId);
        // e.g., redirect to a success page
        break
      case 'error':
        console.error('Payment failed:', event.error);
        // e.g., show an error message to the user
        break
      case 'cancel':
        console.log('Payment cancelled by user at state:', event.dropOffState);
        // e.g., re-enable the checkout button
        break
    }
  })
}

initializeRevolutPay()

PreviousThe payments object

NextPayments.paymentRequest

Module signature
Method details
- mount(target, options)
- on(event, callback)
Handling redirects
Example usage

Payments.revolutPay

Module signature​

Method details​

mount(target, options)​

WidgetPaymentsRevolutPayOptions​

CustomerDetails object​

Address object​

ButtonStyleOptions object​

RevolutPayButtonCashbackCurrency type​

RevolutPayLineItem object​

on(event, callback)​

Supported events​

Event: 'payment'​

RevolutPayDropOffState type​

Handling redirects​

Example usage​

Module signature

Method details

`mount(target, options)`

`WidgetPaymentsRevolutPayOptions`

`CustomerDetails` object

`Address` object

`ButtonStyleOptions` object

`RevolutPayButtonCashbackCurrency` type

`RevolutPayLineItem` object

`on(event, callback)`

Supported events

Event: `'payment'`

`RevolutPayDropOffState` type

Handling redirects

Example usage