Note
Secured Payment Collector collects card, ACH, ACSS, BECS and SEPA data but is optimized to collect non-card data. It collects card data at SAQ AEP level. BlueSnap recommends that you use Hosted Payment Fields to collect card data at SAQ A.
BlueSnap's Secured Payment Collector allows you to securely collect the shopper's sensitive details for ACH/ECP, ACSS, BECS, SEPA 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:
- Obtain the token for the session
- Add the BlueSnap JavaScript file to your form
- Add input fields to your form
- Initialize the Secured Payment Collector
- 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
BLUESNAPDOMAINPATHwith the relevant BlueSnap domain:
- Sandbox:
https://sandpay.bluesnap.com- Production:
https://pay.bluesnap.com
Important
Be sure to include the intended URL for the environment you are choosing to use. Including a URL that does not match the environment it is being used in will prevent the solution from working correctly.
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><form action="#">
<label for="sepaIban">IBAN:</label>
<input id="sepaIban" name="sepaIban" data-bluesnap="sepaIban" placeholder="DE89370400440532013000" />
</form><form action="#">
<label for="acssRoutingNumber">Routing Number:</label>
<input id="acssRoutingNumber" name="acssRoutingNumber" data-bluesnap="acssRoutingNumber" placeholder="acssRoutingNumber" />
<label for="acssAccountType">Account Type:</label>
<input id="acssAccountType" name="acssAccountType" data-bluesnap="acssAccountType" placeholder="acssAccountType" />
<label for="acssAccountNumber">Account Number:</label>
<input id="acssAccountNumber" name="acssAccountNumber" data-bluesnap="acssAccountNumber" placeholder="acssAccountNumber" />
</form>
Note: `acssAgreementId` is not collected as an HTML input field. Pass it as a numeric value in the `data` object supplied to `bluesnap.securedPaymentCollectorSubmitData`.<form action="#">
<label for="becsAccountNumber">Account Number:</label>
<input id="becsAccountNumber" name="becsAccountNumber" data-bluesnap="becsAccountNumber" placeholder="becsAccountNumber" />
<label for="becsBsbNumber">BSB Number:</label>
<input id="becsBsbNumber" name="becsBsbNumber" data-bluesnap="becsBsbNumber" placeholder="becsBsbNumber" />
<label for="becsAccountName">Account Name:</label>
<input id="becsAccountName" name="becsAccountName" data-bluesnap="becsAccountName" placeholder="becsAccountName" />
<label for="becsFinancialInstitution">Financial Institution:</label>
<input id="becsFinancialInstitution" name="becsFinancialInstitution" data-bluesnap="becsFinancialInstitution" placeholder="becsFinancialInstitution" />
<label for="becsBranchName">Branch Name:</label>
<input id="becsBranchName" name="becsBranchName" data-bluesnap="becsBranchName" placeholder="becsBranchName" />
</form>
```
Note: `becsAgreementId` is not collected as an HTML input field. Pass it as a numeric value in the `data` object supplied to `bluesnap.securedPaymentCollectorSubmitData`.
data-bluesnap values
The
data-bluesnapvalues 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:
| Parameter | Required | Description |
|---|---|---|
| PAYMENT_TOKEN | Required | The token you obtained in Step 1. |
| Callback function | Required | Callback function for when the data submission attempt is completed. It will receive a For example, if the data submission was successful (when |
| 3-D Secure boolean | Optional; 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. For bank payment methods such as ACH/ECP, SEPA, ACSS, and BECS, cardData is not returned.
// 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
Mandate and agreement text required for SEPA, ACSS, and BECS
If you are collecting SEPA, ACSS, or BECS payments, you must retrieve and display the applicable mandate or agreement text to the shopper before calling thebluesnap.securedPaymentCollectorSubmitData.For ACSS and BECS, the returned
agreementIdmust also be included in yourdataobject. See Mandate and agreement text below.
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
For ACSS and BECS, the data object must also include the applicable debit agreement ID.
document
.getElementById('submitButton')
.addEventListener('click', function () {
const data = {
amount: 10,
currency: 'USD'
};
bluesnap.securedPaymentCollectorSubmitData(data);
});document
.getElementById('submitButton')
.addEventListener('click', function () {
const data = {
amount: 10,
currency: 'CAD',
acssAgreementId: 12345
};
bluesnap.securedPaymentCollectorSubmitData(data);
});document
.getElementById('submitButton')
.addEventListener('click', function () {
const data = {
amount: 10,
currency: 'AUD',
becsAgreementId: 67890
};
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.
If using surcharging, you should call the Calculate Surcharge API after first initializing the Secured Payment Collector and submitting the shopper's data to BlueSnap. Once you have obtained surcharge information, repeat Steps #4 and #5 to once again initialize and re-submit the data that includes surcharge.
If you're using 3-D Secure, the first initialization and data submission should be done without 3-DS. Once you have obtained surcharge information, you will include 3-D Secure when initializing and submitting the data again.
Supported data object properties
The following table outlines the properties that can be included in your data object that you pass to bluesnap.securedPaymentCollectorSubmitData.
Note: All the properties listed below are only relevant for the 3-D Secure flow, except for amount and currency.
| Property | Type | Required |
|---|---|---|
amount | Number | Required |
currency | String See Currency Codes. | Required |
acssAgreementId | Number | Required for ACSS |
becsAgreementId | Number | Required for BECS |
email | String | Optional |
phone | String | Optional |
billingFirstName | String | Optional |
billingLastName | String | Optional |
billingCountry | String See Country Codes | Optional |
billingState | String | Optional |
billingCity | String | Optional |
billingAddress | String | Optional |
billingZip | String | Optional |
shippingFirstName | String | Optional |
shippingLastName | String | Optional |
shippingCountry | String See Country Codes | Optional |
shippingState | String | Optional |
shippingCity | String | Optional |
shippingAddress | String | Optional |
shippingZip | String | Optional |
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.
For all supported payment methods, include pfToken in the request and set its value to your token from Step 1. Use the applicable API for the shopper's payment method:
| Payment Method | API |
|---|---|
ACH/ECP | Create ECP Transaction |
SEPA | Create SEPA DD Transaction |
ACSS | Create Pre-Authorized Debit Transaction |
BECS | Create BECS Transaction |
Card | Completing Tokenized Payments |
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": "PAYMENT_TOKEN",
"amount": 100,
"currency": "USD",
"payerInfo": {
"zip": "12345",
"firstName": "John",
"lastName": "Doe",
"phone": "1234567890"
},
"softDescriptor": "ABC COMPANY",
"authorizedByShopper": true
}'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": "PAYMENT_TOKEN",
"payerInfo": {
"firstName": "John",
"lastName": "Doe",
"country": "FR"
},
"amount": 9.65,
"currency": "EUR",
"softDescriptor": "ABC COMPANY",
"authorizedByShopper": true
}'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": "PAYMENT_TOKEN",
"amount": 11,
"payerInfo": {
"zip": "12345",
"firstName": "John",
"lastName": "Doe",
"country": "CA"
},
"currency": "CAD",
"authorizedByShopper": true
}'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": "PAYMENT_TOKEN",
"amount": 77,
"payerInfo": {
"zip": "12345",
"firstName": "Boris",
"lastName": "Britva",
"country": "AU"
},
"currency": "AUD",
"authorizedByShopper": true
}'For details on how to process card payments, refer to Completing Tokenized Payments.
Mandate and Agreement Text
For payment methods that require a mandate or debit agreement, you must retrieve and display the applicable text to the shopper before they submit the payment form. Call bluesnap.getMandate(paymentType, language) after bluesnap.securedPaymentCollectorSetup is complete.
SEPA: Retrieve and display the mandate text to the shopper before submission.
ACSS and BECS: Retrieve the agreement text and display it to the shopper before submission. Use the returned agreementId as the value for acssAgreementId or becsAgreementId in the data object passed to bluesnap.securedPaymentCollectorSubmitData. Alternatively, you can create the agreement on your backend before payment collection by using the Create Debit Agreement API.
bluesnap.getMandate('SEPA', 'en')
.then(function (mandateResponse) {
console.log(mandateResponse);
});bluesnap.getMandate('ACSS', 'en')
.then(function (mandateResponse) {
console.log(mandateResponse);
});bluesnap.getMandate('BECS', 'en')
.then(function (mandateResponse) {
console.log(mandateResponse);
});| Parameter | Required | Description |
|---|---|---|
paymentType | Required | Payment type for the returned mandate or agreement text. Supported values are SEPA, ACSS, and BECS. |
| `language` | Optional | Language code for the returned text. Default is en. |
Mandate and Agreement Text
json
[
{
"translations": [
{
"language": "en",
"translationText": "By signing this mandate form, you authorise the merchant to send instructions to your bank to debit your account and your bank to debit your account in accordance with the instructions from the merchant. \nAs part of your rights, you are entitled to a refund from your bank under the terms and conditions of your agreement with your bank. A refund must be claimed within 8 weeks starting from the date on which your account was debited. By signing this you are confirming that you understand your account information will be securely stored."
}
]
}
]json
[
{
"region": "Canada",
"debitType": "ONETIME",
"agreementName": "Pre-Authorized Debit Agreement",
"agreementId": 629525,
"agreementText": "I / we authorize the merchant to debit the bank account I / we have identified on any future purchase that I / we make.\nThe amount debited should equal the checkout amount.\nThe merchant is not required to get my / our authorization for any future sporadic debit.\n\nI / we may revoke this authority at any time, subject to providing notice of 30 days.\nTo obtain a sample cancellation form, or for more information on my / our right to cancel a PAD Agreement, I / we may contact my / our financial institution or visit www.payments.ca.\n\nI / we have certain recourse rights if any debit does not comply with this agreement. For example, I / we have the right to receive reimbursement for any debit that is not consistent with this PAD Agreement.\nTo obtain more information on my / our recourse rights, I / we may contact my / our financial institution or visit www.payments.ca.\n\nI authorize BlueSnap, Inc. to process payments on behalf of the merchant.",
"status": "UNUSED"
}
]json
[
{
"region": "Australia",
"debitType": "ONETIME",
"agreementName": "Direct Debit Request Service Agreement",
"agreementId": 629523,
"agreementText": "By signing a Direct Debit Request, you have authorised us to arrange for your nominated account to be debited according to the agreement we have with you.\n\nChanges by us - We will advise you 14 days in advance of any changes to the Direct Debit arrangements.\n\nChanges by you - For all matters relating to the Direct Debit arrangement, including deferment, stops, cancellations or alteration of any of the arrangements, please contact us.\n\nPlease allow 7 days for the amendments to take effect.\n\nDisputes - If you believe that there has been an error in debiting your account, you should contact us in the first instance to confirm the details so that we can investigate the matter and advise you in writing whether your account has been incorrectly or correctly debited.\nIf we can not resolve the matter, you can still refer it to your Financial Institution and they may lodge a claim on your behalf.\n\nYour responsibility - It is your responsibility to ensure you have sufficient cleared funds available in the account to be debited when payments are due.\n\nReturned Payments - In the event that the debit to your account is returned to us unpaid, you will be notified and will have 7 days to pay the amount. A returned payment fee may apply.\n\nAll customer records and account details will be kept private and confidential and will be disclosed only at the request of the customer or Financial Institution in connection with a claim made to an alleged incorrect or wrongful debit.",
"status": "UNUSED"
}
]