To enable JavaScript:

Merchant Web SDKs

Payments.revolutPay

doc

Payments.revolutPay

Display the Revolut Pay button to allow your customer to make a payment with their Revolut app or cards.

How to mount the Revolut Pay button

There are two options to integrate Revolut Pay on your page:

using events
using events with mobile redirect URLs
using redirect URLs

To learn more about each option, see: Revolut Pay - Integration paths.

To mount the Revolut Pay button on your website:

First, import the RevolutCheckout package.
Call the .payments() method, to instantiate the Revolut Pay object.
Define the relevant paymentOptions including the asynchronous createOrder function.
Mount the Revolut Pay button to allow your customers to make payments with their Revolut app or cards.
Listen to relevant events (if using redirect URLs, you can skip this step).

import RevolutCheckout from '@revolut/checkout'

const { revolutPay } = await RevolutCheckout.payments({
  locale: 'en', // Optional, defaults to 'auto'
  mode: 'sandbox', // Optional, defaults to 'prod'
  publicToken: '<yourPublicApiKey>', // Merchant public API key 
})

const paymentOptions = {
  currency: 'USD', // 3-letter currency code
  totalAmount: number, // In lowest denomination e.g., cents

  // If you wish to implement Revolut Pay with event listening and mobile redirect URLs (skip this option if you only listen to events or only use redirect URLs):
  mobileRedirectUrls: {
    success: 'https://www.example.com/success',
    failure: 'https://www.example.com/failure',
    cancel: 'https://www.example.com/cancel'
  },
  
  // If you wish to implement Revolut Pay with redirect URLs (skip this option if you listen to events):
  redirectUrls: {
    success: 'https://www.example.com/success',
    failure: 'https://www.example.com/failure',
    cancel: 'https://www.example.com/cancel'
  },

  createOrder: async () => {
    // Call your backend here to create an order
    // For more information, see: https://developer.revolut.com/docs/merchant/create-order
    const order = await yourServerSideCall()
    return { publicId: order.token }
  },

  // You can put other optional parameters here
}

revolutPay.mount(target, paymentOptions)

// Call this method if you wish to implement Revolut Pay with event listening (skip this option if you use redirect URLs):
revolutPay.on('payment', (event) => {
  switch (event.type) {
    case 'cancel': {
      if (event.dropOffState === 'payment_summary') {
        log('what a shame, please complete your payment')
      }
      break
    }

    case 'success':
      onSuccess()
      break

    case 'error':
      onError(event.error)
      break
  }
})

Mount options

The mount method of Revolut Pay accepts two arguments:

revolutPay.mount(target, paymentOptions)

Use the target to define where the Revolut Pay button will be rendered on your page.

Use the Options object to define Revolut Pay checkout options, such as product or shipping information, and customize the display of the Revolut Pay button:

revolutPay.mount(target: HTMLElement, paymentOptions: Options)

type Options {
  currency: String,
  totalAmount: Number,
  requestShipping: Boolean,
  savePaymentMethodForMerchant: Boolean,

  // For configuration with mobile redirect URLs
  mobileRedirectUrls: {
    success: String,
    failure: String,
    cancel: String
  }

  // For configuration with redirect URLs
  redirectUrls: {
    success: String,
    failure: String,
    cancel: String
  },

  // For configuration with async
  createOrder: async () => {
    const order = await yourServerSideCall()
    return { publicId: order.token }
  },
  // For configuration without async
  createOrder: () => {
    return yourServerSideCall().then((order) => ({
      publicId: order.token,
    }))
  }

  // Optional properties
  lineItems: {
    name: String,
    totalAmount: Amount,
    unitPriceAmount: Amount,
    quantity: {
      value: Number,
      unit: 'PIECES',
    },
    type:
      | 'TAX'
      | 'GIFT'
      | 'MISC'
      | 'REFUND'
      | 'CHARGE'
      | 'SERVICE'
      | 'PHYSICAL'
      | 'ADJUSTMENT',
    productId: String,
    productUrl: String,
    description: String,
    taxes: {
      name: String,
      type: 'INCLUDED',
      amount: Amount
    }[],
    imageUrls: String[],
    totalTaxAmount: Amount,
    totalDiscountAmount: Amount,
    discounts: {
      name: String,
      type: 'FIXED',
      totalAmount: Amount,
      appliedAmount: Amount
    }[],
    metadata: Record<string, unknown>
  }[],
  buttonStyle: {
    height: String,
    size: ButtonSize[],
    variant: ButtonVariant[],
    radius: ButtonBorderRadius[],
    cashback: Boolean,
    cashbackCurrency: String
  },
  popupOptions: {
    closeOnOverlayClick: Boolean
  },
  validate: Function,
  customer: {
    name: String,
    email: String,
    phone: String,
    dateOfBirth: {
      day: Number,
      month: Number,
      year: Number,
    }
  }
}

