> ## Documentation Index
> Fetch the complete documentation index at: https://docs.alignet.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 2. Integra Flex
> Incluye las librerías, prepara el payload y monta tu primer formulario de pago.
Con un nonce vigente, integra el formulario en tres etapas: carga la librería, construye el payload de pago y monta Flex.
## 1. Incluye el CSS y JavaScript
Para usar Alignet One Flex hay que incluir el siguiente código en el HTML de la página según el ambiente:
```html theme={"system"} theme={"system"}
```
```html theme={"system"} theme={"system"}
```
Estilos predeterminados del formulario de pago. Incluir antes del cierre del ``.
Librería principal de Alignet One Flex. Incluir después del CSS en el ``.
Asegúrate de incluir primero el CSS y luego el JS para garantizar que los estilos se apliquen correctamente antes de que el formulario se inicialice.
## 2. Construye el payload de pago
El `payload` de Flex reutiliza la estructura del **API de Autorización - ecommerce**, con una diferencia importante: debes enviar `payment_method` en el objeto raíz, pero como un objeto vacío `{}`, porque el cliente elegirá el método dentro del formulario.
Piensa este paso como la preparación del request de `POST /charges` para Flex. Lo que construyes aquí será la base de la operación que luego terminarás leyendo en `responseCallback(response)`.
### Qué se conserva y qué cambia
Mantienes `action`, `channel`, `merchant_code`, `merchant_operation_number`, `payment_method` y `payment_details`.
En Flex, `payment_method` viaja como `{}` vacío porque el método real se resuelve en el frontend según lo que el usuario seleccione.
### Estructura del payload
Expande cada bloque para revisar qué campos pertenecen a cada nivel del objeto que enviarás a Flex.
Contiene la información general de la operación y enlaza con `payment_details`, donde viaja el detalle del cobro.
| Campo | Descripción | Ejemplo | Tipo | Obligatorio |
| :-------------------------- | :---------------------------------------------- | :----------------------------------- | :----- | :---------- |
| `action` | Acción a ejecutar | `authorize` | String | SI |
| `channel` | Canal donde se ejecutará la transacción | `ecommerce` | String | SI |
| `merchant_code` | Identificador del comercio | Cadena alfanumérica | String | SI |
| `merchant_operation_number` | Número de pedido de la operación | Cadena numérica entre 6 y 12 dígitos | String | SI |
| `payment_method` | Objeto reservado para Flex. Debe enviarse vacío | `{}` | Object | SI |
| `payment_details` | Objeto con información de la transacción | Object | Object | SI |
Agrupa el monto, moneda y subobjetos operativos del comprador, facturación y envío.
| Campo | Descripción | Ejemplo | Tipo | Obligatorio |
| :---------------------------------- | :----------------------------------------------------------------------------------------------- | :-------------------- | :--------- | :---------- |
| `payment_details.amount` | Monto en centavos de la operación | `1050` | String | SI |
| `payment_details.currency` | Código [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) de la moneda de la operación | `604` | String | SI |
| `payment_details.additional_fields` | Diccionario para enviar campos y valores personalizados según `key:value` | `external_id:5468724` | Dictionary | NO |
| `payment_details.customer` | Objeto con información del cliente que realiza la compra | Object | Object | NO |
| `payment_details.billing` | Objeto con información de facturación | Object | Object | SI |
| `payment_details.shipping` | Objeto con información de envío | Object | Object | NO |
Define los datos opcionales del cliente que realiza la compra, útiles para identificación y contexto de riesgo.
| Campo | Descripción | Tipo | Obligatorio |
| :------------------------------------------------------ | :------------------------------------------------ | :----- | :---------- |
| `payment_details.customer.first_name` | Nombres | String | NO |
| `payment_details.customer.last_name` | Apellidos | String | NO |
| `payment_details.customer.email` | Correo electrónico | String | NO |
| `payment_details.customer.phone` | Objeto con información del teléfono | Object | NO |
| `payment_details.customer.phone.country_code` | Código del país del teléfono | String | NO |
| `payment_details.customer.phone.subscriber` | Número del teléfono | String | NO |
| `payment_details.customer.identity_document` | Objeto con información del documento de identidad | Object | NO |
| `payment_details.customer.identity_document.country` | País del documento | String | NO |
| `payment_details.customer.identity_document.type` | Tipo de documento | String | NO |
| `payment_details.customer.identity_document.identifier` | Número de documento | String | NO |
| `payment_details.customer.location` | Objeto con información de ubicación | Object | NO |
| `payment_details.customer.location.line_1` | Dirección 1 | String | NO |
| `payment_details.customer.location.line_2` | Dirección 2 | String | NO |
| `payment_details.customer.location.city` | Ciudad | String | NO |
| `payment_details.customer.location.state` | Estado | String | NO |
| `payment_details.customer.location.country` | País | String | NO |
Contiene los datos obligatorios de facturación que Flex necesita para procesar la operación.
| Campo | Descripción | Tipo | Obligatorio |
| :------------------------------------------- | :---------------------------------- | :----- | :---------- |
| `payment_details.billing.first_name` | Nombres | String | SI |
| `payment_details.billing.last_name` | Apellidos | String | SI |
| `payment_details.billing.email` | Correo electrónico | String | SI |
| `payment_details.billing.phone` | Objeto con información del teléfono | Object | SI |
| `payment_details.billing.phone.country_code` | Código del país del teléfono | String | SI |
| `payment_details.billing.phone.subscriber` | Número del teléfono | String | SI |
| `payment_details.billing.location` | Objeto con información de ubicación | Object | SI |
| `payment_details.billing.location.line_1` | Dirección 1 | String | SI |
| `payment_details.billing.location.line_2` | Dirección 2 | String | NO |
| `payment_details.billing.location.city` | Ciudad | String | SI |
| `payment_details.billing.location.state` | Estado | String | SI |
| `payment_details.billing.location.country` | País | String | SI |
Incluye la información de envío cuando tu flujo de negocio la necesite para complementar la operación.
| Campo | Descripción | Tipo | Obligatorio |
| :-------------------------------------------- | :---------------------------------- | :----- | :---------- |
| `payment_details.shipping.first_name` | Nombres | String | NO |
| `payment_details.shipping.last_name` | Apellidos | String | NO |
| `payment_details.shipping.email` | Correo electrónico | String | NO |
| `payment_details.shipping.phone` | Objeto con información del teléfono | Object | NO |
| `payment_details.shipping.phone.country_code` | Código del país del teléfono | String | NO |
| `payment_details.shipping.phone.subscriber` | Número del teléfono | String | NO |
| `payment_details.shipping.location` | Objeto con información de ubicación | Object | NO |
| `payment_details.shipping.location.line_1` | Dirección 1 | String | NO |
| `payment_details.shipping.location.line_2` | Dirección 2 | String | NO |
| `payment_details.shipping.location.city` | Ciudad | String | NO |
| `payment_details.shipping.location.state` | Estado | String | NO |
| `payment_details.shipping.location.country` | País | String | NO |
Para S/. 10.50 se debe enviar `1050` y en `currency` el valor `604` para Soles.
En Flex, el objeto raíz debe incluir explícitamente `payment_method: {}` aunque el método final todavía no haya sido seleccionado por el usuario.
### Ejemplo completo
```javascript theme={"system"} theme={"system"}
var payload = {
"action": "authorize",
"channel": "ecommerce",
"merchant_code": "b0deb6f3-e51a-48a7-9268-f1441d46f7bd",
"merchant_operation_number": "221354",
"payment_method": {},
"payment_details": {
"amount": "7000",
"currency": "604",
"billing": {
"first_name": "Levis",
"last_name": "Silvestre",
"email": "levis.silvestre@alignet.com",
"phone": {
"country_code": "+51",
"subscriber": "958435685"
},
"location": {
"line_1": "Av. San Borja Norte 1743",
"line_2": "",
"city": "Lima",
"state": "Lima",
"country": "PE"
}
},
"shipping": {
"first_name": "Levis",
"last_name": "Silvestre",
"email": "levis.silvestre@alignet.com",
"phone": {
"country_code": "+51",
"subscriber": "958435685"
},
"location": {
"line_1": "Av. San Borja Norte 1743",
"line_2": "",
"city": "Lima",
"state": "Lima",
"country": "PE"
}
},
"customer": {
"first_name": "Levis",
"last_name": "Silvestre",
"email": "levis.silvestre@alignet.com",
"phone": {
"country_code": "+51",
"subscriber": "958435685"
},
"identity_document": {
"country": "PER",
"type": "DNI",
"identifier": "72661927"
},
"location": {
"line_1": "Av. San Borja Norte 1743",
"line_2": "",
"city": "Lima",
"state": "Lima",
"country": "PE"
}
}
}
}
```
## 3. Monta el componente
Con el `payload` construido y un `nonce` vigente, crea la instancia de `FlexPaymentForms` y monta el formulario en tu DOM.
Necesitas un `nonce` vigente del [API Nonce](/pagos-virtuales/checkout-web/preparacion) y el `payload` de [Construcción del payload](/pagos-virtuales/checkout-web/integrar-flex) antes de continuar.
### Parámetros del constructor
Expande cada bloque para revisar los campos que puedes enviar al constructor.
| Campo | Tipo | Descripción |
| :-------- | :----------- | :--------------------------------------------------------------------------------------------------------------------------- |
| `nonce` | Alfanumérico | Código encriptado generado en backend mediante el [API Nonce](/pagos-virtuales/checkout-web/preparacion). |
| `payload` | Objeto JSON | Detalles de la compra y del comprador preparados en [Construcción del payload](/pagos-virtuales/checkout-web/integrar-flex). |
Controla el comportamiento visual general del componente.
| Campo | Tipo | Descripción |
| :------------------------------- | :------ | :-------------------------------------------------------- |
| `settings.display_result_screen` | Boolean | Muestra la pantalla de resultado al finalizar el proceso. |
| `settings.show_close_button` | Boolean | Muestra el botón para cerrar el componente. |
| `settings.show_border` | Boolean | Activa o desactiva el borde visual del componente. |
| `settings.show_operation_number` | Boolean | Muestra el número de operación dentro del flujo. |
Define los medios de pago que Flex mostrará al comprador.
| Campo | Tipo | Descripción |
| :------------------------- | :-------------- | :---------------------------------------------------------------------------------------------------------------- |
| `display_settings.methods` | Array de String | Lista necesaria para la visualización. Acepta `CARD`, `YAPE`, `QR`, `BANK_TRANSFER`, `CUOTEALO` o `PAGOEFECTIVO`. |
Debes enviar `display_settings.methods` con los métodos de pago que necesitas visualizar en Flex.
Configura los idiomas disponibles dentro del formulario.
| Campo | Tipo | Descripción |
| :---------------------- | :-------------- | :----------------------------------------------------------------- |
| `i18n.mode` | String | Modo de idiomas. Para este flujo se usa `multi`. |
| `i18n.default_language` | String | Idioma predeterminado: `es` o `en`. |
| `i18n.languages` | Array de String | Lista de idiomas habilitados. Actualmente se soportan `es` y `en`. |
### Inicializar y montar Flex
Envía el `nonce`, el `payload` y la configuración que necesite tu integración.
```javascript theme={"system"} theme={"system"}
const paymentForm = new FlexPaymentForms({
nonce,
payload,
settings: {
display_result_screen: true,
show_close_button: true,
show_border: false,
show_operation_number: true
},
display_settings: {
methods: ["QR", "BANK_TRANSFER", "CARD"]
},
i18n: {
mode: "multi",
default_language: "es",
languages: ["es", "en"]
}
});
```
Agrega al HTML el elemento donde Flex generará su DOM.
```html theme={"system"} theme={"system"}
```
Monta la instancia y entrega las funciones que procesarán la respuesta, el seguimiento y los errores.
```javascript theme={"system"} theme={"system"}
paymentForm.init(
document.querySelector("#flex-container"),
responseCallback,
trackingCallback,
onErrorCallback
);
```
Si defines `i18n.default_language`, utiliza uno de los idiomas incluidos en `i18n.languages`.
`#flex-container` es solo un ejemplo. Puedes usar otro selector, siempre que el elemento exista antes de ejecutar `paymentForm.init(...)`.
Configura la experiencia visual y adapta Flex a tu interfaz y a dispositivos móviles.