Tokenization Forms

Use Tokenization Forms to collect and tokenize the payment details of buyers. Our Tokenization Form offers a low-code solution to easily take in credit card and bank data and tokenize in a PCI-compliant way.

Finix’s Tokenization Forms provide flexible customization options, including the ability to:

• Show and hide specific fields
• Customize labels and placeholder text
• Modify error messages to match your brand's voice
• Control input styling both inside and outside the iframe
• Accept both card and ACH payment methods in a single form
• Use custom fonts within the embedded iframe
• Pre-fill values for select fields
• Manage multiple forms on the same page simultaneously

There are three Tokenization Forms available:

• A TokenForm to accept both card numbers and bank accounts.
• A CardTokenForm to only accept credit or debit cards.
• A BankTokenForm that access both USA and CAN bank accounts.

Every Tokenization Form uses a versioned finix.js JavaScript library to secure sensitive card and bank account data. Having buyers input their data into a Tokenization Form prevents third parties from accessing the submitted information.

Once initialized, the library communicates the state of the form through a JavaScript callback. The state object includes logic that validates the payment details submitted by the buyer.

Tokenization Overview

Step 1: Send token information via finix.js

Install finix.js library

First, we'll need to add the finix.js library to the webpage hosting the form that collects payment details.

To add the library, include the following the script:

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

Using this URL will automatically update the finix.js library to the latest V1 version.

Versioning

You can lock your form to a specific version of the finix.js library to ensure consistent behavior and avoid unexpected changes from future updates. To specify a finix.js library version to use, update the URL to your desired version. This example uses V1.2.3 of the finix.js library:

<script
    type="text/javascript"
    src="https://js.finix.com/v/1/2/3/finix.js"
></script>

Initialize the Tokenization Form

Initialize the form with:

const form = window.Finix.TokenForm("form-elements", options);

const form = window.Finix.CardTokenForm("form-elements", options);

const form = window.Finix.BankTokenForm("form-elements", options);

Define Input Fields

Next, define and customize what exact fields will be included and required in the Tokenization Form.

Aspects of the input fields you can change include:

Style Tokenization Form

Style the Tokenization Form with your brand identity and colors.

Styling you can change includes:

View our HTML example above to see how you can style the form inputs.

We'll also need to configure what happens when the buyer submits the form. Specifically, the form needs to:

• Register a click event that fires when the buyer submits their information.
• Define a callback for handling the response.

Create a function that submits the form and handles the response. Include your Application ID, so the library submits the field values under your account during the executed POST request.

const onSubmit = () => {
    form.submit("sandbox", "APgPDQrLD52TYvqazjHJJchM", function (err, res) {
        // call the form submit function and supply the environment and application ID to submit under
        const tokenData = res.data || {};
        const token = tokenData.id;
    });
};

This onSubmit function can either be:

• Passed to the Form options object to automatically create a submit button.
• Added to a custom submit button. You can do this by adding a click event handler to your custom button that calls this onSubmit function.

Arguments

Step 2. Handle Response from finix.js

Finix will return back a token with a prefix of TK.

{
  "id" : "TKeD6uad8xZc52Rqg1VhvSBw",
  "created_at" : "2025-06-10T00:31:53.54Z",
  "updated_at" : "2025-06-10T00:31:53.54Z",
  "currency" : "USD",
  "expires_at" : "2025-06-11T00:31:53.54Z",
  "fingerprint" : "FPRrcobjtdU98gr4sjiqYR1Qg",
  "instrument_type" : "PAYMENT_CARD"
}

Once you've handled the response, store the ID to utilize the token in the future. You will eventually send the token ID from your front-end client to your back-end server.

    const tokenData = res.data || {};     // get token ID from response
    const token = tokenData.id;
    function handleResponse(response) // This would be your custom logic

Many customers implement additional logic after a buyer enters their payment information, using the returned token. For example, some customers choose to implement a different workflow depending if a PAYMENT_CARD or BANK_ACCOUNT is returned by finix.js.

Step 3. Send response to your backend

Now that you have the token, you should send this to your backend. You will need this ID to eventually do an authenticated call to Finix in the next step.

fetch('/your/backend', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ token: token }),
})

Fraud Detection

We recommend also collecting a fraud_session_id to detect and block potentially fraudulent payments.

For more information, see Fraud Detection.

Step 4: Send an authenticated request to Finix to claim the Payment Instrument

Create Buyer Identity

Before you can run a Sale or an Authorization, you'll need:

• Create an Identity for the buyer.
• Create a Payment Instrument with the created Identity and the token from the previous step.

You can create an Identity with minimal or no information.

• To avoid asking for the same info multiple times, you don't need to request additional information from the buyer when creating an Identity.
• You don't need to create an additional Identity for the buyer if one already exists.

To create an Identity, make a POST request with whatever details you've gathered (e.g. name, email, phone), or create an empty Identity by leaving the entity empty:

curl https://finix.sandbox-payments-api.com/identities \
  -H "Content-Type: application/json" \
  -H 'Finix-Version: 2022-02-01' \
  -u  USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
  -d '{
    "entity": {}
  }'

