BlueSnap.comAPI BasicsPayment APIEmbedded PaymentsReporting & ToolsSupport GuidesTest
API Reference

Secured Payment Collector

BlueSnap's Secured Payment Collector allows you to securely collect the shopper's sensitive details for ACH/ECP and card payments. Secured Payment Collector consists of discrete input fields that give you complete control over the look and feel of your checkout form while giving customers the seamless experience of staying on your website. When the shopper submits the checkout form, BlueSnap securely captures and tokenizes their sensitive information. You can then include the token in the API request to finish the transaction or save their information for future use.

Implementing Secured Payment Collector

Implementing Secured Payment Collector consists of these steps:
1. Obtain the token for the session
2. Add the BlueSnap JavaScript file to your form
3. Add input fields to your form
4. Initialize the Secured Payment Collector
5. Submit the shopper's data to BlueSnap
Updating an expired token
Using the token to process payments

📘

Insert the domain for either Sandbox or Production

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

  • Sandbox: https://sandpay.bluesnap.com
  • Production: https://pay.bluesnap.com

1. Obtain the token for the session

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

Production: https://ws.bluesnap.com/services/2/payment-fields-tokens
Sandbox: https://sandbox.bluesnap.com/services/2/payment-fields-tokens

The response provides the token in the location header. For example:
Production: https://ws.bluesnap.com/services/2/payment-fields-tokens/12345abcde
Sandbox: https://sandbox.bluesnap.com/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/5/bluesnap.js"></script>

3: Add the input fields to your form

Add input elements to your form with a data-bluesnap attribute so BlueSnap knows where to capture the sensitive data from. See the code samples below for the specific inputs to add to your form. 

<form action="#">
  <label for="ecpRoutingNumber">Routing Number:</label>
  <input id="ecpRoutingNumber" name="ecpRoutingNumber" data-bluesnap="ecpRoutingNumber" placeholder="ACH/ECP Routing Number" />

  <label for="ecpAccountNumber">Account Number:</label>
  <input id="ecpAccountNumber" name="ecpAccountNumber" data-bluesnap="ecpAccountNumber" placeholder="ACH/ECP Account Number" />

  <label for="ecpAccountType">Account Type:</label>
  <input id="ecpAccountType" name="ecpAccountType" data-bluesnap="ecpAccountType" placeholder="ACH/ECP Account Type" />
</form>

<form action="#">
  <label for="ccn">credit card number:</label>
  <input id="ccn" name="ccn" data-bluesnap="ccNumber" pattern="^[0-9]{10,26}$" placeholder="1234567890123456" />

  <label for="cvv">cvv:</label>
  <input id="cvv" name="cvv" data-bluesnap="cvv" pattern="^[0-9]{3,4}$" placeholder="123" />

  <label for="exp">expiration date:</label>
  <input id="exp" name="exp" data-bluesnap="expDate" pattern="^[0-9]{2}\/[0-9]{4}$" placeholder="MM/YYYY" />
</form>

<form action="#">
  <label for="last4digits">Credit card (last 4 digits)</label>
  <input id="last4digits" name="last4digits" data-bluesnap=" last4Digits" pattern="^[0-9]{4}$" placeholder="1234" />

  <label for="type">Card type</label>
  <input id="type" name="type" data-bluesnap="ccType" pattern="^[A-Z]{3,}([_][A-Z]{3,}){0,}$" placeholder="VISA" />
</form>

🚧

data-bluesnap values

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

4. Initialize the Secured Payment Collector

After the DOM and the BlueSnap JavaScript file are fully loaded, initialize the Secured Payment Collector by calling bluesnap.securedPaymentCollectorSetup with the following parameters:

ParameterRequiredDescription
PAYMENT_TOKENRequiredThe token you obtained in Step 1.
Callback functionRequiredCallback function for when the data submission attempt is completed. It will receive a sdkResponse object containing the submission result. Your function should detect the result and respond accordingly.

For example, if the data submission was successful (when sdkResponse.code is 1), you should continue the form submission to your server and process the payment.
3-D Secure booleanOptional; Only applicable for card payments.Whether the card transaction should use 3-D Secure. Default value is false.

