Processing payments

Learn how to split transactions with your sub-merchants.


After creating an account holder, you can immediately start processing payments on their behalf.

When a shopper pays on your marketplace, MarketPay gives you the ability to automatically split these funds between multiple accounts. By splitting payments, you can send the funds belonging to your sub-merchants to their accounts, and your marketplace fee to your Liable Account.

With every payment, capture, or refund you can customize the split between any number of accounts and amounts including your own Liable Account.

Supported payment methods

MarketPay supports most of the widespread payment methods, such as major card brands (Visa, Mastercard, Amex, Discover/Diners), Apple Pay, Google Pay, SEPA, iDEAL, Sofort, and more.

Providing split data

Split data defines how a payment is split. You can split a payment into any number of accounts.

Provide split data in the additionalData object. This object is present in all payment requests for any payment integration (e.g. /authorise and /payments endpoints).

Split data can also be provided when submitting a capture or refund request.

Split API uses dot notation with key-value pairs to provide information.

For each request, you will need to specify the split.api as 1, the amount of the transaction total in split.totalAmount, and the currency in split.currencyCode:

...
"additionalData": {
   "split.api":1,
   "split.totalAmount":40000,
   "split.currencyCode":"USD",
   ...
}

Provide the number of times you will split the payment in split.nrOfItems. Specify each split as an item followed by an incrementing number starting at 1: split.item1, split.item2, and so on.

Each split item will also need to include:

  • The amount to be split.
  • The split type. A type of MarketPlace sends the amount to the account specified. A split type of Commission sends the split to your liable account.
  • The account to send the split. This is the accountCode of one of your account holder's accounts or your own liable account.
  • An optional reference, this is returned in our reporting for that specific transaction split.

Transactions are split into accounts and not account holders.

Here is an example for splitting a 400.00 USD transaction:

  • 300.00 is being split into an account with accountCode of 163298747.
  • 100.00 being split into the platform's liable account.
 {
   ...
   "additionalData":{
      "split.api":"1",
      "split.nrOfItems":"2",
      "split.totalAmount":40000,
      "split.currencyCode":"USD",
      "split.item1.amount":30000,
      "split.item1.type":"MarketPlace",
      "split.item1.account":"163298747",
      "split.item1.reference":"QXhlbFN0b2x0ZW5iZXJnCg",
      "split.item2.amount":10000,
      "split.item2.type":"Commission",
      "split.item2.reference":"THVjYXNCbGVkc29lCg"
   },
   ...
}

Validating split information

Adyen frontend systems only validate the format of the split data. The accounts provided in split data will not be validated by frontend.

If you provide split data with an account that does not exist, or provide an account where it's account holder is not active, the full amount of the transaction will be sent to the liable account regardless of the original split data.

You will receive a PAYMENT_FAILURE notification of the failed split. You can use Fund transfer to correct any account balances.

Processing split payments

Test cards

To verify how your payment requests work, use test cards provided by Adyen.

For more information, see Test card numbers.

To split a payment,  provide split data as part of the payment request. All of Adyen's payment integrations support providing spit data in the  additionalData object. Split data can be used regardless of your  PCI level.

If you do not know what the total split will look like for your account holders at point of a payment, you can skip providing any split data at payment and instead provide split data at capture. Split data provided at capture will override any split data provided with the initial payment request.

Here is an example split provided with /payments call.

Request (POST /payments)
{
   "paymentMethod":{
      "type":"scheme",
      "number":"4400 0000 0000 0008",
      "expiryMonth":"10",
      "expiryYear":"2020",
      "holderName":"John Smith",
      "cvc":"737"
   },
   "amount":{
      "value":40000,
      "currency":"USD"
   },
   "reference":"YOUR_REFERENCE_NUMBER",
   "merchantAccount":"YOUR_MERCHANT_ACCOUNT",
   "returnUrl":"https://your-company.com/...",
   "additionalData":{
      "split.api":"1",
      "split.nrOfItems":"2",
      "split.totalAmount":40000,
      "split.currencyCode":"USD",
      "split.item1.amount":30000,
      "split.item1.type":"MarketPlace",
      "split.item1.account":"163298747",
      "split.item1.reference":"QXhlbFN0b2x0ZW5iZXJnCg",
      "split.item2.amount":10000,
      "split.item2.type":"Commission",
      "split.item2.reference":"THVjYXNCbGVkc29lCg"
   }
}

When using Checkout SDK, provide split data with the /paymentSession call.

Request (POST /paymentSession)
{
   "amount":{
      "value":40000,
      "currency":"USD"
   },
   "reference":"YOUR_REFERENCE_NUMBER",
   "merchantAccount":"YOUR_MERCHANT_ACCOUNT",
   "shopperReference":"yourShopperId_IOfW3k9G2PvXFu2j",
   "channel":"Android",
   "token":"TOKEN_YOU_GET_FROM_CHECKOUT_SDK",
   "returnUrl":"app://",
   "countryCode":"NL",
   "shopperLocale":"nl_NL",
   "sessionValidity":"2017-04-06T13:09:13Z",
   "additionalData":{
      "split.api":"1",
      "split.nrOfItems":"2",
      "split.totalAmount":"40000",
      "split.currencyCode":"USD",
      "split.item1.amount":"30000",
      "split.item1.type":"MarketPlace",
      "split.item1.account":"163298747",
      "split.item1.reference":"QXhlbFN0b2x0ZW5iZXJnCg",
      "split.item2.amount":"10000",
      "split.item2.type":"Commission",
      "split.item2.reference":"THVjYXNCbGVkc29lCg"
   }
}