{
  "id" : "IDjeAJX9kXMyGVvp8PQjGJH7",
  "created_at" : "2025-06-10T20:36:01.15Z",
  "updated_at" : "2025-06-10T20:36:01.15Z",
  "application" : "APgPDQrLD52TYvqazjHJJchM",
  "entity" : {
    "ach_max_transaction_amount" : 0,
    "amex_mid" : null,
    "annual_card_volume" : 0,
    "business_address" : null,
    "business_name" : null,
    "business_phone" : null,
    "business_tax_id_fingerprint" : null,
    "business_tax_id_provided" : false,
    "business_type" : null,
    "default_statement_descriptor" : null,
    "discover_mid" : null,
    "dob" : null,
    "doing_business_as" : null,
    "email" : null,
    "first_name" : null,
    "has_accepted_credit_cards_previously" : false,
    "incorporation_date" : null,
    "last_name" : null,
    "max_transaction_amount" : 0,
    "mcc" : null,
    "ownership_type" : null,
    "personal_address" : {
      "line1" : null,
      "line2" : null,
      "city" : null,
      "region" : null,
      "postal_code" : null,
      "country" : null
    },
    "phone" : null,
    "principal_percentage_ownership" : null,
    "short_business_name" : null,
    "tax_authority" : null,
    "tax_id_fingerprint" : null,
    "tax_id_provided" : false,
    "title" : null,
    "url" : null
  },
  "identity_roles" : [ ],
  "tags" : { },
  "type" : "PERSONAL",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDjeAJX9kXMyGVvp8PQjGJH7"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDjeAJX9kXMyGVvp8PQjGJH7/verifications"
    },
    "merchants" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDjeAJX9kXMyGVvp8PQjGJH7/merchants"
    },
    "settlements" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDjeAJX9kXMyGVvp8PQjGJH7/settlements"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDjeAJX9kXMyGVvp8PQjGJH7/authorizations"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDjeAJX9kXMyGVvp8PQjGJH7/transfers"
    },
    "payment_instruments" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDjeAJX9kXMyGVvp8PQjGJH7/payment_instruments"
    },
    "associated_identities" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDjeAJX9kXMyGVvp8PQjGJH7/associated_identities"
    },
    "disputes" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDjeAJX9kXMyGVvp8PQjGJH7/disputes"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
    }
  }
}

Some customers choose to update this Identity at a later time with a PUT request using the information from the Payment Instrument below.

Create a Payment Instrument

Create a Payment Instrument by making a POST request to /payment_instruments with the relevant token and the Identity#id created for the buyer. To learn the available fields, please see create a payment_instrument.

curl https://finix.sandbox-payments-api.com/payment_instruments \
    -H "Content-Type: application/json" \
    -H 'Finix-Version: 2022-02-01' \
    -u  USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
    -d '{
      "token": "TKghUufLdh4QQ96CBi928HP3",
      "type": "TOKEN",
      "identity": "ID4KUMjzTggPzmCbvRUryQpE"
    }'

{
    "id": "PImmCg3Po7oNi7jaZcXhfkEu",
    "created_at": "2022-10-10T05:32:17.78Z",
    "updated_at": "2022-10-10T05:35:04.55Z",
    "application": "APgPDQrLD52TYvqazjHJJchM",
    "created_via": "API",
    "currency": "USD",
    "enabled": true,
    "fingerprint": "FPRiCenDk2SoRng7WjQTr7RJY",
    "identity": "ID4KUMjzTggPzmCbvRUryQpE",
    "instrument_type": "PAYMENT_CARD",
    "address": {
        "line1": "900 Metro Center Blv",
        "line2": null,
        "city": "San Francisco",
        "region": "CA",
        "postal_code": "94404",
        "country": "USA"
    },
    "address_verification": "POSTAL_CODE_AND_STREET_MATCH",
    "bin": "520082",
    "brand": "MASTERCARD",
    "card_type": "DEBIT",
    "expiration_month": 12,
    "expiration_year": 2029,
    "issuer_country": "NON_USA",
    "last_four": "8210",
    "name": "Amy White",
    "security_code_verification": "MATCHED",
    "tags": {
        "card_name": "Business Card"
    },
    "type": "PAYMENT_CARD",
    "_links": {
        "self": {
            "href": "https://finix.sandbox-payments-api.com/payment_instruments/PImmCg3Po7oNi7jaZcXhfkEu"
        },
        "authorizations": {
            "href": "https://finix.sandbox-payments-api.com/payment_instruments/PImmCg3Po7oNi7jaZcXhfkEu/authorizations"
        },
        "transfers": {
            "href": "https://finix.sandbox-payments-api.com/payment_instruments/PImmCg3Po7oNi7jaZcXhfkEu/transfers"
        },
        "verifications": {
            "href": "https://finix.sandbox-payments-api.com/payment_instruments/PImmCg3Po7oNi7jaZcXhfkEu/verifications"
        },
        "application": {
            "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
        },
        "identity": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDgWxBhfGYLLdkhxx2ddYf9K"
        },
        "updates": {
            "href": "https://finix.sandbox-payments-api.com/payment_instruments/PImmCg3Po7oNi7jaZcXhfkEu/updates"
        }
    }
}

Card Type

For cards, the type is saved in card_type. Available values for Payment Instruments with type: PAYMENT_CARD include:

• CREDIT
• DEBIT
• HSA_FSA
• NON_RELOADABLE_PREPAID
• RELOADABLE_PREPAID
• UNKNOWN

Updating a Payment Instrument

If you are interested in updating a payment_instrument, you can do so. This is helpful if you already have buyer address and don't want to collect it on the token_form. To learn the available fields to update, please see update an payment_instrument.

Examples

Finix Sample Store

If you want to see our Tokenization Forms in action, visit our sample store. You can view our related github project here.

React Example

The example below uses our CardTokenForm with minimal styling and Finix's submit button. You can update the CSS and which fields you want to show.

HTML Example

The example below uses our TokenForm that allows you to tokenize card or bank accounts. In this example, we include a number of different styling options you can use in HTML, React, vanilla JavaScript, and more.

Additional Tokenization Form Examples

See the following for examples of how to use our Tokenization Forms to tokenize payment details. You can build your own form by editing the various elements:

Next Steps

With the Payment Instrument created, you can proceed with creating and capturing an Authorization or creating a Transfer.