Tokenization Forms

Learn how to use Tokenization Forms to securely accept payment details of your buyers.

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, includes functionality to:

Show and hide specific fields
Customize labels and placeholders
Modify error messages to match your writing style
Control input styling within and outside the Tokenization Form
Accept both and ACH in the same form
Support for custom fonts within the iframe
Ability to pre-set values for certain fields
Supports running multiple forms on the same page

Examples

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.

Library

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 to only accept a routing and account number.

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.

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	`TokenForm`	Accept bank account details, a debit card, or a credit card.
Debit and Credit Cards	`CardTokenForm`	Accept credit or debit cards.
Bank Accounts	`BankTokenForm`	Accept bank account details, including account number and routing number.

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	`TokenForm`	Accept bank account details, a debit card, or a credit card.
Debit and Credit Card - Minimal	`CardTokenForm`	Accept credit or debit cards.
Bank Accounts - Minimal	`BankTokenForm`	Accept bank account details, including account number and routing number.

Step 1: Add 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:

Copy

Copied

<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 set a specific version of the finix.js library for your form to lock to. To specify a finix.js library version to use, update the URL to your desired version. This example uses V1.0.5 of the finix.js library:

Copy

Copied

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

Step 2: Initialize the Tokenization Form

Initialize the form with:

TokenFormCardTokenFormBankTokenForm

Copy

Copied

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

Copy

Copied

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

Copy

Copied

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

Step 3: Define Input Fields

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

attention

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.

View our HTML example above to see how all the options can be used.

Step 4: 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.

Step 5: Submit Payload and Handle Response

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.

Copy

Copied

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.

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

Copy

Copied

    const tokenData = res.data || {};     // get token ID from response
    const token = tokenData.id;

    alert("Your token ID is: " + token);
    console.log(tokenData);
  });
}

Fraud Detection

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

For more information, see Fraud Detection.

Step 6: Create an Identity for the Buyer

Before you can use the newly tokenized card or bank account, you'll need to:

Create an Identity for the buyer.
Create a Payment Instrument with the created Identity.

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:

Copy

Copied

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": {}
    }'

HTTP Request

POST https://finix.sandbox-payments-api.com/identities

Request Arguments

Field	Type	Description
`city`	`string`, optional	City (max 20 characters)
`country`	`string`, optional	3-Letter country code
`email`	`string`, optional	Email address
`first_name`	`string`, optional	First name
`last_name`	`string`, optional	Last name
`line1`	`string`, optional	First line of the address (max 35 characters)
`line2`	`string`, optional	Second line of the address (max 35 characters)
`phone`	`string`, optional	Phone number
`postal_code`	`string`, optional	Zip or postal code (max 7 characters)
`region`	`string`, optional	2-letter state code
`tags`	`object`, optional	Key value pair for annotating custom metadata (e.g. order numbers)

Example response:

Copy

Copied

{
    "id": "ID4KUMjzTggPzmCbvRUryQpE",
    "created_at": "2023-01-03T18:56:30.40Z",
    "updated_at": "2023-01-03T18:56:30.40Z",
    "application": "APgPDQrLD52TYvqazjHJJchM",
    "entity": {
        "amex_mid": null,
        "annual_card_volume": 0,
        "business_address": null,
        "business_name": null,
        "business_phone": 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_provided": false,
        "title": null,
        "url": null
    },
    "tags": {},
    "_links": {
        "self": {
            "href": "https://finix.sandbox-payments-api.com/identities/ID4KUMjzTggPzmCbvRUryQpE"
        },
        "verifications": {
            "href": "https://finix.sandbox-payments-api.com/identities/ID4KUMjzTggPzmCbvRUryQpE/verifications"
        },
        "merchants": {
            "href": "https://finix.sandbox-payments-api.com/identities/ID4KUMjzTggPzmCbvRUryQpE/merchants"
        },
        "settlements": {
            "href": "https://finix.sandbox-payments-api.com/identities/ID4KUMjzTggPzmCbvRUryQpE/settlements"
        },
        "authorizations": {
            "href": "https://finix.sandbox-payments-api.com/identities/ID4KUMjzTggPzmCbvRUryQpE/authorizations"
        },
        "transfers": {
            "href": "https://finix.sandbox-payments-api.com/identities/ID4KUMjzTggPzmCbvRUryQpE/transfers"
        },
        "payment_instruments": {
            "href": "https://finix.sandbox-payments-api.com/identities/ID4KUMjzTggPzmCbvRUryQpE/payment_instruments"
        },
        "associated_identities": {
            "href": "https://finix.sandbox-payments-api.com/identities/ID4KUMjzTggPzmCbvRUryQpE/associated_identities"
        },
        "disputes": {
            "href": "https://finix.sandbox-payments-api.com/identities/ID4KUMjzTggPzmCbvRUryQpE/disputes"
        },
        "application": {
            "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
        }
    }
}

You can update this Identity at a later time with a PUT request that uses the information in the Payment Instrument you create with the token.

Step 7: Create a Payment Instrument

Create a Payment Instrument by making a POST request to /payment_instrument with the relevant token and the Identity#id created for the buyer.

warning

Tokens should be used to create a Payment Instrument right away. Tokens expire within 30 minutes and cannot be used after expiring.

Card TokenBank Token

Copy

Copied

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

Copy

Copied

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
    }'

HTTP Request

POST https://finix.sandbox-payments-api.com/payment_instruments

Request Arguments

Field	Type	Description
`identity`	`string`, required	ID for the `Identity` resource which the account is to be associated
`token`	`string`, required	ID for the `Token` that was returned via the tokenization client
`type`	`string`, required	Must pass TOKEN as the value
`attempt_bank_account_validation_check`	`boolean`, optional	Recommended to reduce ACH Returns (Bank Tokens only)

Example response:

Card TokenBank Token

Copy

Copied

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

Copy

Copied

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

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

You can also update the buyer Identity with a PUT request using the information saved in the Payment Instrument.

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.

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.