Split payments at capture

When you process split payments for your users, the split amounts are not always known or decided at the time of authorization. For example:

• When a payment is pre-authorized with the intention of an authorization adjustment later.
• When the payment is processed using a payment method that does not support automatic capture.
• Order flows when the payment is captured manually, only when the order is shipped.

In such cases, you can provide the split instructions in a /payments/{paymentPspReference}/captures request instead. You can also override the split instructions you provided in the payment request if you send different split instructions in your capture request. However, we recommend to always include split instructions in your payment request, even when you intend to update these instructions in your capture request.

Requirements

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

Enable manual capture

To have better control over when a payment is captured, or to provide split instructions at capture, you must enable manual capture. You can enable manual capture for all payments processed in your merchant account, or for specific payments only.

Capture all payments manually

To enable manual capture for all payments in a merchant account:

1. In your Customer Area, switch to your merchant account.
2. Go to Settings > Account settings.
3. For the POS Capture Delay, select manual.
4. Select Submit.
5. Follow up each authorized Terminal API payment with a POST /payments/{paymentPspReference}/captures API call.

Capture specific payments manually

To enable manual capture for a specific payment:

1. Add a manual capture flag to each payment request that you want to capture manually.
2. Make a POST /payments/{paymentPspReference}/captures API call for that specific authorization.

Split a payment at the time of capture

To split a payment at the time of capture:

1. From the transactionID field in the payment response, get the pspReference of the authorization you want to capture.

2. To capture and split a payment at the same time, send a POST /payments/{paymentPspReference}/captures request, where paymentPspReference is the pspReference of the authorization you want to capture.

   In the body, include the splits array. For each item in the 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. You do not need to specify this field when type is Commission.
   amount.value		The value of the split amount. You do not need to specify this field for transaction fees, since 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 the commission to your liable balance account. You can also book different types of the transaction fees to different balance accounts.
   amount.currency		Required for currency conversion The currency of the split amount.
   reference		Required if type is BalanceAccount Your unique identifier for the specific transaction split.
   description		Your description for that specific transaction split, which is returned in our reporting.

   Here is an example of how you can split the payment amount at the time of capture, when a customer pays for goods worth EUR 80.00:

   • EUR 76.00 is booked to your user's balance account as payment for the goods.
   • EUR 4.00 is booked to your liable balance account as your platform's commission.
   • All transaction fees are booked against your user's balance account, deducted from the sale amount.

3. In the capture response, note the following:

   • paymentPspReference: the PSP reference of the authorization
   • pspReference: the PSP reference associated with this capture request. This is different from the PSP reference of the authorization.

   • status: received

4. Listen to the CAPTURE webhook to learn the outcome of the request.

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 platform's liable balance account.

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

Track fund movements

To track the status of the fund transfers initiated by a capture request:

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.

Example

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

In this case, your server receives webhooks for each balance account involved, and each split of the payment amount.

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

Surcharges

When your users pass on the costs of accepting payments to their customers, this is called a surcharge. You can use split instructions to define how to book the surcharge within your platform.

For more information, see Surcharge.

See also