Initialize the component

with payload built and nonce and established an instance of FlexPaymentForms and put the form on your DOM.

You need a nonce Current API Nonce and payload of Construction of payload before we continue.

Building parameters

Expand every block to check the fields you can send to the builder.

Mandatory information

Field	Type	Description
`nonce`	Alphanumeric	Code encryption generated by backend API Nonce.
`payload`	Subject matter JSON	Details of purchase and buyer prepared at Construction of payload.

Settings

Control the general visual performance of the component.

Field	Type	Description
`settings.display_result_screen`	Boolean	Display the result screen at the end of the process.
`settings.show_close_button`	Boolean	Display the button to close the component.
`settings.show_border`	Boolean	It activates or deactivates the visual edge of the component.
`settings.show_operation_number`	Boolean	It shows the operation number inside the flow.

Object display_sittings

Define the means of payment that Flex will show the buyer.

Field	Type	Description
`display_settings.methods`	Array de String	List necessary for viewing. Accept `CARD`, `YAPE`, `QR`, `BANK_TRANSFER`, `CUOTEALO` or `PAGOEFECTIVO`.

You have to send display_settings.methods with the payment methods you need to visualise at Flex.

Subject matter

Configure available languages within form.

Field	Type	Description
`i18n.mode`	String	Language mode. For this flow it’s used `multi`.
`i18n.default_language`	String	Undetermined language: `es` or `en`.
`i18n.languages`	Array de String	List of authorized languages. currently supported `es` and `en`.

Initiate and mount Flex

It creates an instance

Send the nonce, payload and the configuration that your integration needs.

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

Create the container

Add to HTML the element where Flex will generate their DOM.

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

Surrender form

Fits the instance and delivers the functions that will process the response, monitoring and errors.

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

If you define i18n.default_languageand uses one of the languages listed in i18n.languages.

#flex-container That’s just an example. Can use another selector as long as the item exists before running paymentForm.init(...).

Responsive conduct

Flex retains its internal structure while the outer container calculates an appropriate scale for viewing.

Web

Keep the original scale as soon as the form fits into the window.

Cell

Reduces the form proportionally to avoid horizontal cuts.

Dynamic constore

Refigure height when Flex change of passage or payment method.

Example of implementation

That visual example uses a popular presentation. The initialization, callbacks and dismantling described above also apply to drunk and expanded presentations.

Structure HTML
Base Styles
Responsible logic
Unmount 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 = "";
}

Life cycle of the instance

paymentForm.terminate?.() complete the internal processes, list and resources that maintain the Flex. That operation is different from eliminating the form from DOM (flexContainer.innerHTML = "") and applying to any type of presentation.

The operator ?. run terminate() only when the method exists. That prevents an error if the loaded version of Flex Do not implement that method.

When to dismount according to presentation

Presentation	When to Unmount	Following visual action
Drink	When you hide the checkout, you change Section or navigate to another screen.	Withdraw or replace the constore where it was Flex.
Popup (modal)	When the buyer closes his pup or his flow ends.	Hide the overlay and return the focus to the main interface.
Expand	When you get a check out or leave an expanded vision.	Take the panel or restore the earlier Layout.

In all 3 cases, first process any outstanding result and then run unmountFlex() before updating the visual presentation.

Do not modify the internal styles of Flex. Execut unmountFlex() When you withdraw the form, regardless of whether it’s embedded, into a popup or an expanded view.

own result screen

When you set up settings.display_result_screen: false, Flex doesn’t have his final screen. Your application should get the response, evaluate the status of the transaction and display an own result screen.

Mount form

paymentForm.init(...) challenges Flex inside the container.

Receives result

Flex run responseCallback(response). Read the result from response.transaction.state and conduct related business validations.

Show your screen

Save the response at the status of your application and navigate or render the result screen from the merchant.

Unmount Flex

When the result has been processed, run terminate(), cleanes the container and updates the presentation drunk, popup or expanded.

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

Don’t run terminate() before receiving and processing responseCallback(response). If you finish the instance earlier, you can stop the flow and lose the result that Flex He’s been put up.

Reusable cleaning

It encapsulates initiation and dismantling into an independent framework controller. You can use them from pure JavaScript or connect them to React’s life cycle, Vue, Angular or other technologies.

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

Execut destroy() before withdrawing the container from the page.

Implementation SPA

Connect destroy() to change of path or to dismount vision.

Dynamic presentation

Do so by hiding the embossed block, closing the Popup or getting an expanded view.

container.replaceChildren() an empty constore equivalent to container.innerHTML = ""without dependent on a specific framework.

terminate() does not return the payment response. The result always comes with the first call of paymentForm.init(...). Check. Capture callback functions to interpret and confirm the operation.

Management of closure with show_close_button

Figure settings.show_close_button: true to display the native clasp of Flex. That option works with embumbing, pounding and expanding presentations.

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

When the buyer presses the button, Flex send message cerro el carrito with onErrorCallback. Although using the error call, this message represents a voluntary action by the buyer and not a technical failure.

Show the button

Active show_close_button inside settings.

Play the event

Identifies the exact message cerro el carrito in onErrorCallback.

Close presentation

Execut onClose() for dismantling Flex and update the interface.

It implements an exclusive branch for voluntary closure and preserves other messages as technical errors:

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

The closing flow is show_close_button → onErrorCallback → onClose() → unmountFlex(). hideFlexPresentation() represents the visual logic of your application: remove the embedded block, hide the popup or get an expanded view.

Execut onClose() only after complete message cerro el carrito. Any other value received at onErrorCallback have to continue to manage technical errors.

Before posting

Check the component in these scenarios:

Scenario	Expected result
Wide viewing web	The form keeps the scale `1` and it’s focused.
Vertical and horizontal cell	No horizontal scroll or cut constore appears.
Retirement	The scale recalculates without re-initializing Flex.
Change of step or method	The new height remains inside the Viewport.
Virtual keyboard open	Active fields are still visible and usable.

The callbacks do not replace payment confirmation from backend. Continue with the callback guide to interpret the result.

Next step

Capture callback functions

Define responseCallback, trackingCallback and onErrorCallback to react correctly to the flow.

Construction of payload

If you haven’t put up an operation’s item, come back to the guide to payload.

Getting started

Integration

Payments

Building parameters

Initiate and mount Flex

Responsive conduct

Web

Cell

Dynamic constore

Example of implementation

Life cycle of the instance

When to dismount according to presentation

own result screen

Reusable cleaning

JavaScript

Implementation SPA

Dynamic presentation

Management of closure with show_close_button

Show the button

Play the event

Close presentation

Before posting

Next step

Capture callback functions

Construction of payload

​Building parameters

​Initiate and mount Flex

​Responsive conduct

Web

Cell

Dynamic constore

​Example of implementation

​Life cycle of the instance

​When to dismount according to presentation

​own result screen

​Reusable cleaning

JavaScript

Implementation SPA

Dynamic presentation

​Management of closure with show_close_button

Show the button

Play the event

Close presentation

​Before posting

​Next step

Capture callback functions

Construction of payload

Building parameters

Initiate and mount Flex

Responsive conduct

Example of implementation

Life cycle of the instance

When to dismount according to presentation

own result screen

Reusable cleaning

Management of closure with show_close_button

Before posting

Next step