With every payment, capture, or refund on Adyen for Platforms, you can split the funds between any number of balance accounts in your platform, including your liable balance account. For example, when a customer pays, you can split the funds into two parts. One part goes to your liable balance account as your platform's fee, and the other part goes to your user's balance account as the sale amount.
To split funds, provide split information through API requests.
Supported payment methods
Adyen for Platforms supports a wide range of payment methods, such as major card brands (Visa, Mastercard, American Express, Discover/Diners) and local payment methods. Restrictions may apply where Adyen is not in the settlement flow. Reach out to your Adyen contact to find out about supported payment methods.
Providing split information through API requests
You can split funds as many times as you need and into any number of balance accounts in your platform, including your liable balance account.
You can provide split information:
- At the time of payment.
- When capturing a payment.
- When refunding a payment.
To split funds, add a splits array in your /payments, /captures or /refunds request. For each split object in the array, specify the following fields:
| Parameter | Required | Description |
|---|---|---|
| account |  |
The ID of the balance account to which the split amount will be sent. |
| amount.value | |
The value of the split amount. |
| reference | |
Your unique identifier for the split. While this field is only required in the API if type is BalanceAccount, we strongly recommend sending a reference for all other types. You can use the reference to reconcile the split and the associated payment in the transaction overview and in the reports. Without a reference, the amounts are merged and you will be unable to reconcile the split. |
| type | |
Set the type to BalanceAccount when sending the amount to other balance accounts in your platform. Other types such as Commission or VAT sends the split amount to your liable balance account. |
Here is an example of how you can split a payment when a customer pays for goods worth 400.00 USD.
- 396.00 USD goes to the seller as payment for the goods. You'll send the payment to the balance account ID BA00000000000000000000002 (this is the balance account of the seller).
- 4.00 USD goes to your liable balance account as your platform's commission.
Validating split information
Adyen front-end systems only validate the format of the split data. The balance accounts provided in split data are not validated by the front end.
Payments, captures, and refunds may succeed, but the funds are not split if the balance account specified in the request does not exist or is linked to an account holder with a closed status. When this happens, the full amount of the transaction is sent to your platform's liable balance account.
To correct balances, you can transfer funds between balance accounts in your platform.
Split at payment
To split funds at the time of payment, provide split data in your POST /payments request. You can send split data regardless of your PCI compliance level.
If you do not know the split amount at the time of payment, you can skip providing this at payment and provide split data at capture instead. Split data provided at capture overrides any split data provided with the initial payment request.
Below is an example of a payment request with split data.
# Set your X-API-KEY with the API key from the Customer Area.
curl https://checkout-test.adyen.com/v69/payments \
-H "x-API-key: YOUR_X-API-KEY" \
-H "content-type: application/json" \
-d '{
"paymentMethod": {
"type": "scheme",
"number": "4111111111111111",
"cvc": "737",
"expiryMonth": "03",
"expiryYear": "2030",
"holderName": "John Smith"
},
"amount": {
"value": 40000,
"currency": "USD"
},
"reference": "YOUR_ORDER_NUMBER",
"merchantAccount": "YOUR_MERCHANT_ACCOUNT",
"returnUrl": "https://your-company.com/...",
"splits":[
{
"amount":{
"value":39600
},
"type":"BalanceAccount",
"account":"BA00000000000000000000002",
"reference":"Your reference for the sale amount"
},
{
"amount":{
"value":400
},
"type":"Commission",
"reference":"Your reference for the commission"
}
]
}'Split at capture
Some platforms do not know the final split (or prefer not to decide this) at the point of payment. In this case, you can provide split data with a /payments/paymentPspReference/captures request. Note that you can only split at capture for payment methods that support separate captures. For example, you cannot split at capture for Sofort or iDEAL payments because these don't support separate captures.
Providing split data at capture overrules data from the original payment request. If you don't send split data in the capture request, then we'll use the split data from the payment authorisation.
Partial captures require you to supply split data. If you don't provide split data, then all the funds to go to the liable balance account.
# Set your X-API-KEY with the API key from the Customer Area.
curl https://checkout-test.adyen.com/v69/payments/{paymentPspReference}/captures \
-H "x-API-key: YOUR_X-API-KEY" \
-H "content-type: application/json" \
-d '{
"merchantAccount": "YOUR_MERCHANT_ACCOUNT",
"amount": {
"value": 599,
"currency": "EUR"
},
"reference": "YOUR_REFERENCE_NUMBER",
"splits":[
{
"amount":{
"value":399
},
"type":"BalanceAccount",
"account":"BA00000000000000000000003",
"reference":"Partial capture #1"
},
{
"amount":{
"value":200
},
"type":"BalanceAccount",
"account":"BA00000000000000000000002",
"reference":"Partial capture #2"
}
]
}'Handling transaction fees
Transaction fees refer to the costs you incur on a transaction in your platform, that are not known at the time of payment. They are calculated by Adyen after we receive the /payments request.
By default, these fees are deducted from your liable balance account. However, you can also book them directly to a balance account of your user. This is useful if you want to pass on the transaction fees to your user directly, instead of settling this later via a transfer of funds. You can charge the following fees directly to your user:
- Interchange
- Scheme Fees
- Acquirer Markup
- Blend Commission
Processing fees and discounts due to tiered pricing structures cannot be booked directly to the user’s balance account since these are aggregated amounts (inclusive of refused and cancelled transactions) and cannot be allocated to individual payments.
To pass transaction fees on to your user, submit a /payments request with an additional split item in the splits array, specifying the following fields:
| Parameter | Required | Description |
|---|---|---|
| account | |
The ID of the balance account from which the transaction fees should be deducted. |
| reference | |
Your reference for the fees to help you reconcile your balances later. |
| description | |
Your description for the fees to help you reconcile your balances later. |
| type | |
The type of split. Set this to PaymentFee. |
For example, a split payment of USD 400.00 can be split into two parts:
- USD 396.00 is the sale amount (booked to the user’s balance account: BA00000000000000000000001)
- USD 4.00 is your platform’s commission (booked to your liable balance account).
The fees incurred on this transaction can be booked directly to your user.
# Set your X-API-KEY with the API key from the Customer Area.
curl https://checkout-test.adyen.com/v69/payments \
-H "x-API-key: YOUR_X-API-KEY" \
-H "content-type: application/json" \
-d '{
"paymentMethod": {
"type": "scheme",
"number": "4111111111111111",
"cvc": "737",
"expiryMonth": "03",
"expiryYear": "2030",
"holderName": "John Smith"
},
"amount": {
"value": 40000,
"currency": "USD"
},
"reference": "YOUR_ORDER_NUMBER",
"merchantAccount": "YOUR_MERCHANT_ACCOUNT",
"returnUrl": "https://your-company.com/...",
"splits":[
{
"amount":{
"value":39600
},
"type":"BalanceAccount",
"account":"BA00000000000000000000001",
"reference":"Your reference for the sale amount",
"description": "Your description for the sale amount"
},
{
"amount":{
"value":400
},
"type":"Commission",
"reference":"Your reference for the commission",
"description": "Your description for the commission"
},
{
"account": "BA00000000000000000000001",
"reference": "Your reference for the fees",
"description": "Your description for the fees",
"type": "PaymentFee"
}
]
}'The transaction fees are calculated automatically, so even if you provide an amount for this split item, it will be disregarded. Once the calculations are done, an an internal transfer request is triggered to deduct these fees from the specified balance account. The transfer request includes the type of fee, the currency and the amount charged. You can find a breakdown of the fees on the Payment details page of the transaction in the Customer Area, and in the Balance Platform Accounting Report.
Split a refund
We recommend that you always provide split data in refunds so that you are always in control and can support different refund scenarios, such as partial and multiple partial refunds.
Send split data in your refund request to support different refund scenarios, such as a partial and multiple partial refunds.
When sending split data on a refund request, you must:
- Only use balance accounts that were part of the original split.
- Use the same
referencevalues from the original split.
For example, let's split a 10 USD payment with 2 USD going to your liable balance account and 8 USD going to account BA00000000000000000000003. The split data has reference values splitId_1 and splitId_1_commission.
Here is an example/payments request with a splits array.
# Set your X-API-KEY with the API key from the Customer Area.
curl https://checkout-test.adyen.com/v69/payments \
-H "x-API-key: YOUR_X-API-KEY" \
-H "content-type: application/json" \
-d '{
"paymentMethod":{
"type":"scheme",
"number":"4400 0000 0000 0008",
"expiryMonth":"10",
"expiryYear":"2020",
"holderName":"John Smith",
"cvc":"737"
},
"amount":{
"value":1000,
"currency":"USD"
},
"reference":"YOUR_REFERENCE_NUMBER",
"merchantAccount":"YOUR_MERCHANT_ACCOUNT",
"returnUrl":"https://your-company.com/...",
"splits":[
{
"amount":{
"value":200
},
"type":"Commission",
"reference":"splitId_1_commission"
},
{
"amount":{
"value":800
},
"type":"BalanceAccount",
"account":"BA00000000000000000000003",
"reference":"splitId_1"
}
]
}'The following example is the refund of the above payment if you split the refund with 5 USD from your liable balance account and 5 USD from account BA32272223222B5DHXHHG73VM. The refund must use the same reference values as the original split data in the payment request (splitId_1 and splitId_1_commission).
Here is an example /payments/paymentPspReference/refunds request where you provide the split data:
# Set your X-API-KEY with the API key from the Customer Area.
curl https://checkout-test.adyen.com/v69/payments/{paymentPspReference}/refunds \
-H "x-API-key: YOUR_X-API-KEY" \
-H "content-type: application/json" \
-d '{
"reference":"YOUR_REFERENCE_NUMBER",
"merchantAccount":"YOUR_MERCHANT_ACCOUNT",
"amount":{
"value":1000,
"currency":"USD"
},
"splits":[
{
"amount":{
"value":500
},
"type":"Commission",
"reference":"splitId_1_commission"
},
{
"amount":{
"value":500
},
"type":"BalanceAccount",
"account":"BA00000000000000000000003",
"reference":"splitId_1"
}
]
}'Chargeback and disputes
A chargeback occurs when a customer disputes a payment.
As a platform, you are responsible for all disputes and dispute management, including being the first line of support for your users and the customers of your platform. You must have your contact details on your website or app, and manage all disputes between your customers and your users.
Handling chargebacks
When a chargeback event occurs on your platform, you can choose how to credit or debit the disputed amount from or to your platform's balance accounts. You can also transfer funds between balance accounts in your platform to correct balances.
You can set up the methods to handle chargebacks on two levels:
- Balance platform level: Set a default method to handle all chargebacks. Contact our Support Team to configure a default method on balance platform level.
- Payment level: Set a method for each payment. The chargeback handling method you set at payment level overrides any default method set at balance platform level.
Methods to handle chargebacks
There are 3 methods by which you can handle all chargebacks events. You can book the disputed amount against:
The entire disputed amount is booked against your liable balance account. Adyen applies this method by default if you do not configure a method on the balance platform level or the payment level. The currency and amount do not need to match those of the original payment.
In case you configure another method as default for your platform, you can still choose to deduct from your liable account for each payment (payment level).
To configure this method on payment level, add a platformChargebackLogic object in your /payments request. Specify the following field:
| Parameter | Required | Description |
|---|---|---|
behavior |
|
The method of handling chargebacks. Set this to deductFromLiableAccount. |
# Set your X-API-KEY with the API key from the Customer Area.
curl https://checkout-test.adyen.com/v69/payments \
-H "x-API-key: YOUR_X-API-KEY" \
-H "content-type: application/json" \
-d '{
"amount": {
"currency": "USD",
"value": 10000
},
"merchantAccount": "YOUR_MERCHANT_ACCOUNT",
"paymentMethod": {
"cvc": "737",
"expiryMonth": "03",
"expiryYear": "2030",
"holderName": "John Smith",
"number": "4111111111111111",
"type": "scheme"
},
"reference": "YOUR_PAYMENT_REFERENCE",
"platformChargebackLogic": {
"behavior": "deductFromLiableAccount"
},
"splits": [
{
"account": "BA00000000000000000000001",
"amount": {
"value": 7000
},
"description": "YOUR_DESCRIPTION_1",
"reference": "YOUR_REFERENCE_1",
"type": "BalanceAccount"
},
{
"account": "BA00000000000000000000002",
"amount": {
"value": 2000
},
"description": "YOUR_DESCRIPTION_2",
"reference": "YOUR_REFERENCE_2",
"type": "BalanceAccount"
},
{
"account": "BA00000000000000000000003",
"amount": {
"value": 1000
},
"description": "YOUR_DESCRIPTION_3",
"reference": "YOUR_REFERENCE_3",
"type": "BalanceAccount"
}
]
}'