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

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

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

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

Component Instance API

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

render(container)

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?)

Tokenizes the current card data and returns a payment token. Available on CardInput instances only.

declare const submit: (options?: {cardholderName?: string}) => Promise<{
  token?: string; // payment token
  error?: string; // validation error
}>;

Example:

const {token, error} = await cardInput.submit({cardholderName: 'Jane Doe'});
if (error) {
  // Show validation error to user
} else {
  // Confirm payment with the token
  await monei.confirmPayment({paymentId: '...', paymentToken: token});
}

updateProps(newProps)

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, Vue, Angular, Svelte), prop updates are handled automatically — you don't need to call updateProps() manually.

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

Alias for destroy(). Removes the component and cleans up resources.

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
@monei-js/vue-components	Vue 3	Vue Components
@monei-js/angular-components	Angular	Angular Components
@monei-js/svelte-components	Svelte 5	Svelte Components

tip

The legacy .driver() API is deprecated. See the Migration Guide for upgrade instructions.

CardInput Component

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

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

Prop	Type	Required	Description
paymentId	string	Yes*	Payment ID from create payment. 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.
orderId	string	No	Alias for sessionId — normalizes to sessionId internally.
language	string	No	ISO 639-1 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	No	Customize appearance using CSS properties. See Style object below.
placeholders	object	No	Custom input placeholders. See Placeholders below.
errorMessages	object	No	Custom error messages. See 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) => 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

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

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

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

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

Deprecated

createToken() is deprecated. Use instance.submit() instead, which is available directly on the CardInput instance:

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

See the Migration Guide 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<{
  token?: string; // payment token
  error?: string; // validation error
}>;

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 is a customizable Component that renders a PayPal payment button.

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 {
      // 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

Prop	Type	Required	Description
paymentId	string	Yes*	Payment ID from create payment. 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.
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, 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.
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.
onSubmit	(result: {token?: string; error?: string}) => void	Yes	Called when the customer approves the payment.
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.

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 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 in both development and production.

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 {
      // 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

Prop	Type	Required	Description
paymentId	string	Yes*	Payment ID from create payment. 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.
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, in uppercase. Required with accountId.
language	string	No	ISO 639-1 language code. Supported: en, es, ca, pt, de, it, fr, nl, et, fi, lv, no, pl, ru. Auto-detected by default.
onSubmit	(result: {token?: string; error?: string}) => void	Yes	Called when the customer approves the payment.
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

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 is a customizable Component that renders a Bizum payment button.

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 {
      // Confirm payment using the token.
      moneiTokenHandler(result.token);
    }
  },
  onError(error) {
    console.log(error);
  },
  ...otherOptions
});

// render Component on the page
bizum.render('#bizum');

Bizum options

Prop	Type	Required	Description
paymentId	string	Yes*	Payment ID from create payment. 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.
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, 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 language code. Supported: en, es, ca, pt, de, it, fr, nl, et, fi, lv, no, pl, ru. Auto-detected by default.
onSubmit	(result: {token?: string; error?: string}) => void	Yes	Called when the customer approves the payment.
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.

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

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.

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 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 component instead.

You can provide additional customer information in parameters.

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

Confirm payment params

Param	Type	Required	Description
paymentId	string	Yes	Payment ID from create payment
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 language code. Supported: en, es, ca, pt, de, it, fr, nl, et, fi, lv, no, pl, ru. Overrides browser language
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	No	Customer information (name, email, phone)
billingDetails	BillingDetails	No	Billing address and contact details
shippingDetails	BillingDetails	No	Shipping address and contact details (same shape as billingDetails)
style	{width: string, height: string}	No	Popup window dimensions (e.g. "400px", "100%")

PaymentMethod

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

Check confirm payment for the full list of parameters.

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, 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 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);
  });