Field	Description	Format	Required
`target`	Determines where the Revolut Pay button will be rendered on your site (e.g., a DOM node like, `document.getElementById("kiwi")` or a CSS selector like, `"#kiwi"`).	HTML Element	Yes

Options object:

Field	Description	Format	Required
`currency`	3-letter currency code (e.g. 'USD').	String	Yes
`totalAmount`	The amount to be paid by the customer, given in the lowest denomination (e.g. cents).	Number	Yes
`requestShipping`	If `true`, the shipping address and delivery method are quickly collected through Revolut Pay from the user. Your backend must support Fast checkout for this functionality to work (for more information, see: Implement Revolut Pay with Fast checkout). Default: `false`.	Boolean	No
`savePaymentMethodForMerchant`	If `true`, the customer gives permission to the merchant to use the payment method (Revolut account or card details saved via Revolut Pay) in the future. The customer only needs to authorise this payment method once, then the merchant can use this payment method to take future payments without further action required from the customer. This feature is useful when managing recurring payments or setting up scheduled payments in the future. To learn more about merchant initiated transactions, see: Configure Revolut Pay button: Merchant initiated transactions. Default: `false`.	Boolean	No
`mobileRedirectUrls`	Object containing the URLs a user is redirected to in a mobile flow, upon different payment events. Could be used to combine event listening on desktop and redirects on mobile. Do not use relative URLs!	Object	No
`redirectUrls`	Object containing the URLs a user is redirected to, upon different payment events. Do not use relative URLs!	Object	No
`createOrder`	Callback function handling the order creation operation, and returning the `token`. For more information, see: Merchant API: Create an order.	Function	Yes
`lineItems`	List of items in the customer's cart at checkout.	List of objects	No
`buttonStyle`	Dictionary that controls the style of the button.	Dictionary	No
`popupOptions`	Dictionary that controls the behaviour of the popup.	Dictionary	No
`validate`	You can define an asynchronous function that needs to be fulfilled before payment is processed. The function can return either a boolean or throw an error (in case the validation failed). If you return a boolean: `true` will allow the payment flow to continue, while `false` will terminate the payment and the widget closes. If you throw an error: when the validation fails the payment flow is terminated, the widget displays the error message, then the widget closes.	Function	No
`customer`	Object containing customer details the merchant already has. These details can be prefilled upon initializing the widget. Only valid details are prefilled.	Object	No

mobileRedirectUrls object:

Field	Description	Format	Required
`success`	The URL a user is redirected to, if the payment is successful.	String	Yes
`failure`	The URL a user is redirected to, if the payment fails.	String	Yes
`cancel`	The URL a user is redirected to, if the user cancels the payment.	String	Yes

redirectUrls object:

Field	Description	Format	Required
`success`	The URL a user is redirected to, if the payment is successful.	String	Yes
`failure`	The URL a user is redirected to, if the payment fails.	String	Yes
`cancel`	The URL a user is redirected to, if the user cancels the payment.	String	Yes

lineItems array:

Field	Description	Format	Required
`name`	Name of the product.	String	Yes
`totalAmount`	Total price sum of all the items in the customer's cart.	Amount	Yes
`unitPriceAmount`	Unit price of the product.	Amount	Yes
`quantity`	Dictionary defining the quantity and unit of the product.	Object	No
`type`	The type of the product connected to the order. Possible values: `'TAX'` `'GIFT'` `'MISC'` `'REFUND'` `'CHARGE'` - Refers to charge back payments `'SERVICE'` `'PHYSICAL'` `'ADJUSTMENT'`	Enum	No
`productId`	The ID of the product connected to the order.	String	No
`productUrl`	The URL where the product is available online.	String	No
`description`	The product description.	String	No
`taxes`	List of taxes applied to the given item in the order.	List	No
`imageUrls`	List of URLs pointing to images of the given item.	List	No
`totalTaxAmount`	Total sum of taxes applied to the given item in the order.	Amount	No
`totalDiscountAmount`	Total sum of discounts applied to the given item in the order.	Amount	No
`discounts`	List objects containing information about possible discounts, defined by the merchant.	List of objects	No
`metadata`	Additional meta information of the given item in the order.	Dictionary	No

quantity object:

Field	Description	Format	Required
`value`	Quantity of the product, in the given unit.	Number	Yes
`unit`	The measurement unit used for the chosen product (e.g. `'PIECES'`).	String	Yes

taxes array:

Field	Description	Format	Required
`name`	Name of the tax.	String	Yes
`type`	Type of the tax. Possible values: `'INCLUDED'`	String	No
`amount`	Total amount of the tax	Amount	Yes

