{"metadata":{"image":[],"title":"","description":""},"api":{"url":"","auth":"required","examples":{"codes":[]},"settings":"","results":{"codes":[]},"params":[]},"next":{"description":"","pages":[]},"title":"Customer Onboarding","type":"basic","slug":"customer-onboarding","excerpt":"","body":"##Before you begin\n*  You must have worked with a BlueSnap Implementation Engineer to register your platform with us.\n*  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. Refer to [Setting up IPNs](http://support.bluesnap.com/docs/ipn-setup) for more information.\n* 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:\n   * requests for additional information, if necessary\n   * emailed decisions from BlueSnap's review\n   * the link set up the payout\n   * all other email communications \n\n##Process\n1. [Collect your customer's information](#section-step-1-collect-your-customer-s-information)\n2. [Create the merchant account](#section-step-2-create-the-merchant-account)\n3. [BlueSnap reviews the account](#section-step-3-bluesnap-reviews-the-merchant-account)\n4. [Create the credentials for your merchant](#section-step-4-create-the-credentials-for-your-merchant)\n<p id=\"testing\" />\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"After you have read the following steps, you can test the approval workflow.\\nRead through the steps below and then proceed to the [testing instructions](#section-test-the-merchant-approval-process).\",\n  \"title\": \"Testing\"\n}\n[/block]\n<hr />\n\n##Step 1: Collect your customer's information\nBlueSnap'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. \n\n**How it works**\n\n1. You create a token for the specific session, using a server-to-server API call.\n2. On the checkout form, you call BlueSnap’s JavaScript file. \n3. 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.\n4. Once the form has been submitted, you can use the token to create the customer's merchant account. \n\n### Implementing Secure Customer Data Fields\nBefore you begin, create a form on your website for customers to enter their [personal information](#section-supported-customer-data-elements). Then you can begin implementing Secure Customer Data Fields, which consists of these steps: \n\n1. [Obtain the token for the session](#section-1-obtain-the-token-for-the-session)\n2. [Add the BlueSnap JavaScript file to your form](#section-2-add-the-bluesnap-javascript-file-to-your-form)\n3. [Add the Secure Customer Data Fields to your form](#section-3-add-the-secure-customer-data-fields-to-your-form)\n4. [Initialize the Secure Customer Data Fields with your token](#section-4-initialize-the-secure-customer-data-fields)\n5. [Submit and tokenize the customer's data](#section-5-submit-and-tokenize-the-customer-s-data)\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Insert the domain for either Sandbox or Production\",\n  \"body\": \"In all steps below, replace the `BLUESNAPDOMAINPATH` with the relevant BlueSnap domain:\\n* Sandbox: `https://sandbox.bluesnap.com`\\n* Production: `https://ws.bluesnap.com`\"\n}\n[/block]\n### 1. Obtain the token for the session\nObtain the token by sending a server-to-server POST request to:\n\n`BLUESNAPDOMAINPATH/services/2/payment-fields-tokens`\n\nThe response provides the token in the location header. For example: \n`BLUESNAPDOMAINPATH/services/2/payment-fields-tokens/12345abcde`\n\n**Note:** The token expires after 60 minutes. \n\n### 2. Add the BlueSnap JavaScript file to your form\nIn your form, call the BlueSnap JavaScript file by adding the following script. \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<script type=\\\"text/javascript\\\" src=\\\"BLUESNAPDOMAINPATH/web-sdk/4/bluesnap.js\\\"></script>\",\n      \"language\": \"html\"\n    }\n  ]\n}\n[/block]\n### 3. Add the Secure Customer Data Fields to your form\nFor 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. \n\n### Supported customer data elements\nThe 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](#section-required-customer-data-elements) so BlueSnap can create a merchant account for the customer. \n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Data element\",\n    \"h-1\": \"Code\",\n    \"1-0\": \"Business name\",\n    \"1-1\": \"```html\\n<input data-bluesnap=\\\"businessName\\\"/>\\n```\",\n    \"0-0\": \"**Business information**\",\n    \"2-0\": \"Business legal name\",\n    \"2-1\": \"```html\\n <input data-bluesnap=\\\"businessLegalName\\\"/>\\n```\",\n    \"3-0\": \"Business product and service description\",\n    \"4-0\": \"Business phone\",\n    \"6-0\": \"Business website\",\n    \"7-0\": \"Business type\",\n    \"8-0\": \"Business category\",\n    \"9-0\": \"Business tax ID\",\n    \"10-0\": \"Business address\",\n    \"11-0\": \"Business city\",\n    \"12-0\": \"Business state\",\n    \"14-0\": \"Business zip\",\n    \"15-0\": \"Business country\",\n    \"5-0\": \"Business email\",\n    \"h-2\": \"Code\",\n    \"16-0\": \"Business account username\",\n    \"17-0\": \"Business sales volume\",\n    \"18-0\": \"Business registration number\",\n    \"19-0\": \"Business trading name\",\n    \"20-0\": \"Business ACN or ABN\",\n    \"21-0\": \"**Bank information**\",\n    \"13-0\": \"Business suburb\",\n    \"23-0\": \"Bank branch code\",\n    \"24-0\": \"Bank code\",\n    \"25-0\": \"Bank routing number\",\n    \"26-0\": \"Bank account number\",\n    \"35-0\": \"Bank account type\",\n    \"27-0\": \"Bank BSB\",\n    \"22-0\": \"Bank name\",\n    \"41-0\": \"Minimal payout amount\",\n    \"42-0\": \"Refund reserve\",\n    \"36-0\": \"Bank city\",\n    \"37-0\": \"Bank state\",\n    \"38-0\": \"Bank province\",\n    \"40-0\": \"Bank payout currency\",\n    \"28-0\": \"Bank transit number\",\n    \"29-0\": \"Bank institution number\",\n    \"30-0\": \"Bank sort order\",\n    \"31-0\": \"Bank BIC\",\n    \"32-0\": \"Bank IBAN\",\n    \"33-0\": \"Bank SWIFT or BIC code\",\n    \"34-0\": \"Bank account number or IBAN\",\n    \"39-0\": \"Bank country\",\n    \"43-0\": \"**Ownership info**\",\n    \"44-0\": \"Business owner first name\",\n    \"45-0\": \"Business owner last name\",\n    \"46-0\": \"Business owner date of birth\",\n    \"47-0\": \"Business owner government ID number\",\n    \"48-0\": \"Business owner phone\",\n    \"49-0\": \"Business owner address\",\n    \"50-0\": \"Business owner city\",\n    \"51-0\": \"Business owner state\",\n    \"52-0\": \"Business owner zip\",\n    \"53-0\": \"Business owner country\",\n    \"0-1\": \"\",\n    \"3-1\": \"```html\\n<input data-bluesnap=\\\"businessProductAndServiceDesc\\\"/>\\n```\",\n    \"4-1\": \"```html\\n <input data-bluesnap=\\\"businessPhone\\\"/>\\n```\",\n    \"5-1\": \"```html\\n<input data-bluesnap=\\\"businessEmail\\\"/>\\n```\",\n    \"6-1\": \"```html\\n<input data-bluesnap=\\\"businessWebsite\\\"/>\\n```\",\n    \"44-1\": \"```html\\n<input data-bluesnap=\\\"owner[n]FirstName\\\"/>\\n```\",\n    \"43-1\": \"You can collect data for up to 4 business owners. In the code below, replace `[n]` with an integer 1 through 4.\",\n    \"45-1\": \"```html\\n<input data-bluesnap=\\\"owner[n]LastName\\\"/>\\n```\",\n    \"46-1\": \"```html\\n <input data-bluesnap=\\\"owner[n]DateOfBirth\\\"/>\\n```\",\n    \"47-1\": \"```html\\n<input data-bluesnap=\\\"owner[n]GovID\\\"/>\\n```\",\n    \"48-1\": \"```html\\n<input data-bluesnap=\\\"owner[n]Phone\\\"/>\\n```\",\n    \"49-1\": \"```html\\n<input data-bluesnap=\\\"owner[n]Address\\\"/>\\n```\",\n    \"50-1\": \"```html\\n<input data-bluesnap=\\\"owner[n]City\\\"/>\\n```\",\n    \"51-1\": \"```html\\n<input data-bluesnap=\\\"owner[n]State\\\"/>\\n```\",\n    \"52-1\": \"```html\\n<input data-bluesnap=\\\"owner[n]Zip\\\"/>\\n```\",\n    \"53-1\": \"```html\\n<input data-bluesnap=\\\"owner[n]Country\\\"/>\\n```\",\n    \"54-0\": \"**Company representative information**\",\n    \"55-0\": \"Company representative first name\",\n    \"56-0\": \"Company representative last name\",\n    \"57-0\": \"Company representative date of birth\",\n    \"58-0\": \"Company representative government ID\",\n    \"59-0\": \"Company representative phone\",\n    \"60-0\": \"Company representative address\",\n    \"61-0\": \"Company representative city\",\n    \"62-0\": \"Company representative state\",\n    \"63-0\": \"Company representative zip\",\n    \"64-0\": \"Company representative country\",\n    \"65-0\": \"**Additional information**\",\n    \"55-1\": \"```html\\n<input data-bluesnap=\\\"companyRepFirstName\\\"/>\\n```\",\n    \"56-1\": \"```html\\n<input data-bluesnap=\\\"companyRepLastName\\\"/>\\n```\",\n    \"57-1\": \"```html\\n<input data-bluesnap=\\\"companyRepDateOfBirth\\\"/>\\n```\",\n    \"58-1\": \"```html\\n<input data-bluesnap=\\\"companyRepGovID\\\"/>\\n```\",\n    \"59-1\": \"```html\\n<input data-bluesnap=\\\"companyRepPhone\\\"/>\\n```\",\n    \"60-1\": \"```html\\n<input data-bluesnap=\\\"companyRepAddress\\\"/>\\n```\",\n    \"61-1\": \"```html\\n<input data-bluesnap=\\\"companyRepCity\\\"/>\\n```\",\n    \"62-1\": \"```html\\n<input data-bluesnap=\\\"companyRepState\\\"/>\\n```\",\n    \"63-1\": \"```html\\n<input data-bluesnap=\\\"companyRepZip\\\"/>\\n```\",\n    \"64-1\": \"```html\\n<input data-bluesnap=\\\"companyRepCountry\\\"/>\\n```\",\n    \"65-1\": \"\",\n    \"66-0\": \"Service agreement sign date\",\n    \"67-0\": \"Pricing agreement sign date\",\n    \"68-0\": \"Customer's IP address\",\n    \"69-0\": \"Default IPN URL\",\n    \"7-1\": \"```html\\n<input data-bluesnap=\\\"businessType\\\"/>\\n```\",\n    \"8-1\": \"```html\\n<input data-bluesnap=\\\"businessCategory\\\"/>\\n```\",\n    \"9-1\": \"```html\\n<input data-bluesnap=\\\"businessTaxId\\\"/>\\n```\",\n    \"10-1\": \"```html\\n<input data-bluesnap=\\\"businessAddress\\\"/>\\n```\",\n    \"22-1\": \"```html\\n<input data-bluesnap=\\\"bankName\\\"/>\\n```\",\n    \"23-1\": \"```html\\n<input data-bluesnap=\\\"bankBranchCode\\\"/>\\n```\",\n    \"66-1\": \"```html\\n<input data-bluesnap=\\\"serviceAgreementDate\\\"/>\\n```\",\n    \"11-1\": \"```html\\n <input data-bluesnap=\\\"businessCity\\\"/>\\n```\",\n    \"12-1\": \"```html\\n<input data-bluesnap=\\\"businessState\\\"/>\\n```\",\n    \"13-1\": \"```html\\n<input data-bluesnap=\\\"businessSuburb\\\"/>\\n```\",\n    \"14-1\": \"```html\\n<input data-bluesnap=\\\"businessZip\\\"/>\\n```\",\n    \"15-1\": \"```html\\n<input data-bluesnap=\\\"businessCountry\\\"/>\\n```\",\n    \"16-1\": \"```html\\n<input data-bluesnap=\\\"businessAccountUsername\\\"/>\\n```\",\n    \"17-1\": \"```html\\n<input data-bluesnap=\\\"businessSalesVolume\\\"/>\\n```\",\n    \"18-1\": \"```html\\n<input data-bluesnap=\\\"businessRegistrationNumber\\\"/>\\n```\",\n    \"19-1\": \"```html\\n<input data-bluesnap=\\\"businessTradingName\\\"/>\\n```\",\n    \"20-1\": \"```html\\n<input data-bluesnap=\\\"businessAcnOrAbn\\\"/>\\n```\",\n    \"24-1\": \"```html\\n<input data-bluesnap=\\\"bankCode\\\"/>\\n```\",\n    \"25-1\": \"```html\\n<input data-bluesnap=\\\"bankRoutingNumber\\\"/>\\n```\",\n    \"26-1\": \"```html\\n <input data-bluesnap=\\\"bankAccountNumber\\\"/>\\n```\",\n    \"27-1\": \"```html\\n<input data-bluesnap=\\\"bankBsb\\\"/>\\n```\",\n    \"28-1\": \"```html\\n<input data-bluesnap=\\\"bankTransitNumber\\\"/>\\n```\",\n    \"29-1\": \"```html\\n<input data-bluesnap=\\\"bankInstitutionNumber\\\"/>\\n```\",\n    \"30-1\": \"```html\\n<input data-bluesnap=\\\"bankSortOrder\\\"/>\\n```\",\n    \"31-1\": \"```html\\n<input data-bluesnap=\\\"bankBic\\\"/>\\n```\",\n    \"32-1\": \"```html\\n<input data-bluesnap=\\\"bankIban\\\"/>\\n```\",\n    \"33-1\": \"```html\\n<input data-bluesnap=\\\"bankSwiftOrBICCode\\\"/>\\n```\",\n    \"34-1\": \"```html\\n<input data-bluesnap=\\\"bankAccountNumberOrIBAN\\\"/>\\n```\",\n    \"35-1\": \"```html\\n<input data-bluesnap=\\\"bankAccountType\\\"/>\\n```\",\n    \"36-1\": \"```html\\n<input data-bluesnap=\\\"bankCity\\\"/>\\n```\",\n    \"37-1\": \"```html\\n <input data-bluesnap=\\\"bankState\\\"/>\\n```\",\n    \"38-1\": \"```html\\n<input data-bluesnap=\\\"bankProvince\\\"/>\\n```\",\n    \"39-1\": \"```html\\n<input data-bluesnap=\\\"bankCountry\\\"/>\\n```\",\n    \"40-1\": \"```html\\n<input data-bluesnap=\\\"bankPayoutCurrency\\\"/>\\n```\",\n    \"41-1\": \"```html\\n <input data-bluesnap=\\\"bankMinimalPayoutAmount\\\"/>\\n```\",\n    \"42-1\": \"```html\\n<input data-bluesnap=\\\"bankRefundReserve\\\"/>\\n```\",\n    \"67-1\": \"```html\\n<input data-bluesnap=\\\"pricingAgreementDate\\\"/>\\n```\",\n    \"68-1\": \"```html\\n<input data-bluesnap=\\\"merchantIp\\\"/>\\n```\",\n    \"69-1\": \"```html\\n<input data-bluesnap=\\\"defaultIPN\\\"/>\\n```\"\n  },\n  \"cols\": 2,\n  \"rows\": 70\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"data-bluesnap values\",\n  \"body\": \"The `data-bluesnap` values must be entered exactly as they appear in the above table in order for your implementation to work.\"\n}\n[/block]\nBelow 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. \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<form action=\\\"#\\\">\\n  <label for=\\\"businessName\\\">business Name:</label>\\n  <input id=\\\"businessName\\\" name=\\\"businessName\\\" data-bluesnap=\\\"businessName\\\" placeholder=\\\"Business Name\\\" />\\n\\n  <label for=\\\"businessLegalName\\\">business Legal Name:</label>\\n  <input id=\\\"businessLegalName\\\" name=\\\"businessLegalName\\\" data-bluesnap=\\\"businessLegalName\\\" placeholder=\\\"Business Legal Name\\\" />\\n\\n  <!-- Add additional required inputs...  -->\\n</form>\",\n      \"language\": \"html\",\n      \"name\": \"Example\"\n    }\n  ]\n}\n[/block]\n#### Required customer data elements\nFor 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:\n\n* [US Customer](https://developers.bluesnap.com/v8976-Basics/docs/create-us-customer#section-create-merchant-api-parameters-for-us-customers)\n* [Australian Customer](https://developers.bluesnap.com/v8976-Basics/docs/create-au-customer#section-create-merchant-api-parameters-for-australian-customers)\n* [Canadian Customer](https://developers.bluesnap.com/v8976-Basics/docs/create-ca-customer#section-create-merchant-api-parameters-for-canadian-customers)\n* [EU Customer ](https://developers.bluesnap.com/v8976-Basics/docs/create-eu-customer#section-create-merchant-api-parameters-for-eu-customers)\n* [Customers anywhere in the rest of the world](https://developers.bluesnap.com/v8976-Basics/docs/create-row-customer#section-create-merchant-api-parameters-for-row-customers)\n\n### 4. Initialize the Secure Customer Data Fields\nAfter the DOM and the BlueSnap JavaScript file are fully loaded, initialize the Secure Customer Data Fields by calling `bluesnap.partnerSecuredCaptureSetup` with all the following:\n\n* The token you created in Step 1\n* A callback function for when the data submission attempt is completed \n\nYour callback function will receive a [`sdkResponse` object](#section-sdkresponse) 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](#section-step-2-create-the-merchant-account). \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"// Run after DOM and BlueSnap JS are fully loaded\\ndocument.addEventListener('DOMContentLoaded', function () {\\n  bluesnap.partnerSecuredCaptureSetup('TOKEN', function (sdkResponse) {\\n    if (sdkResponse.code === 1) {\\n      // Submission was successful\\n      // Continue form submission to your server and create merchant account...\\n    } else {\\n      // Submission resulted in an error or warning\\n      const { errors, warnings } = sdkResponse.info;\\n      console.log('Errors: ', errors);\\n      console.log('Warnings: ', warnings);\\n    }\\n  });\\n});\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n#### sdkResponse\nThe `sdkReponse` object will be passed to your callback function and will contain the following: \n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Property\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\",\n    \"h-3\": \"Description\",\n    \"0-0\": \"`status`\",\n    \"0-1\": \"String\",\n    \"0-2\": \"The status of the data submission. \\n\\nPossible values: \\n- `Success` - The data submission was successful. Finish the form submission to your server and [create the merchant account](#section-step-2-create-the-merchant-account). \\n\\n- `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. \\n\\n- `Server Error` -  The BlueSnap server encountered a problem. Check `sdkResponse.info.errors` for error details.\",\n    \"0-3\": \"The status of the data submission. \\n\\nPossible values: \\n- `'Success'` - The data submission was successful. You can finish the form submission to your server and [create the merchant account](#section-step-2-create-the-merchant-account). \\n\\n- `'Invalid Data'` - There was an issue with the data passed to BlueSnap. For example, this occurs if an input is missing or empty.  \\n\\n- `'Server Error'` - There was an issue with the BlueSnap server.\",\n    \"1-0\": \"`code`\",\n    \"1-1\": \"Integer\",\n    \"1-2\": \"The status code of the data submission. \\n\\nPossible values: \\n- `1` - When `sdkResponse.status` is `Success`\\n\\n- `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. \\n\\n- `14040` - When `sdkResponse.status` is `Server Error`. The token is expired and needs to be updated. \\n\\n- All other codes indicate a general BlueSnap server error (`sdkResponse.status` is `Server Error`). Check `sdkResponse.info.errors` for error details.\",\n    \"1-3\": \"The status code of the data submission. \\n\\nPossible values: \\n- `1` - When `status` is `'Success'`\\n\\n- `10` - When `status` is `'Invalid Data'` and the error prevents the process from continuing. \\n\\n- `15` - When `status` is `'Invalid Data'` and the error does not prevent the process from continuing. (The callback is called with a warning\\narray. The process continues and your callback is triggered on form completion).\\n\\n- `14040` - Token is expired. Update the token. \\n\\n- `400`, `500` - General server error\",\n    \"2-0\": \"`info`\",\n    \"2-1\": \"Object\",\n    \"2-2\": \"This is present if any errors or warnings occurred. \\n\\nContains: \\n* `errors` - An array of [errors](#section-possible-errors) \\n* `warnings` - An array of [warnings](#section-possible-warnings)\",\n    \"2-3\": \"This is present if any errors or warnings occurred. \\n\\nContains: \\n* `errors` - An array of [errors](#section-possible-errors) \\n* `warnings` - An array of [warnings](#section-possible-warnings)\"\n  },\n  \"cols\": 3,\n  \"rows\": 3\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  status: 'Invalid Data',\\n  code: 15,\\n  info: {\\n    // if an error or warning occurred\\n    errors: ['Some error'],\\n    warnings: ['Some warning']\\n  }\\n}\",\n      \"language\": \"javascript\",\n      \"name\": \"skdResponse Example\"\n    }\n  ]\n}\n[/block]\n#### Possible errors \nWhen `sdkResponse.status` is `'Server Error'`, details about the error will be present in `sdkResponse.info.errors`. Errors prevent the data submission process from continuing. \n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Error\",\n    \"h-1\": \"Description\",\n    \"h-2\": \"Solution\",\n    \"0-0\": \"`Token is expired`\",\n    \"0-1\": \"When `sdkResponse.code` is `14040`. The token is expired.\",\n    \"0-2\": \"Reload the page or implement `bluesnap.setTokenProvider` (see [Updating an expired token](#section-updating-an-expired-token)).\",\n    \"1-0\": \"All other general server errors (when `sdkResponse.code` >= `400`), such as Unauthorized or Server Unavailable\",\n    \"1-1\": \"The error message in `sdkResponse.info.errors` will have specific details.\",\n    \"1-2\": \"If the error can't be resolved by checking the error message, please contact BlueSnap Support.\"\n  },\n  \"cols\": 3,\n  \"rows\": 2\n}\n[/block]\n#### Possible warnings\nWhen `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. \n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Warning message\",\n    \"h-1\": \"Description\",\n    \"0-0\": \"`Data BlueSnap Input <given_key> is missing`\",\n    \"0-1\": \"BlueSnap could not find an input value containing the attribute `data-bluesnap` = ... \\n\\nFor example: 'Data BlueSnap Input owner3Phone is missing'\",\n    \"1-0\": \"`Parameter \\\"...\\\" with value  of \\\"...\\\" is invalid`\",\n    \"1-1\": \"One or more of the input values is invalid. \\n\\nFor example: 'Parameter \\\"bankAccountType\\\" with the value of \\\"savings123\\\" is invalid'\",\n    \"h-2\": \"Solution\",\n    \"0-2\": \"Ensure the input was properly added to the page or display a message in the UI for the customer to enter a value.\",\n    \"1-2\": \"Display a message in the UI for the customer to correct the value.\"\n  },\n  \"cols\": 3,\n  \"rows\": 2\n}\n[/block]\n### 5. Submit and tokenize the customer's data\nWhen 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`. \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"document\\n  .getElementById('submitButton')\\n  .addEventListener('click', function () {\\n    bluesnap.partnerSecuredCaptureSubmitData();\\n  });\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nWhen 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](#section-step-2-create-the-merchant-account) using the token. \n\n**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. \n\n#### Updating an expired token\nTo 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.  \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"bluesnap.setTokenProvider((callback) => {\\n  // 1. Get a new token from your server\\n  fetch('/token')\\n    .then((response) => response.json())\\n    .then((data) => {\\n      // 2. Pass token to BlueSnap\\n      callback(data.token);\\n    })\\n    .catch((error) => {\\n      console.log(error);\\n      callback();\\n    });\\n});\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n#### Styling \nAll of the styling of the `input` fields (such as width, height, and border) can be performed as usual via CSS.\n\n### Capturing customer data in plain text\nIf 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](#section-required-customer-data-elements). \n\n<hr />\n\n##Step 2: Create the merchant account\nWhen 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. \n\nFor instructions on using the **Create-Merchant API**, refer to the page corresponding to your customer's country:\n\n* [US Customer](https://developers.bluesnap.com/v8976-Basics/docs/create-us-customer)\n* [Australian Customer](https://developers.bluesnap.com/v8976-Basics/docs/create-au-customer)\n* [Canadian Customer](https://developers.bluesnap.com/v8976-Basics/docs/create-ca-customer)\n* [EU Customer](https://developers.bluesnap.com/v8976-Basics/docs/create-eu-customer)\n* [Customers anywhere in the rest of the world](https://developers.bluesnap.com/v8976-Basics/docs/create-row-customer)\n\n<hr />\n##Step 3: BlueSnap reviews the merchant account\nYou will receive an [IPN](http://support.bluesnap.com/docs/ipn-setup) based on the outcome of the review. \n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Note\",\n  \"body\": \"The IPN is sent only ***after*** the review process is complete.\"\n}\n[/block]\nThe IPN can contain the following:\n*  Merchant Name (`merchantName`)\n* Merchant Email (`merchantEmail`)\n* Merchant ID (`merchantId`) [The presence of this depends on the review outcome.]\n* Processing (`accountCanProcess`) = `Y`, `N`, or  `Pending`\n * Payout (`payoutStatus`) = `Y`, `N`, or  `Pending`\n\nUse the IPN details to determine what to do next.\n[block:html]\n{\n  \"html\": \"<div>\\n    <table id=\\\"ipn_details\\\">\\n        <tr>\\n            <th>Merchant ID</th>\\n            <th>Processing</th>\\n            <th>Payout</th>\\n            <th>Next Step</th>\\n        </tr>\\n        <tr>\\n          <td>&#x2714;</td>\\n          <td><span class=\\\"api\\\">Y</span></td>\\n          <td><span class=\\\"api\\\">Y</span></td>\\n          <td class=\\\"left\\\">You can <a href=\\\"#section-step-4-create-the-credentials-for-your-merchant\\\">create the merchant credentials</a> and begin processing.</td>\\n        </tr>\\n          <tr>\\n          <td>&#x2714;</td>\\n          <td><span class=\\\"api\\\">Y</span></td>\\n          <td><span class=\\\"api\\\">Pending</span></td>\\n          <td class=\\\"left\\\">You can <a href=\\\"#section-step-4-create-the-credentials-for-your-merchant\\\">create the merchant credentials</a> to begin processing. <br />You will receive a second IPN when the merchant is approved for payout.</td>\\n        </tr>\\n          <tr>\\n          <td>&#x2716;</td>\\n          <td><span class=\\\"api\\\">Pending</span></td>\\n          <td><span class=\\\"api\\\">Pending</span></td>\\n          <td class=\\\"left\\\">You cannot create merchant credentials to begin processing. <br />You will receive a second IPN when the merchant is approved.</td>\\n        </tr>\\n          <tr>\\n          <td>&#x2716;</td>\\n          <td><span class=\\\"api\\\">N</span></td>\\n          <td><span class=\\\"api\\\">N</span></td>\\n          <td class=\\\"left\\\">The merchant has been declined; no further updates will be sent.</td>\\n        </tr>\\n    </table>\\n</div>\\n<style>\\n    .api {\\n        font-family: 'Courier New';\\n        background-color: #efefef;\\n    }\\n\\n    .left {\\n        display: table-cell;\\n        text-align: left;\\n    }\\n\\n    table td {\\n        display: table-cell;\\n        vertical-align: top;\\n      text-align: center;\\n    }\\n\\n    table th {\\n        display: table-cell;\\n        vertical-align: top;\\n    }\\n</style>\"\n}\n[/block]\n<hr />\n##Step 4: Create the credentials for your merchant\nUse 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.  \n\nIf your request is successful, you will receive a `200 OK` response from BlueSnap with the merchant's credentials.\n\n###New Get Merchant API Credentials request\n\n`https://platform.bluesnap.com/services/2/merchants/api-credentials`\n\n####Get Merchant API Credentials Parameters\n[block:html]\n{\n  \"html\": \"<div>\\n    <table id=\\\"section-get-api-credentials\\\">\\n        <tr>\\n            <th>Parameter</th>\\n            <th style=\\\"text-align:left\\\">Required</th>\\n            <th style=\\\"text-align:left\\\">Details</th>\\n            <th style=\\\"text-align:left\\\">Description</th>\\n        </tr>\\n        <tr>\\n            <td class=\\\"left\\\"><span class=\\\"api\\\">approvalTesting</span></td>\\n            <td>No</td>\\n          <td><i>boolean</i></td>\\n          <td class=\\\"left\\\">Default=<span class=\\\"api\\\">false</span>.  If you include this parameter and set it to <span class=\\\"api\\\">true</span>, you are testing the feature.</td>\\n        </tr>\\n        <tr>\\n            <td class=\\\"left\\\"><span class=\\\"api\\\">merchantId</span></td>\\n            <td>Yes</td>\\n          <td><i>numeric</i></td>\\n            <td class=\\\"left\\\">The merchant ID assigned to the merchant and included in the IPN.</td>\\n        </tr>\\n        <tr>\\n            <td class=\\\"left\\\"><span class=\\\"api\\\">username</span></td>\\n            <td>No</td>\\n          <td><i>string</i></td>\\n            <td class=\\\"left\\\">The username for the merchant account.<br />If you don't include it, the response will provide the username.</td>\\n        </tr>\\n        <tr>\\n            <td class=\\\"left\\\"><span class=\\\"api\\\">password</span></td>\\n            <td>No</td>\\n            <td><i>string</i></td>\\n            <td class=\\\"left\\\">The password for the merchant account. Minimum 8 characters and maximum 64 characters.<br />If you don't include a password, the response will provide it.</td>\\n        </tr>\\n        <tr>\\n            <td class=\\\"left\\\"><span class=\\\"api\\\">dataProtectionKey</span></td>\\n            <td>No</td>\\n            <td><i>string</i></td>\\n            <td class=\\\"left\\\">The Data Protection Key for the merchant account.<br />If you don't include it, the response will provide it.\\n              <p>The <a href=\\\"https://support.bluesnap.com/page/setting-up-your-data-protection-key-1\\\" target=\\\"_blank\\\">Data Protection Key</a> is required to perform certain functions.</p></td>\\n        </tr>\\n    </table>\\n</div>\\n<style>\\n    .api {\\n        font-family: 'Courier New';\\n        background-color: #efefef;\\n    }\\n\\n    .left {\\n        display: table-cell;\\n        text-align: left;\\n    }\\n\\n    table td {\\n        display: table-cell;\\n        vertical-align: top;\\n      text-align: center;\\n    }\\n\\n    table th {\\n        display: table-cell;\\n        vertical-align: top;\\n    }\\n</style>\"\n}\n[/block]\n####Get Merchant API Credentials Request examples\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -v -X POST https://platform.bluesnap.com/services/2/merchants/api-credentials \\\\\\n-H 'Content-Type: application/json' \\\\\\n-H 'Accept: application/json' \\\\ \\n-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \\\\\\n-d '\\n{\\n  \\\"merchantId\\\":857345\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Get API Credentials: Request with only merchantId\"\n    },\n    {\n      \"code\": \"curl -v -X POST https://platform.bluesnap.com/services/2/merchants/api-credentials \\\\\\n-H 'Content-Type: application/json' \\\\\\n-H 'Accept: application/json' \\\\ \\n-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \\\\\\n-d '\\n{\\n  \\\"merchantId\\\":857345,\\n  \\\"username\\\":\\\"MerchantUsername\\\",\\n  \\\"password\\\":\\\"kjhdA:::at:::3aA\\\",\\n  \\\"dataProtectionKey\\\": \\\"Kru5Y50p\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"with all data\"\n    },\n    {\n      \"code\": \"curl -v -X POST https://platform.bluesnap.com/services/2/merchants/api-credentials \\\\\\n-H 'Content-Type: application/json' \\\\\\n-H 'Accept: application/json' \\\\ \\n-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \\\\\\n-d '\\n{\\n  \\\"approvalTesting\\\": true,\\n  \\\"merchantId\\\": 857345,\\n  \\\"username\\\": \\\"MerchantUsername\\\",\\n  \\\"password\\\": \\\"[email protected]\\\",\\n  \\\"dataProtectionKey\\\": \\\"Kru5Y50p\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Request in TEST mode\"\n    }\n  ]\n}\n[/block]\n####Get Merchant API Credentials Response examples\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"merchantId\\\": 857345,\\n    \\\"username\\\": \\\"MerchantUsername\\\",\\n    \\\"password\\\": \\\"[email protected]\\\",\\n    \\\"dataProtectionKey\\\": \\\"Kru5Y50p\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Successful response: 200 OK\"\n    }\n  ]\n}\n[/block]\n<hr />\n##Test the merchant approval process\nBefore you actually create a merchant account, you can test the approval workflow.\n1. 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:\n\n   * 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.\n   * Type: string \n   * Valid values:\n     * APPROVED\n     * RECOMMEND_APPROVE\n     * RECOMMEND_DECLINE\n     * DECLINE \n\n2. The API call bypasses the BlueSnap review process [explained above](#section-step-3-bluesnap-reviews-the-merchant-account) and you receive the response that corresponds to the `approvalTesting` parameter value you sent. (Refer to the partial code sample below for details.)\n\n3. You receive the IPN and the log-in email right away.\n >**Notes**:  \n>* To receive an IPN, you must have [configured IPNs](http://support.bluesnap.com/docs/ipn-setup) on your system. \n>* The Merchant ID you receive in the IPN and the API credentials are only valid for the sandbox account. \n\n4. Use the Merchant ID (merchantId) from the IPN to create the merchant's credentials using [Step 4 above](#section-step-4-create-the-credentials-for-your-merchant) and include a valid `approvalTesting` value.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -v -X POST https://platform.bluesnap.com/services/2/merchants/application \\\\\\n-H 'Content-Type: application/json' \\\\\\n-H 'Accept: application/json' \\\\ \\n-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \\\\\\n-d '\\n{ \\n  \\\"approvalTesting\\\": \\\"APPROVED\\\", \\n  \\\"businessInfo\\\": {\\n    \\\"businessName\\\": \\\"My Business\\\",\\n    \\\"legalName\\\": \\\"Business Affiliates, LLC\\\",\\n  ....\",\n      \"language\": \"json\",\n      \"name\": \"Test the Create Merchant API\"\n    }\n  ]\n}\n[/block]\n<hr />\n\n##Start processing transactions!\nYou can begin processing transactions.\n\n##What's next?\nYou should now configure your payout information.  Everything you need to know is [here](https://support.bluesnap.com/docs/launch-get-paid#section-get-paid).","updates":[],"order":2,"isReference":false,"hidden":false,"sync_unique":"","link_url":"","link_external":false,"_id":"5f3ea97821c96c04e08b2e9c","project":"57336fd5a6a9c40e00e13a0b","version":{"version":"8976-Basics","version_clean":"8976.0.0-Basics","codename":"3.35 Release","is_stable":true,"is_beta":false,"is_hidden":false,"is_deprecated":false,"categories":["5f3ea97821c96c04e08b2e4c","5f3ea97821c96c04e08b2e4d","5f3ea97821c96c04e08b2e4e","5f3ea97821c96c04e08b2e4f","5f3ea97821c96c04e08b2e50","5f3ea97821c96c04e08b2e51","5beb278ac442ab0213f00990","5f3ea97821c96c04e08b2e52","5c3f542c12c4ac004bc51718","5f3ea97821c96c04e08b2e53","5df806ccecebde0059f17225","5dfa8a8f340c2b007418eb8a","5f3ea97821c96c04e08b2e54","5e597199fd2b0200117c2c1c"],"_id":"5f3ea97821c96c04e08b2ea6","project":"57336fd5a6a9c40e00e13a0b","__v":0,"forked_from":"5ed00a7701fdb400214da2b6","createdAt":"2018-04-23T14:36:48.535Z","releaseDate":"2018-04-23T14:36:48.535Z"},"category":{"sync":{"isSync":false,"url":""},"pages":[],"title":"Partners","slug":"partners","order":4,"from_sync":false,"reference":false,"_id":"5f3ea97821c96c04e08b2e53","project":"57336fd5a6a9c40e00e13a0b","version":"5f3ea97821c96c04e08b2ea6","createdAt":"2019-03-20T19:00:10.025Z","__v":0},"user":"5beb1b96bc2003003ecd645e","createdAt":"2019-10-17T16:50:21.111Z","__v":0,"parentDoc":null}

Customer Onboarding


Before you begin

  • You must have worked 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. 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 set up the payout
    • all other email communications

Process

  1. Collect your customer's information
  2. Create the merchant account
  3. BlueSnap reviews the account
  4. Create the credentials for your merchant

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

  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 element
Code

Business information

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

Bank information

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

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

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

Company representative first name

<input data-bluesnap="companyRepFirstName"/>

Company representative last name

<input data-bluesnap="companyRepLastName"/>

Company representative date of birth

<input data-bluesnap="companyRepDateOfBirth"/>

Company representative government ID

<input data-bluesnap="companyRepGovID"/>

Company representative phone

<input data-bluesnap="companyRepPhone"/>

Company representative address

<input data-bluesnap="companyRepAddress"/>

Company representative city

<input data-bluesnap="companyRepCity"/>

Company representative state

<input data-bluesnap="companyRepState"/>

Company representative zip

<input data-bluesnap="companyRepZip"/>

Company representative country

<input data-bluesnap="companyRepCountry"/>

Additional information

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

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:

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:

{
  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:


Step 3: BlueSnap reviews the merchant account

You will receive an IPN 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.]
  • Processing (accountCanProcess) = Y, N, or Pending
    • Payout (payoutStatus) = Y, N, or Pending

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 the credentials for your merchant

Use the Merchant ID (merchantId) from the IPN (Step 3) 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":"[email protected]",
  "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": "[email protected]",
  "dataProtectionKey": "Kru5Y50p"
}

Get Merchant API Credentials Response examples

{
    "merchantId": 857345,
    "username": "MerchantUsername",
    "password": "[email protected]",
    "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. 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
  2. The API call bypasses the BlueSnap review process explained above and you receive the response that corresponds to the approvalTesting parameter value you sent. (Refer to the partial code sample below for details.)

  3. 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.
  4. Use the Merchant ID (merchantId) from the IPN to create the merchant's credentials using Step 4 above and include a valid approvalTesting value.

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.

What's next?

You should now configure your payout information. Everything you need to know is here.