Inicializar 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 y el payload de Construcción del payload antes de continuar.

Parámetros del constructor

Expande cada bloque para revisar los campos que puedes enviar al constructor.

Datos obligatorios

Campo	Tipo	Descripción
`nonce`	Alfanumérico	Código encriptado generado en backend mediante el API Nonce.
`payload`	Objeto JSON	Detalles de la compra y del comprador preparados en Construcción del payload.

Objeto settings

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.

Objeto display_settings

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.

Objeto i18n

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

Crea la instancia

Envía el nonce, el payload y la configuración que necesite tu integración.

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"]
  }
});

Crea el contenedor

Agrega al HTML el elemento donde Flex generará su DOM.

<div id="flex-container"></div>

Renderiza el formulario

Monta la instancia y entrega las funciones que procesarán la respuesta, el seguimiento y los errores.

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

Comportamiento responsive

Flex conserva su estructura interna mientras el contenedor externo calcula una escala adecuada para el viewport.

Web

Mantiene la escala original cuando el formulario cabe en la ventana.

Celular

Reduce el formulario proporcionalmente para evitar cortes horizontales.

Contenido dinámico

Recalcula la altura cuando Flex cambia de paso o método de pago.

Ejemplo de implementación

Este ejemplo visual usa una presentación popup. La inicialización, los callbacks y el desmontaje descritos más adelante también aplican a las presentaciones embebida y expandida.

Estructura HTML
Estilos base
Lógica responsive
Desmontar Flex

<div id="payment-modal" class="flex-modal" role="dialog" aria-hidden="true">
  <div class="flex-modal__content">
    <div id="flex-container"></div>
  </div>
</div>

:root {
  --flex-responsive-scale: 1;
  --flex-natural-width: 415px;
  --flex-natural-height: 656px;
}

.flex-modal {
  position: fixed;
  inset: 0;
  z-index: 1000;
  display: none;
  padding: 15px 20px;
  overflow: hidden;
  background: rgb(0 18 37 / 48%);
}

.flex-modal.is-open {
  display: flex;
  align-items: center;
  justify-content: center;
}

.flex-modal__content {
  width: var(--flex-natural-width);
  height: var(--flex-natural-height);
  max-width: calc(100vw - 40px);
  max-height: calc(100vh - 30px);
  max-height: calc(100dvh - 30px);
  transform: scale(var(--flex-responsive-scale));
  transform-origin: center;
}

#flex-container {
  width: 100%;
  height: 100%;
}

const FLEX_RESPONSIVE_LAYOUT = {
  naturalWidth: 415,
  naturalHeight: 656,
  viewportPaddingHorizontal: 40, // 20 px a cada lado
  viewportPaddingVertical: 30,   // 15 px arriba y abajo
  minimumScale: 0.25
};

function calculateResponsiveScale() {
  const viewportWidth = window.visualViewport?.width ?? window.innerWidth;
  const viewportHeight = window.visualViewport?.height ?? window.innerHeight;
  const availableWidth =
    viewportWidth - FLEX_RESPONSIVE_LAYOUT.viewportPaddingHorizontal;
  const availableHeight =
    viewportHeight - FLEX_RESPONSIVE_LAYOUT.viewportPaddingVertical;

  return Math.max(
    FLEX_RESPONSIVE_LAYOUT.minimumScale,
    Math.min(
      1,
      availableWidth / FLEX_RESPONSIVE_LAYOUT.naturalWidth,
      availableHeight / FLEX_RESPONSIVE_LAYOUT.naturalHeight
    )
  );
}

function updateResponsiveScale() {
  const responsiveScale = calculateResponsiveScale();
  document.documentElement.style.setProperty(
    "--flex-responsive-scale",
    String(responsiveScale)
  );
}

// Aplica la escala inicial y la recalcula cuando cambia el viewport.
updateResponsiveScale();
window.addEventListener("resize", updateResponsiveScale);
window.visualViewport?.addEventListener("resize", updateResponsiveScale);

// Muestra el modal.
const paymentModal = document.querySelector("#payment-modal");
paymentModal.classList.add("is-open");
paymentModal.setAttribute("aria-hidden", "false");

// Inicializa Flex.
paymentForm.init(
  document.querySelector("#flex-container"),
  responseCallback,
  trackingCallback,
  onErrorCallback
);

