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.
• Order flows where the payment is captured manually 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

In addition to the general requirements for in-person payments with an Adyen for Platforms integration, take into account the following information.

Limitations

To split payments when you manually capture them, take into account the following points:

• As mentioned in the introduction, we recommend to always include split instructions in your payment request, even when you intend to update these instructions in your capture request. This ensures that funds are booked correctly for payment methods that do not support delayed capture.

• Splitting payments at capture is only possible for payment methods that support separate capture. Most wallet payment methods do not support separate capture of in-person payments. Alipay and WeChat Pay are always captured immediately; these QR code wallets do not support delayed capture.

• When the capture amount differs from the original authorization amount, you must provide split instructions in your capture request. If you do not provide split instructions for such captures, then all funds are booked to your liable balance account.

• The split types Surcharge and Tip are not supported when you split a payment at capture.

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 to split the payment amount at the time of capture, when a customer pays for goods worth USD 80.00:

   • USD 76.00 is booked to your user's balance account as payment for the goods.
   • USD 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.

Track fund movements

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.

To track the status of the funds 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 payload of the balancePlatform.transfer.updated webhook, note that:
   • The event array includes all previous transfer events.
   • 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