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:

Property

Type

Description

status

string

Status of the data submission.

Possible values:

Success — The data submission was successful. Finish the form submission to your server and submit a new merchant application.
Invalid Data — There was an issue with the data passed to BlueSnap, such as a missing input or invalid data format. For details, check sdkResponse.info.warnings.
Server Error — The BlueSnap server encountered a problem. For details, check sdkResponse.info.errors.

code

integer

Status code of the data submission.

Possible values:

1 — sdkResponse.status is Success.

Note: When the response status is Success, it is still possible to have errors when you submit the application. There is no validation on parameter values at this stage.
15 — When sdkResponse.status is Invalid Data and the warning does not prevent the process from continuing. You can continue the data collection and submission process.
14040 — When sdkResponse.status is Server Error. The token is expired and needs to be updated.
All other codes indicate a general BlueSnap server error (sdkResponse.status is Server Error). For details, check sdkResponse.info.errors.

info

object

Present if any errors or warnings occurred.

Contains:

errors — An array of errors
warnings — An array of warnings

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:

Error	Description	Solution
`Token is expired`	The token is expired.	Reload the page or implement `bluesnap.setTokenProvider` (see Update an expired token).
General server errors — when `sdkResponse.code` >= `400`, such as `Unauthorized` or `Server Unavailable`	The error message in `sdkResponse.info.errors` will have specific details.	If the error can't be resolved with the error message, contact BlueSnap Support.

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:

Warning message

Description

Solution

Data BlueSnap Input <given_key> is missing

BlueSnap could not find an input value containing the attribute data-bluesnap=<given_key>

For example: 'Data BlueSnap Input owner3Phone is missing'

Ensure the input was properly added to the page, or display a message in the UI for the customer to enter a value.

Parameter "<given_key>" with value of "<value>" is invalid

One or more input values is invalid.

For example: 'Parameter "bankAccountType" with the value of "savings123" is invalid'

Display a message in the UI for the customer to correct the value.

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

Data	Input Field with Data Attribute
Business name	`<input data-bluesnap="businessName"/>`
Business legal name	`<input data-bluesnap="businessLegalName"/>`
Business product and service description	`<input data-bluesnap="businessProductAndServiceDesc"/>`
Business phone	`<input data-bluesnap="businessPhone"/>`
Business email	`<input data-bluesnap="businessEmail"/>`
Business website	`<input data-bluesnap="businessWebsite"/>`
Business additional website	`<input data-bluesnap="businessAdditionalWebsite[n]"/>`
Business type	`<input data-bluesnap="businessType"/>`
Business category	`<input data-bluesnap="businessCategory"/>`
Business tax ID	`<input data-bluesnap="businessTaxId"/>`
Business address	`<input data-bluesnap="businessAddress"/>`
Business city	`<input data-bluesnap="businessCity"/>`
Business state	`<input data-bluesnap="businessState"/>`
Business suburb	`<input data-bluesnap="businessSuburb"/>`
Business zip	`<input data-bluesnap="businessZip"/>`
Business country	`<input data-bluesnap="businessCountry"/>`
Business account username	`<input data-bluesnap="businessAccountUsername"/>`
Business sales volume	`<input data-bluesnap="businessSalesVolume"/>`
Business registration number	`<input data-bluesnap="businessRegistrationNumber"/>`
Business trading name	`<input data-bluesnap="businessTradingName"/>`
Business ACN or ABN	`<input data-bluesnap="businessAcnOrAbn"/>`
Business Average Transaction Amount	`<input data-bluesnap="businessAverageTransactionAmount"/>`
Business Highest Transaction Amount	`<input data-bluesnap=" businessHighestTransactionAmount"/>`
Business Risk Monitoring	`<input data-bluesnap=" businessRiskMonitoring"/>`
Business Risk Management	`<input data-bluesnap=" businessRiskPayment"/>`
Business Risk by Commission	`<input data-bluesnap=" businessRiskByCommission"/>`

Bank Information

