{"_id":"5d2f378b55a9aa019d0c13a9","project":"57336fd5a6a9c40e00e13a0b","version":{"_id":"5c6c238ff7d54800395355a0","project":"57336fd5a6a9c40e00e13a0b","__v":1,"forked_from":"5beb278ac442ab0213f009cf","createdAt":"2018-04-23T14:36:48.535Z","releaseDate":"2018-04-23T14:36:48.535Z","categories":["5c6c238ff7d548003953555d","5c6c238ff7d548003953555e","5c6c238ff7d548003953555f","5c6c238ff7d5480039535560","5c6c238ff7d5480039535561","5c6c238ff7d5480039535562","5beb278ac442ab0213f00990","5c6c238ff7d5480039535563","5c3f542c12c4ac004bc51718","5c928dba4aa821001ae4f050"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"Main","version_clean":"8976.0.0-Basics","version":"8976-Basics"},"category":{"_id":"5c928dba4aa821001ae4f050","project":"57336fd5a6a9c40e00e13a0b","version":"5c6c238ff7d54800395355a0","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2019-03-20T19:00:10.025Z","from_sync":false,"order":4,"slug":"partners","title":"Partners"},"user":"5beb1b96bc2003003ecd645e","__v":0,"parentDoc":null,"metadata":{"title":"","description":"","image":[]},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2019-07-17T14:58:19.460Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","examples":{"codes":[]},"auth":"required","params":[],"url":""},"isReference":false,"order":2,"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. You need to specify an `email` address in the `businessInfo`.  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--optional-test-the-merchant-approval-process).\",\n  \"title\": \"Testing\"\n}\n[/block]\n<hr />\n\n##Step 1: Collect your customer's information\nCreate the form where your customers can enter their information on your site.  When you create your form, be sure to include all the information we need to create the merchant account for the customer.  \n\nFor details on all the data elements you need to include on your form, refer to the **Parameters** section on 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<hr />\n##Step 2: Create the merchant account\nWhen you have collected all your merchant information, use the Create-Merchant API request to send to BlueSnap for review.  \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\n&nbsp;&nbsp;&nbsp;&nbsp; Merchant Name (`merchantName`)\n&nbsp;&nbsp;&nbsp;&nbsp; Merchant Email (`merchantEmail`)\n&nbsp;&nbsp;&nbsp;&nbsp; Merchant ID (`merchantId`) [The presence of this depends on the review outcome.]\n&nbsp;&nbsp;&nbsp;&nbsp; Payout (`payoutStatus`) = `Yes`, `No`, or  `Pending`\n&nbsp;&nbsp;&nbsp;&nbsp; Processing (`accountCanProcess`) = `Yes`, `No`, or  `Pending`\n\nUse the IPN details to determine what to do next:\n * If the IPN includes a Merchant ID **and** Processing = `Yes`, <br />then you can [create the merchant credentials]#section-step-4-create-the-credentials-for-your-merchant) and begin processing.\n * If the IPN includes a Merchant ID **and** Payout is not `Yes`, <br />then you can [create the merchant credentials](#section-step-4-create-the-credentials-for-your-merchant) to begin processing and you will receive a second IPN when the merchant is approved.\n * If the IPN does **not** include a Merchant ID **and** Payout = `No`, <br />then the merchant has been declined and no further updates will be sent.\n\n<br />\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[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Caution\",\n  \"body\": \"If you provide the merchant with these credentials, they can log into their console and make changes, potentially causing transactions not to be processed.\"\n}\n[/block]\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\\n    <table id=\\\"section-get-api-credentials\\\">\\n\\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><span class=\\\"api\\\">merchantId</span></td>\\n            <td class=\\\"left\\\">Yes</td>\\n          <td class=\\\"left\\\"><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><span class=\\\"api\\\">username</span></td>\\n            <td class=\\\"left\\\">No</td>\\n          <td class=\\\"left\\\"><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><span class=\\\"api\\\">password</span></td>\\n            <td class=\\\"left\\\">No</td>\\n            <td class=\\\"left\\\"><i>string</i></td>\\n            <td class=\\\"left\\\">The password for the merchant account.<br />If you don't include it, the response will provide the password.</td>\\n        </tr>\\n        <tr>\\n            <td><span class=\\\"api\\\">dataProtectionKey</span></td>\\n            <td class=\\\"left\\\">No</td>\\n            <td class=\\\"left\\\"><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      \\n    </table>\\n\\n\\n</div>\\n\\n\\n\\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    }\\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}\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\\\": \\\"kjhdA@3aA\\\",\\n    \\\"dataProtectionKey\\\": \\\"Kru5Y50p\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Successful response: 200 OK\"\n    }\n  ]\n}\n[/block]\n<hr />\n##(Optional) 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).\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<br />\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).","excerpt":"","slug":"customer-onboarding","type":"basic","title":"Customer Onboarding"}

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. You need to specify an email address in the businessInfo. 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

Create the form where your customers can enter their information on your site. When you create your form, be sure to include all the information we need to create the merchant account for the customer.

For details on all the data elements you need to include on your form, refer to the Parameters section on page corresponding to your customer's country:


Step 2: Create the merchant account

When you have collected all your merchant information, use the Create-Merchant API request to send to BlueSnap for review.

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.]
     Payout (payoutStatus) = Yes, No, or Pending
     Processing (accountCanProcess) = Yes, No, or Pending

Use the IPN details to determine what to do next:

  • If the IPN includes a Merchant ID and Processing = Yes,
    then you can [create the merchant credentials]#section-step-4-create-the-credentials-for-your-merchant) and begin processing.
  • If the IPN includes a Merchant ID and Payout is not Yes,
    then you can create the merchant credentials to begin processing and you will receive a second IPN when the merchant is approved.
  • If the IPN does not include a Merchant ID and Payout = No,
    then the merchant has been declined and 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.

Caution

If you provide the merchant with these credentials, they can log into their console and make changes, potentially causing transactions not to be processed.

New Get Merchant API Credentials request

https://platform.bluesnap.com/services/2/merchants/api-credentials

Get Merchant API Credentials Parameters

Parameter Required Details Description
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.
If you don't include it, the response will provide the password.
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"
}

Get Merchant API Credentials Response examples

{
    "merchantId": 857345,
    "username": "MerchantUsername",
    "password": "kjhdA@3aA",
    "dataProtectionKey": "Kru5Y50p"
}


(Optional) 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.

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.