Using Hosted Fields

To pass off the burden of complying with Payment Card Industry Data Security Standards (PCI DSS), use Finix Hosted field to collect and tokenize buyer information.

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 submitted 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 the form that collects payment details. 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 your 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 fields 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'll 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 buyers submit the form and define a callback for handling the response.

Once you've handled the response, 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,
  "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 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, make an authenticated POST request to the /payment_instrument and create a Payment Instrument with the relevant token and Identity information.

warning

Tokens should be associated right away. Tokens that don't get associated within 30 mins of creation get invalidated.

Copy
Copied
curl https://finix.sandbox-payments-api.com/payment_instruments \
    -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

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

Example Response:

Copy
Copied
{{
  "id" : "PIgJumLJwcNei1CziTynNgcE",
  "application" : "APchHsSPxqhUX64YpTuefJR7",
  "fingerprint" : "FPRiCenDk2SoRng7WjQTr7RJY",
  "tags" : {
    "card_type" : "Test Card"
  },
  "expiration_month" : 12,
  "expiration_year" : 2029,
  "bin" : "520082",
  "last_four" : "8210",
  "brand" : "MASTERCARD",
  "card_type" : "DEBIT",
  "name" : "John Smith",
  "address" : {
    "line1" : "400 Main ST",
    "line2" : null,
    "city" : "San Francisco",
    "region" : "CA",
    "postal_code" : "90291",
    "country" : null
  },
  "address_verification" : "UNKNOWN",
  "security_code_verification" : "UNKNOWN",
  "created_at" : "2022-07-22T02:42:45.70Z",
  "updated_at" : "2022-07-22T02:42:45.70Z",
  "instrument_type" : "PAYMENT_CARD",
  "type" : "PAYMENT_CARD",
  "currency" : "USD",
  "identity" : "IDgWxBhfGYLLdkhxx2ddYf9K",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIgJumLJwcNei1CziTynNgcE"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIgJumLJwcNei1CziTynNgcE/authorizations"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIgJumLJwcNei1CziTynNgcE/transfers"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIgJumLJwcNei1CziTynNgcE/verifications"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APchHsSPxqhUX64YpTuefJR7"
    },
    "identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDgWxBhfGYLLdkhxx2ddYf9K"
    },
    "updates" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIgJumLJwcNei1CziTynNgcE/updates"
    }
  }
}

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
  • NON_RELOADABLE_PREPAID
  • RELOADABLE_PREPAID
  • UNKNOWN

With the Payment Instrument created, you can proceed with creating and capturing an authorization or creating a transfer.