# 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.
```
```
### 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;
```
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');
```
## `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;
```
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 `` (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.
important
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;
```
### 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. |