{"_id":"5da89bcdec92530019464a5d","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,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2019-10-17T16:50:21.111Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[]},"settings":"","results":{"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*  Merchant Name (`merchantName`)\n* Merchant Email (`merchantEmail`)\n* Merchant ID (`merchantId`) [The presence of this depends on the review outcome.]\n* Processing (`accountCanProcess`) = `Yes`, `No`, or  `Pending`\n * Payout (`payoutStatus`) = `Yes`, `No`, 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\\\">Yes</span></td>\\n          <td><span class=\\\"api\\\">Yes</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\\\">Yes</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\\\">No</span></td>\\n          <td><span class=\\\"api\\\">No</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\\\">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.<br />If you don't include it, the response will provide the password.</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}\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<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.]
  • Processing (accountCanProcess) = Yes, No, or Pending
    • Payout (payoutStatus) = Yes, No, or Pending

Use the IPN details to determine what to do next.

Merchant ID Processing Payout Next Step
Yes Yes You can create the merchant credentials and begin processing.
Yes 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.
No No 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
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.