Using Hosted Fields

Finix Hosted Fields are available to securely collect the the details of a card payment.

Using Hosted Fields

To pass off the burden of complying with Payment Card Industry Data Security Standards (PCI DSS), use Finix Hosted Fields to collect and tokenize the payment details of buyers.

Library Summary

The Hosted Fields use a PaymentForm JavaScript library that lets you secure sensitive card and bank account data. Having buyers input their data into a hosted field prevents third parties from accessing the information that gets submitted.Once the fields are initialized the library communicates the state of the fields through a JavaScript callback. The state object includes information validating the payment details submitted by the buyer.

See the following for examples of how to use our JavaScript library to tokenize payment details:

Step 1: Include Library and Desired HTML Elements

First we'll need to add the PaymentForm library to the webpage that's hosting the form that collects payment details. To add the library, include the following the script:
 <script type="text/javascript" src=""></script>

Step 2: Initialize the Payment Form

Initialize the PaymentForm library with:
window.PaymentForm.card(function(state, binInformation)-> PaymentForm
Next, configure the library to accept cards. This card method is the single entry point into the library. It initializes and returns a PaymentForm object that contains the hosted fields (i.e. name, number, expiration date, and CVV).
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 you have a PaymentForm object, you can customize and style it with your branding.
Requesting an address in your PaymentForm can lower interchange on credit card transactions.

Define Field Arguments

elementIdstring, requiredName of HTML id.
typestring, requiredAPI attribute name that will be sent in the payload.
placeholderstring, requiredWhat the user will see in the input field.
validationsstring, optionalThis 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.
autoCompletestring, optionalThis allows the specified fields to auto-complete fields from saved card information. Available values include:
  • cc-number
  • cc-name
  • cc-exp
  • cc-csc
  • address-line1
  • address-line2
  • address-level1
  • postal-code
  • address-level2
  • Copy
    function defineField(elementId, type, placeholder, validations, autoComplete) {
     // call field method with desired css styling
     const f = form.field(type, {
            placeholder: { text: placeholder, hideOnFocus: true },
            styles: {
              default: {
                color: "black",
              success: {
                color: '#5cb85c',
              error: {
                color: '#d9534f',
      // appends each field wrapper (that contains placeholder and styles) to the appropriate div
    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

    We'll also need to configure what happens when the buyer submits the form.

    The PaymentForm needs to to register a click event that fires when the buyer submits the form and define a callback for handling the response.

    Use the following to submit the form when completed by the buyer:

    submit(environment, applicationID, callback)-> Form
    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 buyers submit the form and define a callback for handling the response.Once you've handled the response, store the 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.
    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){
    // If user types "enter" instead of clicking submit button

    Example Response:

      "status": 201,
      "data": {
        "id": "TKghUufLdh4QQ96CBi928HP3",
        "fingerprint": "FPRiCenDk2SoRng7WjQTr7RJY",
        "created_at": "2022-07-22T02:39:45.87Z",
        "updated_at": "2022-07-22T02:39:45.87Z",
        "instrument_type": "PAYMENT_CARD",
        "expires_at": "2022-07-23T02:39:45.87Z",
        "currency": "USD"
      "cardBrand": "mastercard",
      "bin": "520082"
    We recommend also collecting a fraud_session_id to detect and block potentially fraudulent payments. Add the following to your JavaScript to collect a fraud_session_id.
        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.


    environmentstring, requiredsandbox for testing and live for production
    applicationIdstring, requiredApplication id that the payment card will be scoped to
    callbackfunction, requiredCallback that will be executed when the HTTPRequest is finished.

    Step 5: Create a Payment Instrument

    Before you can use the newly tokenized card or bank account you'll need to connect it with an Identity. To do this, create a Payment Instrument by making an authenticated POST request to /payment_instrument with the relevant token and Identity information.
    Tokens should be used to create a Payment Instrument right away. Tokens that don't get connected within 30 mins of creation expire and can't be used.
    curl \
        -H "Content-Type: application/vnd.json+api" \
        -H 'Finix-Version:2022-02-01' \
        -u  USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
        -d '
                "token": "TKghUufLdh4QQ96CBi928HP3",
                "type": "TOKEN",
                "identity": "IDgWxBhfGYLLdkhxx2ddYf9K"

    HTTP Request


    Request Arguments

    addressobject, requiredBilling 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
    identitystring, requiredID for the Identity resource which the account is to be associated
    namestring, requiredFull name of the registered card holder
    tokenstring, requiredID for the Token that was returned via the tokenization client
    typestring, requiredMust pass TOKEN as the value

    Address-object Request Arguments

    citystring, optionalCity (max 20 characters)
    countrystring, optional3-Letter Country code
    line1string, optionalFirst line of the address (max 35 characters)
    line2string, optionalSecond line of the address (max 35 characters)
    postal_codestring, requiredZip or Postal code (max 7 characters)
    regionstring, optional2-letter State code

    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" : "IDgWxBhfGYLLdkhxx2ddYf9K",
      "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" : ""
        "authorizations" : {
          "href" : ""
        "transfers" : {
          "href" : ""
        "verifications" : {
          "href" : ""
        "application" : {
          "href" : ""
        "identity" : {
          "href" : ""
        "updates" : {
          "href" : ""
    The type of card that gets saved is detailed in card_type. Available values for Payment Instruments with type PAYMENT_CARD include:
    • CREDIT
    • DEBIT
    • HSA_FSA

    Next Steps

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