Vendor Onboarding

This section covers the following topics:

• Creating vendor accounts
• Understanding your vendor's statuses
• Staying informed with webhooks

Creating vendor accounts

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

❗️

Important: KYC Documentation

1. The vendor account must have all the necessary information to be eligible for payout.
2. All documentation must be clear, legible, valid, and current.
3. BlueSnap reviews the vendor account only after all information has been received and the vendor has been included with at least one transaction

👍

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 avoid any payout delays.

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

Below is an example Create Vendor request.

curl -v -X POST https://sandbox.bluesnap.com/services/2/vendors \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
{
  "email": "[email protected]",
  "firstName": "Joe",
  "lastName": "Smith",
  "phone": "1-123-456-7890",
  "address": "123 Main Street",
  "city": "Boston",
  "country": "US",
  "state": "MA",
  "zip": "123456",
  "vendorUrl": "https://mycompany.com",
  "defaultPayoutCurrency": "USD",
  "vendorPrincipal": {
    "firstName": "Joe",
    "lastName": "Smith",
    "address": "123 Main Street",
    "city": "Boston",
    "country": "US",
    "zip": "123456",
    "dob": "28-09-9999",
    "personalIdentificationNumber": "1234",
    "email": "[email protected]"
  },
  "vendorAgreement": {
    "commissionPercent": 30
  },
  "payoutInfo": [
    {
      "payoutType": "ACH",
      "baseCurrency": "USD",
      "nameOnAccount": "vendor",
      "bankAccountType": "CHECKING",
      "bankAccountClass": "PERSONAL",
      "bankName": "Leumi",
      "bankId": "123456789",
      "country": "US",
      "state": "MA",
      "city": "Juneau",
      "address": "1 bank address",
      "zip": "12345",
      "bankAccountId": "36628822",
      "minimalPayoutAmount": 25,
      "paymentReference": "Payment for vendor 1234",
      "refundReserve": 200
    }
  ],
  "ipnUrl": "https://ipnaddress.com"
}'

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>[email protected]</email>
  <first-name>Joe</first-name>
  <last-name>Smith</last-name>
  <phone>1-123-456-7890</phone>
  <address>123 Main Street</address>
  <city>Boston</city>
  <country>US</country>
  <state>MA</state>
  <zip>123456</zip>
  <vendor-url>https://mycompany.com</vendor-url>
  <default-payout-currency>USD</default-payout-currency>
  <frequency>DAILY</frequency>
  <delay>3</delay>
  <vendor-principal>
    <first-name>Joe</first-name>
    <last-name>Smith</last-name>
    <address>123 Main Street</address>
    <city>Boston</city>
    <country>US</country>
    <zip>123456</zip>
    <dob>28-09-9999</dob>
    <personal-identification-number>1234</personal-identification-number>
    <email>[email protected]</email>
  </vendor-principal>
  <vendor-agreement>
    <commission-percent>30</commission-percent>
  </vendor-agreement>
  <payout-info>
    <payout-type>ACH</payout-type>
    <base-currency>USD</base-currency>
    <name-on-account>vendor</name-on-account>
    <bank-account-type>CHECKING</bank-account-type>
    <bank-account-class>PERSONAL</bank-account-class>
    <bank-name>Leumi</bank-name>
    <bank-id>123456789</bank-id>
    <country>US</country>
    <state>MA</state>
    <city>Juneau</city>
    <address>1 bank address</address>
    <zip>12345</zip>
    <bank-account-id>36628822</bank-account-id>
    <minimal-payout-amount>25</minimal-payout-amount>
    <payment-reference>Payment for vendor 1234</payment-reference>
    <refund-reserve>200</refund-reserve>
  </payout-info>
  <ipn-url>https://ipnaddress.com</ipn-url>
</vendor>'

A successful response will include the vendor ID, a unique ID assigned to the vendor, which is 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:

• Create Vendor - JSON
• Create Vendor - XML

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 disable your vendor's ability to sell on your platform. To see an example of updating a vendor's account status, click here.

Note: If you change your vendor's account status from Inactive to Active, their payout status will change to Pending until the account is verified again.

The possible status values are:

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:

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:

📘

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.

• Vendor Status Changed webhook
• Retrieve Vendor request

Staying informed with webhooks

BlueSnap uses webhooks called Instant Payment Notifications (IPNs) to keep you informed. They are HTTP POST messages that are triggered by 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 webhooks enabled in your account settings.

📘

Identifying which vendors were involved in the event

For all vendors involved in the event, their vendor IDs will be sent in the IPN.

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