# MONEI JS Reference

This reference documents every object and method available in MONEI's browser-side JavaScript library, monei.js.

You can use monei.js' APIs to integrate prebuilt Components for different payment methods into your own checkout flows across desktop and mobile.

## Including monei.js[​](#including-moneijs "Direct link to Including monei.js")

Include the **monei.js** script on the checkout page of your site — it should always be loaded directly from `https://js.monei.com`, rather than included in a bundle or hosted yourself.

```
<script src="https://js.monei.com/v3/monei.js"></script>
```

### Using monei.js as a module[​](#using-moneijs-as-a-module "Direct link to Using monei.js as a module")

We also provide an npm package that makes it easier to load and use monei.js as a module.

```
npm i @monei-js/components
```

## `monei` object[​](#monei-object "Direct link to monei-object")

The monei object is your entrypoint to the rest of the monei.js SDK.

## Component instance API[​](#component-instance-api "Direct link to Component instance API")

Every MONEI Component (`CardInput`, `PayPal`, `Bizum`, `PaymentRequest`) returns a component instance with the following methods:

### `render(container)`[​](#rendercontainer "Direct link to rendercontainer")

Mounts the component into the DOM. Accepts a CSS selector string or an `HTMLElement`.

```
const cardInput = monei.CardInput({paymentId: '...', ...options});



// Using a CSS selector

cardInput.render('#card_input_container');



// Using an HTMLElement

cardInput.render(document.getElementById('card_input_container'));
```

### `submit(options?)`[​](#submitoptions "Direct link to submitoptions")

