{"_id":"59dfa8f55c0bae001c2e8b0f","category":{"_id":"59dfa8f45c0bae001c2e8aec","version":"59dfa8f45c0bae001c2e8ae8","project":"57336fd5a6a9c40e00e13a0b","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2017-03-17T15:51:04.102Z","from_sync":false,"order":3,"slug":"marketplace","title":"Marketplace"},"user":"560d5913af97231900938124","parentDoc":null,"project":"57336fd5a6a9c40e00e13a0b","version":{"_id":"59dfa8f45c0bae001c2e8ae8","project":"57336fd5a6a9c40e00e13a0b","__v":1,"createdAt":"2017-10-12T17:40:04.535Z","releaseDate":"2017-10-12T17:40:04.535Z","categories":["59dfa8f45c0bae001c2e8ae9","59dfa8f45c0bae001c2e8aea","59dfa8f45c0bae001c2e8aeb","59dfa8f45c0bae001c2e8aec","59dfa8f45c0bae001c2e8aed","59dfa8f45c0bae001c2e8aee","59dfa8f45c0bae001c2e8aef","59dfa8f45c0bae001c2e8af0"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"3.23. Release","version_clean":"8976.0.0-Basics","version":"8976-Basics"},"__v":0,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-03-17T15:51:51.724Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[]},"auth":"required","params":[],"url":""},"isReference":false,"order":17,"body":"This section will cover the following topics: \n* [Creating vendor accounts](#section-creating-vendor-accounts)\n* [Understanding your vendor's statuses](#section-understanding-your-vendor-s-statuses)\n* [Staying informed with webhooks](#section-staying-informed-with-webhooks)\n\n##Creating vendor accounts\nTo create a new vendor account and begin the onboarding process, you'll submit the vendor's information via the Create Vendor request. To fully board your vendor, you'll collect all the necessary [Know your customer](https://en.wikipedia.org/wiki/Know_your_customer) (KYC), banking, and any additional required information from them, and you'll submit to BlueSnap for verification. \n\nVendors can be created and begin selling with just country and email. The vendor's account must have all the [necessary information](/docs/vendor-verification-requirements) to be eligible for payout. This is because BlueSnap must first verify the vendor's identity before any funds can be paid out. \n<br />\n[block:callout]\n{\n  \"type\": \"success\",\n  \"title\": \"Submit all necessary information in advance\",\n  \"body\": \"Collecting all the [necessary information for payout](/docs/vendor-verification-requirements#section-requirements-for-payout) (commission rate, banking information, business owner information, etc.) up-front and submitting via the Create Vendor request means that you won't have to ask your vendor for their information more than once. Plus, you'll avoid any payout delays.\\n\\n**Note**: It's very important to define your vendor's commission rate during the initial vendor creation, so that transactions can be split appropriately.\"\n}\n[/block]\nBelow is an example Create Vendor request with email, country, and commission percent. \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -v -X POST https://sandbox.bluesnap.com/services/2/vendors \\\\\\n-H 'Content-Type: application/json' \\\\\\n-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \\\\\\n-d '\\n{ \\n    \\\"email\\\": \\\"jane.shopper:::at:::bluesnap.com\\\", \\n    \\\"country\\\": \\\"US\\\", \\n    \\\"vendorAgreement\\\": {\\n    \\t\\\"commissionPercent\\\": 75 \\n      }   \\t\\n     ... \\n}'\",\n      \"language\": \"curl\",\n      \"name\": \"JSON\"\n    },\n    {\n      \"code\": \"curl -v -X POST https://sandbox.bluesnap.com/services/2/vendors \\\\\\n-H 'Content-Type: application/xml' \\\\\\n-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \\\\\\n-d '\\n<vendor xmlns=\\\"http://ws.plimus.com\\\">\\n    <email>jane.shopper@bluesnap.com</email>\\n    <country>US</country>\\n    <vendor-agreement>\\n      <commission-percent>75</commission-percent>\\n    </vendor-agreement>\\n    ...\\n</vendor>'\",\n      \"language\": \"curl\",\n      \"name\": \"XML\"\n    }\n  ]\n}\n[/block]\nA successful response will include the vendor ID, a unique ID assigned to the vendor, which will be required for future requests involving this vendor (in this example, the vendor ID is 19575974).\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"HTTP/ 1.1 201 Created\\nLocation: https://sandbox.bluesnap.com/services/2/vendors/19575974\",\n      \"language\": \"curl\",\n      \"name\": \"201 Created\"\n    }\n  ]\n}\n[/block]\n###For more information: \nVisit our API Reference for additional examples and a  complete list of request properties: \n\n  * [Create Vendor - JSON](/v2.1/docs/create-vendor) \n  * [Create Vendor - XML](/v2.0/docs/create-vendor)  \n\n<br>\n<a class=\"btn btn-primary\" href=\"#\" role=\"button\">Back to Top</a>\n\n<hr>\n\n##Understanding your vendor's statuses \nYour vendor will have three statuses - account, payout, and processing - to indicate if their account is active/inactive and if they are eligible to receive payout or have transactions processed on their behalf. \n\n###Account status \nThis status is managed by you, the Marketplace Merchant, and allows you to to disable your vendor's ability to sell on your platform. To see an example of updating a vendor's account status, click [here](/v2.1/docs/update-vendor).\n\nThe possible status values are: \n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Status Value\",\n    \"h-1\": \"Description\",\n    \"0-0\": \"**Active**\",\n    \"0-1\": \"By default, your vendor's account is active and they are eligible for transaction processing.\\n\\n*Note*: If their [processing status](#section-processing-status) is also **Active**, they may have transactions processed.\",\n    \"1-0\": \"**Inactive**\",\n    \"1-1\": \"Your vendor's account is inactive and they are not eligible for transaction processing. \\n\\n*Note*: If you change your vendor’s account status to **Inactive**, your vendor will be paid out for sales they were associated with prior to the status change.\"\n  },\n  \"cols\": 2,\n  \"rows\": 2\n}\n[/block]\n###Payout status \nThis read-only status, set by BlueSnap, indicates your vendor's eligibility to receive payout based on the vendor information provided. See [Vendor Verification Requirements](/docs/vendor-verification-requirements#section-requirements-for-payout) to understand what information is required for payout. \n\nThe possible status values are: \n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Status Value\",\n    \"h-1\": \"Description\",\n    \"0-0\": \"**Incomplete**\",\n    \"0-1\": \"You have not provided sufficient information to fully board your vendor. Your vendor is eligible for transaction processing, but their payout is suspended.\\n\\n*Note*: If your vendor's payout status is **Incomplete**, you can obtain a list of missing vendor information. See [Staying informed of your vendor's statuses](#section-staying-informed-of-your-vendor-s-statuses).\",\n    \"1-0\": \"**Pending**\",\n    \"1-1\": \"You have provided sufficient information to fully board your vendor and BlueSnap is currently reviewing this information. The vendor is eligible for transaction processing, but their payout is suspended.\\n\\n*Note*: [Updating your vendor's information](/docs/updating-vendor-accounts#section-updating-vendor-properties-and-changes-to-payout-status) may result in their payout status changing to **Pending**.\",\n    \"2-0\": \"**Approved**\",\n    \"2-1\": \"BlueSnap has approved your vendor. They are  eligible to receive payout.\",\n    \"3-0\": \"**Declined**\",\n    \"3-1\": \"BlueSnap has declined your vendor. They are no longer eligible for transaction processing and their payout is suspended.\\n\\n*Note*: If your vendor's payout status changes to **Declined**, you will be provided with a decline reason. See [Staying informed of your vendor's statuses](#section-staying-informed-of-your-vendor-s-statuses).\"\n  },\n  \"cols\": 2,\n  \"rows\": 4\n}\n[/block]\n###Processing status \nThis read-only status, set by BlueSnap, indicates your vendor’s ability to have transactions processed. This status is determined by a combination of your vendor’s account and payout statuses.\n\nThe possible status values are: \n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Status Value\",\n    \"h-1\": \"Description\",\n    \"0-0\": \"**Active**\",\n    \"0-1\": \"Your vendor may have transactions processed.\\n\\n*Note*: Processing status will be **Active** if your vendor's account status is **Active** and their payout status is **Incomplete**, **Pending**, or **Approved**.\",\n    \"1-0\": \"**Inactive**\",\n    \"1-1\": \"Your vendor may not have transactions processed.\\n\\n*Note*: Processing status will be **Inactive** if  your vendor's account status is **Inactive** or their payout status is **Declined**.\"\n  },\n  \"cols\": 2,\n  \"rows\": 2\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Sandbox testing\",\n  \"body\": \"While testing in sandbox, the following vendor status logic will apply: \\n* If you do not supply all [required vendor payout information](/docs/vendor-verification-requirements#section-requirements-for-payout), your vendor's payout status will be **Incomplete**. \\n\\n* If you supply all required payout information, your vendor's payout status will change to **Approved**.\\n\\n* A vendor decline can be simulated by sending a Create or Update Vendor request and setting the value of `phone` to **555-555-5555**. Click [here](/v2.1/docs/update-vendor#section-examples) to see a code sample.\"\n}\n[/block]\n##Staying informed of your vendor's statuses\nThe following tools will help you stay informed of vendor statuses, missing vendor information, and vendor decline reasons.\n* [Vendor Status Changed webhook](https://support.bluesnap.com/docs/ipn-name-reference#vendor-status-changed).\n* [Retrieve Vendor request](/v2.1/docs/retrieve-vendor)  \n\n<br>\n<a class=\"btn btn-primary\" href=\"#\" role=\"button\">Back to Top</a>\n\n<hr>\n\n##Staying informed with webhooks\nBlueSnap uses webhooks called Instant Payment Notifications (IPN's) to keep you informed. They are HTTP POST messages that are triggered on certain events. \n\nBelow are some common webhooks that will keep you informed of your marketplace activity related to vendor onboarding, payout, and sales. \n\n* Auth Only \n* Charge\n* Payout \n* Refund\n* Under Vendor Review \n* Vendor Status Changed \n\nFor a complete list of webhooks and associated parameters, click [here](https://support.bluesnap.com/docs/ipn-name-reference). \nBe sure you have both Default on On-Demand webhooks enabled in your [account settings](https://support.bluesnap.com/docs/ipn-setup).\n[block:callout]\n{\n  \"type\": \"success\",\n  \"body\": \"`vendorId` will be sent in the body of the message to help you identify which vendor was involved in the event.\",\n  \"title\": \"Using vendor ID to link a vendor to the event\"\n}\n[/block]\n<a class=\"btn btn-primary\" href=\"#\" role=\"button\">Back to Top</a>\n<hr>\n\n##Next: Vendor Verification Requirements\nNow that you've created your vendor account and started the onboarding process, you can jump right into learning about vendor verification requirements for processing transactions on your vendor's behalf and vendor payout eligibility. \n\n**[➔ Vendor Verification Requirements](/docs/vendor-verification-requirements)**","excerpt":"Learn about vendor account creation, vendor statuses, tools to stay informed, and other important topics.  \nIf you have questions after reading this guide, check out our answers to [frequently asked questions](https://support.bluesnap.com/docs/merchant-faqs#section--what-is-a-marketplace-).","slug":"vendor-onboarding","type":"basic","title":"Vendor Onboarding"}