discounts array:

Field	Description	Format	Required
`name`	Name of the discount.	String	Yes
`type`	Type of the discount. Possible values: `'FIXED'`	String	No
`totalAmount`	Total amount of the discount	Amount	No
`appliedAmount`	The part of the discount amount that is actually taken into consideration	Amount	No

buttonStyle object:

Field	Description	Format	Required
`height`	Controls the height of the button. Accepts actual CSS values, like: `10px`	String	No
`size`	Controls whether the button should occupy the full width of the division it is in (`large`) or not (`small`). Default: `large`	List of strings	No
`variant`	Controls which color variant of the button is displayed. Default: `dark` Possible values: `dark` `light` `light-outlined`	List of strings	No
`radius`	Controls the size of the button's border radius. Default: `small` Possible values: `none` `small` `large` `round`	List of strings	No
`cashback`	Controls if rewards are applied to payment. The amount is dynamically fetched from Revolut. Default: `true`	Boolean	No
`cashbackCurrency`	3-letter currency code of the reward, displayed on the widget. Default: `GBP`	Enum	Yes

popupOptions object:

Field	Description	Format	Required
`closeOnOverlayClick`	Controls whether the pop-up should close when the overlay is clicked. Default: `true`.	Boolean	No

customer object:

Field	Description	Format	Required
`name`	Customer's name. Example: `'Firstname Lastname'`	String	No
`email`	Customer's email. Example: `'example@email.com'`	String	No
`phone`	Customer's phone number, containing country code and '+' character. Example: `'+441234567890'`	String	No
`dateOfBirth`	Object containing customer's date of birth.	Object	No

dateOfBirth object:

Field	Description	Format	Required
`day`	Customer's birth day.	Number, between 1-31	Yes
`month`	Customer's birth month.	Number, between 1-12	Yes
`year`	Customer's birth year.	Number, 4 digits	Yes

Returns

Methods object:

Field	Description	Format
`destroy`	Manually destroy the button if needed.	Function

Listen to events

Use the following method to listen to relevant Revolut Pay events, triggered by the user clicking the Revolut Pay button:

revolutPay.on(event, handler)

Method parameters

Parameter	Description	Format
`type`	Name of the event type.	String
`handler`	A callback function that will be called with an `event` object when the event `type` is fired.	Function

Event object

The event object for the payment trigger has the following shape:

{type: 'success', orderId: string} | {type: 'error', error: RevolutCheckoutError, orderId?: string} | 
{type: 'cancel', dropOffState:  
  | 'enter_otp'
  | 'payment_summary'
  | 'load_session_data'
  | 'enter_card_details'
  | 'verify_user_details'
  | 'enter_personal_details'
  | 'enter_shipping_details'
  | 'revolut_app_push_challenge',
        
  orderId?: string
}

Event type	Description
`success`	Event type returned when the `payment` is successful.
`error`	Event type returned when the `payment` fails, called with a `RevolutCheckoutError` object.
`cancel`	Event type returned when the `payment` is cancelled, called with a `dropOffState` object. The `dropOffState` refers to the specific step in the payment flow where the customer cancels the payment.

Use event listening with mobile redirect URLs

This configuration can mitigate a potential issue if the customer has the Revolut app not installed and completes the payment through the Revolut Pay web flow.

When customers use Revolut Pay on your checkout page and complete their payment, they are redirected back to the checkout page. However, if the Revolut Pay button is not rendered again upon redirection, the payment flow gets interrupted and stops.

To address this, you can use mobile redirect URLs, so users don't abandon their payments.

Set up your configuration as described in the Listen to events section.

In addition, pass the mobileRedirectUrls object to the paymentOptions to implement Revolut Pay with mobile redirection. These URLs will be the pages customers are redirected to on their mobile devices upon each of the corresponding payment flow events.

Upon successful redirection, you can make any required API calls, then show the customer a success or failure message.

Use redirect URLs

Pass the redirectUrls object to the paymentOptions to implement Revolut Pay without event listening. These URLs will be the pages your customers are redirected upon each of the corresponding payment flow events.

Upon successful redirection, you can make any required API calls, then show the customer a success or failure message.

Fetch public order ID from redirect URL

If you want to execute further operations on the user's order, Revolut Pay will append the corresponding order's token to your redirect URL in the following cases:

success: always present on this URL,
failure, cancel: optional for these URLs, depending on whether an order was already internally created.

For example, with the success URL: www.example.com/success, upon redirection, the URL will look like this: www.example.com/success?_rp_oid=fe34dbd3-3fa9-4d4c-8987-3f7735ba3cdf.

Where the query parameter: _rp_oid contains the token of the order. To fetch the token from the query string, you have two options:

Fetch the query parameter within your code:

