embeddedCheckout()

Mounts the Revolut Checkout widget to a DOM element, providing access to all enabled payment methods through a single, unified interface. The widget aggregates Revolut Pay, Card, Apple Pay, Google Pay, Pay by Bank, and other payment methods configured in your Business Dashboard.

Key features:

• Unified widget for all payment methods
• Dashboard-configured (no code changes to add/reorder methods)
• Automatic payment method optimisation
• Built-in customisation options

Info

For a complete implementation guide with examples, see: Accept payments via Revolut Checkout - Web

Prerequisites​

This payment method requires direct initialisation.

Type signature​

RevolutCheckout.embeddedCheckout: (
  options: EmbeddedCheckoutOptions
) => Promise<EmbeddedCheckoutInstance>

interface EmbeddedCheckoutOptions {
  publicToken: string
  mode: 'prod' | 'sandbox'
  locale?: Locale | 'auto'
  target: HTMLElement
  createOrder: () => Promise<{ publicId: string }>
  onSuccess?: (payload: { orderId: string }) => void
  onError?: (payload: { error: RevolutCheckoutError; orderId: string }) => void
  onCancel?: (payload: { orderId: string | undefined }) => void
  email?: string
  billingAddress?: Address
}

interface EmbeddedCheckoutInstance {
  destroy: () => void
}

Parameters​

Parameter	Description	Type	Required
options	Configuration object for the embedded checkout widget	EmbeddedCheckoutOptions	Yes

EmbeddedCheckoutOptions interface​

Parameter	Description	Type	Required
publicToken	Your Merchant API Public key	string	Yes
mode	API environment	'prod' | 'sandbox'	Yes
locale	Widget language	Locale | 'auto' (default: 'auto')	No
target	DOM element where the widget should be mounted	HTMLElement	Yes
createOrder	Async function that calls your backend to create an order and returns the order token	() => Promise<{publicId: string}>	Yes
onSuccess	Callback triggered when payment completes successfully	(payload: {orderId: string}) => void	No
onError	Callback triggered when payment fails. Receives RevolutCheckoutError	(payload: {error: RevolutCheckoutError, orderId: string}) => void	No
onCancel	Callback triggered when user cancels payment. orderId may be undefined if order creation failed	(payload: {orderId?: string}) => void	No
email	Pre-fill customer's email address	string	No
billingAddress	Pre-fill customer's billing address	Address	No

Return value​

Promise<EmbeddedCheckoutInstance>

interface EmbeddedCheckoutInstance {
  destroy: () => void
}

The promise resolves with an EmbeddedCheckoutInstance object containing:

Property	Description	Type
destroy	Function to remove the widget from the page and clean up resources	() => void

Callback events​

The embedded checkout widget provides the following callback functions for handling payment lifecycle events in your frontend.

Caution

Widget callbacks are not guaranteed to fire due to network issues, browser closures, or ad-blockers. Always use webhooks for critical backend operations like order fulfilment.

Note

In all callbacks, orderId refers to the order's public token (order.token from the API response), not the internal order.id. This is the public identifier used in your frontend code.

onSuccess​

(payload: { orderId: string }) => void

Triggered when the payment completes successfully.

Use cases:

• Display success message to the customer
• Redirect to order confirmation page
• Update UI to reflect successful payment
• Show success animations

Example:

onSuccess: ({ orderId }) => {
  console.log('Payment successful!', orderId)
  window.location.href = `/confirmation?orderId=${orderId}`
}

onError​

(payload: { error: RevolutCheckoutError; orderId: string }) => void

Triggered when the payment fails. The error parameter is a RevolutCheckoutError object containing error details.

Use cases:

• Display error message to the customer
• Log error for debugging
• Re-enable checkout form
• Show retry option

Example:

onError: ({ error, orderId }) => {
  console.error('Payment failed:', error.message, orderId)
  alert(`Payment failed: ${error.message}`)
}

onCancel​

(payload: { orderId: string | undefined }) => void

Triggered when the user cancels the payment. The orderId may be undefined if the order was not created yet.

Use cases:

• Display cancellation message
• Re-enable checkout form
• Track abandonment analytics

Example:

onCancel: ({ orderId }) => {
  console.log('Payment cancelled', orderId)
  alert('Payment was cancelled. You can try again.')
}

Error handling​

Throws: RevolutCheckoutError

The embedded checkout can throw errors in the following scenarios:

• Invalid publicToken
• Failed order creation in the createOrder callback
• Network connectivity issues
• Invalid configuration options
• Widget loading failures

Example error handling:

try {
  const { destroy } = await RevolutCheckout.embeddedCheckout({
    // ... configuration
  })
} catch (error) {
  if (error.name === 'RevolutCheckout') {
    console.error('Checkout initialisation failed:', error.message)
    // Handle initialisation error
  }
}

For error handling within callbacks, see the onError callback section.

Usage example​

import RevolutCheckout from '@revolut/checkout'

// Initialise and mount the embedded checkout
const { destroy } = await RevolutCheckout.embeddedCheckout({
  publicToken: process.env.REVOLUT_PUBLIC_KEY,
  mode: 'prod',
  locale: 'auto',
  target: document.getElementById('checkout-container'),

  createOrder: async () => {
    // Call your backend to create an order
    const response = await fetch('/api/create-order', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        amount: 1000,
        currency: 'GBP'
      })
    })
    const order = await response.json()
    return { publicId: order.token }
  },

  onSuccess: ({ orderId }) => {
    console.log('Payment successful!', orderId)
    window.location.href = `/confirmation?orderId=${orderId}`
  },

  onError: ({ error, orderId }) => {
    console.error('Payment failed:', error.message, orderId)
    alert(`Payment failed: ${error.message}`)
  },

  onCancel: ({ orderId }) => {
    console.log('Payment cancelled', orderId)
    alert('Payment was cancelled.')
  }
})

// Later, if you need to remove the widget:
// destroy()

Pre-fill customer information​

You can improve the checkout experience by pre-filling customer information:

const { destroy } = await RevolutCheckout.embeddedCheckout({
  // ... other configuration
  email: '[email protected]',
  billingAddress: {
    countryCode: 'GB',
    region: 'Greater London',
    city: 'London',
    postcode: 'EC1A 1BB',
    streetLine1: '1 Example Street',
    streetLine2: 'Flat 2B'
  }
})

When provided, these fields are automatically pre-filled in the payment form, reducing friction and potentially increasing conversion rates.

See also​

• Accept payments via Revolut Checkout - Web
• Customise Revolut Checkout in Revolut Business
• Address type reference
• RevolutCheckoutError type reference
• Use webhooks to keep track of the payment lifecycle