Payouts

BlueSnap pays out account funds to you and your vendors. You define your vendor's payout schedule, currencies, and methods in the Create Vendor and Update Vendor APIs, based on the vendor's region.

Refer to Split Payments for more details about how funds are divided between the merchant and your vendors.

Regional Payout

The previous payoutInfo object used in Create Vendor and Update Vendor requests has been deprecated and replaced with payoutConfiguration to support regional payout as detailed in this guide. You must update your requests per the new structure.

If you call this API with payoutInfo or if the merchant is not configured for regional payout, an error will be returned.

Payout Schedule

By default, your vendor's payout schedule follows your approved schedule with BlueSnap. This means that your vendor inherits both your payout frequency and delay unless you modify the payoutConfiguration.payoutFrequency or payoutConfiguration.reviewDelay properties in the Create or Update Vendor request. Depending on your payout schedule, your vendor's payout frequency can be daily, weekly, semi-monthly, or monthly.

Your vendor's payout settings cannot result in quicker payout than your approved schedule with BlueSnap. For example, if you have a payout frequency of daily and a delay of 3 days, then your vendor cannot have a frequency of daily and a delay of 1 day.

Payout Currencies

Vendors can be paid out in one or more of the like-for-like currencies. Refer to Supported Currencies for the full list of payout currencies.

For each of your vendor's payout currencies, there must be an associated bank account. BlueSnap supports only one bank account per payout currency. To support merchants in various regions with different payout currencies, you must set up multiple vendor accounts and associate merchants based on region and the desired payout setup. For each vendor account, the currency and payout method selected must be supported by the region the merchant is boarded to.

To see a code sample of a Create Vendor request for a vendor with 2 payout currencies and 2 bank accounts, click here.

Payout Methods

We offer the following options for vendor payout:

CHAPS in GBP
EFT/ACH in AUD, USD, or CAD
Fast Bank Transfer in CHF, DKK, GBP, NOK, or SEK
SEPA in EUR
WIRE

payoutConfiguration Examples

The following code samples show how the payoutConfiguration property in a Create or Update Vendor request might vary based on your vendor's payout method.

JSON

{
  "payoutConfiguration": {
    "reviewDelay": 15,
    "payoutFrequency": "MONTHLY",
    "defaultLegalEntity": "US",
    "regions": [
      {
        "region": "US",
        "defaultCurrency": "USD",
        "currencyByRegion": [
          {
            "currencyCode": "USD",
            "payoutPaymentType": "ACH",
            "minimumPaymentAmount": 35,
            "reserve": {
              "merchantReserve": {
                "keepOnMerchantReserve": 50
              }
            },
            "bankDetails": [
              {
                "country": "us",
                "state": "PA",
                "city": "Dravosburg",
                "address1": "100 Bettis Rd",
                "zipCode": "98659",
                "paymentReference": "my paymentReference",
                "bankId": "026009593",
                "bankName": "First Commonwealth",
                "accountId": "4451300931",
                "nameOnAccount": "FedEx Cross Border Logistics, Inc.",
                "achAccountClass": "CORPORATE",
                "achAccountType": "CHECKING"
              }
            ]
          }
        ]
      }
    ]
  },
...
}

{
  "payoutConfiguration": {
    "reviewDelay": 15,
    "payoutFrequency": "MONTHLY",
    "defaultLegalEntity": "US",
    "regions": [
      {
        "region": "UK",
        "defaultCurrency": "GBP",
        "currencyByRegion": [
          {
            "currencyCode": "GBP",
            "payoutPaymentType": "CHAPS",
            "minimumPaymentAmount": 50,
            "reserve": {
              "merchantReserve": {
                "keepOnMerchantReserve": 200
              }
            },
            "bankDetails": [
              {
                "country": "UK",
                "city": "Luton",
                "address1": "28 George St",
                "zipCode": "LU1 2AE",
                "intermediaryBic": "GHI123456JKL",
                "intermediaryBankName": "Example Bank",
                "intermediaryBankState": "MA",
                "intermediaryBankCountry": "US",
                "bankId": "984632",
                "bic": "ABC123456DEF",
                "bankName": "Barclays",
                "accountId": "36628822",
                "iban": "377438437843847300022",
                "nameOnAccount": "vendor"
              }
            ]
          }
        ]
      }
    ]
  },
  ...
}

