When accepting an online payment, you can split the payment amount between the balance accounts in your marketplace. This allows you to separately book the sale amount, your marketplace's commission, transaction fees, and the leftover amount after currency conversion.
If you configured stores in your merchant account, you can automatically direct funds and book fees to predefined balance accounts.
Split a payment between balance accounts
To split the payment amount at the time of payment, 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.
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 data at capture instead. Split data provided at capture overrides any split data provided with the initial payment request. However, we recommend that you provide the split information 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 data is provided in the payment request.
The API request validates only the format of the split data, 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.