Manage split configuration profiles

Using the Management API, you can view and update the following details of your split configuration profiles:

• Get a list of all your split configuration profiles or the details of a specific profile.
• Add a rule to or remove a rule from a profile.
• Change the description, conditions, or split logic of a rule.
• Delete a profile.

Requirements

Get a list of all profiles

To get the details of all split configuration profiles in your merchant account, make a GET /merchants/{merchantId}/splitConfigurations request with the ID of your merchant account in the path.

The response contains the array of split configuration profiles in your merchant account.

Get profile details

To get the details of a specific split configuration profile, make a GET /merchants/{merchantId}/splitConfigurations/{splitConfigurationId} request with the ID of your merchant account and the profile in the path.

The response contains the array of rules, conditions, and split instructions in the profile.

Add a rule

To add a rule to an existing split configuration profile, make a POST /merchants/{merchantId}/splitConfigurations/{splitConfigurationId} request with the ID of your merchant account and the profile in the path.

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

Parameter	Required	Description
currency		Define whether the rule applies to a specific currency, or all currencies.
paymentMethod		Define whether the rule applies to a specific payment method, or all payment methods associated with the store. You can differentiate between payment method variants as well, for example, configure different instructions for visagold and visasignature.
fundingSource		Define whether the rule applies only to payments initiated a specific type of card, or all card types.
shopperInteraction		Define whether the rule applies to a specific sales channel, or all channels.
splitLogic		Define the split logic that is applied if the rule conditions are met. For instructions, see Optional configuration.
splitLogic.commission		Define your platform's commission for the payments. This can be a fixed amount, a percentage, or both.
splitLogic.additionalCommission		Define an additional fee as a commission for your user, booked directly to your user's balance account. This can be a fixed amount, a percentage, or both.

Optional configuration

Based on which optional parameters you include in the splitLogic object, you can define to which balance account to book:

• The different types of transaction fees associated with the payment.
• Potential refunds, chargebacks, and their associated fees.
• The remaining amount after currency conversion for online payments.
• The tips and surcharges for in-person payments.

You can define any or all of these parameters in the splitLogic object of the split configuration profile.

Book transaction fees

To book the transaction fees associated with the payment to different balance accounts, you must include at least one of the following parameters in the splitLogic object:

Parameter	Required	Description	Limitation
paymentFee		Required if you don't send any other fee type. Define to which balance account to book the aggregated amount of all transaction fees associated with the payment.	Cannot be combined with any other fee type.
adyenFees		Required if you send aquiringFees. Define to which balance account to book the aggregated amount of Adyen's Commission and Markup for the payment.	Cannot be combined with fee types on a different level: paymentFee, interchange, schemeFee, adyenCommission, or adyenMarkup.
acquiringFees		Required if you send adyenFees. Define to which balance account to book the aggregated amount of the Interchange and Scheme fees associated with the payment.	Cannot be combined with fee types on a different level: paymentFee, interchange, schemeFee, adyenCommission, or adyenMarkup.
adyenCommission		Required if you send interchange, schemeFee, or adyenMarkup. Define to which balance account to book the Adyen's commission for the payment.	Cannot be combined with fee types on a different level: paymentFee, adyenFees, or aquiringFees.
adyenMarkup		Required if you send interchange, schemeFee, or adyenCommission. Define to which balance account to book the Adyen's markup for the payment.	Cannot be combined with fee types on a different level: paymentFee, adyenFees, or aquiringFees.
interchange		Required if you sendschemeFee, adyenCommission, or adyenMarkup. Define to which balance account to book the Interchange associated with the payment.	Cannot be combined with fee types on a different level: paymentFee, adyenFees, or aquiringFees.
schemeFee		Required if you sendinterchange, adyenCommission, or adyenMarkup. Define to which balance account to book the Scheme fees associated with the payment.	Cannot be combined with fee types on a different level: paymentFee, adyenFees, or aquiringFees.

You can send the following combinations in the splitLogic array:

• paymentFee
• aquiringFees and adyenFees
• interchange, schemeFee, adyenCommission, and adyenMarkup

For example, to create a split configuration profile that books the Interchange and Scheme fees to the user's balance account, and every other fee type to your platform's liable balance account, send the following request:

The response returns the following resources:

