Tokenization With Hosted Fields

Library Summary

The PaymentForm library is a javascript library that allows you to secure sensitive card and bank account data. By having the end-user input their data into a hosted field, it prevents third-parties from accessing the information.

Once the fields are initialized the library communicates the state of the fields through a JavaScript callback. The state object includes information about the validity of the submitted value and if the user has entered information in the field.

See the following for examples of how to use our javascript library to tokenize:

Step 1: Include library and desired HTML elements

First we'll need to add the library to the webpage where you're hosting your form. To add the library, include the following the script:

Copy

Copied

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

Step 2: Initialize the payment form

window.PaymentForm.card(function(state, binInformation)-> PaymentForm

The next step is to configure the library. This "card" method is the single entry point into the library. It initializes and returns a PaymentForm object that contains fields(i.e. name, number, expiration date, and CVV).

Copy

Copied

const paymentForm = window.PaymentForm.card(function(state, binInformation){
     // Logic for interacting with form's potential states (see jsFiddle for  example)
});

Step 3: Define input fields and configure styling

Now that we have a PaymentForm object we'll want to style it.

attention

Requesting an address in PaymentForm can lower interchange on credit card transactions.

DefineField Arguments

Field	Type	Description
`elementId`	string, required	Name of HTML id
`type`	string, required	API attribute name that will be sent in the payload
`placeholder`	string, required	What the user will see in the input field
`validations`	string, optional	This allows customers to make a field required. The possible values are required, cardExpiry, cardNumber, and cardCVC. Each of the possible values returns a different error message when the required field is not present. required returns `Value is required`. cardExpiry returns `Invalid expiration date`. cardNumber returns `Invalid card number`. cardCVC returns `Invalid CVV`.
`autoComplete`	string, optional	This allows the specified fields to auto-complete from saved card information. The possible values are: cc-number, cc-name, cc-exp, cc-csc, address-line1, address-line2, address-level1, postal-code, address-level2.

Copy

Copied

function defineField(elementId, type, placeholder, validations, autoComplete) {
 // call field method with desired css styling
 const f = form.field(type, {
        validations,
        placeholder: { text: placeholder, hideOnFocus: true },
        autoComplete,
        styles: {
          default: {
            color: "black",
          },
          success: {
            color: '#5cb85c',
          },
          error: {
            color: '#d9534f',
          },
        }
      });
  // appends each field wrapper (that contains placeholder and styles) to the appropriate div
  document.getElementById(elementId).appendChild(f);
}

defineField("field-wrapper-number", "number", '4111 1111 1111 1111');
defineField("field-wrapper-name", "name", 'Bo Jackson');
defineField("field-wrapper-expiration_date", "expiration_date", '02/2020');
defineField("field-wrapper-security_code", "security_code", '411');

Step 4: Submit payload and handle response

Form#submit(environment, applicationID, callback)-> Form

Finally we will need to register a click event that fires when our users submit the form and define a callback for handling the response.

Next, configure the library to your specific Application where all of the form fields will be submitted during the executed POST request. We'll also want to register a click event that fires when our users submit the form and define a callback for handling the response.

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

Copy

Copied

/*
Form#submit(environment, applicationID, callback)-> Form
*/

function submitForm() {
  // Sandbox or live for environment
  form.submit('sandbox', APgPDQrLD52TYvqazjHJJchM, function(err, res) {
    if (err) {
      console.log("There was an error");
    }
    // For illustrative purposes, we insert the JSON into the html.
    document.getElementById('preview').innerHTML = JSON.stringify(res, null, '  ');
  })
}

document.getElementById('button').addEventListener('click', function (e){
  e.preventDefault();
  submitForm();
})

// If user types "enter" instead of clicking submit button
form.onSubmit(submitForm);

Example Response:

Copy

Copied

{
  "status": 201,
  "statusText": "Created",
  "data": {
    "id": "TKiu6N8r5wN38J1xXdeNjzZY",
    "fingerprint": "FPR-2083311660",
    "created_at": "2017-08-29T06:25:54.29Z",
    "updated_at": "2017-08-29T06:25:54.29Z",
    "instrument_type": "PAYMENT_CARD",
    "expires_at": "2017-08-30T06:25:54.29Z",
    "currency": "USD"
  }
}
{
  "cardBrand": "visa",
  "bin": "411111"
}

We recommend also collecting a fraud_session_id to detect and block potential fraudulent payments. Add the following to your JavaScript to collect a fraud_session_id.

Copy

Copied

    const FinixAuth = window.Finix.Auth('sandbox', 'MUeDVrf2ahuKc9Eg5TeZugvs');
		fraud_session_id = FinixAuth.getSessionKey();

When you make a payment and send the token to your back-end server, include the fraud_session_id. With the fraud_session_id included, Finix can review the details of the transaction and block potential fraud. For more information, see Fraud Detection.

Arguments

Field	Type	Description
`environment`	string, required	`sandbox` for testing and `live` for production
`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 5: Associate to an Identity

Before you can use the newly tokenized card or bank account you will need to associate it with an Identity. To do this you must make an authenticated POST request to the /payment_instruments endpoint with the relevant token and Identity information.

warning

Tokens should be associated right away. Tokens not associated within 30 mins of creation will be invalidated.

Copy

Copied

curl https://finix.sandbox-payments-api.com/payment_instruments \
    -H "Content-Type: application/vnd.json+api" \
    -u  USte61SqeNkAZnpfavK3fQNG:bd98703c-d72c-458e-8873-4295f5bac713 \
    -d '
	{
	    "token": "TKiMxe323RE5Dq3wLVtG8kSW",
	    "type": "TOKEN",
	    "identity": "IDpYDM7J9n57q849o9E9yNrG"
	}'

Example Response:

Copy

Copied

{
  "id" : "PIs4ZXrQB1RjbYJSgkfbcrbM",
  "application" : "APgPDQrLD52TYvqazjHJJchM",
  "fingerprint" : "FPRw9NoorETQgCjFgwKPvcGsV",
  "tags" : { },
  "expiration_month" : 12,
  "expiration_year" : 2029,
  "bin" : "495703",
  "last_four" : "0454",
  "brand" : "VISA",
  "card_type" : "UNKNOWN",
  "name" : null,
  "address" : {
    "line1" : "741 Douglass St",
    "line2" : "Apartment 7",
    "city" : "San Mateo",
    "region" : "CA",
    "postal_code" : "94114",
    "country" : "USA"
  },
  "address_verification" : "UNKNOWN",
  "security_code_verification" : "UNKNOWN",
  "created_at" : "2022-01-27T07:37:27.42Z",
  "updated_at" : "2022-01-27T07:37:27.42Z",
  "instrument_type" : "PAYMENT_CARD",
  "type" : "PAYMENT_CARD",
  "currency" : "USD",
  "identity" : "IDpYDM7J9n57q849o9E9yNrG",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIs4ZXrQB1RjbYJSgkfbcrbM"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIs4ZXrQB1RjbYJSgkfbcrbM/authorizations"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIs4ZXrQB1RjbYJSgkfbcrbM/transfers"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIs4ZXrQB1RjbYJSgkfbcrbM/verifications"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
    },
    "identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDpYDM7J9n57q849o9E9yNrG"
    },
    "updates" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIs4ZXrQB1RjbYJSgkfbcrbM/updates"
    }
  }
}

HTTP Request

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

Request Arguments

Field	Type	Description
`address`	object, required	Billing address (Full description of child attributes below) Note: Including a postal or zip code when creating a `payment_instrument` can lower the interchange on credit card transactions
`identity`	string, required	ID for the `Identity` resource which the account is to be associated
`name`	string, required	Full name of the registered card holder
`token`	string, required	ID for the `Token` that was returned via the tokenization client
`type`	string, required	Must pass TOKEN as the value

Address-object Request Arguments

Field	Type	Description
`city`	string, optional	City (max 20 characters)
`country`	string, optional	3-Letter Country code
`line1`	string, optional	First line of the address (max 35 characters)
`line2`	string, optional	Second line of the address (max 35 characters)
`postal_code`	string, required	Zip or Postal code (max 7 characters)
`region`	string, optional	2-letter State code