Vendor Onboarding

Learn about vendor account creation, vendor statuses, tools to stay informed, and other important topics. If you have questions after reading this guide, check out our answers to [frequently asked questions](https://support.bluesnap.com/docs/merchant-faqs#section--what-is-a-marketplace-).

This section will cover the following topics:

Creating vendor accounts

To create a new vendor account and begin the onboarding process, you'll submit the vendor's information via the Create Vendor request. To fully board your vendor, you'll collect all the necessary Know your customer (KYC), banking, and any additional required information from them, and you'll submit to BlueSnap for verification.

Vendors can be created and begin selling with just country and email. The vendor's account must have all the necessary information to be eligible for payout. This is because BlueSnap must first verify the vendor's identity before any funds can be paid out.

Submit all necessary information in advance

Collecting all the necessary information for payout (commission rate, banking information, business owner information, etc.) up-front and submitting via the Create Vendor request means that you won't have to ask your vendor for their information more than once. Plus, you'll avoid any payout delays.

Note: It's very important to define your vendor's commission rate during the initial vendor creation, so that transactions can be split appropriately.

Below is an example Create Vendor request with email, country, and commission percent.

curl -v -X POST https://sandbox.bluesnap.com/services/2/vendors \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
{ 
    "email": "jane.shopper@bluesnap.com", 
    "country": "US", 
    "vendorAgreement": {
    	"commissionPercent": 75 
      }   	
     ... 
}'
curl -v -X POST https://sandbox.bluesnap.com/services/2/vendors \
-H 'Content-Type: application/xml' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
<vendor xmlns="http://ws.plimus.com">
    <email>jane.shopper@bluesnap.com</email>
    <country>US</country>
    <vendor-agreement>
      <commission-percent>75</commission-percent>
    </vendor-agreement>
    ...
</vendor>'

A successful response will include the vendor ID, a unique ID assigned to the vendor, which will be required for future requests involving this vendor (in this example, the vendor ID is 19575974).

HTTP/ 1.1 201 Created
Location: https://sandbox.bluesnap.com/services/2/vendors/19575974

For more information:

Visit our API Reference for additional examples and a complete list of request properties:



Back to Top


Understanding your vendor's statuses

Your vendor will have three statuses - account, payout, and processing - to indicate if their account is active/inactive and if they are eligible to receive payout or have transactions processed on their behalf.

Account status

This status is managed by you, the Marketplace Merchant, and allows you to to disable your vendor's ability to sell on your platform. To see an example of updating a vendor's account status, click here.

The possible status values are:

Status Value
Description

Active

By default, your vendor's account is active and they are eligible for transaction processing.

Note: If their processing status is also Active, they may have transactions processed.

Inactive

Your vendor's account is inactive and they are not eligible for transaction processing.

Note: If you change your vendor’s account status to Inactive, your vendor will be paid out for sales they were associated with prior to the status change.

Payout status

This read-only status, set by BlueSnap, indicates your vendor's eligibility to receive payout based on the vendor information provided. See Vendor Verification Requirements to understand what information is required for payout.

The possible status values are:

Status Value
Description

Incomplete

You have not provided sufficient information to fully board your vendor. Your vendor is eligible for transaction processing, but their payout is suspended.

Note: If your vendor's payout status is Incomplete, you can obtain a list of missing vendor information. See Staying informed of your vendor's statuses.

Pending

You have provided sufficient information to fully board your vendor and BlueSnap is currently reviewing this information. The vendor is eligible for transaction processing, but their payout is suspended.

Note: Updating your vendor's information may result in their payout status changing to Pending.

Approved

BlueSnap has approved your vendor. They are eligible to receive payout.

Declined

BlueSnap has declined your vendor. They are no longer eligible for transaction processing and their payout is suspended.

Note: If your vendor's payout status changes to Declined, you will be provided with a decline reason. See Staying informed of your vendor's statuses.

Processing status

This read-only status, set by BlueSnap, indicates your vendor’s ability to have transactions processed. This status is determined by a combination of your vendor’s account and payout statuses.

The possible status values are:

Status Value
Description

Active

Your vendor may have transactions processed.

Note: Processing status will be Active if your vendor's account status is Active and their payout status is Incomplete, Pending, or Approved.

Inactive

Your vendor may not have transactions processed.

Note: Processing status will be Inactive if your vendor's account status is Inactive or their payout status is Declined.

Sandbox testing

While testing in sandbox, the following vendor status logic will apply:

  • If you do not supply all required vendor payout information, your vendor's payout status will be Incomplete.

  • If you supply all required payout information, your vendor's payout status will change to Approved.

  • A vendor decline can be simulated by sending a Create or Update Vendor request and setting the value of phone to 555-555-5555. Click here to see a code sample.

Staying informed of your vendor's statuses

The following tools will help you stay informed of vendor statuses, missing vendor information, and vendor decline reasons.



Back to Top


Staying informed with webhooks

BlueSnap uses webhooks called Instant Payment Notifications (IPN's) to keep you informed. They are HTTP POST messages that are triggered on certain events.

Below are some common webhooks that will keep you informed of your marketplace activity related to vendor onboarding, payout, and sales.

  • Auth Only
  • Charge
  • Payout
  • Refund
  • Under Vendor Review
  • Vendor Status Changed

For a complete list of webhooks and associated parameters, click here.
Be sure you have both Default on On-Demand webhooks enabled in your account settings.

Using vendor ID to link a vendor to the event

vendorId will be sent in the body of the message to help you identify which vendor was involved in the event.

Back to Top


Next: Vendor Verification Requirements

Now that you've created your vendor account and started the onboarding process, you can jump right into learning about vendor verification requirements for processing transactions on your vendor's behalf and vendor payout eligibility.

➔ Vendor Verification Requirements