Tokenization Forms
Learn how to use Tokenization Forms to securely accept payment details of your buyers.
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 of the Tokenization Form
- Accept both and ACH in the same form
Examples
React Example
The example below uses ourCardTokenForm
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 ourTokenForm
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.
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 convience, 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 thefinix.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>
finix.js
library to the latest V1 version.Versioning
You can set a specific version of thefinix.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:<script
type="text/javascript"
src="https://js.finix.com/v/1/0/5/finix.js"
></script>
Step 2: 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);
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. |
const options = {
showAddress: true, // show address fields in the form (default is false)
showLabels: true, //show labels in the form (default is true)
labels: { // set custom labels for each field
name: "Cardholder Name", // Supported Fields: "name", "number", "expiration_date", "security_code", "address_line1", "address_line2", "address_city", "address_state", "address_region", "address_country", "address_postal_code"
},
showPlaceholders: true, // turn on or off placeholder text in the fields (default is true)
placeholders: { // set custom placeholders for each field, you can specify them here
// Supported Fields: "name", "number", "expiration_date", "security_code", "address_line1", "address_line2", "address_city", "address_state", "address_region", "address_country", "address_postal_code"
name: "Cardholder Name",
},
hideFields: [ // set custom placeholders for each field, you can specify them here
], // Fields avaiblae to hide: "name", "security_code", "address_line1", "address_line2", "address_city", "address_state", "address_region", "address_country", "address_postal_code", "address_country"
requiredFields: [ // require any specific fields that are not required by default, you can specify them here
"name",
"address_line1",
"address_city",
"address_state",
"address_region",
"address_country",
"address_postal_code",
], // Supported Fields: "name", "address_line1", "address_line2", "address_city", "address_state", "address_region", "address_country", "address_postal_code"
hideErrorMessages: false, // if you want to require a field, but not hide input error messages (default is false)
errorMessages: { // set custom error messages for each field if you are showing error messages
name: "Please enter a valid name", // Supported Fields: "name", "number", "expiration_date", "security_code", "address_line1", "address_line2", "address_city", "address_state", "address_region", "address_country", "address_postal_code"
address_city: "Please enter a valid city",
},
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. |
styles: { // default styling for all fields
default: {
color: "#000",
border: "1px solid #CCCDCF",
borderRadius: "8px",
padding: "8px 16px",
fontFamily: "Helvetica",
fontSize: "16px",
boxShadow: "0px 1px 1px rgba(0, 0, 0, 0.03), 0px 2px 4px rgba(0, 0, 0, 0.03)",
},
success: { // specific styling if the field is valid
color: "#5cb85c",
},
error: {
color: "#d9534f", // specific styling if the field has errors
border: "1px solid rgba(255,0,0, 0.3)",
},
},
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.
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;
});
};
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. |
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;
alert("Your token ID is: " + token);
console.log(tokenData);
});
}
Fraud Detection
We recommend also collecting afraud_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 createdIdentity
.
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.
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": {}
}'
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:
{
"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"
}
}
}
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 aPayment Instrument
by making a POST
request to /payment_instrument
with the relevant token and the Identity#id
created for the buyer.warning
Payment Instrument
right away. Tokens expire within 30 minutes and cannot be used after expiring.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"
}'
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:
{
"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"
}
}
}
{
"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
. Available values for Payment Instruments
with type: PAYMENT_CARD
include:CREDIT
DEBIT
HSA_FSA
NON_RELOADABLE_PREPAID
RELOADABLE_PREPAID
UNKNOWN
Identity
with a PUT request using the information saved in the Payment Instrument
.Updating a Payment Instrument
If you are interested in updating apayment_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 thePayment Instrument
created, you can proceed with creating and capturing an Authorization
or creating a Transfer
.