Search

Are you looking for test card numbers?

Would you like to contact support?

Marketpay icon

Platforms quick start

Start accepting payments and making payouts to your sub-merchants.

Before you begin

Before you start using Adyen for Platforms, make sure that you have performed the following steps:

  1. Contact our Sales Support to make sure you're eligible for using Adyen for Platforms.
  2. Sign up for an Adyen test account at https://www.adyen.com/signup.
    You will get a web service user for performing KYC checks and making payouts.
  3. Create a payments web service user for processing payments. For the required steps, refer to How to get the web service (WS) user password.

For more information, refer to Getting started with Adyen.

Step 1: Sign up sub-merchants

For each sub-merchant, create a corresponding account holder, and one or more (if necessary) accounts.

To create an account holder, call /createAccountHolder, specifying:

  • firstName
  • lastName 
  • email
  • legalEntity (individual or business).

The above fields are required for an account holder to start accepting payments. To initiate the verification process required for the specific country, also include the address object with the country information.

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

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

When you create an account holder, by default we also create an account for this account holder. If you'd rather create accounts manually using the /createAccount endpoint, include in your /createAccountHolder request:

  • createDefaultAccount: false

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

You can either build your own onboarding implementation or use our Hosted Onboarding Page.

If you choose to build your own onboarding implementation, you have to collect the required information from your sub-merchant and send this information 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 a 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 platform should be split between a sub-merchant's account and your platform account. 

To do this, make a /payments call and pass split-specific fields. In the example below, paymentMethod and amount fields contain payment details, while split 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 platform commission (2.00 EUR).

{
   "reference":"marketpay-test-6426782037",
   "merchantAccount":"TestMerchant",
   "paymentMethod":{
      "type":"scheme",
      "number":"4111 1111 1111 1111",
      "expiryMonth":"10",
      "expiryYear":"2020",
      "holderName":"John Smith",
      "cvc":"737"
   },
   "amount":{
      "value": 6200,
      "currency":"EUR"
   },
   "splits":[
      {
        "amount":{
          "value": 6000,
          "currency":"EUR"
        },
        "type": "MarketPlace",
        "account":"151272963",
        "reference":"6124145",
        "description":"Porcelain Doll: Eliza (20cm)"
      },
      {
        "amount":{
          "value": 200,
          "currency":"EUR"
        },     
        "type":"Commission",
        "reference":"6124146"
      }
   ]
}

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

Step 4: Pay out sub-merchants

After an account holder successfully passes required KYC checks, you can initiate a payout to either their bank account or to a card eligible for payouts.

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"
}

You can also 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

All Platforms API create, update, and delete requests are asynchronous, so you must rely on notifications to know the final result of a request. To be aware of all the events that happen to your platform account, as well as get the results of KYC verification and other important changes, your system must be able to accept notifications.

You receive 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).

For more information, refer to Configure notifications and Notification types. You may also want to configure HMAC signing of notifications for additional verification. To do this, see Signing notifications with HMAC.

Create notification configuration request
{
  "configurationDetails":{
    "apiVersion": 5,
    "active": true,
    "description":"Your unique description",
    "eventConfigs":[
      {
        "eventType":"ACCOUNT_HOLDER_VERIFICATION",
        "includeMode":"INCLUDE"
      },
      {
      "eventType":"ACCOUNT_HOLDER_CREATED",
      "includeMode":"INCLUDE"
      }
    ],
    "notifyURL":"https://www.merchant-domain.com/notification-handler",
    "notifyUsername":"yourUsername",
    "notifyPassword":"yourPassword",
    "sslProtocol":"SSL"
  }
}

Next steps