4. Results and cleanup

← Checkout Web overviewSTEP 04 / 05

When you call paymentForm.init(...), Flex accepts three callback functions. The main payment result reaches your frontend through responseCallback(response).

Use responseCallback(response) as the main entry point for frontend results. The returned JSON follows the E-commerce authorization API structure for the payment method selected in Flex.

Callbacks available

responseCallback

Runs when the flow reaches a business outcome and returns the JSON response.

trackingCallback

Runs for flow events such as method changes, clicks or progress through the form.

onErrorCallback

Runs when a technical error occurs while loading or running the component.

Example of implementation

function responseCallback(response) {
    console.log("-------Response-------");
    console.log({response});
}

function trackingCallback(trackdata) {
    console.log("-------Event tracking-------");
    console.log({trackdata});
}

function onErrorCallback(error) {
    console.log("-------Processing error-------");
    console.log({error});
}

paymentForm.init(
    document.querySelector("#demo"),
    responseCallback,
    trackingCallback,
    onErrorCallback
);

How to interpret responseCallback

The field response.payment_method indicates what reference to PayIn you have to use to interpret the JSON response returned by Flex.

Do not use response.meta.status.code to decide whether a payment was approved or declined. It only describes service processing. Read response.transaction.state and confirm the result from your backend using a query or server notifications for the payment method.

The response object follows the contract of Card authorization API.If your flow uses Redirect or 3DS authentication outside the same screen, complete this reading with Considerations for Redirect methods.

The response object follows the contract of Yape authorization API.Even when the result arrives through responseCallback, validate consistency from the backend before confirming the order.

The response object follows the contract of Bank transfer authorization API.This method may require later confirmation. Do not use the frontend as the only source of truth; use Consultation or Notifications.

The response object follows the contract of QR authorization API.Generating a QR or displaying an initial response does not confirm final payment. Use Consultation or Notifications to complete your business logic.

The response object follows the contract of Cuotéalo authorization API.Confirm the final state after redirection or follow-up using Consultation or Notifications.

The response object follows the contract of PagoEfectivo authorization API.Generating a CIP or payment link does not mean funds have been received. Confirm the result using Consultation or Notifications.

Use trackingCallback for events and onErrorCallback for technical failures. Neither replaces the business logic built around responseCallback and backend confirmation.

Life cycle of the instance

The following examples use unmountFlex() from the responsive example. Adapt cleanup to your presentation: embedded, popup or expanded.

paymentForm.terminate?.() ends Flex’s internal processes, listeners and resources. This is different from removing the form from the DOM (flexContainer.innerHTML = "") and applies to every presentation type.

The ?. operator calls terminate() only if the method exists. This avoids errors if the loaded Flex version does not implement it.

When to unmount each presentation

Presentation	When to Unmount	Following visual action
Embedded	When hiding checkout, changing sections or navigating to another screen.	Remove or replace the container that held Flex.
Popup (modal)	When the customer closes the popup or the flow ends.	Hide the overlay and return the focus to the main interface.
Expand	When collapsing checkout or leaving an expanded view.	Collapse the panel or restore the previous 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. Call unmountFlex() When you withdraw the form, regardless of whether it’s embedded, into a popup or an expanded view.

Your own result screen

With settings.display_result_screen: false, Flex does not display its final screen. Your application must receive the response, evaluate the transaction state and display its own result screen.

Mount form

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

Receives result

Flex runs responseCallback(response). Read response.transaction.state and perform the relevant business validations.

Show your screen

Save response in your application state, then navigate to or render your result screen.

Unmount Flex

After processing the result, call terminate(), clear the container and update the embedded, popup or expanded presentation.

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;

    // Process and retain the response before unmounting Flex.
    showMerchantResultScreen({ transactionState, response });
    unmountFlex();
  },
  (tracking) => {
    console.log("Tracking event", tracking);
  },
  (error) => {
    console.error("Flex error", error);
  }
);

Do not call terminate() before receiving and processing responseCallback(response). Ending the instance early can interrupt the flow and lose the result Flex was about to return.

Reusable cleanup

Encapsulate initialization and cleanup in a framework-independent controller. Use it in plain JavaScript or connect it to the lifecycle of React, Vue, Angular or another framework.

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

  function mount() {
    // Avoid retaining a previous instance when reopening 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
});

// Open or recreate the form.
flexController.mount();

// Destroy the instance when closing, navigating away or removing the view.
// flexController.destroy();

JavaScript

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

SPA integration

Call destroy() on route changes or when unmounting the view.

Dynamic presentation

Call it when hiding the embedded block, closing the popup or collapsing an expanded view.

container.replaceChildren() clears the container, like container.innerHTML = "", without depending on a framework.

terminate() does not return the payment response. The result arrives through the first callback passed to paymentForm.init(...). See Capture callback functions to interpret and confirm the operation.

Management of closure with show_close_button

Set settings.show_close_button: true to display the native Flex close button. This works with embedded, popup and expanded presentations.

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

When the customer presses the button, Flex sends cerro el carrito through onErrorCallback. Although it uses the error callback, this message represents a voluntary customer action, not a technical failure. Keep this literal message unchanged in code.

Show the button

Enable show_close_button in settings.

Handle the event

Identify the exact message cerro el carrito in onErrorCallback.

Close presentation

Call onClose() to unmount Flex and update the interface.

Implement a separate branch for voluntary closure and handle 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;
  }

  // Handle other messages as technical errors.
  handleFlexError(error);
}

function onClose() {
  unmountFlex();

  // Hide the popup, remove the embedded block or collapse the expanded view.
  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 collapse an expanded view.

Call onClose() only after matching the exact message cerro el carrito. Continue handling any other value received by onErrorCallback as a technical error.

5. Testing and production

Review security, functional tests and production readiness.

Getting started

Integration

Migration

Payments

Callbacks available

responseCallback

trackingCallback

onErrorCallback

Example of implementation

How to interpret responseCallback

Life cycle of the instance

When to unmount each presentation

Your own result screen

Reusable cleanup

JavaScript

SPA integration

Dynamic presentation

Management of closure with show_close_button

Show the button

Handle the event

Close presentation

5. Testing and production

​Callbacks available

responseCallback

trackingCallback

onErrorCallback

​Example of implementation

​How to interpret responseCallback

​Life cycle of the instance

​When to unmount each presentation

​Your own result screen

​Reusable cleanup

JavaScript

SPA integration

Dynamic presentation

​Management of closure with show_close_button

Show the button

Handle the event

Close presentation

5. Testing and production

Callbacks available

Example of implementation

How to interpret responseCallback

Life cycle of the instance

When to unmount each presentation

Your own result screen

Reusable cleanup

Management of closure with show_close_button