{
  "payoutConfiguration": {
    "reviewDelay": 15,
    "payoutFrequency": "MONTHLY",
    "defaultLegalEntity": "US",
    "regions": [
      {
        "region": "UK",
        "defaultCurrency": "GBP",
        "currencyByRegion": [
          {
            "currencyCode": "GBP",
            "payoutPaymentType": "FAST",
            "minimumPaymentAmount": 50,
            "reserve": {
              "merchantReserve": {
                "keepOnMerchantReserve": 200
              }
            },
            "bankDetails": [
              {
                "country": "UK",
                "city": "Luton",
                "address1": "28 George St",
                "zipCode": "LU1 2AE",
                "intermediaryBic": "GHI123456JKL",
                "intermediaryBankName": "Example Bank",
                "intermediaryBankState": "MA",
                "intermediaryBankCountry": "US",
                "bankId": "984632",
                "bic": "ABC123456DEF",
                "bankName": "Barclays",
                "accountId": "36628822",
                "iban": "377438437843847300022",
                "nameOnAccount": "vendor"
              }
            ]
          }
        ]
      }
    ]
  },
  ...
}

{
  "payoutConfiguration": {
    "reviewDelay": 15,
    "payoutFrequency": "MONTHLY",
    "defaultLegalEntity": "US",
    "regions": [
      {
        "region": "EU",
        "defaultCurrency": "EUR",
        "currencyByRegion": [
          {
            "currencyCode": "EUR",
            "payoutPaymentType": "SEPA",
            "minimumPaymentAmount": 50,
            "reserve": {
              "merchantReserve": {
                "keepOnMerchantReserve": 200
              }
            },
            "bankDetails": [
              {
                "country": "AT",
                "city": "Leitendorf",
                "address1": "Anzengrubergasse 14",
                "zipCode": "8700",
                "intermediaryBic": "GHI123456JKL",
                "intermediaryBankName": "Example Bank",
                "intermediaryBankState": "MA",
                "intermediaryBankCountry": "US",
                "bankId": "0984632",
                "bic": "ABC123456DEF",
                "bankName": "UniCredit",
                "accountId": "36628822",
                "iban": "377438437843847300022",
                "nameOnAccount": "vendor",
                "achAccountClass": "CORPORATE",
                "achAccountType": "CHECKING"
              }
            ]
          }
        ]
      }
    ]
  },
  ...
}

{
  "payoutConfiguration": {
    "reviewDelay": 15,
    "payoutFrequency": "MONTHLY",
    "defaultLegalEntity": "US",
    "regions": [
      {
        "region": "US",
        "defaultCurrency": "USD",
        "currencyByRegion": [
          {
            "currencyCode": "USD",
            "payoutPaymentType": "WIRE",
            "minimumPaymentAmount": 50,
            "reserve": {
              "merchantReserve": {
                "keepOnMerchantReserve": 200
              }
            },
            "bankDetails": [
              {
                "country": "US",
                "state": "MA",
                "city": "Juneau",
                "address1": "1 bank address",
                "zipCode": "12345",
                "intermediaryBic": "GHI123456JKL",
                "intermediaryBankName": "Investment Account",
                "intermediaryBankState": "MA",
                "intermediaryBankCountry": "US",
                "bic": "ABC123456DEF",
                "bankName": "Savings Account",
                "iban": "377438437843847300022",
                "nameOnAccount": "vendor"
              }
            ]
          }
        ]
      }
    ]
  },
  ...
}

XML

<vendor xmlns="http://ws.plimus.com">
  <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>
        </bank-details>
      </currency-by-region>
    </regions>
  </payout-configuration>
  
  ...
  
</vendor>

<vendor xmlns="http://ws.plimus.com">
  <payout-configuration>
    <payout-frequency>MONTHLY</payout-frequency>
    <review-delay>14</review-delay>
    <default-legal-entity>US</default-legal-entity>
    <regions>
      <region>UK</region>
      <default-currency>GBP</default-currency>
      <currency-by-region>
        <currency-code>GBP</currency-code>
        <status>Active</status>
        <payout-payment-type>CHAPS</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>UK</country>
          <city>Luton</city>
          <address-1>28 George St</address-1>
          <zip-code>LU1 2AE</zip-code>
          <intermediary-bic>GHI123456JKL</intermediary-bic>
          <intermediary-bank-name>Example Bank</intermediary-bank-name>
          <intermediary-bank-state>MA</intermediary-bank-state>
          <intermediary-bank-country>US</intermediary-bank-country>
          <bic>ABC123456DEF</bic>
          <bankId>984632</bankId>
          <bank-name>Barclays</bank-name>
          <iban>377438437843847300022</iban>
          <name-on-account>vendor</name-on-account>
        </bank-details>
      </currency-by-region>
    </regions>
  </payout-configuration>
  
  ...
  
