Are you looking for test card numbers?

Would you like to contact support?

Marketpay icon

Hosted onboarding

Onboard users on your platform using an Adyen-hosted page.

Hosted onboarding is our recommended solution to collect the required information you need to onboard your users. You first create legal entities and account holders for your users. You can then customize a page and redirect your users there where they provide their verification information directly to Adyen. This requires less implementation effort from your side.

With hosted onboarding, you can:

Depending on the type of legal entity, the user sees a list of steps to enter the following required information:

Organization

Individual

To see the entire hosted onboarding flow, you can watch a video here:

Before you begin

Make sure that:

Availability

You can onboard the following legal entity types:

Supported countries

You can use hosted onboarding in the following countries where your users are operating.

Europe

Austria (AT)
Belgium (BE)
Czech Republic (CZ)
France (FR)
Germany (DE)
Italy (IT)
Netherlands (NL)
Norway (NO)
Poland (PL)
Portugal (PT)
Spain (ES)
Sweden (SE)
United Kingdom (including Isle of Man & Jersey) (UK)

North America

United States (including Puerto Rico) (US)

Supported languages

Hosted onboarding is available in the following languages.

  • Czech (cs)
  • Dutch (nl)
  • English (en)
  • French (fr)
  • German (de)
  • Italian (it)
  • Norwegian (no)
  • Polish (pl)
  • Portuguese (pt)
  • Spanish (es)
  • Swedish (sv)

The default language for the hosted onboarding page is English. The user can change the language using the dropdown menu in the top right corner.

Customize hosted onboarding themes

You can customize themes for your hosted onboarding page using different templates in your Balance Platform Customer Area.

  1. Log in to your Balance Platform Customer Area.
  2. Select Hosted onboarding.
  3. Select Add new from the dropdown menu.
  4. Add an optional description to identify the theme. If you do not add a description, the themeId is shown in the dropdown menu list.
  5. Add an optional brand logo. The file size limit is 5 MB.
  6. You can add other features for your theme that will appear on the hosted onboarding page. We recommend you use the following:

    Page name Url
    Support Your own support page
    Privacy statement Adyen privacy policy
    F.A.Q. Hosted onboarding FAQs
  7. Select Save.

Note that each theme has a unique themeId. You will need this when you create a hosted onboarding link.



A legal entity resource holds information required for the verification checks. You need to create a legal entity for the user that has a contractual relationship with your platform.

Select a tab below to create a legal entity for an organization or individual:

To create a legal entity for an organization, provide the following information in a POST /legalEntities request. Any additional information you provide will be prefilled for the user in the hosted onboarding page.

Parameter Required Description
type -white_check_mark- Set to organization.
organization -white_check_mark- Object that contains required information about the organization. The legalName and its country.

The following is an example of how to create a legal entity for a private company operating in the US.

Create organization legal entity
curl https://kyc-test.adyen.com/lem/v2/legalEntities \
-u "ws123456@Scope.BalancePlatform_YourBalancePlatform":"YourWsPassword" \
-H "content-type: application/json" \
-X POST \
-d '{
   "type":"organization",
   "organization":{
      "legalName":"Example Company",
      "registeredAddress":{
         "country":"US"
      }
   }
}'

The response returns the legalEntity resource for the organization, identified by its unique id.

Response
{
   "organization":{
      "legalName":"Example Company",
      "registeredAddress":{
         "country":"US"
      }
   },
   "type":"organization",
   "id":"LE322JV223222D5GDNBXRF3W2"
}

Step 2: Create account holders

An account holder resource holds the capabilities that your user can do in your platform, such as the capability to process split payments and pay out their funds to their bank accounts. Capabilities are requested for them by default. If you want them to have a capability that is not part of the default configuration, you need to request the specific capability. The verification process starts after you create an account holder.

To create an account holder, make a POST /accountHolders request specifying:

Parameter Required Description
legalEntityId -white_check_mark- The unique identifier of the account holder's corresponding legal entity.
balancePlatform The unique identifier of the balance platform. Required only if your API credentials has access to multiple balance platforms.
description A human-readable description for the account holder, which can be useful for your staff and support agents.

Here is an example of how you can create an account holder.

