Accept payments via Revolut Pay - Web

Add the Revolut Pay button to your checkout, confirm payment results in your UI, and fulfil orders on authoritative webhooks.

Revolut Pay allows your customers to pay with their card or Revolut bank account, delivering a streamlined checkout experience through your website.

In this tutorial, we'll guide you through integrating Revolut Pay, powered by the Revolut Checkout Widget. The SDK handles the entire payment flow, including redirection and authentication, reducing friction and improving conversion rates.

How it works​

From an implementation perspective, the Revolut Pay SDK works with the following components:

1. Server-side: A server-side endpoint is required to securely communicate with the Merchant API to create orders.
2. Client-side: The SDK uses your public API key to initialise a RevolutCheckout.payments() instance, which gives you access to the revolutPay module. The Revolut Pay button is then configured and mounted, using a token from the created order to initiate the payment. The SDK handles the payment flow, including other actions like redirection or authentication.
3. Endpoint for webhooks: Your server listens for webhook events to reliably track the payment lifecycle. Webhooks are mandatory for critical backend processes like updating order status, managing inventory, or initiating shipping. For more information, see: Use webhooks to keep track of the payment lifecycle.

The payment flow is slightly different based on whether your customer has the Revolut app installed:

Implementation overview​

The high-level implementation steps are the following:

1. Set up endpoint creating orders
2. Install Revolut Checkout package
3. Initialise Revolut Pay SDK
4. Configure Revolut Pay SDK
5. Mount Revolut Pay button
6. Handle payment results

The following sections describe each step in detail. To see working examples, you can skip ahead.

Integration options​

To handle the payment result, you have two integration paths, explained in detail in step 6:

• Redirect URLs: Add redirectUrls to your paymentOptions and the widget redirects the customer to your success, failure, or cancel pages on all devices. The simplest path, suitable for multi-page applications.
• Event listening with mobile redirects: Handle payment outcomes in your client-side code with the .on() method for a dynamic UI, and provide mobileRedirectUrls to redirect customers on mobile devices when the payment continues on a standalone Revolut page (without the Revolut app installed).

Before you begin​

Before you start this tutorial, make sure you have the following:

• An active Merchant account with Revolut Business. If you don't have one yet, apply for a Merchant account.
• Your API keys - both your public key (for initialising the SDK) and secret key (for creating orders on your backend). See Generate the API keys.
• A backend server to securely create orders using the Merchant API. Your secret API key must never be exposed on the client side.
• A website checkout page where you'll mount the Revolut Pay button.

Implement Revolut Pay​

This section walks you through the server- and client-side implementation step by step.

1. Set up endpoint creating orders​

Before implementing the client-side widget, you must first create a dedicated endpoint on your server. This is a critical security step, as your secret API key must never be exposed on the client side.

The role of this server-side endpoint is to act as a secure bridge between your frontend and the Merchant API. When a customer initiates a payment on your website, your frontend will call this endpoint. Your endpoint is then responsible for:

1. Receiving the checkout details (e.g., amount, currency) from the frontend request.
2. Securely calling the Merchant API: Create an order endpoint with the received details.
3. Receiving the order details, including the public token, back from the Merchant API.
4. Passing this token back to your frontend in the response.

In step 4, the createOrder callback calls this endpoint to fetch the token the widget needs to start the payment.

POST /api/orders HTTP/1.1
Host: merchant.revolut.com
Authorization: Bearer sk_abcdef12347890_...
Content-Type: application/json
Revolut-Api-Version: 2026-08-17

{
  "amount": 1000,
  "currency": "GBP"
}

POST /api/orders HTTP/1.1
Host: merchant.revolut.com
Authorization: Bearer sk_abcdef12347890_...
Content-Type: application/json
Revolut-Api-Version: 2026-08-17

{
  "amount": 1000,
  "currency": "GBP"
}

2. Install Revolut Checkout package​

