BlueSnap.comAPI BasicsPayment APIEmbedded PaymentsReporting & ToolsSupport GuidesTest
API Reference

Create Vendor

post https://sandbox.bluesnap.com/services/2/vendors

The Create Vendor request enables you to set up a new vendor who will be associated with your marketplace. The Create Vendor request is where you submit the vendor's KYC information, their banking information, the agreed upon commission split, and so on.

📘

Important: Vendor verification requirements

  • 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 must collect all the necessary Know Your Customer (KYC), banking, and any additional required information from them, and submit to BlueSnap for verification.

  • In addition, to be eligible for payout, the vendor must meet vendor verification requirements.

Try it in the API Explorer

Request Content

vendor container    required, contains the following properties (see vendor):
     email string    required      
     name string     optional
     firstName string     optional
     lastName string     optional
     phone string    optional
     address string    optional
     city string   optional
     country string    required
     state string   optional    applicable if country = US or CA (See State and Province Codes).
     zip string   optional
     taxId string    optional
     vatId string    optional
     vendorUrl string    optional
     defaultPayoutCurrency string    optional    
     frequency string    optional    
     delay integer    optional    
     vendorPrincipal container     optional; (see vendorPrincipal)
     vendorAgreement container     optional; (see vendorAgreement)
     payoutInfo container    optional; (see payoutInfo)
     ipnUrl string    optional

Response Details

If successful, the response HTTP status code is 201 Created.
The response header contains the vendorId.
The vendorId is required for all future transactions associated with this vendor.

Examples

Request Examples

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": "[email protected]",
  "firstName": "Joe",
  "lastName": "Smith",
  "phone": "1-123-456-7890",
  "address": "123 Main Street",
  "city": "Boston",
  "country": "US",
  "state": "MA",
  "zip": "02453",
  "defaultPayoutCurrency": "USD",
  "ipnUrl": "https://ipnaddress.com",
  "vendorPrincipal": {
    "firstName": "Joe",
    "lastName": "Smith",
    "address": "123 Main Street",
    "city": "Boston",
    "country": "US",
    "zip": "02453",
    "dob": "28-09-9999",
    "personalIdentificationNumber": "1234",
    "driverLicenseNumber": "561196411",
    "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": "02453",
      "bankAccountId": "36628822",
      "minimalPayoutAmount": 50,
      "paymentReference": "Payment for vendor 1234",
      "refundReserve": 200
    }
  ]
}'

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 '
{
  "name": "Business ABC",
  "email": "[email protected]",
  "phone": "1-123-455-8765",
  "address": "25 Business Avenue",
  "city": "Boston",
  "country": "US",
  "state": "MA",
  "zip": "02453",
  "taxId": "123456789",
  "vendorUrl": "http://mycompany.com",
  "ipnUrl": "https://ipnaddress.com",
  "defaultPayoutCurrency": "USD",
  "vendorPrincipal": {
    "firstName": "Joe",
    "lastName": "Smith",
    "address": "123 Main Street",
    "city": "Boston",
    "country": "US",
    "zip": "12345",
    "dob": "28-09-9999",
    "personalIdentificationNumber": "1234",
    "driverLicenseNumber": "561196411",
    "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": "02453",
      "bankAccountId": "36628822",
      "minimalPayoutAmount": 50,
      "paymentReference": "Payment for vendor 1234",
      "refundReserve": 200
    }
  ]
}'

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": "[email protected]",
  "firstName": "Joe",
  "lastName": "Smith",
  "phone": "1-123-456-7890",
  "address": "123 Main Street",
  "city": "Boston",
  "country": "US",
  "state": "MA",
  "zip": "02453",
  "defaultPayoutCurrency": "USD",
  "ipnUrl": "https://ipnaddress.com",
  "vendorPrincipal": {
    "firstName": "Joe",
    "lastName": "Smith",
    "address": "123 Main Street",
    "city": "Boston",
    "country": "US",
    "zip": "123456",
    "dob": "28-09-9999",
    "personalIdentificationNumber": "1234",
    "driverLicenseNumber": "561196411",
    "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": "02453",
      "bankAccountId": "36628822",
      "minimalPayoutAmount": 25,
      "paymentReference": "Payment for vendor 1234",
      "refundReserve": 200
    },
    {
      "payoutType": "CHAPS",
      "baseCurrency": "GBP",
      "nameOnAccount": "Jane Shopper",
      "bankAccountType": "CHECKING",
      "bankAccountClass": "PERSONAL",
      "bankName": "Barclays",
      "bankId": "123456",
      "country": "UK",
      "city": "Luton",
      "address": "28 George St",
      "zip": "LU1 2AE",
      "bankAccountId": "36628822",
      "minimalPayoutAmount": 25,
      "paymentReference": "Payment for vendor 1234"
    }
  ]
}'

Response Examples 

HTTP/ 1.1 201 Created
Location: https://sandbox.bluesnap.com/services/2/vendors/19575974

Example Descriptions

Create Vendor: Individual

This example shows a Create Vendor request with sufficient information to fully board an individual vendor. To see the required information for payout, click here. Since frequency and delay were not included in the request, the vendor's payout schedule will default to the Marketplace Merchant's approved schedule with BlueSnap.

Create Vendor: Business

This example shows a Create Vendor request with sufficient information to fully board a business vendor. Note that the primary difference between boarding a business vendor and an individual vendor is that business vendors will require name and either taxId or vatId. To see the required information for payout, click here. Since frequency and delay were not included in the request, the vendor's payout schedule will default to the Marketplace Merchant's approved schedule with BlueSnap.

Create Vendor: with 2 bank accounts

This example shows a Create Vendor request for an individual vendor with 2 bank accounts. The vendor's bank account details are included within separate objects inside the payoutInfo container (1 bank account per object). In this particular example, the vendor will be paid out in USD (via ACH) and GBP (via CHAPS). Their default payout currency is USD.

The following conversion logic applies:

  • Since the vendor's payout currencies are USD and GBP, if a sale occurs in either of these currencies, the sales funds are paid out to the associated bank account.
  • Since the vendor's default payout currency is USD, if a sale occurs in a currency other than USD or GBP, the sales funds are converted to USD and paid out to the associated bank account.

Back to Top

API Explorer

To test out a call, enter the request content below and then click Try it!

Tip: Use the JSON code below as a starting point. You can enter different parameters to see how your test scenario would work. The request headers, including authorization, are already built in for you in this test area, so you should not include them here.

{
  "email": "[email protected]",
  "firstName": "Joe",
  "lastName": "Smith",
  "phone": "1-123-456-7890",
  "address": "123 Main Street",
  "city": "Boston",
  "country": "US",
  "state": "MA",
  "zip": "02453",
  "defaultPayoutCurrency": "USD",
  "ipnUrl": "https://ipnaddress.com",
  "vendorPrincipal": {
    "firstName": "Joe",
    "lastName": "Smith",
    "address": "123 Main Street",
    "city": "Boston",
    "country": "US",
    "zip": "02453",
    "dob": "28-09-9999",
    "personalIdentificationNumber": "1234",
    "driverLicenseNumber": "561196411",
    "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": "02453",
      "bankAccountId": "36628822",
      "minimalPayoutAmount": 50,
      "paymentReference": "Payment for vendor 1234",
      "refundReserve": 200
    }
  ]
}
Language
Credentials
:
Click Try It! to start a request and see the response here!