const searchQueries = new URLSearchParams(window.location.search)
const revolutPublicOrderId = searchQueries.get('rp_oid')

Use the exported utility helper from the @revolut/checkout package:

import { getRevolutPayOrderIdURLParam } from '@revolut/checkout'

const revolutPublicOrderId = getRevolutPayOrderIdURLParam()

If you use a server-side rendered application, for example, React or NextJS, you have to call getRevolutPayOrderIdURLParam() within useEffect() in the following way:

useEffect(() => {
  const revolutPublicOrderId = getRevolutPayOrderIdURLParam()
  // Execute further operations with this order ID here
}, [])

Examples

Insert the following DOM element into your webpage where you want to render the Revolut Pay button, and pass the id of this element as the first argument of the .mount statement:

your-page.html
<div id='revolut-pay'></div>

Example with minimal required values (with event listening)

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

const { revolutPay } = await RevolutCheckout.payments({
  publicToken: '<yourPublicApiKey>' // Merchant public API key
})

const paymentOptions = {
  currency: 'USD', // 3-letter currency code
  totalAmount: 1000, // In lowest denomination e.g., cents
    
  createOrder: async () => {
    // Call your backend here to create an order
    // For more information, see: https://developer.revolut.com/docs/merchant/create-order
    const order = await yourServerSideCall()
    return { publicId: order.token }
  },

  // You can put other optional parameters here
}

revolutPay.mount(document.getElementById('revolut-pay'), paymentOptions)

revolutPay.on('payment', (event) => {
  switch (event.type) {
    case 'cancel': {
      if (event.dropOffState === 'payment_summary') {
        log('what a shame, please complete your payment')
      }
      break
    }

    case 'success':
      onSuccess()
      break

    case 'error':
      onError(event.error)
      break
  }
})

Example with minimal required values (with event listening and mobile redirect URLs)

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

const { revolutPay } = await RevolutCheckout.payments({
  publicToken: '<yourPublicApiKey>' // Merchant public API key
})

const paymentOptions = {
  currency: 'USD', // 3-letter currency code
  totalAmount: 1000, // In lowest denomination e.g., cents
  mobileRedirectUrls: {
    success: 'https://www.example.com/success',
    failure: 'https://www.example.com/failure',
    cancel: 'https://www.example.com/cancel'
  },
    
  createOrder: async () => {
    // Call your backend here to create an order
    // For more information, see: https://developer.revolut.com/docs/merchant/create-order
    const order = await yourServerSideCall()
    return { publicId: order.token }
  },

  // You can put other optional parameters here
}

revolutPay.mount(document.getElementById('revolut-pay'), paymentOptions)

revolutPay.on('payment', (event) => {
  switch (event.type) {
    case 'cancel': {
      if (event.dropOffState === 'payment_summary') {
        log('what a shame, please complete your payment')
      }
      break
    }

    case 'success':
      onSuccess()
      break

    case 'error':
      onError(event.error)
      break
  }
})

Example with minimal required values (with redirect URLs)

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

const { revolutPay } = await RevolutCheckout.payments({
  publicToken: '<yourPublicApiKey>' // Merchant public API key
})

const paymentOptions = {
  currency: 'USD',
  totalAmount: 1000,
  redirectUrls: {
    success: 'https://www.example.com/success',
    failure: 'https://www.example.com/failure',
    cancel: 'https://www.example.com/cancel'
  },

  createOrder: async () => {
    // Call your backend here to create an order
    // For more information, see: https://developer.revolut.com/docs/merchant/create-order
    const order = await yourServerSideCall()
    return { publicId: order.token }
  },

  // You can put other optional parameters here
}

revolutPay.mount(document.getElementById('revolut-pay'), paymentOptions)

PreviousThe payment object

NextThe upsell object

How to mount the Revolut Pay button
Mount options
Returns
Listen to events
- Method parameters
- Event object
Use event listening with mobile redirect URLs
Use redirect URLs
- Fetch public order ID from redirect URL
Examples

Payments.revolutPay

How to mount the Revolut Pay button​

Mount options​

Returns​

Listen to events​

Method parameters​

Event object​

Use event listening with mobile redirect URLs​

Use redirect URLs​

Fetch public order ID from redirect URL​

Examples​

Example with minimal required values (with event listening)​

Example with minimal required values (with event listening and mobile redirect URLs)​

Example with minimal required values (with redirect URLs)​

How to mount the Revolut Pay button

Mount options

Returns

Listen to events

Method parameters

Event object

Use event listening with mobile redirect URLs

Use redirect URLs

Fetch public order ID from redirect URL

Examples

Example with minimal required values (with event listening)

Example with minimal required values (with event listening and mobile redirect URLs)

Example with minimal required values (with redirect URLs)