API-only onboarding

To onboard users, you need to build your own UI where you collect data from your users and submit this data to Adyen. On this page, we explain how you can onboard and verify your users using the Legal Entity Management API and the Configuration API.

Once your users are onboarded with Adyen:

• You can create the corresponding account holder and balance accounts that will hold their funds within your platform.
• The verification process starts. As required by payment industry regulations, Adyen must verify your users before you can pay out their funds. The information that Adyen checks is based on the verification requirements.

Before you begin

Make sure that:

• You have API credentials for the Legal Entity Management API.
• You have reviewed the verification process and the required information for your users.

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.

Step 2: Identify country and collect required information

Create an onboarding flow and collect information from your users with your own UI. During the onboarding, you must collect the verification requirements from your users.

You can issue cards to organizations and sole proprietors operating in the EU, the UK, and the US. In addition to the minimum required information, you also need to provide the data below.

Step 3: Create legal entities

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 connected to the main user.

For example, for organizations you need to create legal entities for all individuals associated with the organization. We refer to these as ultimate beneficial owners (UBOs), directors, and signatories.

Make sure you collect the required information for each legal entity.

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:

Step 4: 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 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 response contains the updated legal entity resource, identified by its unique id.

Step 5: Create account holders

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. 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 balance platform was configured during the design phase. To add a specific capability for an account holder, you need to request an additional capability.

Next, you need to create a corresponding balance account to hold the account holder's funds.

Step 6: Create transfer instruments

Adyen must perform checks on the bank account where your user will receive their payouts. We refer to this bank account as a transfer instrument resource.

Collect the required information and provide this in a POST /transferInstruments request, specifying:

Parameter	Required	Description
type		Set to bankAccount.
legalEntityId		Unique identifier of the legal entity that has the contractual relationship with your platform and owns the bank account. For sole proprietorships, this is the legal entity ID of the individual owner.
bankAccount		Object that contains required information about the legal entity's bank account.

Here is an example request to add a transfer instrument for a bank account in the US:

The response returns the transferInstrument resource, identified by its unique id.

If we are not able to verify the bank account details, you will need to provide additional documents.

Step 7 (Conditional): Upload additional documents

Adyen attempts to verify the data that you provide. However, in some cases, the automatic verification might fail. This could be due to incorrect data or when the data can't be verified. In these cases, Adyen may ask you to provide additional documents.

For example, a remediating action code 1_301 indicates that you need to upload an ID document for the user.

To submit a document to Adyen:

1. Collect the document from the account holder.
2. Upload the document with a POST /documents request, specifying:

Parameter	Required	Description
attachments		Array that contains the document.
owner		Object that contains the owner.id of the resource that owns the document and the owner.type of resource. For type legalEntity, the id is the unique identifier of the legal entity. For type bankAccount, the id is the unique identifier of the transfer instrument.
type		The type of document that you can upload depends on the legal entity type. Refer to types for a full list.

Here is an example of how to upload an identity document for an individual:

The response returns the document resource, identified by its unique id.

After you successfully upload the additional documents, wait for Adyen to inform you of the verification results. Adyen validates documents asynchronously. On average, it takes about 30 seconds to validate a photo ID, and two days for registration documents and bank statements.

Getting the verification results

An account holder's ability to perform different actions in your platform such as withdrawing cash from ATMs depends on the results of the verification. We call these actions capabilities.

To view the results of the verification and the available capabilities, view the account holder details.