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 as it requires less implementation effort on your side. You can customize a theme for your hosted onboarding page. You then need to create legal entities and account holders for your users and redirect them to your page where they provide their verification information directly to Adyen.
You can change the language of the page and control user settings.

If you are using hosted onboarding and just beginning your integration, use Legal Entity Management API v3 for your Legal Entity Management API requests. Otherwise, use Legal Entity Management API v2.

If your users need to sign PCI security questionnaires or accept Adyen's Terms of Service, these steps are included on the hosted onboarding page. You can configure the page settings to select the relevant PCI questionnaires for users to sign.

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

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

Before you begin

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.

Australia
Austria
Belgium
Bulgaria
Canada
Croatia
Cyprus
Czech Republic
Denmark
Estonia
Finland
France
Germany
Gibraltar
Greece
Guernsey
Hungary
Ireland
Isle of Man
Italy
Jersey
Latvia
Liechtenstein
Lithuania
Luxembourg
Malta
Monaco
Netherlands
Norway
Poland
Portugal
Romania
Slovakia
Slovenia
Spain
Sweden
Switzerland
United Kingdom (including Isle of Man & Jersey)
United States (including Puerto Rico)

The default language for the hosted onboarding page is English. You can change the language when creating a hosted onboarding link.

For some countries and legal entity types, your users can choose to instantly verify their bank account details in your hosted onboarding page. They are prompted to log into their online banking environment and confirm their account details. Their bank account is then verified within seconds without them needing to provide a bank statement.

This feature is currently only available for the following countries and legal entity types.

Country Individuals Organizations
Austria -white_check_mark-
Belgium -white_check_mark-
Canada -white_check_mark- -white_check_mark-
Denmark -white_check_mark-
Estonia -white_check_mark-
Finland -white_check_mark-
France -white_check_mark- -white_check_mark-
Germany -white_check_mark- -white_check_mark-
Ireland -white_check_mark-
Italy -white_check_mark-
Latvia -white_check_mark-
Lithuania -white_check_mark-
Netherlands -white_check_mark- -white_check_mark-
Norway -white_check_mark-
Portugal -white_check_mark- -white_check_mark-
Poland -white_check_mark- -white_check_mark-
Spain -white_check_mark-
Sweden -white_check_mark- -white_check_mark-
United Kingdom -white_check_mark- -white_check_mark-
United States -white_check_mark- -white_check_mark-

To test the instant bank verification flow, in your test environment select the test account for your specified country. Enter the corresponding user name and password.

Instant bank verification testing

Country Test account User name Password
Canada Demo Bank asd asd
Belgium Tink Demo Bank u51613239 cty440
Denmark Tink Demo Bank u51613239 cty440
Estonia Tink Demo Bank u91902655 jtx720
Finland Tink Demo Bank u80628915 puv375
France Tink Demo Bank u98563939 ene512
Germany Tink Demo Bank u98235448 cdz248
Italy Tink Demo Bank u51613239 cty440
Latvia Tink Demo Bank u91902655 jtx720
Lithuania Tink Demo Bank u91902655 jtx720
Netherlands Tink Demo Bank u48874162 idz429
Norway Tink Demo Bank u26049657 mip544
Poland Tink Demo Bank u51613239 cty440
Portugal Tink Demo Bank u51613239 cty440
Spain Tink Demo Bank u82144157 ymm529
Sweden Tink Demo Bank u27678322 vrh343
United Kingdom Tink Demo Bank u30315772 ndg370
United States Demo Bank asd asd

Step 1: Set up webhooks

Before you start collecting the required information from users, we recommend that you configure your system to accept our webhooks. Webhooks keep you updated on the progress of your users' verification process, merchant account and capability status changes, notify you of errors and contain instructions on how resolve them. Webhooks are crucial for a successful integration with Adyen, and the only way you'll receive automatic updates.

For instructions on how to configure webhooks, see Webhooks.

A legal entity resource holds information required for the verification checks. You first need to create a legal entity for the user that has a contractual relationship with your platform. You may also need to create legal entities to represent entities associated to the main user.

For sole proprietorships, the legal entity of the individual owner is the main legal entity. You need to first create an individual legal entity and then a legal entity for the sole proprietorship. You will associate them in a later step.

