Search

Are you looking for test card numbers?

Would you like to contact support?

Marketpay icon

Hosted Onboarding Page

Simplify your KYC implementation with an Adyen-hosted onboarding page.

Instead of collecting KYC information from your sub-merchants and sending this information to Adyen through an API call, redirect your sub-merchants to an Adyen-hosted onboarding page where they directly provide their KYC details. You then receive account updates and KYC verification results through notification webhooks.

Our Hosted Onboarding Page (HOP) solution requires less development effort, making it the fastest way to implement KYC. We also recommend using HOP if you require sub-merchants to provide more information after they complete the registration (for example, if one of the KYC checks failed). In the onboarding page, we'll ask your sub-merchants to provide only the new required information.

You can also customize HOP by providing a logo for your onboarding page.

To learn more about information required for the KYC process, refer to KYC verification checks.

How it works

  1. Create an account holder and present a link or a button to your sub-merchant to start the KYC process.

  2. When the sub-merchant selects the link or the button, provide Adyen with the account holder code and get a one-time HOP URL. The URL must be used within 15 seconds.

  3. Handle the redirect. After the sub-merchant is successfully redirected to the page, the session starts. The session is valid for 30 minutes. When the sub-merchant provides KYC information, we send account updates through notification webhooks.

    The sub-merchant is redirected back to your website after they finish providing their details or when the session expires.

  4. You receive the KYC verification results through notification webhooks.

Play the video to see a sample HOP session.

Before you begin

  1. Make sure that you already have the roles to use Platforms APIs. If you don't have the required roles yet, refer to our Quick start guide for more information.
  2. Configure notification webhooks to receive account updates and KYC verification results.
  3. Contact our Support Team to enable hosted onboarding and to provide a default return URL. The default return URL functions as a fallback.

Step 1: Create an account holder

To onboard your sub-merchant, create an Account Holder. The account holder represents your sub-merchant's entity. If the account holder already exists, proceed to Step 2.

For each account holder you create, provide a unique ID, accountHolderCode. This is the ID that you will use in the Platforms API whenever referencing the account holder.

The rest of the information needed to create an account holder is determined by their legalEntity: provide as Individual if onboarding a person or sole proprietor, or Business if onboarding a company.

To create an account holder for an individual or sole proprietor, the minimum information to collect is their name.firstName, name.lastName, and email. You also need to provide name.gender though if you do not want to request it from your sub-merchant, you can pass as UNKNOWN. Include the address object with the country information to initiate the verification process required for the specific country. Provide this information in the /createAccountHolder call.

When collecting your sub-merchant's name, make sure they register with your platform using the name shown on their Photo ID.

POST /createAccountHolder request
{
   "accountHolderCode":"YOUR_UNIQUE_ACCOUNT_HOLDER_CODE",
   "accountHolderDetails":{
      "address": {
        "country": "US"
      },
      "email":"tim@green.com",
      "individualDetails":{
         "name":{
            "firstName":"Tim",
            "gender":"MALE",
            "lastName":"Green"
         }
      }
   },
   "legalEntity":"Individual"
}
Response
{
   "invalidFields": [],
   "pspReference":"8815214563869136",
   "accountCode":"138215709",
   "accountHolderCode":"QklMTFlCT0IK",
   "legalEntity":"Individual",
   "accountHolderDetails":{
      "address":{
         "country":"US"
      },
      ...
   },
    "accountHolderStatus": {
      "status": "Active",
    ...
   },
   ...
}

You receive a response that may contain any of the following status codes:

  • HTTP 200: You can use the information returned in the API response, such as the accountCode, but you should wait for the ACCOUNT_HOLDER_CREATED notification before applying any business logic. The notification confirms when the resource has been added in our central database.
  • HTTP 202: The request has been acknowledged and added to the queue. Use the response to check and confirm the changes you made. Wait for the ACCOUNT_HOLDER_CREATED notification to confirm if the account holder has been successfully created before applying any business logic.

To create an account holder for a business, the minimum information to collect is their businessDetails.legalBusinessNamebusinessDetails.shareholders, and email.  Include an address object with country information to initiate the verification process required for the specific country.

Provide these values along with the unique accountHolderCode and legalEntity as Business in the /createAccountHolder call.

