Adyen MarketPay quick start

This guide provides you with the steps to integrate your marketplace with the Adyen MarketPay system. After completing this tutorial, you will be able to start accepting payments and make payouts to your sub-merchants.

Prerequisites

Before you start using MarketPay services, make sure that you have performed the following steps:

  1. Sign up for an Adyen test account at https://www.adyen.com/signup and contact Support Team to enable MarketPay services for it. Adyen will provide you with credentials of a Marketplace web service user to connect to MarketPay API.
  2. Create a PSP web service user to accept payments. For the required steps, refer to How to get the web service (WS) user password.
  3. Depending on the type of your sub-merchants, there are a number of KYC checks that must be performed to verify them. Contact the Support Team to define required KYC checks for your test account.

For more information on prerequisite steps, refer to Getting started with Adyen.

Step 1 - Sign up sub-merchants

Provide information about your sub-merchants to the Adyen MarketPay system. For each sub-merchant, create a corresponding account holder and one or more accounts for it (where necessary).

To create an account holder, call /createAccountHolder, where you provide firstNamelastNameemail, and legalEntity (individual or business). These fields are required for an account holder to start accepting payments.

The following code illustrates how to create an individual account holder with the required fields only:

{
   "accountHolderCode":"TestAccountHolder5691",
   "accountHolderDetails":{  
      "email":"test@adyen.com",
      "individualDetails":{
         "name":{
            "firstName":"First name",
            "gender":"MALE",
            "lastName":"Last Name"
         }
      }
   },
   "createDefaultAccount":"true",
   "legalEntity":"Individual"
}

If the createDefaultAccount parameter is set to true (as shown above), MarketPay also creates an account for this account holder. Alternatively, you can set createDefaultAccount to false and manually create accounts using the /createAccount call.

Step 2 - Onboard sub-merchants

During the onboarding process, you need to collect additional information from your sub-merchants for KYC verification checks. Successful passing of these checks is required for sub-merchants to process payments at higher tiers and enable payouts

After a sub-merchant provides you with the required information, you can send it to Adyen using either the /updateAccountHolder or /uploadDocument API calls. 

The code below illustrates how to upload a passport using the /uploadDocument call. The image file, which contains the document, must be encoded as the Base64 string and assigned to the documentContent field, and the documentDetail object should contain an account holder code and other information about the document.

{
   "documentContent":"dGVzdCBkb2N1bWVudCBjb250ZW50",
   "documentDetail":{
      "accountHolderCode":"TestAccountHolder534055",
      "documentType":"PASSPORT",
      "filename":"passport.png",
      "description":"test passport description"
   }
}

Since KYC verification is usually performed asynchronously, its result is sent to your backend as a notification. To accept these notifications, configure them as described in Set up notifications.

Step 3 - Process payments

After creating account holders with the basic information, you can immediately start processing payments for them. In this case, the amount customers pay to your marketplace should be split between a sub-merchant's account and your marketplace account. 

To do this, make an /authorise call and pass split-specific fields as additional data. In the example below, card and amount fields contain payment details, while additionalData contains instructions on how to split a payment. In this case, 62.00 EUR will be split between an account holder's account (60.00 EUR) and your marketplace commission (2.00 EUR).

{
   "reference":"marketpay-test-6426782037",
   "merchantAccount":"TestMerchant",
   "card":{
      "number":"4111111111111111",
      "cvc":"737",
      "expiryMonth":"8",
      "expiryYear":"2018",
      "holderName":"John Smith"
   },
   "amount":{
      "value":6200,
      "currency":"EUR"
   },
   "additionalData":{
      "split.api":"1",
      "split.nrOfItems":"2",
      "split.totalAmount":"6200",
      "split.currencyCode":"EUR",
      "split.item1.amount":"6000",
      "split.item1.type":"MarketPlace",
      "split.item1.account":"151272963",
      "split.item1.reference":"6124145",
      "split.item1.description":"Porcelain Doll: Eliza (20cm)",
      "split.item2.amount":"200",
      "split.item2.type":"Commission",
      "split.item2.reference":"6124146"
   }
}

After a transaction has been successfully authorised, you must capture it for the payment to be settled. You can opt for automatic capture (contact Support Team) or make the /capture request manually. In addition, you can partially capture or refund the payment. For more information, refer to Process payments.

Step 4 - Pay out sub-merchants

After an account holder successfully passes required KYC checks, you can initiate a payout to this account holder.

For this, call /payoutAccountHolder as follows. In the example below, currency and value specify the amount to be paid out (997.92 EUR), accountCode and accountHolderCode uniquely identify the source account, while the bankAccountUUID specifies the bank account that receives the payout.

{
   "accountCode":"118731451",
   "amount":{
      "currency":"EUR",
      "value":99792
   },
   "accountHolderCode":"TestAccountHolder877209",
   "description":"12345 – Test",
   "bankAccountUUID":"000b81aa-ae7e-4492-aa7e-72b2129dce0c"
}

Alternatively, you can schedule a payout job to automatically make a payout (e.g. once per day). For more information, refer to Payouts.

Step 5 - Set up notifications

To be aware of all the events that happen to your marketplace account, as well as get the results of KYC verification and other important changes, your system must be able to accept notifications.

MarketPay sends these notifications as callbacks to the URLs you specify via the /createNotificationConfiguration call. In this case, we activate the ACCOUNT_HOLDER_VERIFICATION notification that should be sent to the endpoint on your server (https://www.merchant-domain.com/notification-handler) using the specified connection credentials (testUserName and testPassword).

{
   "configurationDetails":{
      "active":"true",
      "description":"Test notification769551",
      "eventConfigs":[
         {
            "NotificationEventConfiguration":{
               "eventType":"ACCOUNT_HOLDER_VERIFICATION",
               "includeMode":"INCLUDE"
            }
         }
      ],
      "messageFormat":"SOAP",
      "notifyURL":"https://www.merchant-domain.com/notification-handler",
      "notifyUsername":"testUserName",
      "notifyPassword":"testPassword",
      "sendActionHeader":"true",
      "sslProtocol":"SSL"
   }
}

For more information, refer to Configure notifications and Receive notifications.

Questions

Can't find something you are looking for? Look at our FAQ for answers or contact Support.