Data	Input Field with Data Attribute
Bank name	`<input data-bluesnap="bankName"/>`
Bank branch code	`<input data-bluesnap="bankBranchCode"/>`
Bank code	`<input data-bluesnap="bankCode"/>`
Bank routing number	`<input data-bluesnap="bankRoutingNumber"/>`
Bank account number	`<input data-bluesnap="bankAccountNumber"/>`
Bank BSB	`<input data-bluesnap="bankBsb"/>`
Bank transit number	`<input data-bluesnap="bankTransitNumber"/>`
Bank institution number	`<input data-bluesnap="bankInstitutionNumber"/>`
Bank sort order	`<input data-bluesnap="bankSortOrder"/>`
Bank BIC	`<input data-bluesnap="bankBic"/>`
Bank IBAN	`<input data-bluesnap="bankIban"/>`
Bank SWIFT or BIC code	`<input data-bluesnap="bankSwiftOrBICCode"/>`
Bank account number or IBAN	`<input data-bluesnap="bankAccountNumberOrIBAN"/>`
Bank account type	`<input data-bluesnap="bankAccountType"/>`
Bank city	`<input data-bluesnap="bankCity"/>`
Bank state	`<input data-bluesnap="bankState"/>`
Bank province	`<input data-bluesnap="bankProvince"/>`
Bank country	`<input data-bluesnap="bankCountry"/>`
Bank payout currency	`<input data-bluesnap="bankPayoutCurrency"/>`
Minimal payout amount	`<input data-bluesnap="bankMinimalPayoutAmount"/>`
Refund reserve	`<input data-bluesnap="bankRefundReserve"/>`

Ownership Information

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

Merchant Data	Input Field with Data Attribute
Business owner first name	`<input data-bluesnap="owner[n]FirstName"/>`
Business owner last name	`<input data-bluesnap="owner[n]LastName"/>`
Business owner date of birth	`<input data-bluesnap="owner[n]DateOfBirth"/>`
Business owner government ID number	`<input data-bluesnap="owner[n]GovID"/>`
Business owner phone	`<input data-bluesnap="owner[n]Phone"/>`
Owner percent	`<input data-bluesnap=" owner[n]Percent"/>`
Business owner address	`<input data-bluesnap="owner[n]Address"/>`
Business owner city	`<input data-bluesnap="owner[n]City"/>`
Business owner state	`<input data-bluesnap="owner[n]State"/>`
Business owner zip	`<input data-bluesnap="owner[n]Zip"/>`
Business owner country	`<input data-bluesnap="owner[n]Country"/>`

Company Representative Information

Merchant Data	Input Field with Data Attribute
Company representative first name	`<input data-bluesnap="companyRep[n]FirstName"/>`
Company representative last name	`<input data-bluesnap="companyRep[n]LastName"/>`
Company representative date of birth	`<input data-bluesnap="companyRep[n]DateOfBirth"/>`
Company representative government ID	`<input data-bluesnap="companyRep[n]GovID"/>`
Company representative phone	`<input data-bluesnap="companyRep[n]Phone"/>`
Company representative address	`<input data-bluesnap="companyRep[n]Address"/>`
Company representative city	`<input data-bluesnap="companyRep[n]City"/>`
Company representative state	`<input data-bluesnap="companyRep[n]State"/>`
Company representative zip	`<input data-bluesnap="companyRep[n]Zip"/>`
Company representative country	`<input data-bluesnap="companyRep[n]Country"/>`

Additional Information

Merchant Data	Input Field with Data Attribute
Service agreement sign date	`<input data-bluesnap="serviceAgreementDate"/>`
Pricing agreement sign date	`<input data-bluesnap="pricingAgreementDate"/>`
Customer's IP address	`<input data-bluesnap="merchantIp"/>`
Default IPN URL	`<input data-bluesnap="defaultIPN"/>`
Metadata key	`<input data-bluesnap="metadata[n]Key"/>`
Metadata value	`<input data-bluesnap="metadata[n]Value"/>`