Pesquisar

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 with your logo and platform name.
  • 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 https://cal-test.adyen.com/cal/services/Hop/v6/getOnboardingUrl \
-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": "https://your.return-url.com/?submerchant=123",
   "platformName" : "MyShop.com",
   "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": "https://hop-test.adyen.com/hop/view/?token=<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.

Customize your HOP

Change the page language

By default, an onboarding page is rendered in the language set in the browser settings. If the browser language is not supported, the page is rendered in en-US.

To change the language:

  • The account holder can select the language from the drop-down menu at the top of the page.
  • Alternatively, you can send the shopperLocale in your /getOnboardingUrl request. When the account holder opens the page, the page is automatically rendered in the language you specified.

    If the shopperLocale you specified is not supported, the page is rendered in the language set in the browser settings.

The following are the supported values for shopperLocale:

Language shopperlocale
Dutch nl-NL
English - US (default) en-US
French fr-FR
German de-DE
Italian it-IT
Portuguese pt-BR
Spanish es-ES

To add a logo, you need to have the Manage HOP settings role enabled for your Customer Area user. If you don't have the role, contact your Admin user.

You can add a customized logo shown on the onboarding page:

  1. Log in to your Customer Area and select Platform > Configure > Hosted Onboarding.
  2. Upload a logo for your onboarding page with the following image requirements:

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

To customize the name of your platform shown on the welcome page, specify the platformName in your /getOnboardingUrl request.

See also