Before you begin the client-side integration, add the Revolut Checkout package to your project using your preferred package manager. This package is necessary to interact with the Revolut Pay SDK.

npm install @revolut/checkout

npm install @revolut/checkout

yarn add @revolut/checkout

yarn add @revolut/checkout

pnpm add @revolut/checkout

pnpm add @revolut/checkout

bun add @revolut/checkout

bun add @revolut/checkout

3. Initialise Revolut Pay SDK​

Import RevolutCheckout and call RevolutCheckout.payments() with your Public API key to get a revolutPay instance. You can also pass an optional locale parameter here, which is useful if you want to align the language of the Revolut Pay widget with your site's language selector.

import RevolutCheckout from '@revolut/checkout'

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

// Configuration code will go here

import RevolutCheckout from '@revolut/checkout'

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

// Configuration code will go here

4. Configure Revolut Pay SDK​

Next, create a paymentOptions object. This object defines the core details of the payment and will be passed to the revolutPay.mount() method in the next step.

The most critical parameter is createOrder. This is a function you define that calls your backend to create an order via the Merchant API and returns the token (as publicId).

import RevolutCheckout from '@revolut/checkout'

const { revolutPay } = await RevolutCheckout.payments({
  publicToken: 'pk_abcdef12347890_...', // Merchant public API key
  mode: 'prod',
})

const paymentOptions = {
  currency: 'GBP', // 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/api/merchant#create-order
    const order = await yourServerSideCall()
    return { publicId: order.token }
  },

  // You can put other optional parameters here
}

import RevolutCheckout from '@revolut/checkout'

const { revolutPay } = await RevolutCheckout.payments({
  publicToken: 'pk_abcdef12347890_...', // Merchant public API key
  mode: 'prod',
})

const paymentOptions = {
  currency: 'GBP', // 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/api/merchant#create-order
    const order = await yourServerSideCall()
    return { publicId: order.token }
  },

  // You can put other optional parameters here
}

Additional settings​

The Revolut Pay integration also offers a range of options for enhanced functionality. You can include these inside the paymentOptions object.

5. Mount Revolut Pay button​

Now, render the Revolut Pay button on your page.

5.1 Add a DOM element​

First, add an empty <div> container to your HTML file where you want the button to appear.

<!-- ... -->

<div id="revolut-pay"></div>

<!-- ... -->

<!-- ... -->

<div id="revolut-pay"></div>

<!-- ... -->

5.2 Mount the button​

Call the .mount() method from your revolutPay instance, passing the container's selector and the paymentOptions you configured.

import RevolutCheckout from '@revolut/checkout'

const { revolutPay } = await RevolutCheckout.payments({
  publicToken: 'pk_abcdef12347890_...', // Merchant public API key
  mode: 'prod',
})

