Split payments at capture

Learn how to split a transaction at the time of 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.

To split a payment at the time of capture, first you must enable manual captures, then follow up with a /payments/{paymentPspReference}/captures API call containing the split instructions. You can also override the split instructions you provided in the payment request if you send different split instructions in your capture request. If you do not send any split instructions in your capture request, we use the split instructions from the payment authorization.

We recommend to always include split instructions in your payment request, even when you intend to update these instructions in your capture request.

Restrictions

When you split at capture, you must take into account:

Splitting payments at capture is only possible for payment methods that support separate captures.
When using payment methods that do not support delayed captures, the funds may not be booked correctly unless the split instructions are provided in the payment request.
You must always provide split instructions in your capture request when the capture amount varies from the original authorization amount. 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.

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.

All payments in your merchant account:
To manually capture all point-of-sale payments processed through your merchant account, you can enable manual capture for your merchant account through the Customer Area. In this case, you must follow up each authorized Terminal API payment with a POST /payments/{paymentPspReference}/captures API call.
Specific payment:
To enable manual capture for a specific payment, you must add a manual capture flag to each payment request that you want to capture manually, and then 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:

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

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

EUR 396.00 are booked to your user's balance account as payment for the goods.
EUR 4.00 are 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.

Check the result

API response

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

Webhook

Wait for the CAPTURE webhook to learn the outcome of the request.

Additional split instructions

The above example shows you how to:

Book the sale amount to your user's balance account (using type BalanceAccount.
Book all the transaction fees to your user's balance account (using type PaymentFee).
Book the commission to your liable balance account (using type Commission).

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.

Validating split instructions

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.