Select a tab below to create different types of legal entities:

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.

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

Step 3: 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 a user 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. For sole proprietorships, this is the individual legal entity ID of the owner.
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.

The response returns the new accountHolder resource, identified by its unique id. The response also includes a capabilities array. This shows the capabilities that are assigned to the account holder automatically based on how your platform was configured during the design phase. To add a specific capability for an account holder, you need to request an additional capability.

The user that holds a contractual relationship with your platform is the main legal entity. You also need to create legal entities for other entities associated with this user and link them to the main legal entity.

For example:

  • If the main legal entity conducting business with your platform is an organization, then the legal entities of the ultimate beneficial owners (UBOs) of the organization must be linked to the legal entity of the organization.
  • If the legal entity conducting business with your platform is an sole proprietorship, then the legal entity of the individual owner is the main legal entity. This must be linked to the legal entity representing the sole proprietorship.

The example below shows how you can associate a sole proprietorship with the individual owner.

Update the legal entity of the individual by making a PATCH /legalEntities/{id} request, specifying the entityAssociations array.

The array must include:

  • legalEntityId: Unique identifier of the sole proprietorship legal entity being associated.
  • type: Set to soleProprietorship.

When updating the entityAssociations, note that a PATCH request replaces the whole array. If you only want to update one array item, make sure you include all existing items along with the specific change in your request.

The response contains the updated legal entity resource, identified by its unique id.

When you create a hosted onboarding link, use the legal entity ID of the organization as a path parameter.

Users associating legal arrangements in the hosted onboarding page

For users that operate as a sole proprietor, they must select My sole trader name for the name of the account holder for their bank account. This ensures that their individual legal entity is linked to the legal entity of the sole proprietorship.

Step 5 (Conditional): Create business lines

If you have a platform setup (including payment facilitators), Adyen also requires information about the legal entity's line of business, such as their industry, source of funds, and sales channels.

To submit the details of your user's business line information for a platform setup, make a POST /businessLinesrequest specifying the following:

Parameter Required Description
capability -white_check_mark- The capability for which you are creating the business line.
industryCode -white_check_mark- The industry code.
legalEntityId -white_check_mark- The unique identifier of the legal entity that has a contractual relationship with your platform. For example, for an individual who has a sole proprietorship business, this must be the legal entity ID of the individual owner.
salesChannels -white_check_mark- Array of channels in which your user sells goods or services.
Possible values: eCommerce, ecomMoto, pos, posMoto, and payByLink. Sales channels may have different PCI DSS requirements. We recommend that you be familiar with these requirements before creating business lines for your user.
webData Required when salesChannel is eCommerce. The user's web address or the app store URL.

In the response, you receive the id of the business line. You will use this ID to create stores and add payment methods.

Step 6 (Conditional): Create stores

Creating stores is required only if you have a platform setup.

Stores are linked to the legal entity of your user through business lines. Stores ensure that payments are processed in a compliant manner and each processed transaction has an accurate payer statement. You must create separate stores for point-of-sale and ecommerce payments.

For every payment processed through your user's store, you can split the funds between the balance accounts in your platform, including your liable balance account. You can split funds manually for each payment, or you can add a split configuration profile to your user's store to automatically split all payments processed through that store.

Before you begin

Before you create a store, you must:

  • Have access to API credentials for the Management API and the Management API-Stores read and write role to create the store.
  • Collect from your user the address and phone number of the store, and the name of the store that will appear on the bank and credit card statements of shoppers.
  • Know the merchant account ID and the business lines that the store will be associated with.

