BlueSnap.comAPI BasicsPayment APIEmbedded PaymentsReporting & ToolsSupport GuidesTest
API Reference

Payout

Review important topics related to payout and understand how payout works.
If you have questions after reading this guide, check out our FAQs page.

BlueSnap pays out account funds to you and your vendors.
Consider the following topics to familiarize yourself with how payout works.

Marketplace Merchant account vs. Vendor account

There are some key differences between your BlueSnap account and your vendors' BlueSnap accounts.

Payout IPN

If you want to be notified when a payout is sent to your vendors, use the ipnURL field within the API. Providing a URL in this field specifies that the payout IPN should be sent to this URL on every payout to your vendors.

Marketplace Merchant

As the Marketplace Merchant, you have one BlueSnap account, where you receive all commission splits on marketplace sales. You have a bank account (possibly multiple) linked to your BlueSnap account. BlueSnap pays out your funds to your bank account(s).

Vendors

Each of your vendors has a BlueSnap account associated with them, where they receive their commission splits. They each have a bank account linked to their BlueSnap account, where we pay out account funds. Your vendor does not have access to BlueSnap. As the Marketplace Merchant, you communicate all account information to your vendors.

👍

Viewing your vendor's account balance

To view your vendor's account balance, use the Vendor Details report — available through both the Merchant Portal and Reporting API.

Back to Top

Commission

BlueSnap pays you and your vendor according to the agreed-upon commission split, either a percentage or an amount.
The commission split occurs when the shopper's funds are captured for the sale.

You can set the commission split between you and your vendor in the following ways:

  1. Create Vendor request — Inside the Vendor Agreement container include the Commission Percent or the Commission Amount property in the request to be used for all transactions.

  2. Update Vendor request — Inside the Vendor Agreement container include the Commission Percent or the Commission Amount property in the request to be used for all transactions.

  3. For a single transaction — In Auth-Capture, Auth Only, ACH/ECP, and Subscription requests, you may define the commission for that specific transaction. Click here to learn how.

👍

Defining commission rate during vendor creation

We recommend that you define your vendor's commission rate (which is part of the necessary information for payout) during the initial vendor creation.

You can always update the commission rate later via Update Vendor request, or you may override it for a specific transaction.

Back to Top

Vendor payout schedule, currencies, and methods

Vendor payout schedule

By default, your vendor's payout schedule follows your approved schedule with BlueSnap, meaning that your vendor inherits both your payout frequency and delay unless you modify the frequency or delay properties in the Create or Update Vendor requests. Depending on your payout schedule, your vendor's payout frequency can be daily, weekly, semimonthly, or monthly.

Note that 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.

Vendor payout currencies

You can define your vendor's payout currencies via the Create and Update Vendor requests.
Vendors can be paid out in one or more of the like-for-like currencies. To see the full list of payout currencies, click here.

👍

Note

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 see a code sample of a Create Vendor request for a vendor with 2 payout currencies and 2 bank accounts, click here.

Vendor payout methods

You can define your vendor's payout method using the Create and Update Vendor requests. 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

payoutInfo examples

The following code samples show how the payoutInfo property might vary based on your vendor's payout method.

{
  "payoutInfo": [{
    "payoutType": "ACH",
    "baseCurrency": "USD",
    "nameOnAcccount": "Jane Shopper",
    "bankAccountType": "CHECKING",
    "bankAccountClass": "PERSONAL",
    "bankName": "First Bank of Newton",
    "bankId": "12445",
    "country": "US",
    "state": "KS",
    "city": "Newton",
    "address": "128 E Broadway St",
    "zip": "67114", 
    "bankAccountId": "36628822", 
    "minimalPayoutAmount": 25,
    "refundReserve": 200
  }]
    ...  
}

{
  "payoutInfo": [{
    "payoutType": "CHAPS",
    "baseCurrency": "GBP",
    "nameOnAccount": "Jane Shopper",
    "bankAccountType": "CHECKING",
    "bankAccountClass": "PERSONAL",
    "bankName": "Barclays",
    "bankId": "12445",
    "iban": "377438437843847300022",
    "country": "UK",
    "city": "Luton",
    "address": "28 George St",
    "zip": "LU1 2AE",
    "bankAccountId": "36628822", 
    "minimalPayoutAmount": 25, 
    "refundReserve": 200
  }]  
  ...  
}

{
  "payoutInfo": [
    {
      "payoutType": "FAST",
      "baseCurrency": "GBP",
      "nameOnAcccount": "Jane Smith",
      "bankAccountType": "CHECKING",
      "bankAccountClass": "PERSONAL",
      "bankName": "Barclays",
      "bankId": "123456",
      "country": "UK",
      "city": "London",
      "address": "128 E Broadway St",
      "zip": "5201",
      "bankAccountId": "36628822",
      "minimalPayoutAmount": 25,
      "refundReserve": 200
    }
  ]
   ...
}

{
  "payoutInfo": [
    {
      "payoutType": "SEPA",
      "baseCurrency": "EUR",
      "nameOnAccount": "Jane Shopper",
      "bankAccountType": "CHECKING",
      "bankAccountClass": "PERSONAL",
      "bankName": "UniCredit",
      "iban": "DE09100100101234567893",
      "swiftBic": "PBNKDEFFXXX",
      "country": "AT",
      "city": "Leitendorf",
      "address": "Anzengrubergasse 14",
      "zip": "8700",
      "minimalPayoutAmount": 25,
      "refundReserve": 200
    }
  ]
  ...
}

