Developer
Developer
Sandbox
Help

payWithPopup()

View as Markdown

Opens a full-screen modal window with an integrated card payment form. The pop-up provides a PCI-compliant checkout experience where customers can enter their card details, billing information, and complete the payment without leaving your application.

Key features:

  • Full-screen modal with complete payment form
  • PCI-compliant card data handling
  • Built-in billing address collection
  • Support for saved payment methods
  • Automatic email collection if not provided

For a complete implementation guide with examples, see: Accept card payments via card pop-up - Web

For card payments, billingAddress is required. Provide it in payWithPopup(). If you don't pre-fill it, the pop-up collects it before payment continues.

Type signature

RevolutCheckoutInstance.payWithPopup(
  options?: PopupOptions
): RevolutCheckoutInstance

interface PopupOptions {
  name?: string
  email?: string
  phone?: string
  billingAddress?: Address
  shippingAddress?: Address
  locale?: Locale | 'auto'
  savePaymentMethodFor?: 'merchant' | 'customer'
  onSuccess?: () => void
  onError?: (error: RevolutCheckoutError) => void
  onCancel?: () => void
}

Parameters

ParameterDescriptionTypeRequired
optionsConfiguration object for the payment pop-upPopupOptionsNo
ParameterDescriptionTypeRequired
namePre-fill customer's full name in format "FirstName LastName"stringNo*
emailPre-fill customer's email addressstringNo*
phonePre-fill customer's phone numberstringNo
billingAddressProvide or pre-fill customer's billing address for card paymentsAddressYes*
shippingAddressPre-fill customer's shipping address (displayed in Merchant Dashboard only)AddressNo
localeWidget languageLocale | 'auto' (default: 'auto')No
savePaymentMethodForSave payment method for future use'merchant' | 'customer'No
onSuccessCallback triggered when payment completes successfully() => voidNo
onErrorCallback triggered when payment fails. Receives RevolutCheckoutError(error: RevolutCheckoutError) => voidNo
onCancelCallback triggered when user cancels or closes the pop-up() => voidNo

* Required for card payments. If not provided in payWithPopup(), it will be requested in the pop-up.

Return value

RevolutCheckoutInstance

interface RevolutCheckoutInstance {
  destroy: () => void
  // ... other methods
}

The method returns the same RevolutCheckoutInstance for method chaining. The instance contains:

MethodDescriptionType
destroyManually close the pop-up and clean up resources() => void

Callback events

The card pop-up provides callback functions for handling payment lifecycle events in your frontend.

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.

onSuccess

() => 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

Example:

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

onError

(error: RevolutCheckoutError) => 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

Example:

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

onCancel

() => void

Triggered when the user cancels the payment or closes the pop-up window.

Use cases:

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

Example:

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

Usage examples

import RevolutCheckout from '@revolut/checkout'

// Initialise with order token
const instance = await RevolutCheckout(orderToken, 'prod')

// Open payment pop-up
instance.payWithPopup({
  billingAddress: {
    countryCode: 'GB',
    postcode: 'EC1A 1BB',
    city: 'London',
    streetLine1: '1 Example Street',
  },
  onSuccess: () => {
    console.log('Payment successful!')
    window.location.href = '/confirmation'
  },

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

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

Pre-fill customer information

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

const instance = await RevolutCheckout(orderToken, 'prod')

instance.payWithPopup({
  name: 'John Doe',
  email: 'customer@example.com',
  phone: '+447950630319',
  billingAddress: {
    countryCode: 'GB',
    region: 'Greater London',
    city: 'London',
    postcode: 'EC1A 1BB',
    streetLine1: '1 Example Street',
    streetLine2: 'Flat 2B',
  },
  shippingAddress: {
    countryCode: 'GB',
    region: 'Greater London',
    city: 'London',
    postcode: 'EC1A 1BB',
    streetLine1: '1 Example Street',
    streetLine2: 'Flat 2B',
  },
  onSuccess: () => {
    window.location.href = '/confirmation'
  },
  onError: (error) => {
    alert(`Payment failed: ${error.message}`)
  },
})

Save payment method for future use

You can save the customer's payment method for future payments using savePaymentMethodFor:

  • 'customer' - For customer-initiated future payments (express checkout, saved cards)
  • 'merchant' - For merchant-initiated recurring payments (subscriptions, auto-renewals)
instance.payWithPopup({
  name: 'John Doe',
  email: 'customer@example.com',
  billingAddress: {
    countryCode: 'GB',
    postcode: 'EC1A 1BB',
    city: 'London',
    streetLine1: '1 Example Street',
  },
  savePaymentMethodFor: 'customer', // or 'merchant'

  onSuccess: () => {
    console.log('Payment successful and card saved!')
    window.location.href = '/confirmation'
  },

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

See also

Rate this page