Hosted Onboarding Page

Simplify your implementation with an Adyen-hosted onboarding page.

This page is for classic Adyen for Platforms integrations. If you are just starting your implementation, refer to our new integration guide instead.

Send account holders to Adyen's Hosted Onboarding Page (HOP) where they provide additional information directly to Adyen. This is our recommended solution, because it requires less implementation effort on your side.

With HOP, you can:

Collect more information. For example, if the verification fails, account holders can use HOP to provide the new information required from them.
Render the page in your account holder's preferred language.
Customize the page's appearance in your Customer Area.
Customize the hosted onboarding user experience through the /getOnboardingUrl endpoint.
Receive account updates and verification results through notification webhooks.

How it works

Create an account holder and present a link or a button to start the verification process.
When the account holder selects the link or the button, provide Adyen with the account holder code and get a one-time HOP URL.
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 their 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.
Receive the verification results through notification webhooks.

Play the video to see a sample HOP session.

Requirements

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.
Decide whether to collect all required information once in the beginning, or later in stages as they become necessary.
- Upfront verification unlocks all payment processing and payouts, which means you only need to generate the HOP URL once to collect the necessary data.
- Staggered verification requires you generate a new onboarding URL to collect additional information from the account holder whenever the funds processed exceed their current processing tier.

Step 1: Create an account holder

Before you start the verification process, you must create an account holder, taking note of the accountHolderCode in the response.

After an account holder is created, they can immediately start processing payments.

Step 2: Get the HOP URL

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

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:

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.

Step 3: Handle the redirect

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.
Keep track of your account holder's onboarding progress based on the ACCOUNT_HOLDER_UPDATED notification webhooks you receive.
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 verification results

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

For more information, refer to verification results.

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 do not have the role, contact your Admin user.

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