In this section, we outline the necessary information for payout in the following ways:

Full example — A complete example of creating a vendor account.
Vendor properties — The properties in a list format explaining when they are optional or required.

❗️
KYC Documentation
Make sure all the documentation you receive from your vendor and send to us is clear, legible, valid, and current.

Full example

Below is an example of a Create Vendor request with sufficient information to fully board a vendor. In these code samples, we have a US vendor with a payout method of ACH/ECP. All properties are required unless specified as optional in the Vendor properties section below.

📘
Vendor information will vary
➔ Vendor accounts for individuals require information about the person, and vendor accounts for businesses require information about the business and a business representative.
➔ Some information depends on the vendor's country, such as Payout Information and Personal Identification Number.
Review the Vendor properties section below to understand how certain property values vary.
Visit Payout to see code samples of the different payout methods.

Use these code samples as a template, and modify specific properties for your vendor.

JSON

curl -v -X POST https://sandbox.bluesnap.com/services/2/vendors \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
{
  "email": "individual.vendor@example.com",
  "firstName": "Joe",
  "lastName": "Smith",
  "phone": "1-123-456-7890",
  "address": "123 Main Street",
  "city": "Boston",
  "country": "US",
  "state": "MA",
  "zip": "123456",
  "defaultPayoutCurrency": "USD",
  "frequency": "DAILY",
  "delay": 3,
  "ipnUrl": "https://merchant-domain.com/ipn",
  "vendorPrincipal": {
    "firstName": "Joe",
    "lastName": "Smith",
    "address": "123 Main Street",
    "city": "Boston",
    "country": "US",
    "zip": "123456",
    "dob": "28-09-9999",
    "personalIdentificationNumber": "1234",
    "email": "individual.vendor@bluesnap.com"
  },
  "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
    }
  ]
}'

curl -v -X POST https://sandbox.bluesnap.com/services/2/vendors \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
{
  "name": "Business ABC",
  "email": "business.vendor@example.com",
  "phone": "1-123-455-8765",
  "address": "25 Business Avenue",
  "city": "Boston",
  "country": "US",
  "state": "MA",
  "zip": "123456",
  "taxId": "123456789",
  "defaultPayoutCurrency": "USD",
  "frequency": "DAILY",
  "delay": 3,
  "ipnUrl": "https://merchant-domain.com/ipn",
  "vendorUrl": "https://mycompany.com",
  "vendorPrincipal": {
    "firstName": "Joe",
    "lastName": "Smith",
    "address": "123 Main Street",
    "city": "Boston",
    "country": "US",
    "zip": "12345",
    "dob": "28-09-9999",
    "personalIdentificationNumber": "1234",
    "email": "principal.vendor@email.com"
  },
  "vendorAgreement": {
    "commissionPercent": "30"
  },
  "payoutInfo": [
    {
      "payoutType": "ACH",
      "baseCurrency": "USD",
      "nameOnAccount": "name of vendor account",
      "bankAccountType": "CHECKING",
      "bankAccountClass": "CORPORATE",
      "bankName": "Bank of America",
      "bankId": "123456789",
      "country": "US",
      "state": "MA",
      "city": "Boston",
      "address": "1 bank address",
      "zip": "12345",
      "bankAccountId": "36628822",
      "minimalPayoutAmount": 25,
      "paymentReference": "Payment for vendor 1234",
      "refundReserve": 200
    }
  ]
}'

XML

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>individual.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>123456</zip>
  <default-payout-currency>USD</default-payout-currency>
  <frequency>DAILY</frequency>
  <delay>3</delay>
  <ipn-url>https://merchant-domain.com/ipn</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>
    <email>individual.vendor@bluesnap.com</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>
