After the split configuration is applied to your user's store, all payments processed through the store are split automatically according to the defined split logic. If you need to create a new rule, or adjust the rules, conditions, or split logic applied to payments, you can do so at any time using the Management API.
You can modify the following details of a split configuration:
- Create a new rule.
- Update rule conditions.
- Update the split logic in a rule.
- Update the description of the configuration.
Before you begin
Before you modify a split configuration, make sure that:
- Your Management API 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, rule, or split logic). You can use the GET /merchants/{merchantId}/splitConfigurations endpoint to retrieve this information.
Create a split configuration rule
You can define new rules to split payments automatically, even after the split configuration is created and applied to a store.
To add a rule to an existing split configuration, 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 | ![]() |
You must define whether the rule applies to a specific sales channel, or all channels. |
currency | ![]() |
You must define whether the rule applies to a specific currency, or all currencies. |
paymentMethod | ![]() |
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 | ![]() |
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 | ![]() |
You must define from which balance account to deduct the transaction fees. Possible values:
|
splitLogic.chargeback | You can define the chargeback logic. Possible values:
|
|
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:
|
|
splitLogic.surcharge | You can define the logic to apply when booking surcharges. Possible values:
|
|
splitLogic.tip | You can define the logic to apply when booking tips. Possible values:
|
The following example shows how you can add a new rule to existing configuration.
The response returns the full details of the updated split configuration, 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 | ![]() |
The unique identifier of your merchant account. |
splitConfigurationId | ![]() |
The unique identifier of the split configuration you want to update. |
ruleId | ![]() |
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 | ![]() |
You must define whether the rule applies to a specific sales channel, or all channels. |
currency | ![]() |
You must define whether the rule applies to a specific currency, or all currencies. |
paymentMethod | ![]() |
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 split configuration is applied to a payment.
The response returns the full details of the updated split configuration, including the updated rule conditions.
Update the split logic
You can change the way a payment is split 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 parameters:
Path parameters | Required | Description |
---|---|---|
merchantId | ![]() |
The unique identifier of your merchant account. |
splitConfigurationId | ![]() |
The unique identifier of the split configuration you want to update. |
ruleId | ![]() |
The unique identifier of the rule whose split logic you want to update. |
splitLogicId | ![]() |
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 | ![]() |
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. |
paymentFee | ![]() |
You must define from which the balance account to deduct the transaction fees. Possible values:
|
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:
|
|
remainder | You can define the logic to apply when booking the leftover amount (after currency conversion). Possible values:
|
|
surcharge | You can define the logic to apply when booking surcharges. Possible values:
|
|
tip | You can define the logic to apply when booking tips. Possible values:
|
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
To update the description of a split configuration, 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.