Create a store

  1. To create a store, make a POST /stores, specifying:

    Parameter Required Description
    address -white_check_mark- An object that contains:
    • city: the city of the store.
    • country: the country of the store.
    • line1 line2 line3: up to three lines can be used for the street name, street number, and other information. Only the first line is mandatory.
    • postalCode: the postal code of the store.
    • stateOrProvince: Required only for the United States. The state or province of the store as defined in ISO 3166-2. For example, IL in the United States.
    description -white_check_mark- A description for the store.
    businessLineIds An array that contains business line IDs. Required if you have a platform setup. Must be part of the same legal entity as the merchant account. If not specified, the business line of the merchant account is used. Required when there are multiple business lines under the merchant account.
    merchantId -white_check_mark- The merchant account ID.
    phoneNumber -white_check_mark- The complete phone number of the store, beginning with + and the country code.
    reference A reference to recognize the store by. Allowed characters: Lowercase and uppercase letters without diacritics, numbers 0 through 9, hyphen (-), and underscore (_).
    If you do not provide a reference in your POST request, it is populated with the Adyen-generated id.
    shopperStatement -white_check_mark- The store name shown on the shopper's bank or credit card statement and the shopper receipt. Maximum length: 22 characters. Cannot be all numerals.

    You can also make a POST request to /merchants/{merchantId}/stores using the same parameters. In that case you do not need to include the merchant account ID in the request body.

    The following example shows how to create a store:

  1. In the response, note that this includes the Adyen-generated id for the store. You can use this as a path parameter to update the store.

    You will need to use the store reference when making a /payments or /paymentMethods request. For more information, see route a payment to a store.

  1. After you create a store, you must add payment methods to the store. To manage a store, such as update a store's details, see manage stores.

In-person payments

If you are offering in-person payments, you need to order, assign, and configure terminals. Follow the Terminal API integration checklist.

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

If you have a platform setup, before you create a hosted onboarding link for your user, you must configure the page settings to select the relevant PCI questionnaires for them to sign.
If you do not need to add payment methods for your user yet, you can skip these actions and create the hosted onboarding link.

Make a POST /legalEntities/{id}/onboardingLinks request using the main legal entity ID as a path parameter. For sole proprietorships, this is the individual legal entity ID of the owner.

You can customize your page by optionally including the following parameters in the request body. If you only send {} and do not include any parameters in your request, 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 by clicking the button on the screen.
locale The language that will be used for the page.
settings An array containing configuration options for the hosted onboarding page.

The following example shows how you can create a hosted onboarding link. The page will appear in Dutch and the user will not able to change the legal entity type that they signed up with to your platform.

Step 8: 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.

Reduce security risks

To reduce risks:

  • Make the link available only from your own secure environment and only to the user. For example, show the link or button inside their account overview or another page in your UI that is only accessible to them. Note that embedding Hosted Onboarding as an iframe in your environment is not a supported option.
  • If you are using a redirectUrl to redirect your user back to your environment, make sure that this URL cannot be easily tampered with. For example, do not use a URL on a system that is publicly accessible. Automatically validate the host part of the URL before including it in your API request.

Step 9: Get the verification results

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

If you are using a staggered verification process, Adyen informs you when an account holder is moved to a higher tier and what data they need to provide. After the data is verified by Adyen, their payouts are enabled again.

The webhook and the API response provides the status of the verification: valid, invalid, or rejected.

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

Verification valid

When the checks are completed successfully, Adyen sends a balancePlatform.accountHolder.updated webhook with:

Verification invalid

When there are problems with the verification, Adyen sends a balancePlatform.accountHolder.updated webhook.

This section is for platforms that have completed their integration.

The webhook contains the following information:

  • verificationStatus: Set to invalid.
  • allowed: Set to false.
  • problems: Contains verificationErrors, subErrors, and remediatingActions arrays returned on the linked legal entity. If there are verification errors, you must resolve them.

To see any problems also returned on the transfer instrument resource, reach out to your Adyen contact to enable the feature. For example, if your users have multiple transfer instruments, this can help them identify the errors and on which transfer instrument they need to be resolved.

Verification rejected

When the verification is unsuccessful and the capability is rejected, for example due to fraudulent activity, Adyen sends a balancePlatform.accountHolder.updated webhook containing the following information:

If the capability is rejected, any errors cannot be resolved by updating data or uploading documents.

Step 10 (Conditional): Resolve verification errors

When the information provided by the user cannot be verified, they are prompted to correct their information or upload a document. If their session expires, you may need to generate a new hosted onboarding link and redirect the user to resolve the errors.


If you are using a staggered verification process, create a hosted onboarding link. When the account holder is redirected to the link, they are presented with a summary page where they can update their data. After the data is verified by Adyen, their payouts are enabled again.

Next steps