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.

Additionally, the merchant must be set up for regional payout to use this API. If you call Create Vendor when not configured for regional payout, an error will be returned.

❗️
Important: KYC Documentation

The vendor account must have all the necessary information to be eligible for payout.

All documentation must be clear, legible, valid, and current.

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 'Accept: application/json' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
{
  "email": "vendor@example.com",
  "firstName": "Joe",
  "lastName": "Smith",
  "phone": "1-123-456-7890",
  "address": "123 Main Street",
  "city": "Boston",
  "country": "US",
  "state": "MA",
  "zip": "02453",
  "vendorPrincipal": {
    "firstName": "Joe",
    "lastName": "Smith",
    "address": "123 Main Street",
    "city": "Boston",
    "country": "US",
    "zip": "02453",
    "dob": "28-09-9999",
    "personalIdentificationNumber": "1234",
    "driverLicenseNumber": "561196411",
    "email": "individual.vendor@bluesnap.com"
  },
  "vendorAgreement": {
    "commissionPercent": 30
  },
  "payoutConfiguration": {
    "reviewDelay": 15,
    "payoutFrequency": "MONTHLY",
    "defaultLegalEntity": "US",
    "regions": [
      {
        "region": "US",
        "defaultCurrency": "USD",
        "currencyByRegion": [
          {
            "currencyCode": "USD",
            "payoutPaymentType": "ACH",
            "minimumPaymentAmount": 25,
            "bankDetails": [
              {
                "country": "US",
                "state": "MA",
                "city": "Juneau",
                "address1": "1 bank address",
                "zipCode": "02453",
                "paymentReference": "payout for vendor 1234",
                "bankId": "123456789",
                "bankName": "Leumi",
                "accountId": "36628822",
                "nameOnAccount": "vendor",
                "achAccountClass": "PERSONAL",
                "achAccountType": "CHECKING"
              }
            ]
          }
        ]
      }
    ]
  }
}'

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>vendor@example.com</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>12345</zip>
  <ipn-url>https://ipnaddress.com</ipn-url>
  <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>
    <driver-license-number>561196411</driver-license-number>
    <email>individual.vendor@bluesnap.com</email>
  </vendor-principal>
  <vendor-agreement>
    <commission-percent>30</commission-percent>
    </vendor-agreement>
  <payout-configuration>
    <payout-frequency>MONTHLY</payout-frequency>
    <review-delay>14</review-delay>
    <default-legal-entity>US</default-legal-entity>
    <regions>
      <region>US</region>
      <default-currency>USD</default-currency>
      <currency-by-region>
        <currency-code>USD</currency-code>
        <status>Active</status>
        <payout-payment-type>ACH</payout-payment-type>
        <minimum-payment-amount>50</minimum-payment-amount>
        <reserve>
          <merchant-reserve>
            <keep-on-merchant-reserve>200</keep-on-merchant-reserve>
          </merchant-reserve>
        </reserve>
        <bank-details>
          <country>US</country>
          <state>MA</state>
          <city>Juneau</city>
          <address-1>1 bank address</address-1>
          <zip-code>12345</zip-code>
          <payment-reference>Payment for vendor 1234</payment-reference>
          <bic>EXBN01</bic>
          <bank-name>Leumi</bank-name>
          <iban>ABC123456789DEF</iban>
          <ach-account-class>PERSONAL</ach-account-class>
          <ach-account-type>CHECKING</ach-account-type>
          <name-on-account>vendor</name-on-account>
          <status>Pending</status>
        </bank-details>
      </currency-by-region>
    </regions>
  </payout-configuration>
</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:

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 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. 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.
Suspended	BlueSnap 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 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.

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.

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