Here is an example of split data provided with /authorise call.

Request (POST /authorise)
{
   "card":{
      "number":"4400 0000 0000 0008",
      "cvc":"737",
      "expiryMonth":"10",
      "expiryYear":"2020",
      "holderName":"John Smith"
   },
   "amount":{
      "value":40000,
      "currency":"USD"
   },
   "reference":"YOUR_REFERENCE_NUMBER",
   "merchantAccount":"YOUR_MERCHANT_ACCOUNT",
   "additionalData":{
      "split.api":"1",
      "split.nrOfItems":"2",
      "split.totalAmount":"40000",
      "split.currencyCode":"USD",
      "split.item1.amount":"30000",
      "split.item1.type":"MarketPlace",
      "split.item1.account":"163298747",
      "split.item1.reference":"QXhlbFN0b2x0ZW5iZXJnCg",
      "split.item2.amount":"10000",
      "split.item2.type":"Commission",
      "split.item2.reference":"THVjYXNCbGVkc29lCg"
   }
}

Payment statuses

Once a payment has reached the SentForSettle or SettledBulk state, the transaction will show up in the account as a PENDING_CREDIT transaction. Once Adyen has received the funds for the payment, the transaction will be updated to CREDITED and the funds will be available to payout on the account.

You can always look at the transaction associated to all accounts on a account holder using /accountHolderTransactionList call.

Split at capture

Providing a /capture request without split data will use the split data provided at payment authorisaiton. To capture the whole amount of the authorised payment, pass the pspReference from the /authorise response as an originalReference parameter. Also specify the referencemerchantReference, and modificationAmount parameters, as shown below.

The code below illustrates how to capture a split payment.

Request (POST /capture)
{
   "originalReference":"9914810184130051",
   "reference":"YOUR_REFERENCE_NUMBER",
   "merchantAccount":"YOUR_MERCHANT_ACCOUNT",
   "modificationAmount":{
      "value":40000,
      "currency":"USD"
   }
}

Some platforms do not know the final split at point of payment. In this case, you can provide split data with a /capture request. Providing split data at capture overrules the split data provided at payment authorisation.

Partial captures require you to supply split data. Not providing split data will cause all the fund to go to the liable account.

Request (POST /capture)
{
   "originalReference":"9914810184130051",
   "reference":"YOUR_REFERENCE_NUMBER",
   "merchantAccount":"YOUR_MERCHANT_ACCOUNT",
   "modificationAmount":{
      "value":599,
      "currency":"USD"
   },
   "additionalData":{
      "split.api":"1",
      "split.nrOfItems":"2",
      "split.totalAmount":"599",
      "split.currencyCode":"USD",
      "split.item1.amount":"399",
      "split.item1.type":"MarketPlace",
      "split.item1.account":"151272963",
      "split.item1.reference":"Partial capture #1",
      "split.item2.amount":"200",
      "split.item2.type":"MarketPlace",
      "split.item2.account":"181472818",
      "split.item2.reference":"Partial capture #2"
   }
} 

Split a refund

If you need to refund the entire payment amount, make a call to the /refund endpoint. In this call, pass the pspReference from the /authorise response as an originalReference parameter. Also specify the referencemerchantReference, and modificationAmount parameters, as shown below.

Request (POST /refund)
{
   "originalReference":"9914810184130051",
   "reference":"YOUR_REFERENCE_NUMBER",
   "merchantAccount":"YOUR_MERCHANT_ACCOUNT",
   "modificationAmount":{
      "value":40000,
      "currency":"USD"
   }
}

In addition, you can make a partial refund for only a part of the authorised amount. In this case, pass Split information as  additionalData, as shown in the example below.

Request (POST /refund)
{
   "originalReference":"9914810184130051",
   "reference":"YOUR_REFERENCE_NUMBER",
   "merchantAccount":"TestMerchant",
   "modificationAmount":{
      "value":599,
      "currency":"USD"
   },
   "additionalData":{
      "split.api":"1",
      "split.nrOfItems":"2",
      "split.totalAmount":"599",
      "split.currencyCode":"USD",
      "split.item1.amount":"399",
      "split.item1.type":"MarketPlace",
      "split.item1.account":"151272963",
      "split.item1.reference":"Partial refund #1",
      "split.item2.amount":"200",
      "split.item2.type":"MarketPlace",
      "split.item2.account":"181472818",
      "split.item2.reference":"Partial refund #2"
   }
}  

Chargeback and disputes

You are responsible for all disputes and dispute management. This includes providing first line support to your shoppers and sub-merchants, clearly communicating your contact details on your website or app, and managing all disputes between your shoppers and your sub-merchants.

Split chargebacks

Chargebacks, by default, deduct according to original split data. If you want to configure your platform to deduct entirely from your liable account instead, reach out the Support Team.

Partial chargebacks are deducted entirely from your liable account. You can use Fund transfer to correct any account balances.

Next steps

Fund transfer

Manually transfer funds to and from your sub-merchants.

step

Payouts

Make scheduled and one-off payouts to sub-merchants.

link