function unmountFlex() {
  window.removeEventListener("resize", updateResponsiveScale);
  window.visualViewport?.removeEventListener("resize", updateResponsiveScale);

  paymentForm.terminate?.();

  const flexContainer = document.querySelector("#flex-container");
  flexContainer.innerHTML = "";
}

Ciclo de vida de la instancia

paymentForm.terminate?.() finaliza los procesos internos, listeners y recursos que mantiene la instancia de Flex. Esta operación es diferente de eliminar el formulario del DOM (flexContainer.innerHTML = "") y aplica a cualquier tipo de presentación.

El operador ?. ejecuta terminate() solo cuando el método existe. Esto evita un error si la versión cargada de Flex no implementa ese método.

Cuándo desmontar según la presentación

Presentación	Cuándo desmontar	Acción visual posterior
Embebida	Cuando ocultas el checkout, cambias de sección o navegas a otra pantalla.	Retira o reemplaza el contenido donde estaba Flex.
Popup (modal)	Cuando el comprador cierra el popup o termina el flujo.	Oculta el overlay y devuelve el foco a la interfaz principal.
Expandida	Cuando contraes el checkout o abandonas la vista expandida.	Contrae el panel o restaura el layout anterior.

En los tres casos, primero procesa cualquier resultado pendiente y luego ejecuta unmountFlex() antes de actualizar la presentación visual.

No modifiques los estilos internos de Flex. Ejecuta unmountFlex() cuando retires el formulario, sin importar si está embebido, dentro de un popup o en una vista expandida.

Pantalla de resultado propia

Cuando configuras settings.display_result_screen: false, Flex no presenta su pantalla final. Tu aplicación debe recibir el response, evaluar el estado de la transacción y mostrar una pantalla de resultado propia.

Monta el formulario

paymentForm.init(...) renderiza Flex dentro del contenedor.

Recibe el resultado

Flex ejecuta responseCallback(response). Lee el resultado desde response.transaction.state y realiza las validaciones de negocio correspondientes.

Muestra tu pantalla

Guarda el response en el estado de tu aplicación y navega o renderiza la pantalla de resultado del comercio.

Desmonta Flex

Cuando el resultado ya fue procesado, ejecuta terminate(), limpia el contenedor y actualiza la presentación embebida, popup o expandida.

const paymentForm = new FlexPaymentForms({
  nonce,
  payload,
  settings: {
    display_result_screen: false
  }
});

const flexContainer = document.querySelector("#flex-container");

paymentForm.init(
  flexContainer,
  (response) => {
    const transactionState = response.transaction?.state;

    // Procesa y conserva la respuesta antes de desmontar Flex.
    showMerchantResultScreen({ transactionState, response });
    unmountFlex();
  },
  (tracking) => {
    console.log("Evento de seguimiento", tracking);
  },
  (error) => {
    console.error("Error de Flex", error);
  }
);

No ejecutes terminate() antes de recibir y procesar responseCallback(response). Si finalizas la instancia antes, puedes interrumpir el flujo y perder el resultado que Flex todavía no ha entregado.

Limpieza reutilizable

Encapsula la inicialización y el desmontaje en un controlador independiente del framework. Puedes usarlo desde JavaScript puro o conectarlo al ciclo de vida de React, Vue, Angular u otra tecnología.

function createFlexController({
  container,
  configuration,
  onResult,
  onTracking,
  onError
}) {
  let instance = null;

  function mount() {
    // Evita conservar una instancia anterior al volver a abrir Flex.
    destroy();

    instance = new FlexPaymentForms(configuration);
    instance.init(container, onResult, onTracking, onError);
  }

  function destroy() {
    instance?.terminate?.();
    instance = null;
    container.replaceChildren();
  }

  return { mount, destroy };
}

const flexController = createFlexController({
  container: document.querySelector("#flex-container"),
  configuration: {
    nonce,
    payload,
    settings: {
      display_result_screen: false
    }
  },
  onResult: responseCallback,
  onTracking: trackingCallback,
  onError: onErrorCallback
});

// Abre o vuelve a crear el formulario.
flexController.mount();

// Finaliza la instancia al cerrar, navegar o retirar la presentación.
// flexController.destroy();

JavaScript

Ejecuta destroy() antes de retirar el contenedor de la página.

Aplicación SPA

Conecta destroy() al cambio de ruta o al desmontaje de la vista.

Presentación dinámica

Ejecútalo al ocultar el bloque embebido, cerrar el popup o contraer la vista expandida.