const paymentOptions = {
  currency: 'GBP',
  totalAmount: 1000,

  createOrder: async () => {
    // Call your backend here to create an order
    // For more information, see: https://developer.revolut.com/docs/api/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)

import RevolutCheckout from '@revolut/checkout'

const { revolutPay } = await RevolutCheckout.payments({
  publicToken: 'pk_abcdef12347890_...', // Merchant public API key
  mode: 'prod',
})

const paymentOptions = {
  currency: 'GBP',
  totalAmount: 1000,

  createOrder: async () => {
    // Call your backend here to create an order
    // For more information, see: https://developer.revolut.com/docs/api/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)

6. Handle payment results​

Revolut Pay reports the payment result to your frontend through one of two integration paths: redirect URLs, or event listening with mobile redirects. Both paths confirm the result at the UX-level only.

The authoritative payment status for your business logic - fulfilment, shipping, inventory - always arrives on your server via webhooks, which you set up at the end of this step.

Confirm payment result in UI​

You have the following integration paths to choose from:

import RevolutCheckout from '@revolut/checkout'

const { revolutPay } = await RevolutCheckout.payments({
  publicToken: 'pk_abcdef12347890_...', // Merchant public API key
  mode: 'prod',
})

const paymentOptions = {
  currency: 'GBP',
  totalAmount: 1000,

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

  redirectUrls: {
    success: 'https://www.example.com/success',
    failure: 'https://www.example.com/failure',
    cancel: 'https://www.example.com/cancel',
  },

  // You can put other optional parameters here
}

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

import RevolutCheckout from '@revolut/checkout'

const { revolutPay } = await RevolutCheckout.payments({
  publicToken: 'pk_abcdef12347890_...', // Merchant public API key
  mode: 'prod',
})

const paymentOptions = {
  currency: 'GBP',
  totalAmount: 1000,

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

  redirectUrls: {
    success: 'https://www.example.com/success',
    failure: 'https://www.example.com/failure',
    cancel: 'https://www.example.com/cancel',
  },

  // You can put other optional parameters here
}

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

case 'cancel': // Handle payment cancellations if (event.dropOffState === 'payment_summary') { // The payment was abandoned on the payment summary screen } break } }) })

| Parameter | Description |
|-----------|-------------|
| `success` | URL the customer is redirected to on mobile after a successful payment. |
| `failure` | URL the customer is redirected to on mobile after a failed payment. |
| `cancel` | URL the customer is redirected to on mobile after they cancel the payment. |

| Event type | Description |
|------------|-------------|
| `success` | The payment completed successfully. |
| `error` | The payment failed. Error details are available in `event.error.message`. |
| `cancel` | The customer cancelled the payment. `event.dropOffState` shows where - see [Revolut Pay](/docs/sdks/merchant-web-sdk/payment-methods/revolut-pay) for all values. |

:::info
For more information about listening to `payment` events, see: [Revolut Pay](/docs/sdks/merchant-web-sdk/payment-methods/revolut-pay).
:::


#### Handle customer landing on redirect page

Every Revolut Pay integration uses redirects: with `redirectUrls`, the customer is redirected on all devices; with `mobileRedirectUrls`, on mobile only. In both paths, the customer lands on one of your redirect pages after the payment.

When a customer is redirected to your `success`, `failure`, or `cancel` page, Revolut Pay appends the order's public ID (`token`) as a query parameter named `_rp_oid`. For a `success` URL of `https://www.example.com/success`, the final URL is `https://www.example.com/success?_rp_oid=fe34dbd3-3fa9-4d4c-8987-3f7735ba3cdf`.

Retrieve this ID on your redirect page using one of the following methods:

1. **Using `URLSearchParams`:**

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

| Parameter | Description |
|-----------|-------------|
| `success` | URL the customer is redirected to on mobile after a successful payment. |
| `failure` | URL the customer is redirected to on mobile after a failed payment. |
| `cancel` | URL the customer is redirected to on mobile after they cancel the payment. |

| Event type | Description |
|------------|-------------|
| `success` | The payment completed successfully. |
| `error` | The payment failed. Error details are available in `event.error.message`. |
| `cancel` | The customer cancelled the payment. `event.dropOffState` shows where - see [Revolut Pay](/docs/sdks/merchant-web-sdk/payment-methods/revolut-pay) for all values. |

:::info
For more information about listening to `payment` events, see: [Revolut Pay](/docs/sdks/merchant-web-sdk/payment-methods/revolut-pay).
:::


#### Handle customer landing on redirect page

Every Revolut Pay integration uses redirects: with `redirectUrls`, the customer is redirected on all devices; with `mobileRedirectUrls`, on mobile only. In both paths, the customer lands on one of your redirect pages after the payment.

When a customer is redirected to your `success`, `failure`, or `cancel` page, Revolut Pay appends the order's public ID (`token`) as a query parameter named `_rp_oid`. For a `success` URL of `https://www.example.com/success`, the final URL is `https://www.example.com/success?_rp_oid=fe34dbd3-3fa9-4d4c-8987-3f7735ba3cdf`.

Retrieve this ID on your redirect page using one of the following methods:

1. **Using `URLSearchParams`:**

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

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

   import { getRevolutPayOrderIdURLParam } from '@revolut/checkout'
   
   const revolutPublicOrderId = getRevolutPayOrderIdURLParam()

   import { getRevolutPayOrderIdURLParam } from '@revolut/checkout'
   
   const revolutPublicOrderId = getRevolutPayOrderIdURLParam()

   Copy

Send this ID to your backend and resolve it to the order you created in step 1 - your backend looks up the order by its token and uses the stored order id to retrieve the current payment state:

GET /api/orders/{order_id} HTTP/1.1
Host: merchant.revolut.com
Authorization: Bearer sk_abcdef12347890_...
Revolut-Api-Version: 2026-08-17

GET /api/orders/{order_id} HTTP/1.1
Host: merchant.revolut.com
Authorization: Bearer sk_abcdef12347890_...
Revolut-Api-Version: 2026-08-17

Set up webhooks​

Your backend must rely on webhooks as the authoritative source of payment status. Widget events and redirect URLs confirm the result at the UX level only - webhooks are guaranteed, server-to-server notifications that drive your critical backend logic.

POST /api/webhooks HTTP/1.1
Host: merchant.revolut.com
Authorization: Bearer sk_abcdef12347890_...
Content-Type: application/json

{
  "url": "https://example.com/webhooks",
  "events": [
    "ORDER_COMPLETED",
    "ORDER_AUTHORISED",
    "ORDER_PAYMENT_DECLINED",
    "ORDER_PAYMENT_FAILED",
    "ORDER_CANCELLED",
    "ORDER_FAILED"
  ]
}

POST /api/webhooks HTTP/1.1
Host: merchant.revolut.com
Authorization: Bearer sk_abcdef12347890_...
Content-Type: application/json

{
  "url": "https://example.com/webhooks",
  "events": [
    "ORDER_COMPLETED",
    "ORDER_AUTHORISED",
    "ORDER_PAYMENT_DECLINED",
    "ORDER_PAYMENT_FAILED",
    "ORDER_CANCELLED",
    "ORDER_FAILED"
  ]
}

Payment outcomes​

Handle the following scenarios in your webhook handler:

Examples​

The examples below show a complete, self-contained implementation for each integration path: a checkout page, the client-side integration, and a minimal backend that creates orders. Both examples use async/await syntax - see steps 3-6 for the Promise-based equivalents.

Example with redirect URLs​

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8">
    <title>Checkout</title>
  </head>
  <body>
    <h1>Checkout</h1>

    <!-- The Revolut Pay button renders here -->
    <div id="revolut-pay"></div>

    <script type="module" src="/app.js"></script>
  </body>
</html>

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8">
    <title>Checkout</title>
  </head>
  <body>
    <h1>Checkout</h1>

    <!-- The Revolut Pay button renders here -->
    <div id="revolut-pay"></div>

    <script type="module" src="/app.js"></script>
  </body>
</html>

Example with event listening and mobile redirect URLs​

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8">
    <title>Checkout</title>
  </head>
  <body>
    <h1>Checkout</h1>

    <!-- The Revolut Pay button renders here -->
    <div id="revolut-pay"></div>

    <script type="module" src="/app.js"></script>
  </body>
</html>

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8">
    <title>Checkout</title>
  </head>
  <body>
    <h1>Checkout</h1>

    <!-- The Revolut Pay button renders here -->
    <div id="revolut-pay"></div>

    <script type="module" src="/app.js"></script>
  </body>
</html>

Implementation checklist​

Before deploying your implementation to your production environment, complete the checklist below to see if everything works as expected, using the Merchant API's Sandbox environment. To test in Sandbox, change the address of the endpoints you want to test from https://merchant.revolut.com/ to https://sandbox-merchant.revolut.com/. For more information, see: Set up a sandbox account.

As Revolut Pay has more complex user flows compared to other payment methods, the following user journey paths need to be tested (besides general tests):

• Desktop flow
• Mobile flow (without Revolut app installed)
• Mobile flow (with Revolut app installed)

To see if your implementation is able to manage all flows, check each flow against the checks below.

Desktop flow​

This is the least complex of the user flows. Steps are the following:

1. User clicks the Revolut Pay button on the merchant's site.
2. User journey is completed in a popup.
3. Payment completed or failed, the respective message is shown to the customer.

Mobile flow (without Revolut app installed)​

This user flow represents the case where the Revolut app is not installed on the customer's phone:

1. User clicks the Revolut Pay button on the merchant's site using their mobile browser.
2. Client SDK attempts to open the Revolut app.
3. If it is not installed, the user is redirected to a standalone page where the payment flow continues.
4. Payment completed or failed, the customer should be redirected to the merchant site and the respective message is shown to the customer.

Mobile flow (with Revolut app installed)​

This user flow represents the case where the Revolut app is installed on the customer's phone:

1. User clicks the Revolut Pay button on the merchant's site using their mobile browser.
2. Client SDK attempts to open the Revolut app.
3. If it is installed, the Revolut app is opened where the payment flow continues.
4. Payment completed or failed, the Revolut app attempts to redirect the user to the same browser where the flow started.
   Only Google Chrome, Safari, Samsung Internet Browser, Firefox, and Opera are supported. If the user begins on any other browser, successful redirection to the same browser is not guaranteed. The user will be redirected to their default mobile browser.

5. A self-closing page is opened, and the user arrives at the tab where the flow started.

General checks​

• Revolut Pay button is rendered at the intended DOM element.

• Your backend creates the order successfully when clicking the button.

• Order token is successfully fetched.

• Checkout is successful with test cards for successful payment.

• Checkout errors are handled as expected by your application.

  • All cases of cancel events are handled, and every dropOffState is managed as intended. For more information about the cancellation events, see: Revolut Pay.

  • Failed payments are handled with test cards for error cases.

Webhook verification​

• Webhook endpoint is set up to receive order and payment updates.
• Webhook subscription is created with ORDER_AUTHORISED, ORDER_COMPLETED, ORDER_PAYMENT_DECLINED, ORDER_PAYMENT_FAILED, ORDER_CANCELLED, and ORDER_FAILED events.
• ORDER_COMPLETED webhook event is received when a payment completes successfully.
• If using manual capture, ORDER_AUTHORISED is received after authorisation, and ORDER_COMPLETED is received after you capture the payment.
• Your backend only fulfils orders after receiving the ORDER_COMPLETED webhook event - never on widget events or redirect URL arrivals.
• Webhook signature verification is implemented for security.

Revolut Pay specific checks​

New customer​

• Customer is created in the Merchant API upon completing checkout.
• Customer details (email, payment methods, shipping details) saved in the Merchant API.
• On next checkout customer is already logged in.

Existing customer​

• After first login, customer is already logged in on next checkout.
• Existing customer has their details returned.
• New payment method is saved to customer successfully.
• Shipping details are returned/saved to the customer successfully.

Redirect URLs​

If you implemented Revolut Pay with redirect URLs:

• Redirect pages are always opened, both on desktop and mobile.
• Success or failure messaging works on your redirect pages, both on desktop and mobile.
• Redirect pages display the payment result based on the order state retrieved through the Merchant API, not on the redirect URL alone.

Event listening with mobile redirect URLs​

If you implemented Revolut Pay with event listening and mobile redirect URLs:

• All payment events are listened to, when payment was made on desktop.
• Payment events trigger the expected UI updates on desktop.
• Redirect pages are always opened on mobile.
• Success or failure messaging works on your redirect pages on mobile.

If your implementation handles all these cases as you expect in Sandbox, it is advised you also test your implementation in production before going live. Once your implementation passes all the checks in both environments, you can safely go live with your implementation.

These checks only cover the implementation path described in this tutorial. If your application handles more features of the Merchant API, see the Merchant API: Implementation checklists.

What's next​