# `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](/docs/guides/merchant/accept-payments/online-payments/card-payments/web/pop-up)
:::

:::info
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

```typescript
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`](#popupoptions-interface) | 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`       | Provide or pre-fill customer's billing address for card payments                                                                   | [`Address`](/docs/sdks/merchant-web-sdk/types/address) | Yes\*    |
| `shippingAddress`      | Pre-fill customer's shipping address (displayed in Merchant Dashboard only)                                                        | [`Address`](/docs/sdks/merchant-web-sdk/types/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`](/docs/sdks/merchant-web-sdk/types/revolut-checkout-error) | `(error: RevolutCheckoutError) => void`                | No       |
| `onCancel`             | Callback triggered when user cancels or closes the pop-up                                                                          | `() => void`                                           | No       |

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

## Return value

```typescript
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.

:::warning
Widget callbacks are not guaranteed to fire due to network issues, browser closures, or ad-blockers. Always use [webhooks](/docs/guides/merchant/monitor-and-observe/webhooks/using-webhooks) for critical backend operations like order fulfilment.
:::

### `onSuccess`

```typescript
() => 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:**

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

### `onError`

```typescript
(error: RevolutCheckoutError) => void
```

Triggered when the payment fails. The `error` parameter is a [`RevolutCheckoutError`](/docs/sdks/merchant-web-sdk/types/revolut-checkout-error) object containing error details.

**Use cases:**

- Display error message to the customer
- Log error for debugging
- Re-enable checkout form

**Example:**

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

### `onCancel`

```typescript
() => 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:**

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

## Usage examples

- ![With async/await]

  ```typescript
  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.')
    },
  })
  ```

- ![Without async/await]

  ```typescript
  import RevolutCheckout from '@revolut/checkout'

  // Initialise with order token
  RevolutCheckout(orderToken, 'prod').then((instance) => {
    // 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:

```typescript
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)

```typescript
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

- [Accept card payments via card pop-up - Web](/docs/guides/merchant/accept-payments/online-payments/card-payments/web/pop-up)
- [Token-based initialisation](/docs/sdks/merchant-web-sdk/initialisation/token-based)
- [Address type reference](/docs/sdks/merchant-web-sdk/types/address)
- [RevolutCheckoutError type reference](/docs/sdks/merchant-web-sdk/types/revolut-checkout-error)
- [Use webhooks to keep track of the payment lifecycle](/docs/guides/merchant/monitor-and-observe/webhooks/using-webhooks)