container.replaceChildren() vacía el contenido de forma equivalente a container.innerHTML = "", sin depender de un framework específico.

terminate() no devuelve la respuesta del pago. El resultado siempre llega mediante el primer callback de paymentForm.init(...). Revisa Capturar funciones callback para interpretar y confirmar la operación.

Gestionar el cierre con show_close_button

Configura settings.show_close_button: true para mostrar el botón de cierre nativo de Flex. Esta opción funciona en las presentaciones embebida, popup y expandida.

const paymentForm = new FlexPaymentForms({
  nonce,
  payload,
  settings: {
    show_close_button: true
  }
});

Cuando el comprador pulsa el botón, Flex envía el mensaje cerro el carrito mediante onErrorCallback. Aunque utiliza el callback de error, este mensaje representa una acción voluntaria del comprador y no un fallo técnico.

Mostrar el botón

Activa show_close_button dentro de settings.

Interpretar el evento

Identifica el mensaje exacto cerro el carrito en onErrorCallback.

Cerrar la presentación

Ejecuta onClose() para desmontar Flex y actualizar la interfaz.

Implementa una rama exclusiva para el cierre voluntario y conserva los demás mensajes como errores técnicos:

function getFlexErrorMessage(error) {
  if (typeof error === "string") return error;
  return error?.message ?? "";
}

function onErrorCallback(error) {
  const errorMessage = getFlexErrorMessage(error).trim();

  if (errorMessage === "cerro el carrito") {
    onClose();
    return;
  }

  // Los demás mensajes se procesan como errores técnicos.
  handleFlexError(error);
}

function onClose() {
  unmountFlex();

  // Oculta el popup, retira el bloque embebido o contrae la vista expandida.
  hideFlexPresentation();
}

El flujo de cierre es show_close_button → onErrorCallback → onClose() → unmountFlex(). hideFlexPresentation() representa la lógica visual de tu aplicación: retirar el bloque embebido, ocultar el popup o contraer la vista expandida.

Ejecuta onClose() solo cuando el mensaje completo sea cerro el carrito. Cualquier otro valor recibido en onErrorCallback debe continuar por el manejo de errores técnicos.

Antes de publicar

Comprueba el componente en estos escenarios:

Escenario	Resultado esperado
Web con viewport amplio	El formulario conserva la escala `1` y queda centrado.
Celular vertical y horizontal	No aparece scroll horizontal ni contenido cortado.
Cambio de orientación	La escala se recalcula sin reinicializar Flex.
Cambio de paso o método	La nueva altura permanece dentro del viewport.
Teclado virtual abierto	Los campos activos continúan visibles y utilizables.

Los callbacks no reemplazan la confirmación del pago desde backend. Continúa con la guía de callbacks para interpretar el resultado.

Siguiente paso

Capturar funciones callback

Define responseCallback, trackingCallback y onErrorCallback para reaccionar correctamente al flujo.

Construcción del payload

Si todavía no armaste el objeto de la operación, vuelve a la guía del payload.

Primeros pasos

Integración

Pagos

Gestión y Operaciones

Parámetros del constructor

Inicializar y montar Flex

Comportamiento responsive

Web

Celular

Contenido dinámico

Ejemplo de implementación

Ciclo de vida de la instancia

Cuándo desmontar según la presentación

Pantalla de resultado propia

Limpieza reutilizable

JavaScript

Aplicación SPA

Presentación dinámica

Gestionar el cierre con show_close_button

Mostrar el botón

Interpretar el evento

Cerrar la presentación

Antes de publicar

Siguiente paso

Capturar funciones callback

Construcción del payload

​Parámetros del constructor

​Inicializar y montar Flex

​Comportamiento responsive

Web

Celular

Contenido dinámico

​Ejemplo de implementación

​Ciclo de vida de la instancia

​Cuándo desmontar según la presentación

​Pantalla de resultado propia

​Limpieza reutilizable

JavaScript

Aplicación SPA

Presentación dinámica

​Gestionar el cierre con show_close_button

Mostrar el botón

Interpretar el evento

Cerrar la presentación

​Antes de publicar

​Siguiente paso

Capturar funciones callback

Construcción del payload

Parámetros del constructor

Inicializar y montar Flex

Comportamiento responsive

Ejemplo de implementación

Ciclo de vida de la instancia

Cuándo desmontar según la presentación

Pantalla de resultado propia

Limpieza reutilizable

Gestionar el cierre con show_close_button

Antes de publicar

Siguiente paso