Skip to content

finix.js Migration Guide (v1 -> v2)

This guide walks through the changes required to migrate from Finix Tokenization Library v1 to v2.

Why do we have a finix.js v2?

Our finix.js v2 is a major architectural improvement over v1.

While the migration path is intentionally minimal, v2 delivers significant enhancements in security, performance, and flexibility. The underlying tokenization model remains the same, but the delivery, initialization flow, and internal design are now optimized.

What stays the same:

  • Same tokenization flow
  • Drop-in form component with no PCI exposure
  • Same conceptual model of “embed → receive token”

What’s improved:

  • Cleaner initialization
  • Simpler integration code
  • Better separation of configuration vs. runtime behavior
  • Improved form UI

What’s new under the hood:

  • 10× smaller bundle size
  • Fewer internal dependencies
  • Improved security and fraud detection
  • More resilient communication between parent + iframe
  • Stronger isolation of sensitive payment fields

Why this matters:

v2 is built for:

  • Embedded payment experiences
  • Component-based UI frameworks
  • Shadow DOM use cases
  • Web app environments where isolation, reliability, and performance are critical

By simplifying the integration API and optimizing the internal runtime, v2 enables customers to ship more secure and performant PCI-compliant payment experiences with less code.

Overview of What Changed

The migration from v1 to v2 introduces a cleaner initialization model. Most of the library remains familiar, but a few key responsibilities have shifted.

Here are the primary differences:

✔️ Updated Script Version

You'll load v2 instead of v1:

  • v1: https://js.finix.com/v/1/finix.js
  • v2: https://js.finix.com/v/2/finix.js

✔️ TokenForm → PaymentForm

The entry point for embedding changes:

- Finix.TokenForm(...)
+ Finix.PaymentForm(...)

✔️ Initialization Now Includes Environment + Application ID

In v1 these values were passed into .submit():

form.submit("sandbox", "APP_ID", ...)

In v2, they become part of initialization:

Finix.PaymentForm(..., "sandbox", "APP_ID", ...)

✔️ Submit Callback Moves Into Options

In v1, your onSubmit handler existed, but it was only a trigger — you still had to call form.submit() from inside it, and you needed to pass both the environment and the Application ID at that moment.

Example v1 flow:

onSubmit(...) {
  form.submit("sandbox", "APP_ID", (error, response) => { ... });
}

In v2, the form takes care of all submit logic internally, as long as you provide an onSubmit callback upfront. The environment and application are already bound during initialization, so your callback is now just a response handler — much simpler and much safer.

v2 usage:

Finix.PaymentForm(..., {
  onSubmit: (error, response) => {
    // Your callback logic
  }
});

But what if you still want manual submission?

You can still invoke form.submit() in v2.
However, the behavior has changed in a meaningful way:

  • You no longer pass environment and application parameters
  • You do still pass a callback function (just like v1)

In v1, a manual submission looked like:

form.submit("sandbox", "APP_ID", (error, response) => {
  // your code
});

In v2, a manual submission looks like:

form.submit((error, response) => {
  // your callback logic
});

This callback receives:

  • error — any validation or network errors
  • response — the tokenization response

Manual submission is useful when:

  • You want to control precisely when a submission occurs
  • You want to implement custom UI flows
  • You want to handle additional validation or analytics
  • You want to prevent auto-submit and only submit manually

Summary

  • v1 required you to call submit manually and pass the environment and application ID parameters every time.
  • v2 only requires passing onSubmit once, and Finix handles submission automatically.
  • You can still call .submit() manually, but it is now fully context-aware and requires no additional arguments.

The result is a drastically simpler and safer integration model, especially for larger or event-driven applications.

Step-by-Step Migration

1. Update the <script> Source

Before (v1):

<script src="https://js.finix.com/v/1/finix.js"></script>

After (v2):

<script src="https://js.finix.com/v/2/finix.js"></script>

2. Replace TokenForm with PaymentForm

Before:

Finix.TokenForm(...)

After:

Finix.PaymentForm(...)

3. Move Application ID and Environment to Initialization

v1:

form.submit("sandbox", "APP_ID", ...)

v2:

Finix.PaymentForm("finix-form", "sandbox", "APP_ID", options);

4. Move Submit Callback into Options

v1:

form.submit(..., (error, response) => { ... })

v2:

Finix.PaymentForm("finix-form", "sandbox", "APP_ID", {
  onSubmit: (error, response) => { ... }
});

Complete v1 Example (Before Migration)

<script src="https://js.finix.com/v/1/finix.js"></script>

