Secure Customer Data Fields

BlueSnap's Secure Customer Data Fields capture and tokenize your customer's sensitive information, without this data ever touching your server. Secure Customer Data Fields are discrete input fields that give you complete control over the look and feel of your data collection form while giving customers the seamless experience of staying on your website.

How it works

1. You create a token for the specific session, using a server-to-server API call.
2. On the checkout form, you call BlueSnap’s JavaScript file.
3. After the customer completes the form and clicks “Submit”, their personal data is saved in BlueSnap’s database and bound to the token you provided.
4. Once the form has been submitted, you can use the token to create the customer's merchant account.

Implementing Secure Customer Data Fields

Before you begin, create a form on your website for customers to enter their personal information. Then you can begin implementing Secure Customer Data Fields, which consists of these steps:

1. Obtain the token for the session
2. Add the BlueSnap JavaScript file to your form
3. Add the Secure Customer Data Fields to your form
4. Initialize the Secure Customer Data Fields with your token
5. Submit and tokenize the customer's data

📘

Insert the domain for either Sandbox or Production

In all steps below, replace the BLUESNAPDOMAINPATH with the relevant BlueSnap domain:

• Sandbox: https://sandbox.bluesnap.com
• Production: https://ws.bluesnap.com

1. Obtain the token for the session

Obtain the token by sending a server-to-server POST request to:

BLUESNAPDOMAINPATH/services/2/payment-fields-tokens

The response provides the token in the location header. For example:
BLUESNAPDOMAINPATH/services/2/payment-fields-tokens/12345abcde

Note: The token expires after 60 minutes.

2. Add the BlueSnap JavaScript file to your form

In your form, call the BlueSnap JavaScript file by adding the following script.

<script type="text/javascript" src="BLUESNAPDOMAINPATH/web-sdk/4/bluesnap.js"></script>

3. Add the Secure Customer Data Fields to your form

For each piece of information you would like to collect from the customer, you will add an input element to your form with a data-bluesnap attribute. The attribute's value will depend on the specific data element you would like to collect. See the following section for details.

Supported customer data elements

The following table outlines all the supported customer data elements, including the code you can add to your page to collect the information. Be sure to collect all required information so BlueSnap can create a merchant account for the customer.

🚧

data-bluesnap values

The data-bluesnap values must be entered exactly as they appear in the above table in order for your implementation to work.

Below is a form capturing business name and business legal name, only for example purposes. You will need to capture more information in order for BlueSnap to successfully create the merchant account.

<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" />

  <!-- Add additional required inputs...  -->
</form>

Required customer data elements

For details on all the data elements you need to include on your form, refer to the Parameters section on the page corresponding to your customer's country:

• Create an Australian Customer
• Create a Canadian Customer
• Create an EU Customer
• Create a ROW Customer
• Create a UK Customer
• Create a US Customer

4. Initialize the Secure Customer Data Fields

After the DOM and the BlueSnap JavaScript file are fully loaded, initialize the Secure Customer Data Fields by calling bluesnap.partnerSecuredCaptureSetup with all the following:

• The token you created in Step 1
• A callback function for when the data submission attempt is completed

Your callback function will receive a sdkResponse object containing the data submission result. Your function should detect the result and respond accordingly. For example, if the data submission was successful, you should continue the form submission to your server and create the customer's merchant account.

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

sdkResponse

The sdkReponse object will be passed to your callback function and will contain the following:

{
  status: 'Invalid Data',
  code: 15,
  info: {
    // if an error or warning occurred
    errors: ['Some error'],
    warnings: ['Some warning']
  }
}

Possible errors

When sdkResponse.status is 'Server Error', details about the error will be present in sdkResponse.info.errors. Errors prevent the data submission process from continuing.

Possible warnings

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

5. Submit and tokenize the customer's data

When the customer clicks the submit button on your form, submit the customer's data directly to BlueSnap, where it will be securely stored and associated with your token, by calling bluesnap.partnerSecuredCaptureSubmitData.

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

When the data submission attempt is completed, the callback you provided to BlueSnap in Step 4 will be called with the results. If the submission was successful (when sdkResponse.code is 1), then you will continue the form submission to your server and create the customer's merchant account using the token.

Note: After a successful data submission to BlueSnap (when sdkResponse.code is 1), all data within the input fields will be deleted to maintain the customer's confidentiality.

Updating an expired token

To allow BlueSnap to handle token expiration, provide a function that obtains a new token from your server. BlueSnap will automatically call 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('/token')
    .then((response) => response.json())
    .then((data) => {
      // 2. Pass token to BlueSnap
      callback(data.token);
    })
    .catch((error) => {
      console.log(error);
      callback();
    });
});

Styling

All of the styling of the input fields (such as width, height, and border) can be performed as usual via CSS.