Create Vendor Accounts

To create a new vendor account and begin the onboarding process, you will submit the vendor's information via the Create Vendor API. Review the verification guidelines and requirements here first.

🚧
The merchant must be set up for regional payout, meaning that your request will include payoutConfiguration to reflect regional payout settings.
If you call this API with the previous payoutInfo object or if the merchant is not configured for regional payout, an error will be returned. You must update your requests per the new structure.

Vendor Verification Guidelines

The information required to verify a vendor depends on the vendor type and country:

Individuals must provide personal information.
Businesses must provide business information and a business representative.
Some requirements are country-specific, including payout details and identification fields such as a personal identification number.

BlueSnap reviews a vendor only after all required information has been submitted and the vendor has been included in at least one transaction. During review, BlueSnap may request additional documentation, such as a passport or driver’s license. Any documentation you submit must be clear, legible, valid, and current.

You must also present your vendor with a link to the latest BlueSnap Vendor Agreement. They must expressly consent to these terms and conditions before they begin using BlueSnap. You will capture their date of consent and IP address in the termsOfService object in the Create Vendor request.

Submit Information in Advance

Collecting as much KYC and payout information (e.g., commission rate, banking information, business owner information, etc.) as you can in advance and submitting it with the Create Vendor request means you won't have to ask your vendor for their information more than once.

Define your vendor's payout currency (if not USD) in their payout details prior to processing transactions to avoid significant delays in payout. Define your vendor's commission rate to ensure that all transactions are split properly.

BlueSnap reviews the vendor account only after all the necessary information has been received and the vendor has been included on at least one transaction.

Create Vendor Request

Below is an example Create Vendor API request for individual and business accounts. Use these code samples as a template and modify specific properties for your vendor.

Refer to the JSON and XML API specifications for a full list of vendor properties.

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",
  "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
  },
  "termsOfService": {
    "acceptedDate": "18-05-2026",
    "vendorIp": "123.65.45.32"
  },
  "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>[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>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>[email protected]</email>
  </vendor-principal>
  <vendor-agreement>
    <commission-percent>30</commission-percent>
    </vendor-agreement>
  <terms-of-service>
    <accepted-date>18-02-2026</accepted-date>
    <vendor-ip>123.65.45.32</vendor-ip>
  </terms-of-service>
  <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>'

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",
  "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
  },
  "termsOfService": {
    "acceptedDate": "18-05-2026",
    "vendorIp": "123.65.45.32"
  },
  "payoutConfiguration": {
    "reviewDelay": 15,
    "payoutFrequency": "MONTHLY",
    "defaultLegalEntity": "US",
    "regions": [
      {
        "region": "US",
        "defaultCurrency": "USD",
        "currencyByRegion": [
          {
            "currencyCode": "USD",
            "payoutPaymentType": "ACH",
            "minimumPaymentAmount": 50,
            "reserve": {
              "merchantReserve": {
                "keepOnMerchantReserve": 200
              }
            },
            "bankDetails": [
              {
                "country": "US",
                "state": "MA",
                "city": "Boston",
                "address1": "1 bank address",
                "zipCode": "02453",
                "paymentReference": "payout for vendor 1234",
                "bankId": "123456789",
                "bankName": "Bank of America",
                "accountId": "36628822",
                "nameOnAccount": "name of vendor account",
                "achAccountClass": "CORPORATE",
                "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">
  <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>
  <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>
    <driver-license-number>561196411</driver-license-number>
    <email>[email protected]</email>
  </vendor-principal>
  <vendor-agreement>
    <commission-percent>30</commission-percent>
  </vendor-agreement>
  <terms-of-service>
    <accepted-date>18-02-2026</accepted-date>
    <vendor-ip>123.65.45.32</vendor-ip>
  </terms-of-service>
  <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>CORPORATE</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

Track Vendor Status

Notifications of any changes to your vendor's account and payout statuses are sent using the Vendor Status Changed webhook.

If the vendor's payout status is Inactive due to incomplete vendor information, the vendorMissingFields parameter will indicate what you still need to provide. For example:

{
  "bluesnapNode": "2",
  "ipnId": "f5eb0f7e-2091-4364-8b28-bf429e70d651",
  "ipnV2": "Y",
  "plimusNode": "2",
  "transactionType": "VENDOR_STATUS_CHANGED",
  "vendorAccountOpenedDate": "06/11/2026 04:46 PM",
  "vendorAccountStatus": "Active",
  "vendorAccountStatusChangedDate": "",
  "vendorId": "1256687",
  "vendorMissingFields": "defaultLegalEntity",
  "vendorName": "Example Vendor,
  "vendorPayoutStatus": "Inactive"
}

However, BlueSnap recommends calling the Vendor API to check a vendor's status and missing fields because it provides more granular information:

When the payout status returned in the webhook is Inactive, make a Retrieve Vendor API request. The verification.payoutStatus property in the response provides context about why the vendor was not approved for payout yet.
- Incomplete: You have not provided sufficient information to fully board your vendor.
- Pending: You have provided sufficient information to fully board your vendor and BlueSnap is currently reviewing this information.
- Declined: BlueSnap has declined your vendor.
If Incomplete, check the verification.missingItems array in the response to see what vendor information you need to provide. For example, "missingItems": ["vendor.phone", "vendor.address", "vendor.payoutConfiguration.defaultLegalEntity"]
Make an Update Vendor API request to provide those missing fields. The API response should indicate that the status is now Pending.
Wait for another webhook notification to confirm that the payout status is updated to Active.