Tokenizes the current card data and returns a [`SubmitResult`](#submitresult). Available on `CardInput` instances only.

```
declare const submit: (options?: {cardholderName?: string}) => Promise<SubmitResult>;
```

Example:

```
const result = await cardInput.submit({cardholderName: 'Jane Doe'});

if (result.error) {

  // Show validation error to user

} else {

  // result.paymentMethod === 'card'

  await monei.confirmPayment({paymentId: '...', paymentToken: result.token});

}
```

### `updateProps(newProps)`[​](#updatepropsnewprops "Direct link to updatepropsnewprops")

Updates component props after render. Useful for reactive prop changes in vanilla JS. Returns a `Promise` that resolves when the update is delivered to the component.

```
// Update language dynamically

await cardInput.updateProps({language: 'es'});



// Update style

await cardInput.updateProps({

  style: {

    input: {fontSize: '18px'}

  }

});
```

note

When using framework packages ([React](https://docs.monei.com/monei-js/react/.md), [Vue](https://docs.monei.com/monei-js/vue/.md), [Angular](https://docs.monei.com/monei-js/angular/.md), [Svelte](https://docs.monei.com/monei-js/svelte/.md)), prop updates are handled automatically — you don't need to call `updateProps()` manually.

### `destroy()`[​](#destroy "Direct link to destroy")

Removes the component from the DOM and cleans up all internal resources (event listeners, iframe connections). After calling `destroy()`, the instance cannot be reused.

```
cardInput.destroy();
```

### `close()`[​](#close "Direct link to close")

Alias for [`destroy()`](#destroy). Removes the component and cleans up resources.

## Framework integration[​](#framework-integration "Direct link to Framework integration")

MONEI Components are available as native components for popular frameworks. Each framework package handles mounting, prop syncing, and cleanup automatically.

| Package                        | Framework | Guide                                                             |
| ------------------------------ | --------- | ----------------------------------------------------------------- |
| `@monei-js/react-components`   | React     | [React Components](https://docs.monei.com/monei-js/react/.md)     |
| `@monei-js/vue-components`     | Vue 3     | [Vue Components](https://docs.monei.com/monei-js/vue/.md)         |
| `@monei-js/angular-components` | Angular   | [Angular Components](https://docs.monei.com/monei-js/angular/.md) |
| `@monei-js/svelte-components`  | Svelte 5  | [Svelte Components](https://docs.monei.com/monei-js/svelte/.md)   |

tip

The legacy `.driver()` API is deprecated. See the [Migration Guide](https://docs.monei.com/monei-js/migration/.md) for upgrade instructions.

## `CardInput` Component[​](#cardinput-component "Direct link to cardinput-component")

CardInput is a customizable Component used to collect sensitive card information in your payment forms.

### Create an instance of the CardInput Component.[​](#create-an-instance-of-the-cardinput-component "Direct link to Create an instance of the CardInput Component.")

```
const cardInput = monei.CardInput({

  paymentId: 'af6029f80f5fc73a8ad2753eea0b1be0',

  ...otherOptions

});



// render Component on the page

cardInput.render('#card_input_container');
```

### CardInput options[​](#cardinput-options "Direct link to CardInput options")

| Prop            | Type                                                               | Required | Description                                                                                                                                                                                                                                                                                                           |
| --------------- | ------------------------------------------------------------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `paymentId`     | string                                                             | Yes\*    | Payment ID from [create payment](https://docs.monei.com/apis/rest/payments-create/.md). Generated token will be bound to this payment.                                                                                                                                                                                |
| `accountId`     | string                                                             | Yes\*    | Your MONEI account ID. Use with `sessionId` instead of `paymentId` to generate a token before creating the payment.                                                                                                                                                                                                   |
| `sessionId`     | string                                                             | Cond.    | Unique session ID in your system. Provide a different `sessionId` for each customer to ensure the token-generating customer matches the paying customer. Required with `accountId` if passing a token to your server. Must match the value in [create payment](https://docs.monei.com/apis/rest/schemas/payment/.md). |
| `orderId`       | string                                                             | No       | Alias for `sessionId` — normalizes to `sessionId` internally.                                                                                                                                                                                                                                                         |
| `language`      | string                                                             | No       | [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) language code. Supported: `en`, `es`, `ca`, `pt`, `de`, `it`, `fr`, `nl`, `et`, `fi`, `lv`, `no`, `pl`, `ru`. Auto-detected by default based on geolocation and browser preferences.                                                               |
| `style`         | [CardInputStyle](#cardinput-style-object)                          | No       | Customize appearance using CSS properties. See [Style object](#cardinput-style-object) below.                                                                                                                                                                                                                         |
| `fonts`         | [FontConfig](#custom-fonts)\[]                                     | No       | Load custom web fonts inside the iframe so a `style.base.fontFamily` reference actually renders. See [Custom fonts](#custom-fonts) below.                                                                                                                                                                             |
| `placeholders`  | object                                                             | No       | Custom input placeholders. See [Placeholders](#cardinput-placeholders) below.                                                                                                                                                                                                                                         |
| `errorMessages` | object                                                             | No       | Custom error messages. See [Error messages](#cardinput-error-messages) below.                                                                                                                                                                                                                                         |
| `onFocus`       | () => void                                                         | No       | Called when card input is focused.                                                                                                                                                                                                                                                                                    |
| `onBlur`        | () => void                                                         | No       | Called when card input is blurred.                                                                                                                                                                                                                                                                                    |
| `onLoad`        | () => void                                                         | No       | Called when card input is fully loaded.                                                                                                                                                                                                                                                                               |
| `onEnter`       | () => void                                                         | No       | Called when user presses **Enter** inside card input.                                                                                                                                                                                                                                                                 |
| `onChange`      | (event: [CardInputOnChangeEvent](#cardinputonchangeevent)) => void | No       | Called on every user input. Used for real-time validation.                                                                                                                                                                                                                                                            |
| `onError`       | (error: Error) => void                                             | No       | Called when there is an error.                                                                                                                                                                                                                                                                                        |

\* Either `paymentId` or `accountId` is required. **Cond.** = required when using `accountId`.

#### CardInput placeholders[​](#cardinput-placeholders "Direct link to CardInput placeholders")

| Prop         | Type   | Default       |
| ------------ | ------ | ------------- |
| `cardNumber` | string | "Card number" |
| `expiryDate` | string | "MM/YY"       |
| `cvc`        | string | "CVC"         |

#### CardInput error messages[​](#cardinput-error-messages "Direct link to CardInput error messages")

| Prop                | Type   | Default                                  |
| ------------------- | ------ | ---------------------------------------- |
| `emptyCardNumber`   | string | "Enter a card number"                    |
| `invalidCardNumber` | string | "Card number is invalid"                 |
| `emptyExpiryDate`   | string | "Enter an expiry date"                   |
| `monthOutOfRange`   | string | "Expiry month must be between 01 and 12" |
| `yearOutOfRange`    | string | "Expiry year cannot be in the past"      |
| `dateOutOfRange`    | string | "Expiry date cannot be in the past"      |
| `invalidExpiryDate` | string | "Expiry date is invalid"                 |
| `invalidCardType`   | string | "Card type is not supported"             |
| `emptyCVC`          | string | "Enter a CVC"                            |
| `invalidCVC`        | string | "CVC is invalid"                         |

#### `CardInputOnChangeEvent`[​](#cardinputonchangeevent "Direct link to cardinputonchangeevent")

| Property      | Type    | Description                                         |
| ------------- | ------- | --------------------------------------------------- |
| `isTouched`   | boolean | Whether the card input has been touched.            |
| `isSubmitted` | boolean | Whether the form has been submitted.                |
| `cardType`    | string? | Detected card type (e.g. `visa`, `mastercard`).     |
| `error`       | string? | Validation error message. Display this to the user. |

### CardInput Style object[​](#cardinput-style-object "Direct link to CardInput Style object")

components are styled using a Style object. It consists of CSS properties nested under objects for any of the following variants:

* **base** `object` - base Component style
* **loading** `object` - base Component style when Component is loading
* **invalid** `object` - applied when the Component has invalid input
* **input** `object` - applied to individual inputs
* **cardNumber** `object` - applied to card number input
* **expiryDate** `object` - applied to expiry date input
* **cvc** `object` - applied to cvc input
* **icon** `object` - applied to icon

The following pseudo-classes and pseudo-elements can also be styled using a nested object inside of a variant:

* `:focus`
* `:hover`
* `::placeholder`
* `::selection`
* `:-webkit-autofill`

```
const style = {

  base: {

    height: '45px',

    lineHeight: '45px',

    padding: '8px 12px',

    fontSize: '16px'

  },

  invalid: {

    color: '#dc2727'

  }

};



const cardInput = monei.CardInput({

  paymentId: 'af6029f80f5fc73a8ad2753eea0b1be0',

  style: style,

  ...otherOptions

});



// render Component on the page

cardInput.render('#card_input_container');
```

## Card Part Components[​](#card-part-components "Direct link to Card Part Components")

Mount the card number, expiry date and CVC as three independent Components, each in its own secure iframe, placed anywhere in your checkout markup. Use them instead of [`CardInput`](#cardinput-component) when you need full control over the layout — your own grid, your own labels, your own spacing. Card data never touches your page: it stays inside MONEI-hosted iframes, so your PCI DSS scope is the same as with `CardInput` (SAQ A).

A [`CardGroup`](#cardgroup) coordinates the parts and performs tokenization:

```
const cardGroup = monei.CardGroup({

  paymentId: 'af6029f80f5fc73a8ad2753eea0b1be0',

  onChange: (event) => {

    // event.complete is true when all mounted parts are valid

    payButton.disabled = !event.complete;

  }

});



monei.CardNumber({group: cardGroup}).render('#card-number');

monei.CardExpiry({group: cardGroup}).render('#card-expiry');

monei.CardCvc({group: cardGroup}).render('#card-cvc');



payButton.addEventListener('click', async () => {

  const {token, error} = await cardGroup.submit();

  if (error) {

    // the offending part is already highlighted; show the message

    errorEl.textContent = error;

    return;

  }

  const result = await monei.confirmPayment({paymentId, paymentToken: token});

});
```

<!-- -->

Focus moves automatically from number to expiry to CVC as the customer completes each field, and `Backspace` on an empty field walks back — the same behavior as `CardInput`. Browser card autofill fills all three parts from a single selection.

### `CardGroup`[​](#cardgroup "Direct link to cardgroup")

Holds the payment identifiers and exposes `submit()`. Payment identifiers belong on the group **only** — the part Components accept presentation props exclusively and reject `paymentId`/`accountId`.

Never call `render()` on a group: it renders automatically (a hidden coordination frame) when the first part renders.

#### CardGroup options[​](#cardgroup-options "Direct link to CardGroup options")

| Prop              | Type                                                 | Required | Description                                                                                                                                                                                      |
| ----------------- | ---------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `paymentId`       | string                                               | Yes\*    | Payment ID from [create payment](https://docs.monei.com/apis/rest/payments-create/.md). Generated token will be bound to this payment.                                                           |
| `accountId`       | string                                               | Yes\*    | Your MONEI account ID. Requires `amount` and `currency`.                                                                                                                                         |
| `sessionId`       | string                                               | Cond.    | Unique session ID in your system. Same semantics as [`CardInput`](#cardinput-options).                                                                                                           |
| `amount`          | number                                               | Cond.    | Payment amount in the smallest currency unit. Required with `accountId`.                                                                                                                         |
| `currency`        | string                                               | Cond.    | Three-letter [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code. Required with `accountId`.                                                                                        |
| `transactionType` | 'SALE' \| 'AUTH'                                     | No       | Controls when funds are captured. `SALE` (default): capture immediately. `AUTH`: authorize only, capture later.                                                                                  |
| `language`        | string                                               | No       | Default language for every part. A part-level `language` overrides it.                                                                                                                           |
| `style`           | [CardInputStyle](#cardinput-style-object)            | No       | Default style for every part (the `input`, `cardNumber`, `expiryDate`, `cvc` and `invalid` variants apply). A part-level `style` overrides it.                                                   |
| `fonts`           | [FontConfig](#custom-fonts)\[]                       | No       | Custom web fonts, loaded in every part iframe.                                                                                                                                                   |
| `placeholders`    | object                                               | No       | Default placeholders for every part. See [CardInput placeholders](#cardinput-placeholders).                                                                                                      |
| `errorMessages`   | object                                               | No       | Custom error messages. See [CardInput error messages](#cardinput-error-messages).                                                                                                                |
| `autoAdvance`     | boolean                                              | No       | Automatic focus advance between parts. Default: on — except on iOS, where a cross-iframe focus change does not bring up the keyboard. Pass `true` to force it on, `false` to disable everywhere. |
| `onChange`        | (event: {complete: boolean; error?: string}) => void | No       | Aggregate state across the mounted parts. `complete` drives your pay button.                                                                                                                     |
| `onError`         | (error: Error) => void                               | No       | Called when there is an error.                                                                                                                                                                   |

\* Either `paymentId` or `accountId` (with `amount` and `currency`) is required.

#### `submit(options?)`[​](#cardgroup-submit "Direct link to cardgroup-submit")

Collects the three fields inside MONEI's iframes, validates them, and creates a payment token. Returns the same result shape as [`CardInput.submit()`](#submitoptions): `{token?, error?, paymentMethod: 'card'}`. On a validation error the offending part marks itself invalid — you only need to display the returned `error` message.

All three parts must be mounted; `submit()` fails fast with a descriptive error otherwise.

#### `updateProps(newProps)` / `destroy()`[​](#cardgroup-lifecycle "Direct link to cardgroup-lifecycle")

`updateProps` accepts any [CardGroup option](#cardgroup-options); presentation changes propagate to every mounted part. `destroy()` tears down the coordination frame — destroy the parts first.

### `CardNumber`, `CardExpiry`, `CardCvc`[​](#card-parts "Direct link to card-parts")

Each part renders exactly one input that fills its mount container. The part draws no border, background or shadow — **you own the box** and style it in your own CSS, with the [state classes](#card-part-state-classes) below as hooks.

#### Card part options[​](#card-part-options "Direct link to Card part options")

| Prop            | Type                                                         | Required | Description                                                                        |
| --------------- | ------------------------------------------------------------ | -------- | ---------------------------------------------------------------------------------- |
| `group`         | CardGroup                                                    | Yes      | The [`CardGroup`](#cardgroup) this part belongs to. Cannot be changed after mount. |
| `language`      | string                                                       | No       | Overrides the group default for this part.                                         |
| `style`         | [CardInputStyle](#cardinput-style-object)                    | No       | Overrides the group default for this part.                                         |
| `placeholder`   | string                                                       | No       | Placeholder for this part's input.                                                 |
| `errorMessages` | object                                                       | No       | Overrides the group default for this part.                                         |
| `fonts`         | [FontConfig](#custom-fonts)\[]                               | No       | Overrides the group default for this part.                                         |
| `onChange`      | (event: [CardPartChangeEvent](#cardpartchangeevent)) => void | No       | Called on every input and validation change.                                       |
| `onFocus`       | () => void                                                   | No       | Called when the part's input gains focus.                                          |
| `onBlur`        | () => void                                                   | No       | Called when the part's input loses focus.                                          |
| `onEnter`       | () => void                                                   | No       | Called when the user presses **Enter** inside the part.                            |
| `onLoad`        | () => void                                                   | No       | Called when the part is mounted and interactive.                                   |
| `onError`       | (error: Error) => void                                       | No       | Called when there is an error.                                                     |

#### `CardPartChangeEvent`[​](#cardpartchangeevent "Direct link to cardpartchangeevent")

| Property   | Type    | Description                                                                                    |
| ---------- | ------- | ---------------------------------------------------------------------------------------------- |
| `empty`    | boolean | Whether the field is empty.                                                                    |
| `complete` | boolean | Whether the field holds a complete, valid value.                                               |
| `error`    | string? | Validation error, present after the customer leaves an invalid field or after a failed submit. |
| `brand`    | string? | `CardNumber` only: the detected card brand (e.g. `visa`, `mastercard`, `amex`).                |

The event never contains card data — field values stay inside the MONEI iframes.

#### Part instance methods[​](#card-part-methods "Direct link to Part instance methods")

Each mounted part exposes `focus()`, `blur()` and `clear()`. Because the input lives inside an iframe, an HTML `<label for>` cannot focus it — wire your labels through `focus()` instead:

```
document.querySelector('label[data-for="card-number"]').addEventListener('click', () => {

  cardNumber.focus();

});
```

#### State classes[​](#card-part-state-classes "Direct link to State classes")

Each part toggles these classes on **your mount container**, so your CSS can style the box by state (the equivalent of styling a native input's states):

| Class                       | When                                                     |
| --------------------------- | -------------------------------------------------------- |
| `monei-component--focus`    | The part's input has focus.                              |
| `monei-component--invalid`  | The field has a validation error (blurred or submitted). |
| `monei-component--empty`    | The field is empty.                                      |
| `monei-component--complete` | The field holds a complete, valid value.                 |

```
.card-box {

  border: 1px solid #e0e0e0;

  border-radius: 4px;

}

.card-box.monei-component--focus {

  border-color: #3297d3;

}

.card-box.monei-component--invalid {

  border-color: #dc2727;

}
```

#### Autofill and keyboard behavior[​](#card-part-behavior "Direct link to Autofill and keyboard behavior")

* **Browser autofill** fills all three parts from one saved-card selection in Chromium-based browsers. Behavior in other browsers may vary — always keep manual entry usable.
* **Tab order** follows your DOM order; each part is exactly one tab stop. Mount the parts in number → expiry → CVC order for the natural flow.
* On **iOS**, automatic focus advance is off by default: a programmatic focus change across iframes does not raise the on-screen keyboard.

## `createToken` function[​](#createtoken-function "Direct link to createtoken-function")

Deprecated

`createToken()` is deprecated. Use [`instance.submit()`](#submitoptions) instead, which is available directly on the CardInput instance:

```
const {token, error} = await cardInput.submit();
```

See the [Migration Guide](https://docs.monei.com/monei-js/migration/.md) for details.

Use this function to generate payment token.

note

Payment tokens generated by monei.js Components expire as soon as they are used or 5 days after creation.

Pass an instance of CardInput Component.

```
declare const createToken: (Component: MoneiComponent) => Promise<SubmitResult>;
```

Example:

```
monei

  .createToken(cardInput) // pass a reference to an instance of your CardInput Component

  .then(function (result) {

    console.log(result);

    if (result.error) {

      // Inform the user if there was an error.

    } else {

      // Confirm payment using the token.

      moneiTokenHandler(result.token);

    }

  })

  .catch(function (error) {

    // Something went wrong while generating token

    console.log(error);

  });
```

## `PayPal` Component[​](#paypal-component "Direct link to paypal-component")

PayPal is a customizable Component that renders a PayPal payment button.

### Create an instance of the PayPal Component.[​](#create-an-instance-of-the-paypal-component "Direct link to Create an instance of the PayPal Component.")

```
const paypal = monei.PayPal({

  paymentId: 'af6029f80f5fc73a8ad2753eea0b1be0',

  onSubmit(result) {

    if (result.error) {

      // Inform the user if there was an error.

    } else {

      // result.paymentMethod === 'paypal'

      // Confirm payment using the token.

      moneiTokenHandler(result.token);

    }

  },

  onError(error) {

    console.log(error);

  },

  ...otherOptions

});



// render Component on the page

paypal.render('#paypal_container');
```

### PayPal options[​](#paypal-options "Direct link to PayPal options")

| Prop                      | Type                                                                                                              | Required | Description                                                                                                                                                                                                                                                                         |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `paymentId`               | string                                                                                                            | Yes\*    | Payment ID from [create payment](https://docs.monei.com/apis/rest/payments-create/.md). Generated token will be bound to this payment.                                                                                                                                              |
| `accountId`               | string                                                                                                            | Yes\*    | Your MONEI account ID. Use with `sessionId` instead of `paymentId` to generate a token before creating the payment.                                                                                                                                                                 |
| `sessionId`               | string                                                                                                            | Cond.    | Unique session ID in your system. Provide a different `sessionId` for each customer to ensure the token-generating customer matches the paying customer. Required with `accountId`. Must match the value in [create payment](https://docs.monei.com/apis/rest/schemas/payment/.md). |
| `amount`                  | number                                                                                                            | Cond.    | Amount in the smallest currency unit (e.g., 100 = 1.00 USD). Required with `accountId`.                                                                                                                                                                                             |
| `currency`                | string                                                                                                            | Cond.    | Three-letter [ISO currency code](https://en.wikipedia.org/wiki/ISO_4217), in uppercase. Required with `accountId`.                                                                                                                                                                  |
| `transactionType`         | 'SALE' \| 'AUTH'                                                                                                  | No       | Controls when funds are captured. `SALE` (default): capture immediately. `AUTH`: authorize only, capture later.                                                                                                                                                                     |
| `language`                | string                                                                                                            | No       | Language for the PayPal button. Auto-detected by default. [Supported languages](https://developer.paypal.com/docs/checkout/reference/customize-sdk/#locale).                                                                                                                        |
| `cspNonce`                | string                                                                                                            | No       | Nonce value for Content Security Policy. Pass this if your page uses a CSP `script-src` nonce.                                                                                                                                                                                      |
| `borderRadius`            | number \| string                                                                                                  | No       | Custom border radius for the PayPal button container.                                                                                                                                                                                                                               |
| `requestShipping`         | boolean                                                                                                           | No       | Enable shipping address collection in the PayPal checkout. Requires `accountId` flow (incompatible with `paymentId`). See [Express Checkout](https://docs.monei.com/integrations/express-checkout/.md).                                                                             |
| `shippingOptions`         | [ShippingOption](#shippingoption)\[]                                                                              | No       | Available shipping options displayed in the PayPal checkout. Requires `requestShipping: true`.                                                                                                                                                                                      |
| `onShippingAddressChange` | (address: [Address](#address)) => Promise<[ShippingAddressChangeResult](#shippingaddresschangeresult)>            | No       | Called when the customer changes their shipping address in the PayPal checkout. Return updated shipping options and/or amount.                                                                                                                                                      |
| `onShippingOptionChange`  | (option: [ShippingOption](#shippingoption)) => Promise<[ShippingOptionChangeResult](#shippingoptionchangeresult)> | No       | Called when the customer selects a different shipping option. Return updated amount.                                                                                                                                                                                                |
| `onSubmit`                | (result: [SubmitResult](#submitresult)) => void                                                                   | Yes      | Called when the customer approves the payment. Returns a [`SubmitResult`](#submitresult) with `paymentMethod: 'paypal'`.                                                                                                                                                            |
| `onBeforeOpen`            | () => boolean                                                                                                     | No       | Called before the PayPal window is opened. Return `false` to prevent the window from opening.                                                                                                                                                                                       |
| `onLoad`                  | (isSupported: boolean) => void                                                                                    | No       | Called when PayPal is fully loaded. If PayPal is not supported, the component will not render and `onLoad` fires with `false`.                                                                                                                                                      |
| `onError`                 | (error: Error) => void                                                                                            | No       | Called when there is an error.                                                                                                                                                                                                                                                      |
| `style`                   | object                                                                                                            | No       | Customize the button appearance. See style properties below.                                                                                                                                                                                                                        |

\* Either `paymentId` or `accountId` is required. **Cond.** = required when using `accountId`.

note

PayPal always returns payer information (name, email) regardless of configuration — there is no separate `requestBilling` prop for PayPal. Billing details are always included in the [`SubmitResult`](#submitresult).

#### PayPal style[​](#paypal-style "Direct link to PayPal style")

| Prop           | Type                                                                     | Default | Description                                        |
| -------------- | ------------------------------------------------------------------------ | ------- | -------------------------------------------------- |
| `height`       | number \| string                                                         | —       | Button height in pixels. Values from `25` to `55`. |
| `color`        | 'gold' \| 'blue' \| 'silver' \| 'white' \| 'black'                       | —       | Button color theme.                                |
| `shape`        | 'pill' \| 'rect'                                                         | —       | Button shape.                                      |
| `layout`       | 'horizontal' \| 'vertical'                                               | —       | Button layout when multiple buttons are available. |
| `label`        | 'checkout' \| 'credit' \| 'pay' \| 'buynow' \| 'paypal' \| 'installment' | —       | Button label text.                                 |
| `size`         | 'small' \| 'medium' \| 'large' \| 'responsive'                           | —       | Button size preset.                                |
| `borderRadius` | number \| string                                                         | —       | Custom border radius for the button.               |

## `PaymentRequest` Component[​](#paymentrequest-component "Direct link to paymentrequest-component")

PaymentRequest is a customizable Component that renders a Google Pay or Apple Pay payment button depending on the browser and operating system of the user. PaymentRequest replaces the deprecated `GooglePay` component — it automatically shows Google Pay, Apple Pay, or Click to Pay based on device support.

note

Apple Pay requires [domain verification](https://docs.monei.com/payment-methods/apple-pay/.md#register-your-domain-with-apple-pay) in both development and production.

### Create an instance of the PaymentRequest Component.[​](#create-an-instance-of-the-paymentrequest-component "Direct link to Create an instance of the PaymentRequest Component.")

```
const paymentRequest = monei.PaymentRequest({

  paymentId: 'af6029f80f5fc73a8ad2753eea0b1be0',

  onSubmit(result) {

    if (result.error) {

      // Inform the user if there was an error.

    } else {

      // result.paymentMethod === 'applePay' or 'googlePay'

      // Confirm payment using the token.

      moneiTokenHandler(result.token);

    }

  },

  onError(error) {

    console.log(error);

  },

  ...otherOptions

});



// render Component on the page

paymentRequest.render('#payment_request');
```

### PaymentRequest options[​](#paymentrequest-options "Direct link to PaymentRequest options")

| Prop                      | Type                                                                                                              | Required | Description                                                                                                                                                                                                                                                                         |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `paymentId`               | string                                                                                                            | Yes\*    | Payment ID from [create payment](https://docs.monei.com/apis/rest/payments-create/.md). Generated token will be bound to this payment.                                                                                                                                              |
| `accountId`               | string                                                                                                            | Yes\*    | Your MONEI account ID. Use with `sessionId` instead of `paymentId` to generate a token before creating the payment.                                                                                                                                                                 |
| `sessionId`               | string                                                                                                            | Cond.    | Unique session ID in your system. Provide a different `sessionId` for each customer to ensure the token-generating customer matches the paying customer. Required with `accountId`. Must match the value in [create payment](https://docs.monei.com/apis/rest/schemas/payment/.md). |
| `amount`                  | number                                                                                                            | Cond.    | Amount in the smallest currency unit (e.g., 100 = 1.00 USD). Required with `accountId`.                                                                                                                                                                                             |
| `currency`                | string                                                                                                            | Cond.    | Three-letter [ISO currency code](https://en.wikipedia.org/wiki/ISO_4217), in uppercase. Required with `accountId`.                                                                                                                                                                  |
| `language`                | string                                                                                                            | No       | [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) language code. Supported: `en`, `es`, `ca`, `pt`, `de`, `it`, `fr`, `nl`, `et`, `fi`, `lv`, `no`, `pl`, `ru`. Auto-detected by default.                                                                          |
| `requestShipping`         | boolean                                                                                                           | No       | Enable shipping address collection in the Apple Pay / Google Pay wallet UI. Requires `accountId` flow (incompatible with `paymentId`). See [Express Checkout](https://docs.monei.com/integrations/express-checkout/.md).                                                            |
| `requestBilling`          | boolean                                                                                                           | No       | Enable billing address collection. Works with both `accountId` and `paymentId` flows.                                                                                                                                                                                               |
| `shippingOptions`         | [ShippingOption](#shippingoption)\[]                                                                              | No       | Available shipping options displayed in the wallet UI. Requires `requestShipping: true`.                                                                                                                                                                                            |
| `onShippingAddressChange` | (address: [Address](#address)) => Promise<[ShippingAddressChangeResult](#shippingaddresschangeresult)>            | No       | Called when the customer changes their shipping address in the wallet UI. Return updated shipping options and/or amount. The address is redacted mid-flow (no street-level data — only country, city, state, zip).                                                                  |
| `onShippingOptionChange`  | (option: [ShippingOption](#shippingoption)) => Promise<[ShippingOptionChangeResult](#shippingoptionchangeresult)> | No       | Called when the customer selects a different shipping option. Return updated amount.                                                                                                                                                                                                |
| `onSubmit`                | (result: [SubmitResult](#submitresult)) => void                                                                   | Yes      | Called when the customer approves the payment. Returns a [`SubmitResult`](#submitresult) with `paymentMethod: 'applePay'` or `'googlePay'`.                                                                                                                                         |
| `onBeforeSubmit`          | () => void                                                                                                        | No       | Called before payment is submitted. Use for validation or analytics.                                                                                                                                                                                                                |
| `onBeforeOpen`            | () => boolean                                                                                                     | No       | Called before the payment window is opened. Return `false` to prevent the window from opening.                                                                                                                                                                                      |
| `onLoad`                  | (isSupported: boolean) => void                                                                                    | No       | Called when the component is fully loaded. If the payment method is not supported, the component will not render and `onLoad` fires with `false`.                                                                                                                                   |
| `onError`                 | (error: Error) => void                                                                                            | No       | Called when there is an error.                                                                                                                                                                                                                                                      |
| `style`                   | object                                                                                                            | No       | Customize the button appearance. See style properties below.                                                                                                                                                                                                                        |

\* Either `paymentId` or `accountId` is required. **Cond.** = required when using `accountId`.

#### PaymentRequest style[​](#paymentrequest-style "Direct link to PaymentRequest style")

| Prop           | Type                            | Default   | Description                                                                                                                                   |
| -------------- | ------------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `height`       | string \| number                | —         | Button height in pixels. Values from `25` to `55`.                                                                                            |
| `color`        | 'default' \| 'black' \| 'white' | 'default' | Button color theme.                                                                                                                           |
| `type`         | 'buy' \| 'plain' \| 'donate'    | 'plain'   | Button label: `'buy'` = "Buy with Google Pay / Apple Pay", `'donate'` = "Donate with Google Pay / Apple Pay", `'plain'` = no additional text. |
| `borderRadius` | number \| string                | —         | Custom border radius for the button.                                                                                                          |
| `fontFamily`   | string                          | —         | Custom font family for the button text.                                                                                                       |

## `Bizum` Component[​](#bizum-component "Direct link to bizum-component")

Bizum is a customizable Component that renders a Bizum payment button.

### Create an instance of the Bizum Component.[​](#create-an-instance-of-the-bizum-component "Direct link to Create an instance of the Bizum Component.")

```
const bizum = monei.Bizum({

  paymentId: 'af6029f80f5fc73a8ad2753eea0b1be0',

  onSubmit(result) {

    if (result.error) {

      // Inform the user if there was an error.

    } else {

      // result.paymentMethod === 'bizum'

      // Confirm payment using the token.

      moneiTokenHandler(result.token);

    }

  },

  onError(error) {

    console.log(error);

  },

  ...otherOptions

});



// render Component on the page

bizum.render('#bizum');
```

### Bizum options[​](#bizum-options "Direct link to Bizum options")

| Prop              | Type                                            | Required | Description                                                                                                                                                                                                                                                                         |
| ----------------- | ----------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `paymentId`       | string                                          | Yes\*    | Payment ID from [create payment](https://docs.monei.com/apis/rest/payments-create/.md). Generated token will be bound to this payment.                                                                                                                                              |
| `accountId`       | string                                          | Yes\*    | Your MONEI account ID. Use with `sessionId` instead of `paymentId` to generate a token before creating the payment.                                                                                                                                                                 |
| `sessionId`       | string                                          | Cond.    | Unique session ID in your system. Provide a different `sessionId` for each customer to ensure the token-generating customer matches the paying customer. Required with `accountId`. Must match the value in [create payment](https://docs.monei.com/apis/rest/schemas/payment/.md). |
| `phoneNumber`     | string                                          | No       | Pre-fill the customer's phone number for the Bizum payment flow.                                                                                                                                                                                                                    |
| `amount`          | number                                          | Cond.    | Amount in the smallest currency unit (e.g., 100 = 1.00 USD). Required with `accountId`.                                                                                                                                                                                             |
| `currency`        | string                                          | Cond.    | Three-letter [ISO currency code](https://en.wikipedia.org/wiki/ISO_4217), in uppercase. Required with `accountId`.                                                                                                                                                                  |
| `transactionType` | 'SALE' \| 'AUTH'                                | No       | Controls when funds are captured. `SALE` (default): capture immediately. `AUTH`: authorize only, capture later.                                                                                                                                                                     |
| `fullscreen`      | boolean                                         | No       | Set to `true` to open the Bizum payment window in fullscreen mode.                                                                                                                                                                                                                  |
| `language`        | string                                          | No       | [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) language code. Supported: `en`, `es`, `ca`, `pt`, `de`, `it`, `fr`, `nl`, `et`, `fi`, `lv`, `no`, `pl`, `ru`. Auto-detected by default.                                                                          |
| `onSubmit`        | (result: [SubmitResult](#submitresult)) => void | Yes      | Called when the customer approves the payment. Returns a [`SubmitResult`](#submitresult) with `paymentMethod: 'bizum'`.                                                                                                                                                             |
| `onBeforeOpen`    | () => boolean                                   | No       | Called before the Bizum window is opened. Return `false` to prevent the window from opening.                                                                                                                                                                                        |
| `onOpen`          | () => void                                      | No       | Called when the Bizum payment window is opened.                                                                                                                                                                                                                                     |
| `onLoad`          | (isSupported: boolean) => void                  | No       | Called when the component is fully loaded. If Bizum is not supported, the component will not render and `onLoad` fires with `false`.                                                                                                                                                |
| `onError`         | (error: Error) => void                          | No       | Called when there is an error.                                                                                                                                                                                                                                                      |
| `style`           | object                                          | No       | Customize the button appearance. See style properties below.                                                                                                                                                                                                                        |
| `fonts`           | [FontConfig](#custom-fonts)\[]                  | No       | Load custom web fonts so a `style.fontFamily` reference actually renders. See [Custom fonts](#custom-fonts).                                                                                                                                                                        |

\* Either `paymentId` or `accountId` is required. **Cond.** = required when using `accountId`.

#### Bizum style[​](#bizum-style "Direct link to Bizum style")

| Prop           | Type             | Default | Description                                                               |
| -------------- | ---------------- | ------- | ------------------------------------------------------------------------- |
| `height`       | string \| number | —       | Button height in pixels. Values from `25` to `55`.                        |
| `type`         | 'pay' \| 'plain' | 'plain' | Button label: `'pay'` = "Pay with Bizum", `'plain'` = no additional text. |
| `borderRadius` | number \| string | —       | Custom border radius for the button.                                      |
| `fontFamily`   | string           | —       | Custom font family for the button text.                                   |

## Custom fonts[​](#custom-fonts "Direct link to Custom fonts")

Mirrors Stripe Elements' `fonts` API. Use the `fonts` option to load merchant-chosen web fonts inside the component iframe so a `style.base.fontFamily` (or `style.fontFamily` for Bizum) reference actually paints in the requested font, not whatever the customer's device has installed.

### Supported components[​](#supported-components "Direct link to Supported components")

`fonts` is accepted by:

* [`CardInput`](#cardinput-component)
* [`Bizum`](#bizum-component)

`fonts` is **not** accepted by [`PayPal`](#paypal-component), [`PaymentRequest`](#paymentrequest-component), or `GooglePay` — wallet button glyphs are rendered by the wallet SDK in vendor-controlled DOM that ignores host CSS, so loading a custom font there would have no visible effect.

### `FontConfig`[​](#fontconfig "Direct link to fontconfig")

Each entry in the `fonts` array is one of:

```
type FontFace = {

  family: string; // e.g. 'Inter', 'Roboto Mono', 'Source Sans 3'

  src: string; // url(https://...) or url(data:font/woff2;base64,...)

  weight?: string | number; // 100..1000 or 'normal' | 'bold' | 'lighter' | 'bolder'

  style?: 'normal' | 'italic' | 'oblique';

  display?: 'auto' | 'block' | 'swap' | 'fallback' | 'optional';

  unicodeRange?: string; // e.g. 'U+0020-007F, U+30??'

};



type FontConfig = {cssSrc: string} | FontFace;
```

### Two forms[​](#two-forms "Direct link to Two forms")

**1. `cssSrc`** — link an external stylesheet that contains `@font-face` rules. Today this works only with **Google Fonts** (`fonts.googleapis.com`); other CDNs (Adobe Fonts, Bunny Fonts) are not in the default Content Security Policy allowlist.

```
const cardInput = monei.CardInput({

  paymentId: '...',

  style: {base: {fontFamily: 'Inter, sans-serif'}},

  fonts: [{cssSrc: 'https://fonts.googleapis.com/css2?family=Inter:wght@400;600;700&display=swap'}]

});
```

**2. Explicit `FontFace`** — provide all `@font-face` descriptors yourself. Works for **any HTTPS host** plus inlined `data:` URLs. Use this for self-hosted fonts.

```
const cardInput = monei.CardInput({

  paymentId: '...',

  style: {base: {fontFamily: 'Inter, sans-serif'}},

  fonts: [

    {

      family: 'Inter',

      src: 'url(https://your-cdn.example.com/fonts/inter-400.woff2)',

      weight: 400,

      display: 'swap'

    },

    {

      family: 'Inter',

      src: 'url(https://your-cdn.example.com/fonts/inter-700.woff2)',

      weight: 700,

      display: 'swap'

    }

  ]

});
```

### Multiple weights[​](#multiple-weights "Direct link to Multiple weights")

Pass one entry per `(family, weight, style)` combination. Same family with different weights produces multiple `@font-face` rules — the browser picks the matching weight when CSS requests bold or italic.

### Loading semantics[​](#loading-semantics "Direct link to Loading semantics")

* The component iframe injects a `<link>` (for `cssSrc`) or registers each `FontFace` (for explicit), then waits up to **3 seconds** for fonts to load before first paint. If a font CDN is slow or unreachable, the component renders with the next family in the stack — the page is never blocked indefinitely.
* Default `font-display` for explicit `FontFace` entries is `swap`. Override per entry if you need a different policy.
* Validation runs on every entry; malformed values (e.g. invalid `weight`, non-`https:`/non-`data:` `src`, suspicious characters in `family`) are silently dropped to prevent CSS injection.
* `CardInput` field widths automatically adapt to the merchant's font when fonts are loaded — placeholders are measured alongside typed-digit samples and the widest wins. Decorative or cursive fonts (e.g. Lobster) fit without clipping; sans-serif rendering is unchanged.

### Migration[​](#migration "Direct link to Migration")

Already passing `style.base.fontFamily` (or `style.fontFamily`) to a component? Behavior is unchanged — without a matching `fonts` entry, the customer's device renders whatever it has installed, same as today. To opt into deterministic rendering, pair the existing `fontFamily` with a `fonts` entry that loads it.

```
// Before — works only on devices that already have Inter

monei.CardInput({

  paymentId: '...',

  style: {base: {fontFamily: 'Inter, sans-serif'}}

});



// After — Inter loads via Google Fonts on every device

monei.CardInput({

  paymentId: '...',

  style: {base: {fontFamily: 'Inter, sans-serif'}},

  fonts: [{cssSrc: 'https://fonts.googleapis.com/css2?family=Inter:wght@400;600;700'}]

});
```

## `confirmPayment` function[​](#confirmpayment-function "Direct link to confirmpayment-function")

After you generate the **paymentToken** using one of the Components, use this function to confirm the payment passing the obtained `paymentToken`. It will automatically show a popup window with a 3D Secure confirmation screen if required.

When called without a `paymentToken`, `confirmPayment` opens the MONEI Payment Modal where the customer can select a payment method and complete the payment. See [Use Payment Modal](https://docs.monei.com/integrations/use-payment-modal/.md) for the full integration guide.

info

Not all payment methods are available in the Payment Modal. Apple Pay is not supported in the modal — use the [PaymentRequest](#paymentrequest-component) component instead.

You can provide additional customer information in parameters.

```
declare const confirmPayment: (params: ConfirmPaymentParams) => Promise<PaymentResult>;
```

### Confirm payment params[​](#confirm-payment-params "Direct link to Confirm payment params")

| Param                   | Type                                                                                  | Required | Description                                                                                                                                                                                              |
| ----------------------- | ------------------------------------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `paymentId`             | string                                                                                | Yes      | Payment ID from [create payment](https://docs.monei.com/apis/rest/payments-create/.md)                                                                                                                   |
| `paymentToken`          | string                                                                                | No       | Token generated by monei.js. If present the popup opens directly to 3D Secure confirmation (if needed)                                                                                                   |
| `generatePaymentToken`  | boolean                                                                               | No       | If `true`, generates a permanent token representing the payment method used                                                                                                                              |
| `fullscreen`            | boolean                                                                               | No       | If `true`, opens a fullscreen confirmation window                                                                                                                                                        |
| `language`              | string                                                                                | No       | Two-letter [ISO 639-1](https://en.wikipedia.org/wiki/ISO_639-1) language code. Supported: `en`, `es`, `ca`, `pt`, `de`, `it`, `fr`, `nl`, `et`, `fi`, `lv`, `no`, `pl`, `ru`. Overrides browser language |
| `paymentMethod`         | [PaymentMethod](#paymentmethod)                                                       | No       | Pre-fill payment method details (e.g. cardholder name/email)                                                                                                                                             |
| `allowedPaymentMethods` | string\[]                                                                             | No       | Restrict available payment methods. Supported: `card`, `googlePay`, `clickToPay`, `bizum`, `paypal`                                                                                                      |
| `customDomain`          | string                                                                                | No       | Custom domain for the payment popup. Required if you have a custom domain configured                                                                                                                     |
| `customer`              | [Customer](https://docs.monei.com/apis/rest/schemas/payment-customer/.md)             | No       | Customer information (name, email, phone)                                                                                                                                                                |
| `billingDetails`        | [BillingDetails](https://docs.monei.com/apis/rest/schemas/payment-billingdetails/.md) | No       | Billing address and contact details                                                                                                                                                                      |
| `shippingDetails`       | [BillingDetails](https://docs.monei.com/apis/rest/schemas/payment-billingdetails/.md) | No       | Shipping address and contact details (same shape as billingDetails)                                                                                                                                      |
| `style`                 | {width: string, height: string}                                                       | No       | Popup window dimensions (e.g. `"400px"`, `"100%"`)                                                                                                                                                       |

#### `PaymentMethod`[​](#paymentmethod "Direct link to paymentmethod")

| Field                  | Type   | Description                  |
| ---------------------- | ------ | ---------------------------- |
| `card.cardholderName`  | string | Cardholder name to pre-fill  |
| `card.cardholderEmail` | string | Cardholder email to pre-fill |

Check [confirm payment](https://docs.monei.com/apis/rest/payments-confirm/.md) for the full list of parameters.

tip

When using [express checkout](https://docs.monei.com/integrations/express-checkout/.md) with shipping (accountId flow), create the payment server-side passing `paymentToken`, `billingDetails`, and `shippingDetails` from the [`SubmitResult`](#submitresult). For billing-only checkout (paymentId flow), pass `billingDetails` to `confirmPayment`.

### Payment result[​](#payment-result "Direct link to Payment result")

| Prop                      | Type             | Description                                                                                                                                                            |
| ------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                      | string           | Unique identifier for the payment                                                                                                                                      |
| `status`                  | string           | The status of the payment                                                                                                                                              |
| `amount`                  | positive integer | Amount intended to be collected by this payment. A positive integer representing how much to charge in the smallest currency unit (e.g., 100 cents to charge 1.00 USD) |
| `currency`                | string           | Three-letter [ISO currency code](https://en.wikipedia.org/wiki/ISO_4217), in uppercase                                                                                 |
| `accountId`               | string           | MONEI account ID                                                                                                                                                       |
| `orderId`                 | string           | An order ID from your system. A unique identifier that can be used to reconcile the payment with your internal system                                                  |
| `statusCode`              | string           | Payment status code                                                                                                                                                    |
| `statusMessage`           | string           | Human readable status message, can be displayed to a user                                                                                                              |
| `nextAction`              | object           | If present, tells you what actions you need to take for your customer to fulfill a payment using the provided source                                                   |
| `nextAction.type`         | string           | The type of next action                                                                                                                                                |
| `nextAction.mustRedirect` | boolean          | Whether the customer must be redirected                                                                                                                                |
| `nextAction.redirectUrl`  | string           | URL to redirect the customer to                                                                                                                                        |

Check [payment object](https://docs.monei.com/apis/rest/schemas/payment/.md) for the full description of each field

Example:

```
monei

  .confirmPayment({

    paymentId: 'af6029f80f5fc73a8ad2753eea0b1be0',

    paymentToken: 'fe6786e08ded3191cf2f623e120a0bacda715bf2',

    ...otherOptions

  })

  .then(function (result) {

    // Payment result

    console.log(result);

  })

  .catch(function (error) {

    // Something went wrong while confirming payment

    console.log(error);

  });
```

## Type Reference[​](#type-reference "Direct link to Type Reference")

### `SubmitResult`[​](#submitresult "Direct link to submitresult")

Returned by all component `onSubmit` callbacks and `CardInput.submit()`.

| Property          | Type                                    | Description                                                                                                                                |
| ----------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `token`           | string                                  | Payment token. Use with `confirmPayment` or pass to your server.                                                                           |
| `error`           | string                                  | Validation error message. Present instead of `token` when tokenization fails.                                                              |
| `paymentMethod`   | [PaymentMethodType](#paymentmethodtype) | Which payment method was used: `'card'`, `'applePay'`, `'googlePay'`, `'paypal'`, or `'bizum'`.                                            |
| `finalAmount`     | number                                  | Wallet-authorized total in minor units. May differ from initial `amount` if shipping changed the total. Only present for express checkout. |
| `billingDetails`  | [BillingDetails](#billingdetails)       | Billing address and contact info collected by the wallet. Only present when `requestBilling` is true (or always for PayPal).               |
| `shippingDetails` | [BillingDetails](#billingdetails)       | Shipping address and contact info collected by the wallet. Only present when `requestShipping` is true.                                    |
| `shippingOption`  | [ShippingOption](#shippingoption)       | The shipping option selected by the customer. Only present when `requestShipping` is true.                                                 |

### `PaymentMethodType`[​](#paymentmethodtype "Direct link to paymentmethodtype")

```
type PaymentMethodType = 'card' | 'applePay' | 'googlePay' | 'paypal' | 'bizum';
```

### `ShippingOption`[​](#shippingoption "Direct link to shippingoption")

| Property      | Type                   | Required | Description                                                |
| ------------- | ---------------------- | -------- | ---------------------------------------------------------- |
| `id`          | string                 | Yes      | Unique identifier for the shipping option.                 |
| `label`       | string                 | Yes      | Display label (e.g., "Standard Shipping").                 |
| `description` | string                 | No       | Additional description (e.g., "5-7 business days").        |
| `amount`      | number                 | Yes      | Shipping cost in minor units (e.g., 500 = 5.00 EUR).       |
| `type`        | 'SHIPPING' \| 'PICKUP' | No       | Shipping type. Defaults to `'SHIPPING'`. Used by PayPal.   |
| `selected`    | boolean                | No       | Whether this option is initially selected. Used by PayPal. |

### `ShippingAddressChangeResult`[​](#shippingaddresschangeresult "Direct link to shippingaddresschangeresult")

Returned from `onShippingAddressChange` callback.

| Property          | Type                                 | Description                                               |
| ----------------- | ------------------------------------ | --------------------------------------------------------- |
| `shippingOptions` | [ShippingOption](#shippingoption)\[] | Updated shipping options for the new address.             |
| `amount`          | number                               | Updated total amount in minor units (product + shipping). |

### `ShippingOptionChangeResult`[​](#shippingoptionchangeresult "Direct link to shippingoptionchangeresult")

Returned from `onShippingOptionChange` callback.

| Property | Type   | Description                                               |
| -------- | ------ | --------------------------------------------------------- |
| `amount` | number | Updated total amount in minor units (product + shipping). |

### `BillingDetails`[​](#billingdetails "Direct link to billingdetails")

| Property  | Type                | Description     |
| --------- | ------------------- | --------------- |
| `name`    | string              | Full name.      |
| `email`   | string              | Email address.  |
| `phone`   | string              | Phone number.   |
| `company` | string              | Company name.   |
| `address` | [Address](#address) | Postal address. |

### `Address`[​](#address "Direct link to address")

| Property  | Type   | Description                  |
| --------- | ------ | ---------------------------- |
| `country` | string | Two-letter ISO country code. |
| `city`    | string | City name.                   |
| `line1`   | string | Street address line 1.       |
| `line2`   | string | Street address line 2.       |
| `zip`     | string | Postal / ZIP code.           |
| `state`   | string | State, province, or region.  |