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 don't 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 don't 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 thepspReference
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 thepspReference
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 whentype
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 BalanceAccountYour 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 authorizationpspReference
: 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.