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 building an implementation to collect and submit KYC information, redirect your sub-merchants to Adyen's Hosted Onboarding Page (HOP). When in HOP, sub-merchants can directly provide their KYC details. You then receive account updates and KYC verification results through notification webhooks.

HOP requires less development effort, making it the fastest way to implement KYC.

With HOP, you can:

  • Redirect sub-merchants to an Adyen-hosted page where they provide their KYC details.
  • Collect more information after sub-merchants complete the registration. For example, if a KYC check fails, sub-merchants can use HOP to provide the new information required from them.
  • Render the page in your sub-merchant's preferred language. HOP supports English, Brazilian Portuguese, Dutch, French, German, Italian, and Spanish.
  • Customize the page with your logo and platform name.

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 the accountHolderCode.

    In your request, you can also include optional parameters such as the URL where the sub-merchant 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 a sub-merchant with accountHolderCode AH0121-TimGreen with the page page rendered in Dutch:

    /getOnboardingUrl request
    {
      "{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 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
    {
      "invalidFields": [],
      "pspReference": "9115677600500127",
      "resultCode": "Success",
      "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

Change the page language

By default, an onboarding page is rendered in US English (en-US).

To change the language, the sub-merchant can select the language from the drop-down menu on the top the page, or you can also send the shopperLocale in your /getOnboardingUrl request.

Set the shopperLocale to any of the languages below. If the shopperLocale is specified in the request or if the language you sent in the request is not supported, the page uses the browser language. If the browser language is not supported, the page uses en-US by default.

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

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

  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

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

See also