{
  "payoutInfo": [{
    "payoutType": "WIRE",
    "baseCurrency": "CAD",
    "nameOnAccount": "Jane Shopper",
    "bankAccountType": "CHECKING",
    "bankAccountClass": "PERSONAL",
    "bankName": "First Bank of Newton",
    "bankId": "12445",
    "country": "US",
    "state": "KS",
    "city": "Newton",
    "address": "128 E Broadway St",
    "zip": "67114",
    "bankAccountId": "36628822", 
    "minimalPayoutAmount": 25,
    "refundReserve": 200
  }]  
  ...  
}

<vendor xmlns="http://ws.plimus.com">

  <payout-info>
    <payout-type>ACH</payout-type>
    <base-currency>USD</base-currency>
    <name-on-account>Jane Shopper</name-on-account>
    <bank-account-type>CHECKING</bank-account-type>
    <bank-account-class>PERSONAL</bank-account-class>
    <bank-name>First Bank of Newton</bank-name>
    <bank-id>12445</bank-id>
    <country>US</country>
    <state>KS</state>
    <city>Newton</city>
    <address>128 E Broadway St</address>
    <zip>67114</zip>
    <bank-account-id>36628822</bank-account-id>
    <minimal-payout-amount>25</minimal-payout-amount>
    <refund-reserve>200</refund-reserve>
  </payout-info>
  
  ...
  
</vendor>

<vendor xmlns="http://ws.plimus.com">

  <payout-info>
    <payout-type>CHAPS</payout-type>
    <base-currency>GBP</base-currency>
    <name-on-account>Jane Shopper</name-on-account>
    <bank-account-type>CHECKING</bank-account-type>
    <bank-account-class>PERSONAL</bank-account-class>
    <bank-name>Barclays</bank-name>
    <bank-id>12445</bank-id>
    <iban>377438437843847300022</iban>
    <country>UK</country>
    <city>Luton</city>
    <address>28 George St</address>
    <zip>LU1 2AE</zip>
    <bank-account-id>36628822</bank-account-id>
    <minimal-payout-amount>25</minimal-payout-amount>
    <refund-reserve>200</refund-reserve>
  </payout-info>
  
  ...
  
</vendor>

<vendor xmlns="http://ws.plimus.com">
  <payout-info>
    <payout-type>FAST</payout-type>
    <base-currency>GBP</base-currency>
    <name-on-account>Jane Smith</name-on-account>
    <bank-account-type>CHECKING</bank-account-type>
    <bank-account-class>PERSONAL</bank-account-class>
    <bank-name>Barclays</bank-name>
    <bank-id>123456</bank-id>
    <country>UK</country>
    <city>London</city>
    <address>128 E Broadway St</address>
    <zip>5201</zip>
    <bank-account-id>36628822</bank-account-id>
    <minimal-payout-amount>25</minimal-payout-amount>
    <refund-reserve>200</refund-reserve>
  </payout-info>
  ...
</vendor>

<vendor xmlns="http://ws.plimus.com">
  <payout-info>
    <payout-type>SEPA</payout-type>
    <base-currency>EUR</base-currency>
    <name-on-account>Jane Shopper</name-on-account>
    <bank-account-type>CHECKING</bank-account-type>
    <bank-account-class>PERSONAL</bank-account-class>
    <bank-name>UniCredit</bank-name>
    <iban>DE09100100101234567893</iban>
    <swift-bic>PBNKDEFFXXX</swift-bic>
    <country>AT</country>
    <city>Leitendorf</city>
    <address>Anzengrubergasse 14</address>
    <zip>8700</zip>
    <minimal-payout-amount>25</minimal-payout-amount>
    <refund-reserve>200</refund-reserve>
  </payout-info>
  ...
</vendor>

<vendor xmlns="http://ws.plimus.com">

  <payout-info>
    <payout-type>WIRE</payout-type>
    <base-currency>CAD</base-currency>
    <name-on-account>Jane Shopper</name-on-account>
    <bank-account-type>CHECKING</bank-account-type>
    <bank-account-class>PERSONAL</bank-account-class>
    <bank-name>First Bank of Newton</bank-name>
    <bank-id>12445</bank-id>
    <country>US</country>
    <state>KS</state>
    <city>Newton</city>
    <address>128 E Broadway St</address>
    <zip>67114</zip>
    <bank-account-id>36628822</bank-account-id>
    <minimal-payout-amount>25</minimal-payout-amount>
    <refund-reserve>200</refund-reserve>
  </payout-info>
  
  ...

</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 defaultPayoutCurrency must have an associated bank account defined within payoutInfo.

  • You may add an additional bank account to your vendor by adding another object inside payoutInfo with the bank account details. To see a code sample for a vendor with two bank accounts, click here.

  • One bank account per payout currency is supported.

FX conversion

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

Some questions to consider:

  • 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.

Back to Top

Next: API Reference

Now that you've read through this guide, check out our JSON or XML API Reference for all of our API calls and comprehensive examples.