Hosted onboarding

Hosted onboarding requires limited implementation effort on your side. You must first create legal entities and merchant accounts for your users, then generate a link to redirect them to the hosted onboarding page. On this page, they can provide information required for the verification process directly to Adyen.

With hosted onboarding, you can:

• Create a customized theme for the page.
• Present the page to users in different languages.

Before you begin

Make sure that:

• You have API credentials for the Legal Entity Management API and the Management API.
• You have the Merchant Manage Hosted Onboarding role in your Customer Area. Contact our Support Team to request this role.
• Your server is properly configured to accept webhooks and you have subscribed to the Account data notifications in your Customer Area.

Supported countries

You can use Essentials to onboard your users if they operate in the following countries:

Country	Organizations	Sole proprietors
Australia (beta)
Austria
Belgium
Cyprus
Czech Republic
Denmark
Estonia
Finland
France
Germany
Greece
Hungary
Ireland
Italy
Latvia
Lithuania
Luxembourg
Netherlands
Poland
Portugal
Romania
Singapore (beta)
Slovakia
Slovenia
Spain
Switzerland
United Kingdom (including Isle of Man & Jersey)
United States

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

Customize onboarding page

You can customize the theme of your onboarding page using different templates in your live Customer Area. If you do not customize the theme, the onboarding page will show Adyen's logo by default.

You must have the Merchant Manage Hosted Onboarding role to customize themes.

To create an onboarding theme:

1. Log in to your live 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 list.

5. Add an optional brand logo. The file size limit is 5 MB in a PDF or JPG file.

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.	Onboarding FAQs

7. Select Save.

Each theme has a unique id. You will need this when you create a hosted onboarding link.

Step 1: Create legal entities

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, and the individuals representing that entity.

Select a tab below to create a legal entity for your user:

Step 2 (Optional): Associate legal entities for sole proprietorships

You must associate the individual legal entity representing the sole proprietor with the sole proprietorship legal entity.

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.

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

Step 3: Create business lines

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

Parameter	Required	Description
capability		The capability for which you are creating the business line.
industryCode		The industry code.
legalEntityId		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		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 store and add payment methods.

Step 4: Create merchant account

Your user's payments are processed in sub-accounts of your company account, called merchant accounts. The merchant account is where they receive the payout of funds, as well as the reports used for reconciliation. It is also where you can configure their payment methods, processing currencies, and override risk management rules set at company level.

To create a merchant account, make a POST /merchants call, specifying:

Parameter	Required	Description
businessLineId		The unique identifier of your user's business line.
companyId		The unique identifier of your company account.
legalEntityId		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.
pricingPlan		The previously agreed pricing plan for the merchant account. Your Adyen contact will provide the values that you can use.
reference		Your reference for the merchant account. If your company account has a template, then the reference is required and must be unique within the company account.
description		Your description for the merchant account.
salesChannels		The list of sales channels of your user's business line(s).

In the response, you receive the id of the merchant account. You will need to use this ID to create stores and to activate your user's account.

Step 5 (Optional): Create stores

If your user wants to accept in-person payments, you must create a store in their merchant account. A store ensures that the processed transactions correspond to an accurate payer statement.

Stores are linked to the legal entity of your user through business lines. To create a store, you first need to 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 customers.

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

Parameter	Required	Description
address		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		A description for the store.
merchantId		The merchant account ID.
phoneNumber		The complete phone number of the store, beginning with + and the country code.
reference		A unique 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		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:

The response includes the Adyen-generated id for the store.

Step 6: Create hosted onboarding link

To create a link to the hosted onboarding page, make a POST /legalEntities/{id}/onboardingLinks request, using the main legal entity ID as a path parameter.

You can optionally include 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 your 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, 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.
settings		An array containing configuration options for the hosted onboarding page.

By default, the following settings are set to true. Set to false to not allow the action.

• changeLegalEntityType: The user can change their legal entity type.
• editPrefilledCountry: The user can change the country of their legal entity's address, for example the registered address of an organization.

By default, the following settings are set to false. Set to true to allow the action.

• allowIntraRegionCrossBorderPayout: The user can select a payout account in a different EU/EEA country than the country of their legal entity.
• allowBankAccountFormatSelection: The user can select the format for their payout account if applicable.

Your user must sign PCI questionnaires for all of their relevant salesChannels. By default, these value are set to false. Set each of the following values to true to require the user to sign a PCI questionnaires for that sales channel type.

• requirePciSignEcommerce
• requirePciSignPos
• requirePciSignEcomMoto
• requirePciSignPosMoto

Supported languages

The following languages are currently supported.

Language	Locale
Czech	cs-CZ
Dutch	nl-NL
Estonian	et-EE
English	en-US
Finnish	fi-FI
French	fr-FR
German	de-DE
Greek	el-GR
Hungarian	hu-HU
Italian	it-IT
Latvian	lv-LV
Lithuanian	lt-LT
Polish	pl-PL
Portuguese	pt-PT
Slovakian	sk-SK
Slovenian	sl-SI
Spanish	es-ES
Swedish	sv-SE

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

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.

Besides providing the required information about their company and its representative, your users are also asked to sign the services agreement and a security questionnaire. By signing the security questionnaire, they provide their compliance with the requirements laid down in the Payment Card Industry Data Security Standards (PCI DSS) for collecting, processing, storing, and transmitting cardholder data in a secure environment.

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 8: Get the verification results

To get updates about the verification status and results, listen to the merchant.updated webhook.

The merchant.updated webhook 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.

Step 9: Resolve verification errors

If 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.