• splitConfigurationId: The unique identifier of the split configuration profile.
• ruleId: The unique identifier of the split configuration rule.
• splitLogicId: The unique identifier of the split instructions that are applied when the predefined conditions are met.

You will need these IDs when you want to change the details of the split configuration profile.

Book refunds and chargebacks

To define the split instructions for potential refunds, chargebacks, and the fees incurred by them, you can include the following parameters in the splitLogic object.

Parameter	Required	Description
refund		Define the refund logic. You can book the entire refund amount to your platform's liable balance account, your user's balance account, or split the refund amount between the balance accounts specified in the original payment (with the same split ratio). Required if you want set refundCostAllocation.
refundCostAllocation		Define to which balance account to book the fees incurred by the refund.
chargeback		Define the chargeback logic. You can book the entire disputed amount to your platform's liable balance account, your user's balance account, or split the disputed amount between the balance accounts specified in the original payment (with the same split ratio). Required if you want set chargebackCostAllocation.
chargebackCostAllocation		Define to which balance account to book the fees incurred by the chargeback.

In the following example, we create a split configuration profile that books:

• The refund amount to your user's balance account.
• The fees incurred by refunds to your liable balance account.
• The chargeback amount according to the original payment's split ratio.
• The fees incurred by chargebacks to your liable balance account.

The response returns the following resources:

• splitConfigurationId: The unique identifier of the split configuration profile.
• ruleId: The unique identifier of the split configuration rule.
• splitLogicId: The unique identifier of the split instructions that are applied when the predefined conditions are met.

You will need these IDs when you want to change the details of the split configuration profile.

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.

Change the conditions

You can update the conditions that determine whether the payment is split automatically by modifying the rule in the profile. For more information on these conditions, see Rule conditions.

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

Path parameters	Required	Description
merchantId		The unique identifier of your merchant account.
splitConfigurationId		The unique identifier of the split configuration profile 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
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. You can differentiate between payment method variants as well, for example, configure different instructions for visagold and visasignature.
fundingSource		You must define whether the rule applies only to payments initiated by a specific type of card, or any card type.
shopperInteraction		You must define whether the rule applies to a specific sales channel, or all channels.

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

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

Change the split logic

You can change the way a transaction 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		The unique identifier of your merchant account.
splitConfigurationId		The unique identifier of the split configuration profile 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, a percentage, or both.
paymentFee or another transaction fee type		You must define to which balance account to book the transaction fees associated with the payment.
chargeback		You can define the chargeback logic. You can book the entire disputed amount to your platform's liable balance account, your user's balance account, or split the disputed amount between the balance accounts specified in the original payment (with the same split ratio).
chargebackCostAllocation		You can define to which balance account to book the fees incurred by chargebacks.
refund		You can define the refund logic. You can book the entire refund amount to your platform's liable balance account, your user's balance account, or split the refund amount between the balance accounts specified in the original payment (with the same split ratio).
refundCostAllocation		You can define to which balance account to book the fees incurred by the refund.
additionalCommission		You can define an additional fee as a commission for your user, booked directly to your user's balance account.
remainder		You can define to which balance account to book the amount left over after currency conversion.
surcharge		You can define to which balance account to book surcharges.
tip		You can define to which balance account to book the gratuity.

The following example shows how you can change the way payments are split if they meet the conditions of the split configuration rule. The previous split instruction was to apply an additional commission of a fixed amount of EUR 0.01 + 0.1%, and here we show how to change that into a commission of a fixed amount of EUR 1.00.

The response returns the whole profile, including the new splitLogic object that contains the updated instructions.

Change 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 with the ID of your merchant account and split configuration profile in the path, and the new description in the body.

The response returns the whole profile, including the updated description.

Remove a rule

All split configuration profiles must contain at least one rule. Therefore, deleting the only rule in the profile is not possible. If you want to remove a rule but keep the profile, make sure the profile contains at least one other rule. Otherwise, delete the whole profile.

To remove a rule, make a DELETE /merchants/{merchantId}/splitConfigurations/{splitConfigurationId}/rules/{ruleId} request with the ID of your merchant account, split configuration profile, and rule in the path.

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

Delete a profile

To delete a split configuration profile, make a DELETE /merchants/{merchantId}/splitConfigurations/{splitConfigurationId} request with the ID of your merchant account and split configuration profile in the path.

The response contains all details of the deleted profile.

See also