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 FAQs page.

This section covers the following topics:

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:


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

Status ValueDescription
ActiveBy 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.
InactiveYour 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 ValueDescription
IncompleteYou 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.
PendingYou 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.
ApprovedBlueSnap has approved your vendor. They are eligible to receive payout.
DeclinedBlueSnap has declined your vendor. They are no longer eligible for transaction processing and their payout is suspended.

Notes:
- 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.
- Any transactions involving the vendor will be automatically refunded.
SuspendedBlueSnap has suspended the vendor account.

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 ValueDescription
ActiveYour 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.
InactiveYour 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 (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