payWithPopup()

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

Info

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

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​

Parameter	Description	Type	Required
options	Configuration object for the payment pop-up	PopupOptions	No

PopupOptions interface​

Parameter	Description	Type	Required
name	Pre-fill customer's full name in format "FirstName LastName"	string	No*
email	Pre-fill customer's email address	string	No*
phone	Pre-fill customer's phone number	string	No
billingAddress	Pre-fill customer's billing address	Address	No*
shippingAddress	Pre-fill customer's shipping address (displayed in Merchant Dashboard only)	Address	No
locale	Widget language	Locale | 'auto' (default: 'auto')	No
savePaymentMethodFor	Save payment method for future use	'merchant' | 'customer'	No
onSuccess	Callback triggered when payment completes successfully	() => void	No
onError	Callback triggered when payment fails. Receives RevolutCheckoutError	(error: RevolutCheckoutError) => void	No
onCancel	Callback triggered when user cancels or closes the pop-up	() => void	No

* Required if not provided during order creation via API. If not provided, 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:

Method	Description	Type
destroy	Manually 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.

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.

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({
  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: '[email protected]',
  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: '[email protected]',
  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​

• Accept card payments via card pop-up - Web
• Token-based initialisation
• Address type reference
• RevolutCheckoutError type reference
• Use webhooks to keep track of the payment lifecycle