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 in a separate API request, 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.

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 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. Each time 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 MarketPay 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 return URL functions as a fallback return URL in case none is included in the API request.

Step 1: Create an account holder and start the KYC process

  1. Make a POST /createAccountHolder request, specifying a unique accountHolderCode.

    {
        "accountHolderCode": "YourUniqueAccountHolderCode",
        "accountHolderDetails": {
            "address": {
                "country": "NL"
            },
            "individualDetails": {
                "name": {
                    "firstName": "YourName",
                    "gender": "UNKNOWN",
                    "lastName": "TestData"
                }
            },
            "email": "test@test.com"
        },
        "legalEntity": "Individual"
    }

    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 notification before applying any business logic. The notification confirms when the account holder 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 performing any business logic.

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

Step 2: Get the Hosted Onboarding Page URL

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. Maximum length of 500 characters. If you don't provide this in the request, the sub-merchant is redirected back to the default return URL configured in your platform account. If this is not provided in the request and no default return URL is configured, the request fails.

    {
      "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.

    {
      "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 HTPP 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 request for a new URL.

  2. As the sub-merchant provides KYC information, we send account updates through an ACCOUNT_HOLDER_UPDATED notification webhooks. Refer to the notifications so you can keep track of their progress.

  3. The sub-merchant is redirected back to your returnUrl with an HTTP GET if:

    • Their session expires (after 30 minutes).
    • They finish the onboarding process.

    When the sub-merchant is redirected back to your page, inform them of their onboarding progress based from the webhook notifications you received. For example, if the sub-merchant's session expired or they did not finish the onboarding process, repeat step 2 and request for a new URL 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 updates and results in an ACCOUNT_HOLDER_VERIFICATION notification.

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