Marketpay icon

Manage split configuration profiles

Learn how to update or remove a split configuration profile.

After a split configuration profile is applied to your user's store, all transactions processed through the store are automatically split according to the defined split logic. If you need to add a new rule, or adjust the rules, conditions, or split logic applied to the transactions, you can do so at any time in your Customer Area, or using the Management API.

You can modify the following details of a split configuration profile:

Before you begin

  • If you are using the Management API, make sure that:
    • Your credential has the Management API - SplitConfiguration read and write role.
    • You have at hand the IDs of the resources you want to update (split configuration profile, rule, or split logic). You can use the GET /merchants/{merchantId}/splitConfigurations endpoint to retrieve this information.
  • If you want to manage split configuration profiles in your Customer Area, you must have the Manage new split configuration settings role.

Add a rule

You can define new rules for splitting transactions automatically, even after the split configuration profile has been created and applied to a store.

To add a rule to an existing split configuration profile, make a POST /merchants/{merchantId}/splitConfigurations/{splitConfigurationId} request, specifying the merchantId and splitConfigurationId in the path.

In the body of the request, include the following fields:

Parameter Required Description
shopperInteraction -white_check_mark- You must define whether the rule applies to a specific sales channel, or all channels.
currency -white_check_mark- You must define whether the rule applies to a specific currency, or all currencies.
paymentMethod -white_check_mark- You must define whether the rule applies to a specific payment method, or all payment methods associated with the store.
fundingSource You can define whether the rule applies to only credit or debit, or all transactions.
splitLogic.commission -white_check_mark- You must define the commission fee for the payments. This can be a fixed amount (specified in minor units), a percentage (specified in basis points), or both.
splitLogic.paymentFee -white_check_mark- You must define from which balance account to deduct the transaction fees.

Possible values:
  • deductFromLiableAccount: deducts the transaction fees from your platform's liable balance account.
  • deductFromOneBalanceAccount: deducts the transaction fees from one of your user's balance accounts, which you specify when you update your user's store.
splitLogic.chargeback You can define the chargeback logic.

Possible values:
  • deductFromLiableAccount: books the entire disputed amount against your platform's liable balance account.
  • deductFromOneBalanceAccount: books the entire disputed amount from one of your user's balance accounts, which you specify when you update your user's store.
  • deductAccordingToSplitRatio: splits the disputed amount between the balance accounts in the original payment, using the same split ratio used in the original payment.
splitLogic.additionalCommission You can define an additional fee as a commission for your user. This can be a fixed amount (specified in minor units), a percentage (specified in basis points), or both. The specified amount and/or percentage is booked directly to your user's balance account.
splitLogic.remainder You can define the logic to apply when booking the leftover amount (after currency conversion).

Possible values:
  • addToLiableAccount: books the remainder against your platform's liable balance account.
  • addToOneBalanceAccount: books the remainder against one of your user's balance accounts, which you specify when you update your user's store.
splitLogic.surcharge You can define the logic to apply when booking surcharges.

Possible values:
  • addToLiableAccount: books the surcharge amount to your platform's liable balance account.
  • addToOneBalanceAccount: books the surcharge amount to one of your user's balance accounts, which you specify when you update your user's store.
splitLogic.tip You can define the logic to apply when booking tips.

Possible values:
  • addToLiableAccount: books the tip to your platform's liable balance account.
  • addToOneBalanceAccount: books the tip to one of your user's balance accounts, which you specify when you update your user's store.

The following example shows how you can add a new rule to existing profile.

The response returns the full details of the updated split configuration profile, including the ruleId of the new rule in the rules array.

Update rule conditions

You can update the conditions that determine whether the payment is split automatically by modifying the rule.

To change the conditions of a rule, make a PATCH /merchants/{merchantId}/splitConfigurations/{splitConfigurationId}/rules/{ruleId} request, specifying the following parameters:

Path parameters Required Description
merchantId -white_check_mark- The unique identifier of your merchant account.
splitConfigurationId -white_check_mark- The unique identifier of the split configuration you want to update.
ruleId -white_check_mark- The unique identifier of the rule whose conditions you want to update.

In the body of the request, include the following fields:

Parameter Required Description
shopperInteraction -white_check_mark- You must define whether the rule applies to a specific sales channel, or all channels.
currency -white_check_mark- You must define whether the rule applies to a specific currency, or all currencies.
paymentMethod -white_check_mark- You must define whether the rule applies to a specific payment method, or all payment methods associated with the store.
fundingSource You can define whether the rule applies to only credit or debit, or all transactions.

You must send all conditions in the request, not only the ones you want to update.

The following example shows how you can change the conditions that define whether the payment is split according to the logic defined in the split configuration profile.

The response returns the full details of the updated split configuration profile, including the updated rule conditions.

Update the split logic

You can change the way a payment is split between the balance accounts of your platform by modifying the split logic of the rule.

To change the split logic used in a rule, make a PATCH /merchants/{merchantId}/splitConfigurations/{splitConfigurationId}/rules/{ruleId}/splitLogic/{splitLogicId} request, specifying the following path parameters:

Path parameters Required Description
merchantId -white_check_mark- The unique identifier of your merchant account.
splitConfigurationId -white_check_mark- The unique identifier of the split configuration profile you want to update.
ruleId -white_check_mark- The unique identifier of the rule whose split logic you want to update.
splitLogicId -white_check_mark- The unique identifier of the split logic object you want to update.

In the body of the request, include the following fields:

Parameter Required Description
commission -white_check_mark- You must define your platform's commission fee for the payments. This can be a fixed amount (specified in minor units), a percentage (specified in basis points), or both.
paymentFee -white_check_mark- You must define from which the balance account to deduct the transaction fees.

Possible values:
  • deductFromLiableAccount: deducts the transaction fees from your platform's liable balance account.
  • deductFromOneBalanceAccount: deducts the transaction fees from one of your user's balance accounts, which you can specify when you update your user's store.
additionalCommission You can define an additional fee as a commission for your user. This can be a fixed amount (specified in minor units), a percentage (specified in basis points), or both. The specified amount and/or percentage is booked directly to your user's balance account.
chargeback You can define the chargeback logic.

Possible values:
  • deductFromLiableAccount: books the entire disputed amount against your platform's liable balance account.
  • deductFromOneBalanceAccount: books the entire disputed amount from one of your user's balance accounts, which you can specify when you update your user's store.
  • deductAccordingToSplitRatio: splits the disputed amount between the balance accounts of the original payment, according to same split ratio.
remainder You can define the logic to apply when booking the leftover amount (after currency conversion).

Possible values:
  • addToLiableAccount: books the remainder against your platform's liable balance account.
  • addToOneBalanceAccount: books the remainder against one of your user's balance accounts, which you can specify when you update your user's store.
surcharge You can define the logic to apply when booking surcharges.

Possible values:
  • addToLiableAccount: books the surcharge amount to your platform's liable balance account.
  • addToOneBalanceAccount: books the surcharge amount to one of your user's balance accounts, which you can specify when you update your user's store.
tip You can define the logic to apply when booking tips.

Possible values:
  • addToLiableAccount: books the tip to your platform's liable balance account.
  • addToOneBalanceAccount: books the tip to one of your user's balance accounts, which you can specify when you update your user's store.

You must send all split logic items in the request, not only the ones you want to update.

The following example shows how you can change the way payments are split if they meet the conditions of the split configuration rule.

The response returns the full details of the updated split configuration, including the new splitLogic object containing the updated logic to apply.

Update the description

You can only update the description of a split configuration profile by using the Management API.

To update the description of a profile, make a PATCH /merchants/{merchantId}/splitConfigurations/{splitConfigurationId} request, specifying the merchantId and splitConfigurationId in the path, and the new description in the body.

The response returns the full details of the updated split configuration, including the updated description.

Delete a rule

All split configuration profiles must contain at least one rule. Therefore, deleting the only rule in the profile is not possible. In this case, you must delete the whole configuration profile.

To delete a rule, make a DELETE /merchants/{merchantId}/splitConfigurations/{splitConfigurationId}/rules/{ruleId} request, specifying the merchantId, splitConfigurationId, and ruleId in the path.

The response returns the full details of the updated split configuration, including all remaining rules.

Delete a profile

To delete a split configuration profile, make a DELETE /merchants/{merchantId}/splitConfigurations/{splitConfigurationId} request, specifying the merchantId and splitConfigurationId in the path.