</vendor>

<vendor xmlns="http://ws.plimus.com">
  <payout-configuration>
    <payout-frequency>MONTHLY</payout-frequency>
    <review-delay>14</review-delay>
    <default-legal-entity>US</default-legal-entity>
    <regions>
      <region>UK</region>
      <default-currency>GBP</default-currency>
      <currency-by-region>
        <currency-code>GBP</currency-code>
        <status>Active</status>
        <payout-payment-type>FAST</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>UK</country>
          <city>Luton</city>
          <address-1>28 George St</address-1>
          <zip-code>LU1 2AE</zip-code>
          <intermediary-bic>GHI123456JKL</intermediary-bic>
          <intermediary-bank-name>Example Bank</intermediary-bank-name>
          <intermediary-bank-state>MA</intermediary-bank-state>
          <intermediary-bank-country>US</intermediary-bank-country>
          <bic>ABC123456DEF</bic>
          <bankId>984632</bankId>
          <bank-name>Barclays</bank-name>
          <account-id>36628822</account-id>
          <iban>377438437843847300022</iban>
          <name-on-account>vendor</name-on-account>
        </bank-details>
      </currency-by-region>
    </regions>
  </payout-configuration>
  
  ...
  
</vendor>

<vendor xmlns="http://ws.plimus.com">
  <payout-configuration>
    <payout-frequency>MONTHLY</payout-frequency>
    <review-delay>14</review-delay>
    <default-legal-entity>US</default-legal-entity>
    <regions>
      <region>EU</region>
      <default-currency>EUR</default-currency>
      <currency-by-region>
        <currency-code>EUR</currency-code>
        <status>Active</status>
        <payout-payment-type>SEPA</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>AT</country>
          <city>Leitendorf</city>
          <address-1>Anzengrubergasse 14</address-1>
          <zip-code>8700</zip-code>
          <intermediary-bic>GHI123456JKL</intermediary-bic>
          <intermediary-bank-name>Example Bank</intermediary-bank-name>
          <intermediary-bank-state>MA</intermediary-bank-state>
          <intermediary-bank-country>US</intermediary-bank-country>
          <bic>PBNKDEFFXXX</bic>
          <bankId>984632</bankId>
          <bank-name>UniCredit</bank-name>
          <account-id>36628822</account-id>
          <iban>DE09100100101234567893</iban>
          <ach-account-class>PERSONAL</ach-account-class>
          <ach-account-type>CHECKING</ach-account-type>
          <name-on-account>vendor</name-on-account>
        </bank-details>
      </currency-by-region>
    </regions>
  </payout-configuration>
  
  ...
  
</vendor>

<vendor xmlns="http://ws.plimus.com">
  <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>WIRE</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>
          <intermediary-bic>GHI123456JKL</intermediary-bic>
          <intermediary-bank-name>Investment Account</intermediary-bank-name>
          <intermediary-bank-state>MA</intermediary-bank-state>
          <intermediary-bank-country>US</intermediary-bank-country>
          <bic>PBNKDEFFXXX</bic>
          <bank-name>Savings Account</bank-name>
          <iban>DE09100100101234567893</iban>
          <name-on-account>vendor</name-on-account>
        </bank-details>
      </currency-by-region>
    </regions>
  </payout-configuration>
  
  ...
  
</vendor>

📘
Reminders

We strongly recommend setting your vendor's minimal payout amount to $25 or more to avoid payout delays and negative balances.

Your vendor's payoutConfiguration.regions.defaultCurrency for payout in a given region must have an associated bank account defined within currencyByRegion.bankDetails.

You may add additional regions, currencies, and bank accounts by adding another object inside payoutConfiguration.regions with the details. To see a code sample for a vendor with two regions, click here.

One bank account per payout currency is supported.

Payout Webhook

If you want to be notified when a payout is sent to your vendors, specify the ipnURL in the Vendor API.

Providing a URL in this field specifies that the payout webhook should be sent to this URL upon every payout to your vendors.

FX Conversion

To support multiple currencies in your marketplace, consider the effects that Foreign Exchange (FX) conversion has on item pricing and payout.

What happens if the sale occurs in a currency different from the vendor's payout currency?
What tools does BlueSnap offer to help with item pricing?

Visit FX Conversion for more information.