Getting Started

The Firstoken Captures SDK is a powerful JavaScript library that enables secure data capture through customizable forms. It ensures compliance with PCI security requirements by intercepting sensitive data and replacing it with tokens before it reaches the client's server.

Quick Integration

Step 1: Include the SDK

To begin, include the Firstoken Captures SDK JavaScript file inside the body of your web application.

<body>
    <script src="https://cdn.firstoken.co/captures/js/2.3/sdk.js" integrity="sha256-D0P+mQ7N6E0tbReEGYNTjoGqRmWUX87oCLd8PNvs5vg=" crossorigin="anonymous"></script>
    ...
</body>

For reviewing previous versions of Captures SDK JS go to versions section.

Step 2: Setting up HTML elements

Next, insert the necessary HTML elements within your form application. It is crucial to use specific ID tags for proper rendering of the SDK.

These elements serve as placeholders where the SDK's iframes will be inserted. For optimal data security, we recommend using "div" elements instead of "input" elements. Here is an example:

<form id="collect-form" method="post">
    <div class="form-field-group ">
      <div id="cc-holder"></div>
      <div id="cc-number"></div>
      <div id="cc-expiration-date"></div>
      <div id="cc-cvv"></div>
    </div>
    <div class="form-buttons"> <button type="submit" class="form-button">Process</button>
      <button type="submit" class="form-button inactive"> Regresar</button>
    </div>
  </form>

In the example above, each "div" element has a unique ID corresponding to the type of data it will capture (e.g., card number, cardholder name, expiration date, security code).

  • cc-number: corresponds to the field where the card number will be received

  • cc-holder: corresponds to the field where the cardholder's name will be received

  • cc-expiration-date: corresponds to the field where the expiration date will be received

  • cc-cvv: corresponds to the field where the security code will be received

Step 3: Initialize the SDK

To initialize the Firstoken Capture SDK component, you need to call the .init() method in the JavaScript file and provide the Inbound Route ID (previously created in the Firstoken web portal) as the first argument. Here is an example:

const routeId = "your-route-id";
const FT = window.FTCaptures.init(routeId, "production", function(state) {
    console.log('SDK initialized successfully');
}));

Note: If you want to perform tests in an environment, it is recommended to create an Inbound Route in the FirsToken Staging portal and place the "staging" environment in the second parameter.

The return value of this call provides information about the current state of the form, including the condition of the fields.

Step 4: Create and setup form fields

Each field in the form must be initialized using the appropriate code. Here is an example of one of them:

FT.field("#cc-number", {
      type: "card-number",
      name: "card_number",
      placeholder: "Card Number",
      autocomplete: “cc-number”,
      brandIcon: "true",
      errorColor: "750000",
      required: "true",
      css: { 
           “background-color”: “#000000”,
           “color”: “#FFFFFF”
        }
    });

By doing this, the Firstoken Capture SDK will create an iframe for each initialized field. The library supports various types of built-in inputs, such as card number, cardholder name, card expiration date, and card security code.

Step 5: Field validation

To validate the form fields, you can utilize the following code snippet:

FTCaptures.on("cardNumberValidationFailed", function (event) {
    console.log(event.data.isValid)
});

This code allows you to handle input errors and respond to relevant events.

Step 6: Capture validation values

Leverage the capabilities of the Firstoken Captures SDK to capture and handle validation values. The SDK may offer built-in mechanisms or hooks to intercept and process validation values during the submission process.

const validationResults = await FTCaptures.validate(routeId);
console.log(validationResults)

This function requires the Route Id value to identify the elements created in the form without interfering with other Iframes on the webpage, such as Google Analytics or Google Tag Manager.

The snippet should be placed inside the submit method within your form event listener, as an async function, in order to await the validation response.

Step 7: Handle Form Submission

To send the form data, you need to define a submit method within your form event listener. Here is an example:

FTCaptures.tokenize(routeId).then(function (result) {
  console.log(result)
}).catch(function (err) {
  console.log(err)
});

In this method, you can retrieve the serialized form data using the `serializeForm()` function provided by the Firstoken Captures SDK. You can then process the data as needed.

This function requires the Route Id value to identify the elements created in the form without interfering with other Iframes on the webpage, such as Google Analytics or Google Tag Manager.

By following these steps, you can successfully integrate and configure the Firstoken Captures SDK to securely capture data via customizable forms on your website.

Need Enhanced Security?

For JWT authentication, content encryption, and advanced security features, refer to our full example of usage. To encrypt payload data sent to us, please contact support to enable this feature on your inbound route.

Next Steps

PreviousCaptures SDK JSNextFunctions

Last updated

Was this helpful?