Create an account holder
curl https://balanceplatform-api-test.adyen.com/bcl/v2/accountHolders \
-H "x-api-key: YOUR_BALANCE_PLATFORM_API_KEY" \
-H "content-type: application/json" \
-d '{
  "{hint:Required if you have multiple balance platforms}balancePlatform{/hint}": "YOUR_BALANCE_PLATFORM_ACCOUNT",
  "{hint:Free-text field}description{/hint}":"S.Hopper - Staff 123",
  "{hint:Unique legal entity ID}legalEntityId{/hint}":"LE1249248458283"
}'

The response returns the new accountHolder resource, identified by its unique id. The response also includes a capabilities array. In most cases, default capabilities are configured for your platform during the design phase. To add a specific capability for an account holder, you need to request it.

Response
{
    "balancePlatform": "YOUR_BALANCE_PLATFORM_ACCOUNT",
    "description": "S.Hopper - Staff 123",
    "id": "AHA1B2C3D4E5F6G7H8I9J0",
    "status": "active",
    "legalEntityId":"LE959JV223222D5DL3T7HGJ86",
    "capabilities":{
      "receiveFromPlatformPayments":{
        "enabled":"true",
        "requested":"true",
        "allowed":"false",
        "verificationStatus":"pending"
     }
   }
}

Create your link in your Balance Platform Customer Area or by making a POST /onboardingLinks request.

Make a POST /onboardingLinks request using the legal entity ID as a path parameter. You can optionally include the following parameters in the request body. If you do not include any parameters, the default Adyen page is shown to the user.

Parameter Required Description
themeId The unique identifier of the theme.
redirectUrl The link to your platform where the user is redirected after completing hosted onboarding.
locale The language that will be used for the page, specified by a combination of two letter ISO 639-1 language and ISO 3166-1 alpha-2 country codes. If not specified in the request or if the language is not supported, the page uses the browser language. If the browser language is not supported, the page uses en-US by default.

The following language-country combinations are currently supported:

  • cs-CZ
  • de-DE
  • en-US
  • es-ES
  • fr-FR
  • it-IT
  • nl-NL
  • no-NO
  • pl-PL
  • pt-PT
  • sv-SE
"Hosted
{
    "url": "YOUR_HOSTED_ONBOARDING_LINK"
}

Step 4: Handle the redirect

Provide the link to the user. For example, in your UI, show them a link or button. When they select it, get the hosted onboarding link and redirect them to the page. You have 4 minutes to redirect them before the link expires. If the link expires, you must generate a new link. The link also expires if the user refreshes the page and their session will end.

Step 5: Get the verification results

To get updates about the verification status and results, you can:

The webhook and the API response provides the status of the verification. If the verification is unsuccessful, you must resolve the verification errors.

The webhook examples below show when the verification is successful and when the capability is not allowed because the verification is invalid.

When the checks have been completed and all are successful, Adyen sends a balancePlatform.accountHolder.updated webhook with:
balancePlatform.accountHolder.updated webhook - verification completed
{
  "environment" : "test",
  "type" : "balancePlatform.accountHolder.updated",
  "data" : {
    "balancePlatform" : "YOUR_BALANCE_PLATFORM",
    "date" : "2021-01-01T00:00:00+01:00",
    "accountHolder" : {
    "balancePlatform" : "YOUR_BALANCE_PLATFORM",
    "description" : "Test Account holder",
    "id" : "AH32272223222B5D3755J3C3C",
    "legalEntityId" : "LE322JC223222D5CR2PHBG46C",
    "capabilities" : {
       "receivePayments" : {
         "requested" : true,
         "requestedLevel" : "medium",
         "requestedSettings" : {},
         "allowed" : true,
         "allowedLevel" : "medium",
         "allowedSettings" : {
            "maxAmount: {
              "value": 75000,
              "currency": "EUR
            },
            "interval": "daily"
         },
         "enabled" : true,
         "verificationStatus": "valid"
       }
    }
  }
}
.

Step 6: Resolve verification errors (Conditional)

If the information provided by the user cannot be verified or additional information is required, you need to generate a new hosted onboarding link and redirect the user to resolve the errors.

Next steps