With BlueSnap Relay™, you can quickly onboard your customers and begin processing transactions on their behalf. On your platform, you can collect Know Your Customer (KYC) information, and using a simple API call, you can send that data to BlueSnap for automated underwriting and approval. This lets you begin processing transactions quickly and BlueSnap will never be visible to your merchants.
Here's the simple 4-step process:
- Collect your customer's information
- Create the merchant account
- BlueSnap reviews the account
- Create credentials for your merchant
Before you begin
- You must work with a BlueSnap Implementation Engineer to register your platform with us.
- You must be set up to receive IPNs. To enable IPNs, you must set up a server and URL on your side and then configure IPNs in your BlueSnap account. Be sure to enable the "Send Vendor Onboarded" IPN to receive notifications when the vendor onboarding process is approved and complete. Refer to Setting up IPNs for more information.
- Determine the email address you want to use for the customer's merchant account. This email will receive all communications related to the account, including:
- Requests for additional information, if necessary
- emailed decisions from BlueSnap's review
- The link to set up payout
- All other email communications
- If you intend to use Bluesnap’s operator marketplace, be sure to include your vendor ID when using the Create Customer API request.
Testing
After you have read the following steps, you can test the approval workflow.
Read through the steps below and then proceed to the testing instructions.
Step 1: Collect your customer's information
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
- You create a token for the specific session, using a server-to-server API call.
- On the checkout form, you call BlueSnap’s JavaScript file.
- 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.
- 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:
- Obtain the token for the session
- Add the BlueSnap JavaScript file to your form
- Add the Secure Customer Data Fields to your form
- Initialize the Secure Customer Data Fields with your token
- Submit and tokenize the customer's data
Insert the domain for either Sandbox or Production
In all steps below, replace the
BLUESNAPDOMAINPATHwith 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 element | Code |
|---|---|
| Business information | |
| Business name | html <input data-bluesnap="businessName"/> |
| Business legal name | html <input data-bluesnap="businessLegalName"/> |
| Business product and service description | html <input data-bluesnap="businessProductAndServiceDesc"/> |
| Business phone | html <input data-bluesnap="businessPhone"/> |
| Business email | html <input data-bluesnap="businessEmail"/> |
| Business website | html <input data-bluesnap="businessWebsite"/> |
| Business type | html <input data-bluesnap="businessType"/> |
| Business category | html <input data-bluesnap="businessCategory"/> |
| Business tax ID | html <input data-bluesnap="businessTaxId"/> |
| Business address | html <input data-bluesnap="businessAddress"/> |
| Business city | html <input data-bluesnap="businessCity"/> |
| Business state | html <input data-bluesnap="businessState"/> |
| Business suburb | html <input data-bluesnap="businessSuburb"/> |
| Business zip | html <input data-bluesnap="businessZip"/> |
| Business country | html <input data-bluesnap="businessCountry"/> |
| Business account username | html <input data-bluesnap="businessAccountUsername"/> |
| Business sales volume | html <input data-bluesnap="businessSalesVolume"/> |
| Business registration number | html <input data-bluesnap="businessRegistrationNumber"/> |
| Business trading name | html <input data-bluesnap="businessTradingName"/> |
| Business ACN or ABN | html <input data-bluesnap="businessAcnOrAbn"/> |
| Bank information | |
| Bank name | html <input data-bluesnap="bankName"/> |
| Bank branch code | html <input data-bluesnap="bankBranchCode"/> |
| Bank code | html <input data-bluesnap="bankCode"/> |
| Bank routing number | html <input data-bluesnap="bankRoutingNumber"/> |
| Bank account number | html <input data-bluesnap="bankAccountNumber"/> |
| Bank BSB | html <input data-bluesnap="bankBsb"/> |
| Bank transit number | html <input data-bluesnap="bankTransitNumber"/> |
| Bank institution number | html <input data-bluesnap="bankInstitutionNumber"/> |
| Bank sort order | html <input data-bluesnap="bankSortOrder"/> |
| Bank BIC | html <input data-bluesnap="bankBic"/> |
| Bank IBAN | html <input data-bluesnap="bankIban"/> |
| Bank SWIFT or BIC code | html <input data-bluesnap="bankSwiftOrBICCode"/> |
| Bank account number or IBAN | html <input data-bluesnap="bankAccountNumberOrIBAN"/> |
| Bank account type | html <input data-bluesnap="bankAccountType"/> |
| Bank city | html <input data-bluesnap="bankCity"/> |
| Bank state | html <input data-bluesnap="bankState"/> |
| Bank province | html <input data-bluesnap="bankProvince"/> |
| Bank country | html <input data-bluesnap="bankCountry"/> |
| Bank payout currency | html <input data-bluesnap="bankPayoutCurrency"/> |
| Minimal payout amount | html <input data-bluesnap="bankMinimalPayoutAmount"/> |
| Refund reserve | html <input data-bluesnap="bankRefundReserve"/> |
| Ownership info | You can collect data for up to 4 business owners. In the code below, replace [n] with an integer 1 through 4. |
| Business owner first name | html <input data-bluesnap="owner[n]FirstName"/> |
| Business owner last name | html <input data-bluesnap="owner[n]LastName"/> |
| Business owner date of birth | html <input data-bluesnap="owner[n]DateOfBirth"/> |
| Business owner government ID number | html <input data-bluesnap="owner[n]GovID"/> |
| Business owner phone | html <input data-bluesnap="owner[n]Phone"/> |
| Business owner address | html <input data-bluesnap="owner[n]Address"/> |
| Business owner city | html <input data-bluesnap="owner[n]City"/> |
| Business owner state | html <input data-bluesnap="owner[n]State"/> |
| Business owner zip | html <input data-bluesnap="owner[n]Zip"/> |
| Business owner country | html <input data-bluesnap="owner[n]Country"/> |
| Company representative information | |
| Company representative first name | html <input data-bluesnap="companyRepFirstName"/> |
| Company representative last name | html <input data-bluesnap="companyRepLastName"/> |
| Company representative date of birth | html <input data-bluesnap="companyRepDateOfBirth"/> |
| Company representative government ID | html <input data-bluesnap="companyRepGovID"/> |
| Company representative phone | html <input data-bluesnap="companyRepPhone"/> |
| Company representative address | html <input data-bluesnap="companyRepAddress"/> |
| Company representative city | html <input data-bluesnap="companyRepCity"/> |
| Company representative state | html <input data-bluesnap="companyRepState"/> |
| Company representative zip | html <input data-bluesnap="companyRepZip"/> |
| Company representative country | html <input data-bluesnap="companyRepCountry"/> |
| Additional information | |
| Service agreement sign date | html <input data-bluesnap="serviceAgreementDate"/> |
| Pricing agreement sign date | html <input data-bluesnap="pricingAgreementDate"/> |
| Customer's IP address | html <input data-bluesnap="merchantIp"/> |
| Default IPN URL | html <input data-bluesnap="defaultIPN"/> |
data-bluesnap values
The
data-bluesnapvalues 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 a US Customer
- Create an Australian Customer
- Create a Canadian Customer
- Create an EU or UK Customer
- Create a ROW 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:
| Property | Type | Description |
|---|---|---|
status | String | The status of the data submission. Possible values: - Success - The data submission was successful. Finish the form submission to your server and create the merchant account.- Invalid Data - There was an issue with the data passed to BlueSnap. For example, this occurs if an input is missing or invalid. Check sdkResponse.info.warnings for details.- Server Error - The BlueSnap server encountered a problem. Check sdkResponse.info.errors for error details. |
code | Integer | The status code of the data submission. Possible values: - 1 - When sdkResponse.status is Success- 15 - When sdkResponse.status is Invalid Data and the warning does not prevent the process from continuing (such as an invalid or missing input). Your data collection and submission process can continue.- 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). Check sdkResponse.info.errors for error details. |
info | Object | This is present if any errors or warnings occurred. Contains: errors - An array of errorswarnings - An array of warnings |
{
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.
| Error | Description | Solution |
|---|---|---|
Token is expired | When sdkResponse.code is 14040. The token is expired. | Reload the page or implement bluesnap.setTokenProvider (see Updating an expired token). |
All other 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 by checking the error message, please contact BlueSnap Support. |
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.
| Warning message | Description | Solution |
|---|---|---|
Data BlueSnap Input <given_key> is missing | BlueSnap could not find an input value containing the attribute data-bluesnap = ...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 "..." with value of "..." is invalid | One or more of the 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. |
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.
Capturing customer data in plain text
If you prefer to capture and store the customer's data yourself, you will need to build the form that captures and validates all the required information.
Step 2: Create the merchant account
When you have collected all your customer's information, use the server-to-server Create-Merchant API request to send it to BlueSnap for review. If you're using the Secure Customer Data Fields, send your token within pfToken in the request. If you're capturing the customer's data yourself, you will send all the data in plaintext to BlueSnap in the request.
For instructions on using the Create-Merchant API, refer to the page corresponding to your customer's country:
- US Customer
- Australian Customer
- Canadian Customer
- Create an EU or UK Customer
- Customers anywhere in the rest of the world
##Step 3: BlueSnap reviews the merchant account You will receive an [IPN](http://support.bluesnap.com/docs/ipn-setup) based on the outcome of the review.
Note
The IPN is sent only after the review process is complete.
The IPN can contain the following:
- Merchant Name (
merchantName) - Merchant Email (
merchantEmail) - Merchant ID (
merchantId) [The presence of this depends on the review outcome.] - Sandbox ID (
sandboxId) - Processing (
accountCanProcess) =Y,N, orPending - Payout (
payoutStatus) =Y,N, orPending
Use the IPN details to determine what to do next.
| Merchant ID | Processing | Payout | Next Step |
|---|---|---|---|
| ✔ | Y | Y | You can create the merchant credentials and begin processing. |
| ✔ | Y | Pending | You can create the merchant credentials to begin processing. You will receive a second IPN when the merchant is approved for payout. |
| ✖ | Pending | Pending | You cannot create merchant credentials to begin processing. You will receive a second IPN when the merchant is approved. |
| ✖ | N | N | The merchant has been declined; no further updates will be sent. |
##Step 4: Create credentials for your merchant Use the Merchant ID (`merchantId`) from the IPN ([Step 3](#section-step-3-bluesnap-reviews-the-merchant-account)) to create the merchant's credentials using the Get Merchant Credentials API request. These credentials are used to send transactions to BlueSnap on behalf of the merchant.
If your request is successful, you will receive a 200 OK response from BlueSnap with the merchant's credentials.
New Get Merchant API Credentials request
https://platform.bluesnap.com/services/2/merchants/api-credentials
Get Merchant API Credentials Parameters
| Parameter | Required | Details | Description |
|---|---|---|---|
| approvalTesting | No | boolean | Default=false. If you include this parameter and set it to true, you are testing the feature. |
| merchantId | Yes | numeric | The merchant ID assigned to the merchant and included in the IPN. |
| username | No | string | The username for the merchant account. If you don't include it, the response will provide the username. |
| password | No | string | The password for the merchant account. Minimum 8 characters and maximum 64 characters. If you don't include a password, the response will provide it. |
| dataProtectionKey | No | string | The Data Protection Key for the merchant account. If you don't include it, the response will provide it. The Data Protection Key is required to perform certain functions. |
Get Merchant API Credentials Request examples
curl -v -X POST https://platform.bluesnap.com/services/2/merchants/api-credentials \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
{
"merchantId":857345
}
curl -v -X POST https://platform.bluesnap.com/services/2/merchants/api-credentials \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
{
"merchantId":857345,
"username":"MerchantUsername",
"password":"kjhdA@3aA",
"dataProtectionKey": "Kru5Y50p"
}
curl -v -X POST https://platform.bluesnap.com/services/2/merchants/api-credentials \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
{
"approvalTesting": true,
"merchantId": 857345,
"username": "MerchantUsername",
"password": "kjhdA@3aA",
"dataProtectionKey": "Kru5Y50p"
}
Get Merchant API Credentials Response examples
{
"merchantId": 857345,
"username": "MerchantUsername",
"password": "kjhdA@3aA",
"dataProtectionKey": "Kru5Y50p"
}
##Test the merchant approval process Before you actually create a merchant account, you can test the approval workflow. 1. Follow the instructions in [Step 2 above](#section-step-2-create-the-merchant-account). However, at the beginning of the API call, include the `approvalTesting` parameter using the following details:
- If you include this parameter, you are testing the customer-onboarding workflow; the customer account is NOT created but you will receive an IPN and an email as you would in an actual onboarding.
- Type: string
- Valid values:
- APPROVED
- RECOMMEND_APPROVE
- RECOMMEND_DECLINE
- DECLINE
-
The API call bypasses the BlueSnap review process explained above and you receive the response that corresponds to the
approvalTestingparameter value you sent. (Refer to the partial code sample below for details.) -
You receive the IPN and the log-in email right away.
Notes:
- To receive an IPN, you must have configured IPNs on your system.
- The Merchant ID you receive in the IPN and the API credentials are only valid for the sandbox account.
-
Use the Merchant ID (merchantId) from the IPN to create the merchant's credentials using Step 4 above and include a valid
approvalTestingvalue.
curl -v -X POST https://platform.bluesnap.com/services/2/merchants/application \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
{
"approvalTesting": "APPROVED",
"businessInfo": {
"businessName": "My Business",
"legalName": "Business Affiliates, LLC",
....
Start processing transactions!
You can begin processing transactions.
KYC/AML Process Details
As a payments technology company, BlueSnap is required to collect and verify information about all BlueSnap merchant accounts. Our regulators require these steps in order to prevent money laundering, tax evasion, and other financial crimes.
Once we receive your merchant’s account application data from you, we will run series
of background checks automatically. In certain cases, the information provided may need additional verification. We may ask for additional documents such as:
• A government-issued photo ID
• A voided check or bank letter
• Business registration documents etc.
• Financial statements
• Processing statements
• Forward delivery schedule
• Website and description of goods related documents
If we need additional documents, someone from our underwriting team will reach out to you with additional instructions. You can also check the status of your application and provide the required documents on your Partner Portal. Submitting accurate information is crucial and it reduces the likelihood we will reach out to you for additional documents. As a platform, you will be responsible for collecting additional documents from your merchants and providing them to BlueSnap in a timely manner. This allows you to create a white-labeled experience for your merchants.