# Referencia de MONEI JS
Esta referencia documenta todos los objetos y métodos disponibles en la biblioteca JavaScript del lado del navegador de MONEI, monei.js.
Puedes usar las APIs de monei.js para integrar componentes prediseñados para distintos métodos de pago en tus propios flujos de checkout en escritorio y móvil.
## Incluir monei.js[](#incluir-moneijs "Enlace directo al Incluir monei.js")
Incluye el script **monei.js** en la página de checkout de tu sitio — siempre debe cargarse directamente desde `https://js.monei.com`, en lugar de incluirlo en un bundle o alojarlo tú mismo.
```
```
### Usar monei.js como módulo[](#usar-moneijs-como-módulo "Enlace directo al Usar monei.js como módulo")
También proporcionamos un paquete npm que facilita la carga y el uso de monei.js como módulo.
```
npm i @monei-js/components
```
## Objeto `monei`[](#objeto-monei "Enlace directo al objeto-monei")
El objeto monei es tu punto de entrada al resto del SDK de monei.js.
## API de instancia de componente[](#api-de-instancia-de-componente "Enlace directo al API de instancia de componente")
Cada componente de MONEI (`CardInput`, `PayPal`, `Bizum`, `PaymentRequest`) devuelve una instancia de componente con los siguientes métodos:
### `render(container)`[](#rendercontainer "Enlace directo al rendercontainer")
Monta el componente en el DOM. Acepta una cadena de selector CSS o un `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 "Enlace directo al submitoptions")
Tokeniza los datos de tarjeta actuales y devuelve un [`SubmitResult`](#submitresult). Solo disponible en instancias de `CardInput`.
```
declare const submit: (options?: {cardholderName?: string}) => Promise;
```
Ejemplo:
```
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 "Enlace directo al updatepropsnewprops")
Actualiza las props del componente tras el renderizado. Útil para cambios reactivos de props en JavaScript vanilla. Devuelve una `Promise` que se resuelve cuando la actualización se entrega al componente.
```
// Update language dynamically
await cardInput.updateProps({language: 'es'});
// Update style
await cardInput.updateProps({
style: {
input: {fontSize: '18px'}
}
});
```
nota
Al usar paquetes de framework ([React](https://docs.monei.com/es/es/monei-js/react/.md), [Vue](https://docs.monei.com/es/es/monei-js/vue/.md), [Angular](https://docs.monei.com/es/es/monei-js/angular/.md), [Svelte](https://docs.monei.com/es/es/monei-js/svelte/.md)), las actualizaciones de props se gestionan automáticamente — no es necesario llamar a `updateProps()` manualmente.
### `destroy()`[](#destroy "Enlace directo al destroy")
Elimina el componente del DOM y limpia todos los recursos internos (listeners de eventos, conexiones de iframe). Tras llamar a `destroy()`, la instancia no puede reutilizarse.
```
cardInput.destroy();
```
### `close()`[](#close "Enlace directo al close")
Alias de [`destroy()`](#destroy). Elimina el componente y libera recursos.
## Integración con frameworks[](#integración-con-frameworks "Enlace directo al Integración con frameworks")
Los componentes de MONEI están disponibles como componentes nativos para los frameworks más populares. Cada paquete de framework gestiona el montaje, la sincronización de props y la limpieza de forma automática.
| Paquete | Framework | Guía |
| ------------------------------ | --------- | ------------------------------------------------------------------------ |
| `@monei-js/react-components` | React | [Componentes React](https://docs.monei.com/es/es/monei-js/react/.md) |
| `@monei-js/vue-components` | Vue 3 | [Componentes Vue](https://docs.monei.com/es/es/monei-js/vue/.md) |
| `@monei-js/angular-components` | Angular | [Componentes Angular](https://docs.monei.com/es/es/monei-js/angular/.md) |
| `@monei-js/svelte-components` | Svelte 5 | [Componentes Svelte](https://docs.monei.com/es/es/monei-js/svelte/.md) |
tip
La API `.driver()` heredada está obsoleta. Consulta la [Guía de migración](https://docs.monei.com/es/es/monei-js/migration/.md) para las instrucciones de actualización.
## Componente `CardInput`[](#componente-cardinput "Enlace directo al componente-cardinput")
CardInput es un componente personalizable que se usa para recopilar información sensible de tarjeta en tus formularios de pago.
### Crear una instancia del componente CardInput.[](#crear-una-instancia-del-componente-cardinput "Enlace directo al Crear una instancia del componente CardInput.")
```
const cardInput = monei.CardInput({
paymentId: 'af6029f80f5fc73a8ad2753eea0b1be0',
...otherOptions
});
// render Component on the page
cardInput.render('#card_input_container');
```
### Opciones de CardInput[](#opciones-de-cardinput "Enlace directo al Opciones de CardInput")
| Prop | Type | Required | Description |
| --------------- | ------------------------------------------------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `paymentId` | string | Yes\* | ID de pago de [crear pago](https://docs.monei.com/es/es/apis/rest/payments-create/.md). El token generado quedará vinculado a este pago. |
| `accountId` | string | Yes\* | Tu ID de cuenta de MONEI. Úsalo con `sessionId` en lugar de `paymentId` para generar un token antes de crear el pago. |
| `sessionId` | string | Cond. | ID de sesión único en tu sistema. Proporciona un `sessionId` distinto para cada cliente a fin de garantizar que el cliente que genera el token coincide con el que realiza el pago. Requerido con `accountId` si se pasa un token al servidor. Debe coincidir con el valor en [crear pago](https://docs.monei.com/es/es/apis/rest/schemas/payment/.md). |
| `orderId` | string | No | Alias de `sessionId` — se normaliza a `sessionId` internamente. |
| `language` | string | No | Código de idioma [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes). Soportados: `en`, `es`, `ca`, `pt`, `de`, `it`, `fr`, `nl`, `et`, `fi`, `lv`, `no`, `pl`, `ru`. Se detecta automáticamente por defecto según la geolocalización y las preferencias del navegador. |
| `style` | [CardInputStyle](#cardinput-style-object) | No | Personaliza el aspecto usando propiedades CSS. Consulta el [objeto Style](#cardinput-style-object) a continuación. |
| `fonts` | [FontConfig](#custom-fonts)\[] | No | Carga fuentes web personalizadas dentro del iframe para que una referencia `style.base.fontFamily` se renderice correctamente. Consulta [Fuentes personalizadas](#custom-fonts) a continuación. |
| `placeholders` | object | No | Placeholders personalizados para los campos. Consulta [Placeholders](#cardinput-placeholders) a continuación. |
| `errorMessages` | object | No | Mensajes de error personalizados. Consulta [Mensajes de error](#cardinput-error-messages) a continuación. |
| `onFocus` | () => void | No | Se llama cuando el campo de tarjeta recibe el foco. |
| `onBlur` | () => void | No | Se llama cuando el campo de tarjeta pierde el foco. |
| `onLoad` | () => void | No | Se llama cuando el campo de tarjeta se ha cargado completamente. |
| `onEnter` | () => void | No | Se llama cuando el usuario pulsa **Enter** dentro del campo de tarjeta. |
| `onChange` | (event: [CardInputOnChangeEvent](#cardinputonchangeevent)) => void | No | Se llama en cada entrada del usuario. Se usa para validación en tiempo real. |
| `onError` | (error: Error) => void | No | Se llama cuando se produce un error. |
\* Se requiere `paymentId` o `accountId`. **Cond.** = requerido al usar `accountId`.
#### Placeholders de CardInput[](#placeholders-de-cardinput "Enlace directo al Placeholders de CardInput")
| Prop | Type | Default |
| ------------ | ------ | ------------- |
| `cardNumber` | string | "Card number" |
| `expiryDate` | string | "MM/YY" |
| `cvc` | string | "CVC" |
#### Mensajes de error de CardInput[](#mensajes-de-error-de-cardinput "Enlace directo al Mensajes de error de CardInput")
| 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 "Enlace directo al cardinputonchangeevent")
| Property | Type | Description |
| ------------- | ------- | -------------------------------------------------------- |
| `isTouched` | boolean | Indica si el campo de tarjeta ha sido tocado. |
| `isSubmitted` | boolean | Indica si el formulario ha sido enviado. |
| `cardType` | string? | Tipo de tarjeta detectado (p. ej. `visa`, `mastercard`). |
| `error` | string? | Mensaje de error de validación. Muéstraselo al usuario. |
### Objeto Style de CardInput[](#objeto-style-de-cardinput "Enlace directo al Objeto Style de CardInput")
Los componentes se estilizan mediante un objeto Style. Consiste en propiedades CSS anidadas bajo objetos para cualquiera de las siguientes variantes:
* **base** `object` - estilo base del componente
* **loading** `object` - estilo base del componente mientras se carga
* **invalid** `object` - se aplica cuando el componente tiene entrada inválida
* **input** `object` - se aplica a los campos individuales
* **cardNumber** `object` - se aplica al campo del número de tarjeta
* **expiryDate** `object` - se aplica al campo de fecha de caducidad
* **cvc** `object` - se aplica al campo CVC
* **icon** `object` - se aplica al icono
Las siguientes pseudoclases y pseudoelementos también pueden estilizarse usando un objeto anidado dentro de una variante:
* `: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');
```
## Función `createToken`[](#función-createtoken "Enlace directo al función-createtoken")
Obsoleto
`createToken()` está obsoleto. Usa [`instance.submit()`](#submitoptions) en su lugar, que está disponible directamente en la instancia de CardInput:
```
const {token, error} = await cardInput.submit();
```
Consulta la [Guía de migración](https://docs.monei.com/es/es/monei-js/migration/.md) para más detalles.
Usa esta función para generar un token de pago.
nota
Los tokens de pago generados por los componentes de monei.js caducan en cuanto se usan o a los 5 días de su creación.
Pasa una instancia del componente CardInput.
```
declare const createToken: (Component: MoneiComponent) => Promise;
```
Ejemplo:
```
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);
});
```
## Componente `PayPal`[](#componente-paypal "Enlace directo al componente-paypal")
PayPal es un componente personalizable que muestra un botón de pago de PayPal.
### Crear una instancia del componente PayPal.[](#crear-una-instancia-del-componente-paypal "Enlace directo al Crear una instancia del componente PayPal.")
```
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');
```
### Opciones de PayPal[](#opciones-de-paypal "Enlace directo al Opciones de PayPal")
| Prop | Type | Required | Description |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `paymentId` | string | Yes\* | ID de pago de [crear pago](https://docs.monei.com/es/es/apis/rest/payments-create/.md). El token generado quedará vinculado a este pago. |
| `accountId` | string | Yes\* | Tu ID de cuenta de MONEI. Úsalo con `sessionId` en lugar de `paymentId` para generar un token antes de crear el pago. |
| `sessionId` | string | Cond. | ID de sesión único en tu sistema. Proporciona un `sessionId` distinto para cada cliente a fin de garantizar que el cliente que genera el token coincide con el que realiza el pago. Requerido con `accountId`. Debe coincidir con el valor en [crear pago](https://docs.monei.com/es/es/apis/rest/schemas/payment/.md). |
| `amount` | number | Cond. | Importe en la unidad de moneda más pequeña (p. ej., 100 = 1,00 USD). Requerido con `accountId`. |
| `currency` | string | Cond. | Código de moneda [ISO](https://en.wikipedia.org/wiki/ISO_4217) de tres letras, en mayúsculas. Requerido con `accountId`. |
| `transactionType` | 'SALE' \| 'AUTH' | No | Controla cuándo se capturan los fondos. `SALE` (por defecto): captura inmediata. `AUTH`: solo autorización, captura posterior. |
| `language` | string | No | Idioma del botón de PayPal. Se detecta automáticamente por defecto. [Idiomas soportados](https://developer.paypal.com/docs/checkout/reference/customize-sdk/#locale). |
| `cspNonce` | string | No | Valor nonce para la Política de Seguridad de Contenido. Pásalo si tu página usa un nonce `script-src` en la CSP. |
| `borderRadius` | number \| string | No | Radio de borde personalizado para el contenedor del botón de PayPal. |
| `requestShipping` | boolean | No | Activa la recopilación de dirección de envío en el checkout de PayPal. Requiere el flujo con `accountId` (incompatible con `paymentId`). Consulta [Express Checkout](https://docs.monei.com/es/es/integrations/express-checkout/.md). |
| `shippingOptions` | [ShippingOption](#shippingoption)\[] | No | Opciones de envío disponibles que se muestran en el checkout de PayPal. Requiere `requestShipping: true`. |
| `onShippingAddressChange` | (address: [Address](#address)) => Promise<[ShippingAddressChangeResult](#shippingaddresschangeresult)> | No | Se llama cuando el cliente cambia su dirección de envío en el checkout de PayPal. Devuelve opciones de envío actualizadas y/o importe. |
| `onShippingOptionChange` | (option: [ShippingOption](#shippingoption)) => Promise<[ShippingOptionChangeResult](#shippingoptionchangeresult)> | No | Se llama cuando el cliente selecciona una opción de envío diferente. Devuelve el importe actualizado. |
| `onSubmit` | (result: [SubmitResult](#submitresult)) => void | Yes | Se llama cuando el cliente aprueba el pago. Devuelve un [`SubmitResult`](#submitresult) con `paymentMethod: 'paypal'`. |
| `onBeforeOpen` | () => boolean | No | Se llama antes de que se abra la ventana de PayPal. Devuelve `false` para evitar que se abra. |
| `onLoad` | (isSupported: boolean) => void | No | Se llama cuando PayPal se ha cargado completamente. Si PayPal no está soportado, el componente no se renderizará y `onLoad` se dispara con `false`. |
| `onError` | (error: Error) => void | No | Se llama cuando se produce un error. |
| `style` | object | No | Personaliza el aspecto del botón. Consulta las propiedades de estilo a continuación. |
\* Se requiere `paymentId` o `accountId`. **Cond.** = requerido al usar `accountId`.
nota
PayPal siempre devuelve la información del pagador (nombre, correo electrónico) independientemente de la configuración — no existe una prop `requestBilling` separada para PayPal. Los datos de facturación siempre están incluidos en el [`SubmitResult`](#submitresult).
#### Estilo de PayPal[](#estilo-de-paypal "Enlace directo al Estilo de PayPal")
| Prop | Type | Default | Description |
| -------------- | ------------------------------------------------------------------------ | ------- | ------------------------------------------------------------ |
| `height` | number \| string | — | Altura del botón en píxeles. Valores de `25` a `55`. |
| `color` | 'gold' \| 'blue' \| 'silver' \| 'white' \| 'black' | — | Tema de color del botón. |
| `shape` | 'pill' \| 'rect' | — | Forma del botón. |
| `layout` | 'horizontal' \| 'vertical' | — | Disposición del botón cuando hay varios botones disponibles. |
| `label` | 'checkout' \| 'credit' \| 'pay' \| 'buynow' \| 'paypal' \| 'installment' | — | Texto de la etiqueta del botón. |
| `size` | 'small' \| 'medium' \| 'large' \| 'responsive' | — | Tamaño predefinido del botón. |
| `borderRadius` | number \| string | — | Radio de borde personalizado para el botón. |
## Componente `PaymentRequest`[](#componente-paymentrequest "Enlace directo al componente-paymentrequest")
PaymentRequest es un componente personalizable que muestra un botón de pago de Google Pay o Apple Pay según el navegador y el sistema operativo del usuario. PaymentRequest sustituye al componente `GooglePay` obsoleto — muestra automáticamente Google Pay, Apple Pay o Click to Pay según el soporte del dispositivo.
nota
Apple Pay requiere [verificación de dominio](https://docs.monei.com/es/es/payment-methods/apple-pay/.md#register-your-domain-with-apple-pay) tanto en desarrollo como en producción.
### Crear una instancia del componente PaymentRequest.[](#crear-una-instancia-del-componente-paymentrequest "Enlace directo al Crear una instancia del componente PaymentRequest.")
```
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');
```
### Opciones de PaymentRequest[](#opciones-de-paymentrequest "Enlace directo al Opciones de PaymentRequest")
| Prop | Type | Required | Description |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `paymentId` | string | Yes\* | ID de pago de [crear pago](https://docs.monei.com/es/es/apis/rest/payments-create/.md). El token generado quedará vinculado a este pago. |
| `accountId` | string | Yes\* | Tu ID de cuenta de MONEI. Úsalo con `sessionId` en lugar de `paymentId` para generar un token antes de crear el pago. |
| `sessionId` | string | Cond. | ID de sesión único en tu sistema. Proporciona un `sessionId` distinto para cada cliente a fin de garantizar que el cliente que genera el token coincide con el que realiza el pago. Requerido con `accountId`. Debe coincidir con el valor en [crear pago](https://docs.monei.com/es/es/apis/rest/schemas/payment/.md). |
| `amount` | number | Cond. | Importe en la unidad de moneda más pequeña (p. ej., 100 = 1,00 USD). Requerido con `accountId`. |
| `currency` | string | Cond. | Código de moneda [ISO](https://en.wikipedia.org/wiki/ISO_4217) de tres letras, en mayúsculas. Requerido con `accountId`. |
| `language` | string | No | Código de idioma [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes). Soportados: `en`, `es`, `ca`, `pt`, `de`, `it`, `fr`, `nl`, `et`, `fi`, `lv`, `no`, `pl`, `ru`. Se detecta automáticamente por defecto. |
| `requestShipping` | boolean | No | Activa la recopilación de dirección de envío en la interfaz del monedero de Apple Pay / Google Pay. Requiere el flujo con `accountId` (incompatible con `paymentId`). Consulta [Express Checkout](https://docs.monei.com/es/es/integrations/express-checkout/.md). |
| `requestBilling` | boolean | No | Activa la recopilación de dirección de facturación. Funciona con los flujos de `accountId` y `paymentId`. |
| `shippingOptions` | [ShippingOption](#shippingoption)\[] | No | Opciones de envío disponibles que se muestran en la interfaz del monedero. Requiere `requestShipping: true`. |
| `onShippingAddressChange` | (address: [Address](#address)) => Promise<[ShippingAddressChangeResult](#shippingaddresschangeresult)> | No | Se llama cuando el cliente cambia su dirección de envío en la interfaz del monedero. Devuelve opciones de envío actualizadas y/o importe. La dirección está redactada durante el flujo (sin datos a nivel de calle — solo país, ciudad, estado y código postal). |
| `onShippingOptionChange` | (option: [ShippingOption](#shippingoption)) => Promise<[ShippingOptionChangeResult](#shippingoptionchangeresult)> | No | Se llama cuando el cliente selecciona una opción de envío diferente. Devuelve el importe actualizado. |
| `onSubmit` | (result: [SubmitResult](#submitresult)) => void | Yes | Se llama cuando el cliente aprueba el pago. Devuelve un [`SubmitResult`](#submitresult) con `paymentMethod: 'applePay'` o `'googlePay'`. |
| `onBeforeSubmit` | () => void | No | Se llama antes de enviar el pago. Úsalo para validación o analíticas. |
| `onBeforeOpen` | () => boolean | No | Se llama antes de que se abra la ventana de pago. Devuelve `false` para evitar que se abra. |
| `onLoad` | (isSupported: boolean) => void | No | Se llama cuando el componente se ha cargado completamente. Si el método de pago no está soportado, el componente no se renderizará y `onLoad` se dispara con `false`. |
| `onError` | (error: Error) => void | No | Se llama cuando se produce un error. |
| `style` | object | No | Personaliza el aspecto del botón. Consulta las propiedades de estilo a continuación. |
\* Se requiere `paymentId` o `accountId`. **Cond.** = requerido al usar `accountId`.
#### Estilo de PaymentRequest[](#estilo-de-paymentrequest "Enlace directo al Estilo de PaymentRequest")
| Prop | Type | Default | Description |
| -------------- | ------------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `height` | string \| number | — | Altura del botón en píxeles. Valores de `25` a `55`. |
| `color` | 'default' \| 'black' \| 'white' | 'default' | Tema de color del botón. |
| `type` | 'buy' \| 'plain' \| 'donate' | 'plain' | Etiqueta del botón: `'buy'` = "Buy with Google Pay / Apple Pay", `'donate'` = "Donate with Google Pay / Apple Pay", `'plain'` = sin texto adicional. |
| `borderRadius` | number \| string | — | Radio de borde personalizado para el botón. |
| `fontFamily` | string | — | Familia de fuente personalizada para el texto del botón. |
## Componente `Bizum`[](#componente-bizum "Enlace directo al componente-bizum")
Bizum es un componente personalizable que muestra un botón de pago de Bizum.
### Crear una instancia del componente Bizum.[](#crear-una-instancia-del-componente-bizum "Enlace directo al Crear una instancia del componente Bizum.")
```
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');
```
### Opciones de Bizum[](#opciones-de-bizum "Enlace directo al Opciones de Bizum")
| Prop | Type | Required | Description |
| ----------------- | ----------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `paymentId` | string | Yes\* | ID de pago de [crear pago](https://docs.monei.com/es/es/apis/rest/payments-create/.md). El token generado quedará vinculado a este pago. |
| `accountId` | string | Yes\* | Tu ID de cuenta de MONEI. Úsalo con `sessionId` en lugar de `paymentId` para generar un token antes de crear el pago. |
| `sessionId` | string | Cond. | ID de sesión único en tu sistema. Proporciona un `sessionId` distinto para cada cliente a fin de garantizar que el cliente que genera el token coincide con el que realiza el pago. Requerido con `accountId`. Debe coincidir con el valor en [crear pago](https://docs.monei.com/es/es/apis/rest/schemas/payment/.md). |
| `phoneNumber` | string | No | Rellena previamente el número de teléfono del cliente para el flujo de pago de Bizum. |
| `amount` | number | Cond. | Importe en la unidad de moneda más pequeña (p. ej., 100 = 1,00 USD). Requerido con `accountId`. |
| `currency` | string | Cond. | Código de moneda [ISO](https://en.wikipedia.org/wiki/ISO_4217) de tres letras, en mayúsculas. Requerido con `accountId`. |
| `transactionType` | 'SALE' \| 'AUTH' | No | Controla cuándo se capturan los fondos. `SALE` (por defecto): captura inmediata. `AUTH`: solo autorización, captura posterior. |
| `fullscreen` | boolean | No | Establece en `true` para abrir la ventana de pago de Bizum en modo pantalla completa. |
| `language` | string | No | Código de idioma [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes). Soportados: `en`, `es`, `ca`, `pt`, `de`, `it`, `fr`, `nl`, `et`, `fi`, `lv`, `no`, `pl`, `ru`. Se detecta automáticamente por defecto. |
| `onSubmit` | (result: [SubmitResult](#submitresult)) => void | Yes | Se llama cuando el cliente aprueba el pago. Devuelve un [`SubmitResult`](#submitresult) con `paymentMethod: 'bizum'`. |
| `onBeforeOpen` | () => boolean | No | Se llama antes de que se abra la ventana de Bizum. Devuelve `false` para evitar que se abra. |
| `onOpen` | () => void | No | Se llama cuando se abre la ventana de pago de Bizum. |
| `onLoad` | (isSupported: boolean) => void | No | Se llama cuando el componente se ha cargado completamente. Si Bizum no está soportado, el componente no se renderizará y `onLoad` se dispara con `false`. |
| `onError` | (error: Error) => void | No | Se llama cuando se produce un error. |
| `style` | object | No | Personaliza el aspecto del botón. Consulta las propiedades de estilo a continuación. |
| `fonts` | [FontConfig](#custom-fonts)\[] | No | Carga fuentes web personalizadas para que una referencia `style.fontFamily` se renderice correctamente. Consulta [Fuentes personalizadas](#custom-fonts). |
\* Se requiere `paymentId` o `accountId`. **Cond.** = requerido al usar `accountId`.
#### Estilo de Bizum[](#estilo-de-bizum "Enlace directo al Estilo de Bizum")
| Prop | Type | Default | Description |
| -------------- | ---------------- | ------- | -------------------------------------------------------------------------------- |
| `height` | string \| number | — | Altura del botón en píxeles. Valores de `25` a `55`. |
| `type` | 'pay' \| 'plain' | 'plain' | Etiqueta del botón: `'pay'` = "Pay with Bizum", `'plain'` = sin texto adicional. |
| `borderRadius` | number \| string | — | Radio de borde personalizado para el botón. |
| `fontFamily` | string | — | Familia de fuente personalizada para el texto del botón. |
## Fuentes personalizadas[](#fuentes-personalizadas "Enlace directo al Fuentes personalizadas")
Refleja la API `fonts` de Stripe Elements. Usa la opción `fonts` para cargar fuentes web elegidas por el comercio dentro del iframe del componente, de modo que una referencia `style.base.fontFamily` (o `style.fontFamily` para Bizum) se renderice con la fuente solicitada, en lugar de la que tenga instalada el dispositivo del cliente.
### Componentes soportados[](#componentes-soportados "Enlace directo al Componentes soportados")
`fonts` es aceptado por:
* [`CardInput`](#cardinput-component)
* [`Bizum`](#bizum-component)
`fonts` **no** es aceptado por [`PayPal`](#paypal-component), [`PaymentRequest`](#paymentrequest-component) ni `GooglePay` — los glifos de los botones de monedero se renderizan mediante el SDK del monedero en un DOM controlado por el proveedor que ignora el CSS del host, por lo que cargar una fuente personalizada allí no tendría ningún efecto visible.
### `FontConfig`[](#fontconfig "Enlace directo al fontconfig")
Cada entrada del array `fonts` es una de las siguientes:
```
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;
```
### Dos formas[](#dos-formas "Enlace directo al Dos formas")
**1. `cssSrc`** — enlaza una hoja de estilos externa que contiene reglas `@font-face`. Actualmente solo funciona con **Google Fonts** (`fonts.googleapis.com`); otros CDN (Adobe Fonts, Bunny Fonts) no están en la lista de permitidos de la Política de Seguridad de Contenido por defecto.
```
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. `FontFace` explícito** — proporciona tú mismo todos los descriptores de `@font-face`. Funciona para **cualquier host HTTPS** además de URLs `data:` embebidas. Úsalo para fuentes alojadas por ti mismo.
```
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'
}
]
});
```
### Múltiples grosores[](#múltiples-grosores "Enlace directo al Múltiples grosores")
Pasa una entrada por cada combinación de `(family, weight, style)`. La misma familia con diferentes grosores genera múltiples reglas `@font-face` — el navegador elige el grosor que coincide cuando el CSS solicita negrita o cursiva.
### Semántica de carga[](#semántica-de-carga "Enlace directo al Semántica de carga")
* El iframe del componente inyecta un `` (para `cssSrc`) o registra cada `FontFace` (para el explícito), y luego espera hasta **3 segundos** para que las fuentes se carguen antes del primer renderizado. Si el CDN de fuentes es lento o no está disponible, el componente se renderiza con la siguiente familia en la pila — la página nunca queda bloqueada indefinidamente.
* El `font-display` por defecto para las entradas `FontFace` explícitas es `swap`. Sobreescríbelo por entrada si necesitas una política diferente.
* La validación se ejecuta en cada entrada; los valores malformados (p. ej., `weight` inválido, `src` que no es `https:`/`data:`, caracteres sospechosos en `family`) se descartan silenciosamente para evitar la inyección de CSS.
* Los anchos de los campos de `CardInput` se adaptan automáticamente a la fuente del comercio cuando las fuentes se cargan — los placeholders se miden junto con muestras de dígitos escritos y gana el más ancho. Las fuentes decorativas o caligráficas (p. ej., Lobster) encajan sin recortarse; el renderizado sans-serif no cambia.
### Migración[](#migración "Enlace directo al Migración")
¿Ya pasas `style.base.fontFamily` (o `style.fontFamily`) a un componente? El comportamiento no cambia — sin una entrada `fonts` coincidente, el dispositivo del cliente renderiza lo que tenga instalado, igual que ahora. Para optar por un renderizado determinista, combina el `fontFamily` existente con una entrada `fonts` que lo cargue.
```
// 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'}]
});
```
## Función `confirmPayment`[](#función-confirmpayment "Enlace directo al función-confirmpayment")
Después de generar el **paymentToken** usando uno de los componentes, usa esta función para confirmar el pago pasando el `paymentToken` obtenido. Mostrará automáticamente una ventana emergente con una pantalla de confirmación 3D Secure si es necesario.
Cuando se llama sin un `paymentToken`, `confirmPayment` abre el Modal de pago de MONEI donde el cliente puede seleccionar un método de pago y completar el pago. Consulta [Usar el Modal de pago](https://docs.monei.com/es/es/integrations/use-payment-modal/.md) para la guía de integración completa.
important
No todos los métodos de pago están disponibles en el Modal de pago. Apple Pay no está soportado en el modal — usa el componente [PaymentRequest](#paymentrequest-component) en su lugar.
Puedes proporcionar información adicional del cliente en los parámetros.
```
declare const confirmPayment: (params: ConfirmPaymentParams) => Promise;
```
### Parámetros de confirmación de pago[](#confirm-payment-params "Enlace directo al Parámetros de confirmación de pago")
| Param | Type | Required | Description |
| ----------------------- | ------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `paymentId` | string | Yes | ID de pago de [crear pago](https://docs.monei.com/es/es/apis/rest/payments-create/.md) |
| `paymentToken` | string | No | Token generado por monei.js. Si está presente, la ventana emergente se abre directamente en la confirmación 3D Secure (si es necesaria) |
| `generatePaymentToken` | boolean | No | Si es `true`, genera un token permanente que representa el método de pago utilizado |
| `fullscreen` | boolean | No | Si es `true`, abre una ventana de confirmación a pantalla completa |
| `language` | string | No | Código de idioma [ISO 639-1](https://en.wikipedia.org/wiki/ISO_639-1) de dos letras. Soportados: `en`, `es`, `ca`, `pt`, `de`, `it`, `fr`, `nl`, `et`, `fi`, `lv`, `no`, `pl`, `ru`. Anula el idioma del navegador |
| `paymentMethod` | [PaymentMethod](#paymentmethod) | No | Rellena previamente los datos del método de pago (p. ej., nombre/correo del titular) |
| `allowedPaymentMethods` | string\[] | No | Restringe los métodos de pago disponibles. Soportados: `card`, `googlePay`, `clickToPay`, `bizum`, `paypal` |
| `customDomain` | string | No | Dominio personalizado para la ventana emergente de pago. Requerido si tienes configurado un dominio personalizado |
| `customer` | [Customer](https://docs.monei.com/es/es/apis/rest/schemas/payment-customer/.md) | No | Información del cliente (nombre, correo electrónico, teléfono) |
| `billingDetails` | [BillingDetails](https://docs.monei.com/es/es/apis/rest/schemas/payment-billingdetails/.md) | No | Dirección de facturación y datos de contacto |
| `shippingDetails` | [BillingDetails](https://docs.monei.com/es/es/apis/rest/schemas/payment-billingdetails/.md) | No | Dirección de envío y datos de contacto (misma estructura que billingDetails) |
| `style` | {width: string, height: string} | No | Dimensiones de la ventana emergente (p. ej., `"400px"`, `"100%"`) |
#### `PaymentMethod`[](#paymentmethod "Enlace directo al paymentmethod")
| Field | Type | Description |
| ---------------------- | ------ | ------------------------------------------- |
| `card.cardholderName` | string | Nombre del titular de la tarjeta a rellenar |
| `card.cardholderEmail` | string | Correo electrónico del titular a rellenar |
Consulta [confirmar pago](https://docs.monei.com/es/es/apis/rest/payments-confirm/.md) para la lista completa de parámetros.
tip
Al usar [express checkout](https://docs.monei.com/es/es/integrations/express-checkout/.md) con envío (flujo accountId), crea el pago en el servidor pasando `paymentToken`, `billingDetails` y `shippingDetails` del [`SubmitResult`](#submitresult). Para checkout solo con facturación (flujo paymentId), pasa `billingDetails` a `confirmPayment`.
### Resultado del pago[](#resultado-del-pago "Enlace directo al Resultado del pago")
| Prop | Type | Description |
| ------------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | string | Identificador único del pago |
| `status` | string | El estado del pago |
| `amount` | positive integer | Importe que se pretende cobrar en este pago. Un entero positivo que representa cuánto cobrar en la unidad de moneda más pequeña (p. ej., 100 céntimos para cobrar 1,00 USD) |
| `currency` | string | Código de moneda [ISO](https://en.wikipedia.org/wiki/ISO_4217) de tres letras, en mayúsculas |
| `accountId` | string | ID de cuenta de MONEI |
| `orderId` | string | Un ID de pedido de tu sistema. Identificador único que puede usarse para reconciliar el pago con tu sistema interno |
| `statusCode` | string | Código de estado del pago |
| `statusMessage` | string | Mensaje de estado legible por humanos, puede mostrarse al usuario |
| `nextAction` | object | Si está presente, indica las acciones que debes realizar para que el cliente complete el pago usando la fuente proporcionada |
| `nextAction.type` | string | El tipo de acción siguiente |
| `nextAction.mustRedirect` | boolean | Si el cliente debe ser redirigido |
| `nextAction.redirectUrl` | string | URL a la que redirigir al cliente |
Consulta el [objeto de pago](https://docs.monei.com/es/es/apis/rest/schemas/payment/.md) para la descripción completa de cada campo.
Ejemplo:
```
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);
});
```
## Referencia de tipos[](#referencia-de-tipos "Enlace directo al Referencia de tipos")
### `SubmitResult`[](#submitresult "Enlace directo al submitresult")
Devuelto por todos los callbacks `onSubmit` de los componentes y por `CardInput.submit()`.
| Property | Type | Description |
| ----------------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `token` | string | Token de pago. Úsalo con `confirmPayment` o pásalo a tu servidor. |
| `error` | string | Mensaje de error de validación. Presente en lugar de `token` cuando la tokenización falla. |
| `paymentMethod` | [PaymentMethodType](#paymentmethodtype) | Método de pago utilizado: `'card'`, `'applePay'`, `'googlePay'`, `'paypal'` o `'bizum'`. |
| `finalAmount` | number | Total autorizado por el monedero en unidades menores. Puede diferir del `amount` inicial si el envío cambió el total. Solo presente en express checkout. |
| `billingDetails` | [BillingDetails](#billingdetails) | Dirección de facturación e información de contacto recopilada por el monedero. Solo presente cuando `requestBilling` es true (o siempre para PayPal). |
| `shippingDetails` | [BillingDetails](#billingdetails) | Dirección de envío e información de contacto recopilada por el monedero. Solo presente cuando `requestShipping` es true. |
| `shippingOption` | [ShippingOption](#shippingoption) | La opción de envío seleccionada por el cliente. Solo presente cuando `requestShipping` es true. |
### `PaymentMethodType`[](#paymentmethodtype "Enlace directo al paymentmethodtype")
```
type PaymentMethodType = 'card' | 'applePay' | 'googlePay' | 'paypal' | 'bizum';
```
### `ShippingOption`[](#shippingoption "Enlace directo al shippingoption")
| Property | Type | Required | Description |
| ------------- | ---------------------- | -------- | ---------------------------------------------------------------- |
| `id` | string | Yes | Identificador único de la opción de envío. |
| `label` | string | Yes | Etiqueta de visualización (p. ej., "Envío estándar"). |
| `description` | string | No | Descripción adicional (p. ej., "5-7 días laborables"). |
| `amount` | number | Yes | Coste de envío en unidades menores (p. ej., 500 = 5,00 EUR). |
| `type` | 'SHIPPING' \| 'PICKUP' | No | Tipo de envío. Por defecto `'SHIPPING'`. Usado por PayPal. |
| `selected` | boolean | No | Si esta opción está seleccionada inicialmente. Usado por PayPal. |
### `ShippingAddressChangeResult`[](#shippingaddresschangeresult "Enlace directo al shippingaddresschangeresult")
Devuelto desde el callback `onShippingAddressChange`.
| Property | Type | Description |
| ----------------- | ------------------------------------ | ----------------------------------------------------------------- |
| `shippingOptions` | [ShippingOption](#shippingoption)\[] | Opciones de envío actualizadas para la nueva dirección. |
| `amount` | number | Importe total actualizado en unidades menores (producto + envío). |
### `ShippingOptionChangeResult`[](#shippingoptionchangeresult "Enlace directo al shippingoptionchangeresult")
Devuelto desde el callback `onShippingOptionChange`.
| Property | Type | Description |
| -------- | ------ | ----------------------------------------------------------------- |
| `amount` | number | Importe total actualizado en unidades menores (producto + envío). |
### `BillingDetails`[](#billingdetails "Enlace directo al billingdetails")
| Property | Type | Description |
| --------- | ------------------- | --------------------- |
| `name` | string | Nombre completo. |
| `email` | string | Dirección de correo. |
| `phone` | string | Número de teléfono. |
| `company` | string | Nombre de la empresa. |
| `address` | [Address](#address) | Dirección postal. |
### `Address`[](#address "Enlace directo al address")
| Property | Type | Description |
| --------- | ------ | --------------------------------- |
| `country` | string | Código de país ISO de dos letras. |
| `city` | string | Nombre de la ciudad. |
| `line1` | string | Dirección postal línea 1. |
| `line2` | string | Dirección postal línea 2. |
| `zip` | string | Código postal. |
| `state` | string | Estado, provincia o región. |