finix.js Migration Guide (v1 to v2)

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:

What’s improved:

What’s new under the hood:

Why this matters:

v2 is built for:

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.

✔️ Updated Script Version

You'll load v2 instead of v1:

✔️ 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:

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:

Manual submission is useful when:

Summary

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");
  1. A DOM reference:
const container = document.getElementById("finix-form");
Finix.PaymentForm(container, "sandbox", "APP_ID");

Environment + Application ID Rules

Migration Checklist

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.

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

To accept only card:

paymentMethods: ["card"];

To accept only bank:

paymentMethods: ["bank"];

Migration Mapping

v1 initializer v2 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.