POST /createAccountHolder request
{
  "accountHolderCode": "YOUR_UNIQUE_ACCOUNT_HOLDER_CODE",
  "accountHolderDetails": {
    "address": {
        "country": "US"
    },
    "businessDetails": {
      "legalBusinessName": "Real Good Restaurant Inc.",
      "shareholders": [
        {
            "name": {
              "firstName": "Maria",
              "gender": "FEMALE",
              "lastName": "Green"
            },
            "address": {
              "country": "US"
            }
        }
      ]
    },
    "email": "maria@green.com"
  },
  "legalEntity": "Business"
}
Response
{
   "invalidFields": [],
   "pspReference":"8815214563869136",
   "accountCode":"138215709",
   "accountHolderCode":"QklMTFlCT0IK",
   "legalEntity":"Business",
   "accountHolderDetails":{
      "address":{
         "country":"US"
      },
      ...
   },
    "accountHolderStatus": {
      "status": "Active",
    ...
   },
   ...
}

You receive a response that can contain one of the following status codes:

  • HTTP 200: You can use the information returned in the API response, such as the accountCode, but you should wait for the ACCOUNT_HOLDER_CREATED before applying any business logic. The notification confirms when the resource has been added in our central database.
  • HTTP 202: The request has been acknowledged and added to the queue. Use the response to check and confirm the changes you made. Wait for the ACCOUNT_HOLDER_CREATED notification to confirm if the account holder has been successfully created. Get the corresponding accountCode from the notification.

Creating an account holder automatically creates an Account. The account's identifier is in the response as accountCode. Save the accountCode, this is the ID you will use to process the account holder's transactions.

An account holder can hold one or more accounts. The account is where all transactions are processed against. Refer to Account structure for more information.

Step 2: Start the KYC process and get the HOP URL

  1. After the account holder is created, present a link or a button to your sub-merchant prompting them to start the KYC process.

  2. When the sub-merchant selects the link or button, make a POST /getOnboardingUrl request, specifying:

    • accountHolderCode: The account holder code you provided when you created the account holder.
    • returnURL: Optional. The URL where the sub-merchant will be redirected back to after they complete the onboarding, or if their session expires. The URL should have a maximum length of 500 characters. If you don't provide the return URL in the request, the sub-merchant is redirected back to the default return URL configured in your platform account. If the return URL is not provided in the request and is also not configured in your platform account, the request fails.
    /getOnboardingUrl request
    {
      "accountHolderCode": "YourUniqueAccountHolderCode",
      "returnUrl": "https://your.return-url.com/?submerchant=123"
    }

    The response contains:

    • redirectURL: The page to where you should redirect your sub-merchant. This URL must be used within 15 seconds and can only be used once.
    • pspReference: The reference for this transaction. We recommend that you store this for troubleshooting purposes.
    /getOnboardingUrl response
    {
      "pspReference": "9115677600500127",
      "submittedAsync": "false",
      "redirectUrl": "https://hop-test.adyen.com/hop/view/?token=<token>"
    }

Step 3: Handle the redirect

  1. Redirect your sub-merchant to the redirectURL within 15 seconds after you received the response. When the sub-merchant is successfully redirected to a hosted onboarding page, the session starts. The session is valid for 30 minutes.

    The sub-merchant receives an HTTP 401 status code if:

    • The redirection did not occur within 15 seconds.
    • The sub-merchant refreshes or reloads the browser after the session has started.

    To resume the session, repeat Step 2 and get a new URL.

  2. Keep track of your sub-merchant's onboarding progress based on ACCOUNT_HOLDER_UPDATED notification webhooks you receive.

  3. When the sub-merchant is redirected back to your return URL, inform them of their onboarding progress based on the notification webhooks you received. For example, if the sub-merchant's session expired or they did not finish the onboarding process, repeat Step 2 to get a new URL and to resume the process. The information they provide is saved per section so the next session continues from the remaining, unsaved sections.

Step 4: Get the KYC verification results

You receive all the subsequent KYC verification results in ACCOUNT_HOLDER_VERIFICATION notification webhooks.

Make sure that you are receiving the notifications to keep your system in sync with ours.

Customize your HOP

You can customize the Hosted Onboarding Page for your marketplace. To do this:

  1. Make sure that you have the Manage HOP settings role enabled for your Customer Area user. If you don't have the role, contact your Admin user to enable it.
  2. Log in to your Customer Area and select Marketpay > Configure > Hosted Onboarding.
  3. Upload a logo for your onboarding page with the following image requirements:

    • Maximum size: 128 x 128 pixels
    • File types: JPG, JPEG, PNG, SVG
    • Maximum file size: 50KB

See also