Secure Customer Data Fields

Secure Customer Data Fields let you capture and tokenize sensitive customer data without storing it on your server. Each field works like a standard HTML input element, so you have full control over how your data collection form looks and behaves.

When you receive the tokenized data, you can send the token in a New Application API request to submit a new merchant application.

Prerequisites

Before you begin, determine which BlueSnap environment you want to use. BlueSnap maintains separate resources for sandbox and production so you can test your integration before submitting production merchant applications.

Each environment has a dedicated domain. When implementing Secure Customer Data Fields, specify the domain in two places:

• The HTML <script> element that loads the BlueSnap Web SDK.
• The server-to-server request that creates the session token.

Replace <bluesnap-domain> wherever it appears with one of the following:

sandpay.bluesnap.com

pay.bluesnap.com

For example, the <script> element to include the Web SDK sandbox environment should use:

<script type="text/javascript" src="https://sandpay.bluesnap.com/web-sdk/5/bluesnap.js"></script>

Implement Secure Customer Data Fields

The following steps describe how to add Secure Customer Data Fields to your merchant application form.

Step 1: Get a Session Token

Each merchant application requires a unique session token. BlueSnap uses this token to associate the merchant’s secure field data with the application submission.

To get a session token, send a server-to-server POST request to the following endpoint:

https://<bluesnap-domain>/services/2/payment-fields-tokens

The token is returned in the Location response header. For example:

HTTP/1.1 201 Created
Location: https://sandpay.bluesnap.com/services/2/payment-fields-tokens/5ad59e4389abba704ee2d61580d1d5cc1ba0ccf114470d404f771a198d99891b_

Use the token value from the end of the Location header when you initialize the form and when you submit the merchant application.

Step 2: Include the BlueSnap Web SDK

Add the BlueSnap Web SDK to the page that contains your merchant application form.

<script type="text/javascript" src="https://<bluesnap-domain>/web-sdk/5/bluesnap.js"></script>

Step 3: Add Secure Customer Data Fields

For each data element that you need to collect, add an input field with the corresponding data-bluesnap attribute. For example, add the following to collect the business name:

<input data-bluesnap="businessName" />

BlueSnap provides a Secure Customer Data Field for each data element required for supported countries and regions. To determine which fields are required for a merchant’s country or region, refer to the applicable section in the New Application API reference.

For a complete list of supported data-bluesnap attributes, refer to Input field reference.

<form id="merchantApplicationForm">
  <label for="businessName">Business name</label>
  <input
    id="businessName"
    name="businessName"
    data-bluesnap="businessName"
    placeholder="Business name"
  />

  <label for="businessLegalName">Business legal name</label>
  <input
    id="businessLegalName"
    name="businessLegalName"
    data-bluesnap="businessLegalName"
    placeholder="Business legal name"
  />

  <!-- Add additional required fields for the merchant's country or region. -->

  <button id="submitButton" type="button">Submit application</button>
</form>

Step 4: Initialize the Form

After the DOM and BlueSnap Web SDK are loaded, call bluesnap.partnerSecuredCaptureSetup.

document.addEventListener("DOMContentLoaded", function () {
  bluesnap.partnerSecuredCaptureSetup("<token>", function (sdkResponse) {
    if (sdkResponse.code === 1) {
      // Secure field data was submitted successfully.
      // Continue by submitting the merchant application to your server.
    } else {
      const { errors, warnings } = sdkResponse.info || {};
      console.log("Errors:", errors);
      console.log("Warnings:", warnings);
    }
  });
});

bluesnap.partnerSecuredCaptureSetup accepts two arguments:

The callback should check whether the submission was successful and handle any errors or warnings. For more information, refer to sdkResponse Object.

Step 5: Submit the Secure Field Data

When the merchant submits the form, call bluesnap.partnerSecuredCaptureSubmitData. This function submits the secure field values directly to BlueSnap. BlueSnap stores the data and binds it to the session token.

document
  .getElementById("submitButton")
  .addEventListener("click", function () {
    bluesnap.partnerSecuredCaptureSubmitData();
  });

After the secure field data is submitted, BlueSnap passes the result to the callback function that you provided in bluesnap.partnerSecuredCaptureSetup.

Step 6: Submit the Merchant Application

After the secure field data is submitted successfully, send the session token as pfToken in the New Application API request:

{
  "pfToken": "<token>",
  "businessInfo": {
    "country": "US"
  }
}

Update an Expired Token

The session token expires after 60 minutes. To let BlueSnap handle token expiration automatically, define a function that obtains a new token from your server. Then, call bluesnap.setTokenProvider before calling bluesnap.partnerSecuredCaptureSetup.

BlueSnap calls your token provider function when an expired token is detected.

bluesnap.setTokenProvider((callback) => {
  fetch("/path/to/token")
    .then((response) => response.json())
    .then((data) => {
      callback(data.token);
    })
    .catch((error) => {
      console.log(error);
      callback();
    });
});

Your token endpoint should request a new token from BlueSnap and return it to the browser.

sdkResponse Object

The sdkReponse object contains the results from your data submission to BlueSnap.

{
  status: 'Success',
  code: 1
}

{
  status: 'Invalid Data',
  code: 15,
  "info": {
    "errors": ["Some error"],
    "warnings": [
      "Parameter \"bankAccountType\" with the value of \"savings123\" is invalid"
    ]
  }
}

{
  status: 'Server Error',
  code: 14040,
  info: {
    errors: ['Token is expired'],
  }
}

Properties

The following table describes its properties:

Errors

When sdkResponse.status is 'Server Error', error details are available in sdkResponse.info.errors. Errors prevent you from continuing the secure field submission process.

Warnings

When sdkResponse.status is 'Invalid Data', warning details are available in sdkResponse.info.warnings. Warnings identify input conditions you may need to address. Unlike errors, warnings do not always prevent the process from continuing.

Input Field Reference

These sections list the supported Secure Customer Data Fields and their associated HTML data-bluesnap attributes. For details about which secure input fields you need for a merchant, see the New Application API request content for the applicable country or region.

Business Information

Bank Information

Ownership Information

You can collect data for up to four business owners. In the data attribute, replace [n] with an integer 1 through 4:

Company Representative Information

Additional Information