Are you looking for test card numbers?

Would you like to contact support?

Atenção, esta página não se encontra disponível em Português
Marketpay icon

Hosted Onboarding Page

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

Instead of building an implementation to collect and submit KYC information, redirect your account holders to Adyen's Hosted Onboarding Page (HOP). HOP requires less development effort, making it the fastest way to implement KYC verification checks.

With HOP, you can:

  • Redirect account holders to an Adyen-hosted page where they provide their information.
  • Collect more information after account holders complete the registration. For example, if a KYC check fails, account holders can use HOP to provide the new information required from them.
  • Render the page in your account holder's preferred language. HOP supports English, Brazilian Portuguese, Dutch, French, German, Italian, and Spanish.
  • Customize the page's appearance in your Customer Area.
  • Customize the hosted onboarding user experience through the /getOnboardingUrl endpoint.
  • Receive account updates and KYC verification results through notification webhooks.

How it works

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

  2. When the account holder selects the link or the button, provide Adyen with the account holder code and get a one-time HOP URL.

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

    The account holder is redirected back to your website after they finish providing their details or when the session expires.

  4. Receive the KYC verification results through notification webhooks.

Play the video to see a sample HOP session.

Before you begin

Contact our Support Team to:

  • Enable hosted onboarding for your platform.
  • Provide a default return URL. The default return URL takes the account holder back to your website.

Step 1: Start the KYC process

Before you can start the KYC process, you should already have created an account holder and have the accountHolderCode.

Next, present a link or a button to your account holder prompting them to start the KYC process.

Step 2: Get the HOP URL

When the account holder selects the link or button, make a POST /getOnboardingUrl request, specifying the accountHolderCode.

In your request, you can also include optional parameters such as the URL where the account holder will be redirected back to (returnURL), the language the page is rendered in (shopperLocale), and the name of the platform shown in the welcome page (platformName).

Here's an example of how you generate a HOP URL for an account holder with accountHolderCode AH0121-TimGreen with the page rendered in Dutch:

Generate a HOP URL
curl \
-H "x-API-key: YOUR_X-API-KEY" \
-H "content-type: application/json" \
-d '{
   "{hint:The unique account holder code}accountHolderCode{/hint}": "AH0121-TimGreen",
   "returnUrl": "",
   "platformName" : "",
   "shopperLocale": "nl-NL"

The response contains:

  • redirectURL: The page to where you should redirect your account holder. 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
  "invalidFields": [],
  "pspReference": "9115677600500127",
  "resultCode": "Success",
  "redirectUrl": "<token>"

Step 3: Handle the redirect

  1. Redirect the account holder to the redirectURL within 15 seconds after you received the response. When they are successfully redirected to a hosted onboarding page, the session starts. The session is valid for 30 minutes.

    The account holder receives an HTTP 401 status code if:

    • The redirection did not occur within 15 seconds.
    • The account holder refreshes or reloads the browser after the session has started.

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

  2. Keep track of your account holder's onboarding progress based on ACCOUNT_HOLDER_UPDATED notification webhooks you receive.

  3. When the account holder is redirected back to your return URL, inform them of their onboarding progress based on the notification webhooks you received. For example, if the account holder'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.

Access HOP on behalf of an account holder

After you generate a HOP link for an account holder, you can also access their HOP link. This is useful, for example, if an account holder is having issues updating their data or uploading documents.

To be able to view and access the HOP link, you must have the Manage HOP settings role enabled for your Customer Area user. If you don't have the role, contact your Admin user.

  1. Log in to your Customer Area.
  2. Go to Platform > Sub-merchants then select the account holder.
  3. In the account holder view, you can select the Hosted onboarding link shown next to the account holder code.

See also