Split payments at authorization

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.

Requirements

Take into account the following requirements, limitations, and preparations to start processing payments.

Split a payment between balance accounts

To split the payment amount at the time of authorization:

1. 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 do not 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: BalanceAccount: books the sale amount to the specified balance account. Commission: books your commission to your liable balance account. Remainder: books the amount left over after a currency conversion to the specified balance account. By default, the amount is booked to your marketplace's liable balance account. We recommend that you also include at least one transaction fee type in your request. All undefined transaction fees are booked to your marketplace's liable balance account. TopUp: books the top-up amount paid by your user to the specified balance account. This split type is not supported for a /sessions request.
   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 that shows you how to split the payment amount at the time of payment, when a customer pays EUR 400.00:

   • With type BalanceAccount, we book EUR 396.00 to your user's balance account as payment for the goods or services.
   • With type PaymentFee, we book all the transaction fees to your user's balance account.
   • With type Commission, we book EUR 4.00 to your liable balance account as your marketplace's commission.

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

Troubleshooting

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 transaction 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 and its fees are booked to your marketplace's liable balance account.

To correct the balances, you can transfer the funds between the balance accounts in your marketplace.

Track fund movements

To track the status of the fund transfers initiated by a payment:

1. Listen to the following webhooks:
   • Transfer webhooks: Adyen sends a balancePlatform.transfer.created webhook to inform your server that funds will be credited to balance accounts, and balancePlatform.transfer.updated webhooks after every status change.
   • Transaction webhooks: Adyen sends a balancePlatform.transaction.created webhook to inform your server that funds have been credited to a balance account.
2. Acknowledge the webhooks. We send these webhooks for every split item in the payment.
3. In the balancePlatform.transfer.updated webhook payload, note that the event array includes all previous transfer events, and the sequenceNumber defines the number of webhooks sent for the transfer, including the current one.

Examples

Your server receives webhooks for each split of the payment amount. The following examples are based on a standard split payment use case.

Additional split instructions

In addition to the standard use cases, you can also book the following split types to your user's balance account:

• Transaction fees
• Leftover amount after currency conversion (remainder)
• Chargebacks
• Top-ups

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.

Potential chargebacks and costs

When payments of your users are charged back, you can choose how to book the disputed amount to the balance accounts in your marketplace.

For more information, see Chargebacks and disputes.

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.

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.

See also