Depending on the shopper's payment method, your code will look similar to the following code samples. The primary difference between the code samples is whether sdkResponse contains the cardData property. 

// Run after DOM and BlueSnap JS are fully loaded
document.addEventListener('DOMContentLoaded', function () {
  bluesnap.securedPaymentCollectorSetup(
    'PAYMENT_TOKEN',
    function (sdkResponse) {
      if (sdkResponse.code == 1) {
        // Data submission was a success
        // Continue form submission to your server & complete the transaction
      } else {
        // Data submission resulted in error or warning
        const { errors, warnings } = sdkResponse.info;
        console.log('Errors: ', errors);
        console.log('Warnings: ', warnings);
      }
    },
    false
  );
});

// Run after DOM and BlueSnap JS are fully loaded
document.addEventListener('DOMContentLoaded', function () {
  bluesnap.securedPaymentCollectorSetup(
    'PAYMENT_TOKEN',
    function (sdkResponse) {
      if (sdkResponse.code == 1) {
        // Submission was successful
        const { cardData /*, threeDSecure */ } = sdkResponse;
        console.log('Card Data:', cardData);
        // Continue form submission to your server & complete the transaction
      } else {
        // Submission resulted in an error or warning
        const { errors, warnings } = sdkResponse.info;
        console.log('Errors: ', errors);
        console.log('Warnings: ', warnings);
      }
    },
    false // set to true for 3-D Secure
  );
});

5. Submit the shopper's data to BlueSnap

When the shopper clicks the submit button on your form, you will submit their data directly to BlueSnap, where it will be securely stored and associated with your token. Call bluesnap.securedPaymentCollectorSubmitData with an object containing details about the transaction. At a minimum, include the transaction amount and currency (see Supported data object properties). The transaction details contained in the object will be tokenized along with the shopper's sensitive payment details

document
  .getElementById('submitButton')
  .addEventListener('click', function () {
    const data = {
      amount: 10,
      currency: 'USD'
    };
    bluesnap.securedPaymentCollectorSubmitData(data);
  });

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), your callback will continue the form submission to your server, where you can process the transaction using the token.

Note: After a successful data submission to BlueSnap, all data within the input fields containing a data-bluesnap attribute will be deleted to maintain the shopper's confidentiality.

Supported data object properties

The following table outlines the properties that can be included in your data object that you pass to bluesnap.securedPaymentCollectorSubmitData.

PropertyTypeRequired
amountNumberRequired
currencyString

See Currency Codes.		Required
emailStringOptional
phoneStringOptional
billingFirstNameStringOptional
billingLastNameStringOptional
billingCountryString

See Country Codes		Optional
billingStateString

See State and Province Codes		Optional
billingCityStringOptional
billingAddressStringOptional
billingZipStringOptional
shippingFirstNameStringOptional
shippingLastNameStringOptional
shippingCountryString

See Country Codes		Optional
shippingStateString

See State and Province Codes		Optional
shippingCityStringOptional
shippingAddressStringOptional
shippingZipStringOptional

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.securedPaymentCollectorSetup, 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.

// Run before calling bluesnap.securedPaymentCollectorSetup
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();
    });
});

Using the token to process payments

After submitting the shopper's data to BlueSnap, your callback from Step 4 will be triggered. If the data submission was successful, you can process the transaction by including the token in your API request. This must be done from your server and requires using your API Credentials.

To process an ACH/ECP payment, send a Create ECP Transaction request. As part of the required properties, include pfToken in the request, with its value set to your token from Step 1. 

curl -v -X POST https://sandbox.bluesnap.com/services/2/alt-transactions/ \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \ 
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
{
  "pfToken": "eba795a8ec2a8e7754afe7a69b0a0869fba0e6daec01e2d81e1ccbb6771c24ab_",
  "amount": 100,
  "currency": "USD",
  "payerInfo": {
    "zip": "12345",
    "firstName": "John",
    "lastName": "Doe",
    "phone": "1234567890"
  },
  "softDescriptor": "ABC COMPANY",
  "authorizedByShopper": true
}'

For details on how to process card payments, refer to Completing Tokenized Payments.