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.
Depending on the type of legal entity, the user sees a list of steps to enter the following required information:
- Company details
- Decision makers
- Payout details: the minimum information needed to process and pay out to the user's bank account.
To see an example of the entire hosted onboarding flow, you can watch a video here:
Hosted onboarding in Germany
Hosted onboarding in the US
Before you begin
Make sure that:
- You have API credentials for the Legal Entity Management API.
- You have the BalancePlatform Manage Hosted onboarding role in your Balance Platform Customer Area. Contact our Support Team to request this role.
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.
| Country | Organizations | Individuals | Sole proprietorships |
|---|---|---|---|
| Australia |  |
|
|
| Austria | |
|
|
| Belgium | |
|
|
| Bulgaria | |
|
|
| Canada | |
|
|
| Croatia | |
|
|
| Cyprus | |
|
|
| Czech Republic | |
|
|
| Denmark | |
|
|
| Estonia | |
|
|
| Finland | |
|
|
| France | |
|
|
| Germany | |
|
|
| Greece | |
|
|
| Hungary | |
|
|
| Ireland | |
|
|
| Italy | |
|
|
| Latvia | |
|
|
| Lithuania | |
|
|
| Luxembourg | |
|
|
| 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.
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.
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 | |
Set to organization. |
| organization | |
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.
curl https://kyc-test.adyen.com/lem/v3/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.
Step 2 (Conditional): Associate legal entities
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. For example, if the main legal entity conducting business with your platform is an sole proprietorship, then the legal entity of the individual owner must be linked to the legal entity of the sole proprietorship.
To associate legal entities, update the main legal entity by making a PATCH /legalEntities/{id} request, specifying the entityAssociations array.
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 example below show how you can associate a sole proprietorship to the individual owner.
Update the legal entity of the individual by making a PATCH /legalEntities/{id} request.
The array must include:
- legalEntityId: Unique identifier of the sole proprietorship legal entity being associated.
- type: Set to soleProprietorship.
curl https://kyc-test.adyen.com/lem/v3/legalEntities/LE00000000000000000000001 \
-u "ws123456@Scope.BalancePlatform_YourBalancePlatform":"YourWsPassword" \
-H "content-type: application/json" \
-X PATCH \
-d '{
"entityAssociations": [
{
"legalEntityId": "LE00000000000000000000002",
"type": "soleProprietorship"
}
]
}'The response contains the updated legalEntity resource, identified by its unique id. When you create a hosted onboarding link, use the legal entity ID of the individual owner as a path parameter.
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 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 | |
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.
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}":"Test Account holder",
"{hint:Unique legal entity ID}legalEntityId{/hint}":"LE00000000000000000000001"
}'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.
{
"balancePlatform":"YOUR_BALANCE_PLATFORM_ACCOUNT",
"capabilities":{
"receiveFromBalanceAccount":{
"allowed": false,
"enabled": true,
"requested": true,
"verificationStatus":"pending"
},
"receiveFromPlatformPayments":{
"allowed": false,
"enabled": true,
"requested": true,
"verificationStatus": "pending"
},
"sendToBalanceAccount":{
"allowed": false,
"enabled": true,
"requested": true,
"verificationStatus":"pending"
},
"sendToTransferInstrument":{
"allowed": false,
"enabled": true,
"requested": true,
"verificationStatus":"pending"
}
},
"description":"Test Account holder",
"id":"AH00000000000000000000001",
"legalEntityId":"LE00000000000000000000001",
"reference":"YOUR_INTERNAL_IDENTIFIER",
"status":"active"
}Step 4 (Conditional): Create business lines
For additional financial products, such as business bank accounts, or to configure a platform setup,
Adyen also requires information about the legal entity's line of business, such as their industry, source of funds, and sales channels.
| Parameter | Required | Description |
|---|---|---|
| service | |
The service for which you are creating the business line. Set this to paymentProcessing. |
| 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. |
| 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. |
curl https://kyc-test.adyen.com/lem/v3/businessLines \
-u "ws123456@Scope.BalancePlatform_YourBalancePlatform":"YourWsPassword" \
-H "content-type: application/json" \
-X POST \
-d '{
"service": "paymentProcessing",
"industryCode": "339E",
"salesChannels": [
"eCommerce",
"ecomMoto"
],
"legalEntityId": "LE322JV223222D5FZ9N74BSGM",
"webData": [
{
"webAddress": "https://yoururl.com"
}
]
}'id of the business line. You will use this ID to create stores and add payment methods..Step 5: Create hosted onboarding link
Create your link in your Balance Platform Customer Area or by making a POST /legalEntities/{id}/onboardingLinks request.
Make a POST /legalEntities/{id}/onboardingLinks request using the legal entity ID as a path parameter. 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.
curl https://kyc-test.adyen.com/lem/v3/legalEntities/{id}/onboardingLinks \
-u "ws123456@Scope.BalancePlatform_YourBalancePlatform":"YourWsPassword" \
-H "content-type: application/json" \
-X POST \
-d '{
"themeId":"YOUR_THEME",
"redirectUrl":"https://your.return-url.com/",
"locale":"nl-NL",
"settings":{
"changeLegalEntityType":false
}
}'Step 6: 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 7: Get the verification results
To get updates about the verification status and results, you can:
- Listen to balancePlatform.accountHolder.updated webhooks.
- Make a GET /accountHolders/{id} request.
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, when the capability is not allowed because the verification is invalid, and when the capability is rejected.
- verificationStatus: Set to valid.
- allowed: Set to true.
{
"data":{
"accountHolder":{
"capabilities":{
"sendToTransferInstrument":{
"allowed":"true",
"enabled":"true",
"requested":"true",
"verificationStatus":"valid"
}
},
"description":"Test Account holder",
"id":"AH00000000000000000000001",
"legalEntityId":"LE00000000000000000000001",
"reference":"YOUR_INTERNAL_IDENTIFIER",
"status":"active"
},
"balancePlatform":"YOUR_BALANCE_PLATFORM"
},
"environment":"test",
"type":"balancePlatform.accountHolder.updated"
}Step 8 (Conditional): 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.
