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 want to use. BlueSnap maintains resources for both sandbox and production environments so you can safely test your integration before processing live transactions.

Each environment has a dedicated domain. When implementing Secure Customer Data Fields, you have to specify the domain in two places: the HTML <script> element that loads the SDK and the token request. In steps where you specify the domain, replace <bluesnap-domain> with the one of the following:

Sandbox domain

sandpay.bluesnap.com

Production domain

pay.bluesnap.com

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

src="sandpay.bluesnap.com/web-sdk/5/bluesnap.js"

Implement Secure Customer Data Fields

The following steps describe how to add Secure Customer Data Fields to your website.

Step 1: Get a Session Token

Each merchant application requires a unique session token. BlueSnap saves your merchant data and associates it with the token so you do not have to store sensitive information on your server. When you are ready to submit the merchant application, you send the token in the request.

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 response header in the following format:

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

For example:

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

📘

Note

The token expires after 60 minutes. You can get a new token from BlueSnap when the token expires. For details, see Update an Expired Token.

Step 2: Include the BlueSnap Web SDK

The BlueSnap SDK provides access to functions and objects that you must implement in your application code. To include the Web SDK, add the following script element to the web page that contains your 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 a Secure Customer Data Field that corresponds to that data element. For example, to collect the business name, add <input data-bluesnap="businessName"/> to your form.

BlueSnap provides a Secure Customer Data Field for each data element required for all supported countries and regions. To see details about all required data elements for your merchant's location, go to the applicable location in the New Application API reference documentation. For a comprehensive list of corresponding Secure Data Fields, see Input Field Reference.

This truncated sample form captures the business name and business legal name:

<form action="#">
  <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" />

  <!-- Additional required inputs...  -->
</form>

👍

Customize your input fields

You can add other attributes to the Secure Customer Data Field input elements. For example, you can add the class attribute to apply CSS styles, and you can add the placeholder text to suggest expected values for the field.

Step 4: Initialize Your Form

You need to initialize the Secure Customer Data Fields on your web page to ensure they were correctly added to your data collection form. To initialize the form, add an event listener to the document object that calls bluesnap.partnerSecuredCaptureSetup after the DOM and BlueSnap Web SDK are fully loaded:

// Run after DOM and BlueSnap JS are fully loaded
document.addEventListener('DOMContentLoaded', function () {
  bluesnap.partnerSecuredCaptureSetup('<token>', function (sdkResponse) {
    if (sdkResponse.code === 1) {
      // Success
      // Continue form submission to your server and create merchant account...
    } else {
      // Receive error or warning
      const { errors, warnings } = sdkResponse.info;
      console.log('Errors: ', errors);
      console.log('Warnings: ', warnings);
    }
  });
});

bluesnap.partnerSecuredCaptureSetup accepts two arguments:

• Session token
• Callback function that executes after the form is submitted to BlueSnap.

The callback takes as an argument an sdkReponse object, which contains the result of your form submission to BlueSnap. This object returns a status description, status code, warning messages, and error messages. The callback should determine whether the initialization was successful, and it should identify any warning or error messages and respond accordingly.

For complete details, see sdkResponse Object.

Step 5: Submit the Form

When the merchant submits the form, call bluesnap.partnerSecuredCaptureSubmitData. This function submits the customer data directly to BlueSnap where we securely store the data and bind it to the session token:

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

After the data is submitted, the result is stored in an sdkResponse object and passed to the partnerSecuredCaptureSetup callback function .

If the submission was successful, BlueSnap binds the merchant data to the token. You can send the token in the request when you submit the merchant application.

📘

Note

After you successfully submit data to BlueSnap (sdkResponse.code is 1), all data within the input fields is deleted to maintain the customer's confidentiality.

Update an Expired Token

The session token expires after 60 minutes. To allow BlueSnap to handle token expiration, write a function that obtains a new token from your server.

BlueSnap automatically calls your function when an expired token is detected, preventing an error from occurring. Prior to calling bluesnap.partnerSecuredCaptureSetup, call bluesnap.setTokenProvider with your function. Your function should contact your server to get the token, and then your function should call the provided callback with it:

bluesnap.setTokenProvider((callback) => {
  // 1. Get a new token from your server
  fetch('path/to/token')
    .then((response) => response.json())
    .then((data) => {
      // 2. Pass token to BlueSnap
      callback(data.token);
    })
    .catch((error) => {
      console.log(error);
      callback();
    });
});

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', details about the error are available in sdkResponse.info.errors. Errors prevent you from continuing the data submission process:

Warnings

When sdkResponse.status is 'Invalid Data', details about the warning will be present in sdkResponse.info.warnings. Warnings inform you about input conditions you might want to address. Unlike errors, warnings do not prevent your data collection or submission process from continuing:

Input Field Reference

These sections list all secure customer data fields and their associated HTML input element and data attribute so you can add them to your application.

For details about which secure input fields you need for your merchant, see New Application API for the applicable country or region.

🚧

Important

The data-bluesnap attribute values must be entered exactly as they appear in these tables.

Business Information

Bank Information

Ownership Information

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

Company Representative Information

Additional Information