# Tokenization Forms

Token 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

![Tokenization Form Sequence Diagram](/assets/tokenization-form-sequence-diagram.5e132064ed6040d2da768fbae0895911c9e6f2bd6077c0e3733b56f59f6f1ca8.28b10c14.png)

### 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:


```html
<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:


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

#### Initialize the Tokenization Form

Initialize the form with:


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


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


```javascript
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.

Lowering interchange on credit cards
Requesting an address in your Tokenization Form can lower interchange on credit card transactions.

Aspects of the input fields you can change include:

| Field | Type | Description |
|  --- | --- | --- |
| `showAddress` | `boolean` | Show address fields in the form (defaults to `false`). |
| `showLabels` | `boolean` | Show labels in the form (defaults to `true`). |
| `labels` | `object` | Set custom labels for each field. |
| `showPlaceholders` | `boolean` | Turn on or off placeholder text in the fields (defaults to `true`). |
| `placeholders` | `object` | Set custom placeholders for each field. |
| `hidefields` | `array[string]` | Specify which fields to hide. |
| `requiredFields` | `array[string]` | Require any specific fields that are not required by default. |
| `hideErrorMessages` | `boolean` | If you want to require a field, but not hide input error messages (defaults to `false`). |
| `errorMessages` | `object` | Set custom error messages for each field if you are showing error messages. |
| `defaultValues` | `object` | Set default values for each field. This can only be set once on load. |
| `fonts` | `array[object]` | Set custom fonts to be used inside the form inputs. |


#### Style Tokenization Form

Style the Tokenization Form with your brand identity and colors.

Styling you can change includes:

| Field | Description |
|  --- | --- |
| `color` | Color of the fields. |
| `border` | Border of the fields. |
| `borderRadius` | Rounding of the fields' border. |
| `padding` | Spacing inside the field. |
| `fontSize` | Size of the font used by the fields. |
| `boxShadow` | Shadow of the fields. |
| `success` | Styling if the value entered is valid. |
| `error` | Styling if the value entered is invalid and can't be accepted. |


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.


```javascript
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

| Field | Type | Description |
|  --- | --- | --- |
| `environment` | `string`, **required** | `sandbox` for testing and `live` for live environments |
| `applicationId` | `string`, **required** | `Application` id that the payment card will be scoped to |
| `callback` | `function`, **required** | Callback that will be executed when the HTTPRequest is finished. |


### Step 2. Handle Response from finix.js

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


```json Example Token Response
{
  "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.


```javascript Sample Javascript workflow
    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.

Token usage and expiration
Tokens should be used to create a `Payment Instrument` right away in the next step. Tokens expire within 30 minutes and cannot be used after expiring.


``` Sample Javascript workflow

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](/guides/online-payments/fraud-and-risk/fraud-detection).

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

#### Create Buyer Identity

Optional step if you already have a buyer identity created
If you already created a Buyer Identity beforehand, you can skip this step.

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:

Blank Buyer Identity

```shell Create Blank Buyer Identity
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": {}
  }'
```

Example response:


```json Blank Buyer Identity Response
{
  "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"
    }
  }
}
```

Filled out buyer Identity

```shell Filled out buyer Identity
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": {
            "phone": "7145677613",
            "first_name": "John",
            "last_name": "Smith",
            "email": "finix_example@finix.com",
            "personal_address": {
                "city": "San Mateo",
                "country": "USA",
                "region": "CA",
                "line2": "Apartment 7",
                "line1": "741 Douglass St",
                "postal_code": "94114"
            }
            },
            "identity_roles": [
            "BUYER"
            ],
            "tags": {
            "key": "value"
            }
     }'
```

Example Response:


```json Filled out buyer Identity Response
{
  "id" : "IDpwdtfvTX6dbgcET3653yun",
  "created_at" : "2025-06-10T14:55:47.61Z",
  "updated_at" : "2025-06-10T14:55:47.61Z",
  "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" : "finix_example@finix.com",
    "first_name" : "John",
    "has_accepted_credit_cards_previously" : false,
    "incorporation_date" : null,
    "last_name" : "Smith",
    "max_transaction_amount" : 0,
    "mcc" : null,
    "ownership_type" : null,
    "personal_address" : {
      "line1" : "741 Douglass St",
      "line2" : "Apartment 7",
      "city" : "San Mateo",
      "region" : "CA",
      "postal_code" : "94114",
      "country" : "USA"
    },
    "phone" : "7145677613",
    "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" : [ "BUYER" ],
  "tags" : {
    "key" : "value"
  },
  "type" : "PERSONAL",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDpwdtfvTX6dbgcET3653yun"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDpwdtfvTX6dbgcET3653yun/verifications"
    },
    "merchants" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDpwdtfvTX6dbgcET3653yun/merchants"
    },
    "settlements" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDpwdtfvTX6dbgcET3653yun/settlements"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDpwdtfvTX6dbgcET3653yun/authorizations"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDpwdtfvTX6dbgcET3653yun/transfers"
    },
    "payment_instruments" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDpwdtfvTX6dbgcET3653yun/payment_instruments"
    },
    "associated_identities" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDpwdtfvTX6dbgcET3653yun/associated_identities"
    },
    "disputes" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDpwdtfvTX6dbgcET3653yun/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`](/api/payment-instruments/createpaymentinstrument).

