Account holders and accounts

Start the onboarding process by creating an account holder. To create an account holder, you need to get the sub-merchant's legal entity type, collect the minimum required information, and send the information in an API request.

Once the account holder is created and active, you can start processing payments for them. However, to pay out their funds, they have to provide more information (such as their bank account details) and pass verification checks.

Step 1: Identify their legal entity type

When creating an account holder, you need to specify the sub-merchant's legal entity type. Their legal entity type determines the kind of information that Adyen requires for their verification checks.

An account holder can be one of the following legal entities: Individual, Business, Nonprofit, Partnership, or Public company.

If an account holder signs up using an incorrect legal entity type, you can change the legal entity.

Step 2: Collect the minimum required information

Collect the minimum required information from your sub-merchant depending on their legal entity type.

Step 3: Create an account holder

Submit the information that you collected with the /createAccountHolder endpoint. The fields that you need to include depend on their legal entity type.

Requests using /createAccountHolder are processed asynchronously. You'll receive a response to your API request, but you must wait for the webhooks to know the final result of a request.

The API response may contain any of the following HTTP status codes:

• HTTP 200: You can use the information that the API returns in the response, such as the accountCode, but you should wait for the ACCOUNT_HOLDER_CREATED and ACCOUNT_CREATED notification webhooks before performing any business logic. The notification webhooks confirm when the resources have been added to our central database.
• HTTP 202: The request has been acknowledged and added to the queue. Use the response to check and confirm the changes you made. Wait for the ACCOUNT_HOLDER_CREATED and ACCOUNT_CREATED notification webhooks to confirm if the account holder has been successfully created. Get the corresponding accountCode from the notification.

When an account holder is created, an account is also automatically created identified by the accountCode. Save the accountCode—this is the ID you will use to process the account holder's transactions.

The accountHolderStatus.status determines if processing payments and payouts are allowed. A newly created account holder has accountHolderStatus.status Active. This means that you can immediately start processing payments on their behalf. For more information, refer to account holder statuses.

Step 4: (Optional) Create additional accounts

You can optionally create additional accounts for an account holder. For example, create multiple accounts if an account holder has different business lines and would like to keep funds and accounting history separate for each line.

To create an additional account, make a /createAccount request and provide the accountHolderCode.

Requests using /createAccount are processed asynchronously. You'll receive a response to your API request, but you must wait for the webhooks to know the final result of a request.

The API response may contain any of the following HTTP status codes:

• HTTP 200: You can use the information that the API returns in the response, such as the accountCode, but you should wait for the ACCOUNT_CREATED notification webhook before performing any business logic. The notification confirms when the resources have been added to our central database.
• HTTP 202: The request has been acknowledged and added to the queue. Use the response to check and confirm the changes you made. Wait for the ACCOUNT_CREATED notification webhook to confirm if the account holder has been successfully created. Get the corresponding accountCode from the notification.