BlueSnap.comAPI BasicsPayment APIEmbedded PaymentsReporting & ToolsSupport GuidesTest
API Reference

Vendor Verification Requirements

Learn about the vendor verification requirements for processing transactions and payout eligibility.
If you have questions after reading this guide, check out our FAQs page.

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.

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",
  "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": "[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
    }
  ]
}'

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": "[email protected]",
  "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": "[email protected]"
  },
  "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
    }
  ]
}'

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>
  <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>[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>
</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>[email protected]</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>[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>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>'

Back to Top

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.

  • firstName is required for individuals.
  • lastName is required for individuals.
  • name is required for businesses. Value is vendor's business name.
  • Either taxId or vatId is required for businesses (only one per request).
  • email is required.
  • phone is required.
  • country is required. Value is vendor's country code.
  • state is required if country value is US or CA.
  • city is required.
  • zip is required.
  • 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. Contains vendor principal owner info. Show/hide properties
    • firstName is required.
    • lastName is required.
    • address is required.
    • country is required. Value is vendor principal's country code.
    • city is required.
    • zip is required.
    • dob is required. Value is vendor principal's date of birth.
    • personalIdentificationNumber is required if vendor principal 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. Note: only one of ID fields personalIdentificationNumber, driversLicenseNumber or passportNumber is required.
    • driverLicenseNumber is only required if no other ID fields, such as personalIdentificationNumber or passportNumber, have been provided.
    • passportNumber is only required if no other ID fields, such as personalIdentificationNumber or driverLicenseNumber, have been provided.
    • email is required.
  • vendorAgreement is required. Contains vendor commission info. Show/hide properties
    • commissionPercent The value is vendor's commission percent for marketplace sales. Either percent or amount must be set.
    • commissionAmount The value is vendor's commission amount for marketplace sales. Either percent or amount must be set.
  • payoutInfo is required. Contains vendor payout info. Show/hide properties
    • payoutType is required. Possible values: ACH, CHAPS, FAST, SEPA, WIRE.
    • baseCurrency is required. Value is payout currency for bank account.
    • bankName is required.
    • address is required. Value is street address of vendor's bank.
    • country is required. Value is country code of vendor's bank.
    • state is required if bank country value is US or CA.
    • city is required.
    • zip is required.
    • nameOnAccount is required.
    • bankAccountClass is required. Possible values: PERSONAL, CORPORATE, INTERNATIONAL
    • bankAccountType is required. Possible values: CHECKING, SAVINGS
    • 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).

Back to Top

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