<div id="finix-form"></div>

<script>
  const onSubmit = () => {
    form.submit("sandbox", "APgPDQrLD52TYvqazjHJJchM", (error, response) => {
      const tokenData = response.data || {};
      console.log(tokenData);
    });
  };

  const form = Finix.TokenForm("finix-form", {
    onSubmit,
  });
</script>

Full v2 Example (After Migration)

<script src="https://js.finix.com/v/2/finix.js"></script>

<div id="finix-form"></div>

<script>
  Finix.PaymentForm("finix-form", "sandbox", "APgPDQrLD52TYvqazjHJJchM", {
    onSubmit: (error, response) => {
      const tokenData = response.data || {};
      console.log("Generated token:", tokenData.id);
    }
  });
</script>

PaymentForm API Reference

Finix.PaymentForm(
  element,        // required: DOM ID string OR HTMLElement reference
  environment,    // required: "sandbox" | "prod"
  applicationId,  // required: must belong to chosen environment
  options         // optional: behavior customization, including onSubmit
);

Element Parameter Details

You may pass either:

1) A DOM element ID (string):

Finix.PaymentForm("finix-form", "sandbox", "APP_ID");

2) A DOM reference:

const container = document.getElementById("finix-form");
Finix.PaymentForm(container, "sandbox", "APP_ID");

DOM references improve compatibility with:

  • Shadow DOM
  • Web components
  • Micro frontends
  • Modern UI frameworks

Environment + Application ID Rules

  • Allowed environments: sandbox and prod

  • Your Application ID must belong to the same environment to ensure you are tokenizing against the correct environment/services.

    • Sandbox ID + prod = will fail
    • Prod ID + sandbox = will fail

Migration Checklist

  • Update script reference to /v/2/
  • Replace TokenForm with PaymentForm
  • Move Application ID from submit to initialization
  • Move environment from submit to initialization
  • (Optional) Move submission callback to onSubmit option
  • Test token generation

Complete Example (v2)

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width,initial-scale=1" />
  <title>Payment Form Minimal</title>

  <style>
    #finix-form {
      width: 50%;
      margin: 0 auto;
      max-width: 600px;
      min-width: 200px;
    }
  </style>

  <script src="https://js.finix.com/v/2/finix.js"></script>
</head>
<body>
  <h1>Payment Form Test Page</h1>
  <div id="finix-form"></div>

  <script>
    Finix.PaymentForm("finix-form", "sandbox", "APgPDQrLD52TYvqazjHJJchM", {
      onSubmit: (error, response) => {
        const tokenData = response.data || {};
        console.log("Generated token:", tokenData.id);
      }
    });
  </script>
</body>
</html>

Accepted Payment Methods (Cards vs. Bank Accounts)

In v1, you needed to control accepted payment methods at the initializer level, which required switching payment methods and swapping initializer functions.

  • TokenForm() — supported both card + bank
  • CardTokenForm() — supported card only
  • BankTokenForm() — supported bank only

v2 Simplifies This with a Single Initializer

In v2, there is only one initializer (Finix.PaymentForm()), and you configure the acceptable payment methods with the paymentMethods option.

Default behavior:

paymentMethods: ["card", "bank"];

This matches TokenForm() from v1 (both are accepted).

To accept only card:

paymentMethods: ["card"];

To accept only bank:

paymentMethods: ["bank"];

Migration Mapping

v1 initializerv2 equivalent
TokenForm()Finix.PaymentForm(..., { paymentMethods: ["card","bank"] }) (default)
CardTokenForm()Finix.PaymentForm(..., { paymentMethods: ["card"] })
BankTokenForm()Finix.PaymentForm(..., { paymentMethods: ["bank"] })

Example Usage

Example: Card-Only Form

Finix.PaymentForm("finix-form", "sandbox", "APP_ID", {
  paymentMethods: ["card"],
  onSubmit: (error, response) => {
    console.log("Generated token:", response?.data?.id);
  }
});

Example: Bank-Only Form

Finix.PaymentForm("finix-form", "sandbox", "APP_ID", {
  paymentMethods: ["bank"],
  onSubmit: (error, response) => {
    console.log("Generated token:", response?.data?.id);
  }
});

Example: (Default) Card + Bank

Finix.PaymentForm("finix-form", "sandbox", "APP_ID", {
  // paymentMethods default to ["card", "bank"],
  onSubmit: (error, response) => {
    console.log("Generated token:", response?.data?.id);
  }
});

Support

For migration assistance:

We're here to help you transition as smoothly as possible.