Card Payment Instrument
To create a Card Payment Instrument:


```json
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"
    }'
```

Example response after creating a card payment instrument:


```json
{
    "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"
        }
    }
}
```

Bank Payment Instrument
To create a Bank Payment Instrument:


```shell
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",
      "attempt_bank_account_validation_check": true
    }'
```

Example response after creating a bank payment instrument:


```json
{
    "id": "PI4yPRtCbfRcUR9JeiBEEuaD",
    "created_at": "2024-08-28T20:00:49.58Z",
    "updated_at": "2024-08-28T20:00:49.58Z",
    "application": "AP4qd3xXeA33Excs1QSf81Jm",
    "created_via": "API",
    "currency": "USD",
    "disabled_code": null,
    "disabled_message": null,
    "enabled": true,
    "fingerprint": "FPReqhJ8rG1hLKCKfZtSwhLHf",
    "identity": "IDcZJkLaxXvEkg37fG2o9HAq",
    "instrument_type": "BANK_ACCOUNT",
    "account_type": "PERSONAL_CHECKING",
    "bank_account_validation_check": "INVALID",
    "bank_code": "123456788",
    "country": "USA",
    "institution_number": null,
    "masked_account_number": "**MASKED**",
    "name": "John Doe",
    "transit_number": null,
    "tags": {},
    "third_party": null,
    "third_party_token": null,
    "type": "BANK_ACCOUNT",
    "_links": {
        "self": {
            "href": "https://finix.sandbox-payments-api.com/payment_instruments/PI4yPRtCbfRcUR9JeiBEEuaD"
        },
        "authorizations": {
            "href": "https://finix.sandbox-payments-api.com/payment_instruments/PI4yPRtCbfRcUR9JeiBEEuaD/authorizations"
        },
        "transfers": {
            "href": "https://finix.sandbox-payments-api.com/payment_instruments/PI4yPRtCbfRcUR9JeiBEEuaD/transfers"
        },
        "verifications": {
            "href": "https://finix.sandbox-payments-api.com/payment_instruments/PI4yPRtCbfRcUR9JeiBEEuaD/verifications"
        },
        "application": {
            "href": "https://finix.sandbox-payments-api.com/applications/AP4qd3xXeA33Excs1QSf81Jm"
        },
        "identity": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDcZJkLaxXvEkg37fG2o9HAq"
        }
    }
}
```

#### 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`](/api/payment-instruments/updatepaymentinstrument).

## Examples

### Finix Sample Store

If you want to see our Tokenization Forms in action, visit our [sample store](https://finixsamplestore.com). You can view our related github project [here](https://github.com/finix-payments/accept-a-payment).

### 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.

br
iframe
### 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.

br
iframe
### 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:

| Tokenization Form Examples | Library Name | Description |
|  --- | --- | --- |
| [**Tokenization Form**](https://jsfiddle.net/finix_docs/paqh60zg/4/) | `TokenForm` | Accept bank account details, a debit card, or a credit card. |
| [**Debit and Credit Cards**](https://jsfiddle.net/finix_docs/p26bvotx/2/) | `CardTokenForm` | Accept credit or debit cards. |
| [**Bank Accounts**](https://jsfiddle.net/finix_docs/qrnwtoub/1/) | `BankTokenForm` | Accept bank account details, including account number and routing number. |


details
summary
Minimal Versions
For your convenience, Finix provides minimal versions of the Tokenization Forms without any comments:

| Tokenization Form Examples | Library Name | Description |
|  --- | --- | --- |
| [Tokenization Form - Minimal](https://jsfiddle.net/finix_docs/je83h6vd/) | `TokenForm` | Accept bank account details, a debit card, or a credit card. |
| [Debit and Credit Card - Minimal](https://jsfiddle.net/finix_docs/5ov93jrs/) | `CardTokenForm` | Accept credit or debit cards. |
| [Bank Accounts - Minimal](https://jsfiddle.net/finix_docs/cm169g0s/) | `BankTokenForm` | Accept bank account details, including account number and routing number. |


## Token Forms Changelog

### Version 1.3.2

Released on April 28, 2025

#### Double Confirmation of Bank Accounts

We've updated our Bank Forms to now force a buyer to confirm the bank account account number before creating the Token. This can be helpful in minimizing ACH returns from buyers incorrectly adding their bank account number.

To enable, pass in `confirmAccountNumber: true` as part of the available `options`.

#### Dark Mode Support

We've added support for Dark Mode browsers.

To enable, pass in `enableDarkMode: true` as part of the available `options`.

#### Minor Improvements

We made a number of minor improvements to help minmize resizing issues and BIN data not returning as expected.

## Next Steps

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



Making a Payment
Learn how to create a transfer and debit funds.

Creating and Capturing an Authorization
Learn how authorize funds on a card.