When you authorize an online payment on behalf of your user, you can split the payment amount between the balance accounts in your marketplace by including the split instructions in your authorization request. This allows you to separately book the sale amount, your marketplace's commission, transaction fees, and the leftover amount after currency conversion.
Split a payment between balance accounts
To split the payment amount at the time of authorization, add a splits array to your POST /payments or POST /sessions request.
For each item in the /payments splits array or the /sessions splits array, specify the following fields:
| Parameter | Required | Description |
|---|---|---|
account |
 |
The account that will receive (or be charged) the split amount. This is the balanceAccountId of one of your user's balance accounts or your marketplace's liable balance account. You don't need to specify this field when type is Commission. |
amount.currency |
Required for currency conversion |
The currency of the part of the payment you want to the specified account. |
amount.value |
|
The value of the part of the payment you want to the specified account. You do not need to specify this field for transaction fees or the remainder, because they are not known at the time of payment. |
type |
|
Defines the part of the payment you want to book to the specified account.Possible values:
|
reference |
Required if type is BalanceAccount |
Your unique identifier for the part of the payment you want to book to the specified account. You need this for reconciliation, as explained under Best practices. |
description |
Your description for the part of the payment you want to booking to the specified account, returned in our reports. |
Here is an example of how you can split the payment amount at the time of payment, when a customer pays EUR 400.00.
- EUR 396.00 is booked to your user's balance account as payment for the goods or service.
- EUR 4.00 is booked to your liable balance account as your marketplace's commission.
- All transaction fees are booked to your user's balance account, deducted from the sale amount.
In the response, note that your reference from the request is returned as the merchantReference. You need this information for reconciliation, as explained under Best practices.
Additional split instructions
The above example shows you how to:
- Book the sale amount to your user's balance account (using
typeBalanceAccount. - Book all the transaction fees to your user's balance account (using
typePaymentFee). - Book the commission to your liable balance account (using
typeCommission).
This is the standard use case for most payments. However, you can additionally extend your split instructions to cover more specific use cases.
Different types of transaction fees
The split type PaymentFee books the total amount of all your transaction fees to the specified balance account. However, you can also choose to split the total transaction fee amount, and book different kinds of fees to different balance accounts.
For more information about the transaction fee types, and how to book them to different balance accounts, see Transaction fees.
Remainder after currency conversion
When you process payments on behalf of your users, you can convert the currency of those payments. Due to the constantly fluctuating exchange rates, you may have a leftover amount after currency conversion, called a Remainder. You can book this remainder to the balance account of your choice.
For more information about currency conversion and booking the remainder, see Currency conversion.
Top-ups
A payment made by your user to increase the balance in their balance account is called a top-up. You can book this top-up to your user's balance account.
For more information about booking the top-up, see Top-ups.
Potential chargebacks and costs
When a chargeback occurs on of your users' payments, you can choose how to book the disputed amount to the balance accounts in your marketplace.
For more information, see Chargebacks and disputes.
Best practices
We strongly recommend sending a reference for all sets of split instructions in your /payments or /sessions request. You can use the reference to reconcile the split amounts in the transaction overview and in the reports. Without a reference, the split amounts are aggregated in a single entry and you will be unable to reconcile the transactions.
If you do not know the split amounts at the time of payment, you can provide split instructions at capture instead. Split instructions provided at capture override any split instructions provided with the initial payment request. However, we recommend that you provide the split instructions at the time of payment, rather than at capture. Because some payment methods do not support delayed captures, the funds may not be booked correctly unless the split instructions are provided in the payment request.
The API request validates only the format of the split instructions, not the balance accounts specified in the request. This means that even if the payment, capture, and refund is successful, it is possible that the funds are not credited to/deducted from the specified balance account. If the balance account does not exist, or it is linked to an account holder with a closed status, the full transaction (sale amount, commission, and fees) is booked to your platform's liable balance account.
To correct the balances, you can transfer the funds between the balance accounts in your platform.