Marketplace icon

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

Requirement Description
API credentials You must have credentials for the following API:
Webhooks Ensure that your server can receive and accept standard webhooks.
Subscribe to any of the following webhooks:
Limitations 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.

    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. In the General settings, next to Capture delay, select the edit icon .
    4. From the dropdown list, select Manual.
    5. Select Submit.
    6. Follow up each authorized 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 payment response or the AUTHORISATION webhook, 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 Required 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 Required 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 Required 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.
      • Remainder: books the amount left over after a currency conversion to the specified balance account.
      • You can also book different types of the transaction fees to different balance accounts.
      • 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.
      amount.currency Conditionally required Required for currency conversion
      The currency of the split amount.
      reference Conditionally required 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 marketplace'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 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 capture request:

    1. Listen to the following webhooks:
    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:

    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 a chargeback occurs on of your users' payments, 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