</vendor>'

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">
  <name>Business ABC</name>
  <email>business.vendor@example.com</email>
  <phone>1-123-455-8765</phone>
  <address>25 Business Avenue</address>
  <city>Boston</city>
  <country>US</country>
  <state>MA</state>
  <zip>123456</zip>
  <tax-id>123456789</tax-id>
  <default-payout-currency>USD</default-payout-currency>
  <frequency>DAILY</frequency>
  <delay>3</delay>
  <vendor-url>https://mycompany.com</vendor-url>
  <ipn-url>https://merchant-domain.com/ipn</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>12345</zip>
    <dob>28-09-9999</dob>
    <personal-identification-number>1234</personal-identification-number>
    <email>principal.vendor@email.com</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>name of vendor account</name-on-account>
    <bank-account-type>CHECKING</bank-account-type>
    <bank-account-class>CORPORATE</bank-account-class>
    <bank-name>Bank of America</bank-name>
    <bank-id>123456789</bank-id>
    <country>US</country>
    <state>MA</state>
    <city>Boston</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>
</vendor>'

Vendor properties

This section lists the vendor properties for payout to businesses and individuals. More information on any of the below properties can be found in our API Reference.

email, phone, country (the vendor's country code), state (if country value is US or CA), city, and zip are required.
firstName and lastName are required for individuals.
name and either taxId or vatId are required for businesses. Only provide one of taxId or vatId per request.
defaultPayoutCurrency* is optional. Default value is USD. If a sale occurs in a currency for which there is not an associated bank account, sale funds will be converted to this currency.
frequency is optional. Default value is Marketplace Merchant's payout frequency.
delay is optional. Default value is Marketplace Merchant's payout delay.
vendorUrl is optional. Value is the main, customer-facing URL of the vendor's business.
ipnUrl is optional. Value is the URL where the Payout IPN should be sent.
vendorPrincipal is required and contains vendor principal owner info:
- firstName, lastName, address, country (the vendor principal's country code), city, zip, dob (date of birth), email, and one of the three following ID fields are required.
- personalIdentificationNumber is only required if country value is US. In this case, the value is the last four digits of Social Security Number, and no other ID field (driverLicenseNumber or passportNumber) is required. Otherwise, value is the full National Identification Number.
- driverLicenseNumber is only required if no other ID fields have been provided.
- passportNumber is only required if no other ID fields have been provided.
vendorAgreement is required and contains vendor commission info:
- commissionPercent is vendor's commission percent for marketplace sales. Either percent or amount must be set.
- commissionAmount is vendor's commission amount for marketplace sales. Either percent or amount must be set.
payoutInfo is required and contains vendor payout info:
- payoutType (ACH, CHAPS, FAST, SEPA, or WIRE), baseCurrency (payout currency for bank account), bankName, address (street address of vendor's bank), country (country code of vendor's bank), state (if country value is US or CA), city, zip, nameOnAccount, bankAccountClass (PERSONAL, CORPORATE, or INTERNATIONAL), bankAccountType (CHECKING or SAVINGS), and the following are required.
- Either bankId or swiftBic is required, but not both.
- Either bankAccountId or iban is required, but not both.
- minimalPayoutAmount is optional. We recommend setting this value to 25 or more to avoid payout delays and negative balances.
- paymentReference is optional. Value is the reference text that appears on the vendor's bank statement when they are paid out.
- refundReserve is optional. We recommend setting a value for this property to ensure your vendor has enough funds available for refunds.

*Your vendor's defaultPayoutCurrency must have an associated bank account defined within payoutInfo.

🚧
Missing vendor information

BlueSnap may ask for additional information if it is needed for vendor verification (e.g., driver's license or passport image).

Make sure all the documentation you receive from your vendor and send to us is clear, legible, valid, and current.

👍
Staying informed of vendor status changes
Any changes to your vendor’s status is sent to you using the Vendor Status Changed webhook.
If your vendor's payout status is Approved, then your vendor is eligible for payout (see Vendor Onboarding).

Next: Updating Vendor Accounts

Now that you've learned about the vendor verification requirements for processing transactions and payout eligibility, move on to updating your vendor's account.

➔ Updating Vendor Accounts