API-only onboarding

To onboard users on your platform, you need to build your own UI where you collect data from your users and submit this data to Adyen. You can onboard users operating in any of the supported countries. On this page, we explain how you can onboard and verify your users using the Legal Entity Management API.

Before you begin

Make sure that:

You have API credentials for the Legal Entity Management API and the Management API.

You have reviewed the verification process and the required information for your users.

Your server is properly configured to accept webhooks and you have subscribed to the Account data notifications in your Customer Area.

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: Associate legal entities

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

Step 3: 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 4: Create business lines

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

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.

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

Step 5: 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 6: Check security requirements

Because your users have a direct connection with card schemes, they must comply 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. To prove their compliance, they must sign a Self-Assessment Questionnaire (SAQ) before they can start processing card payments. The questionnaire asks them to confirm the security of their cardholder data environment, which typically includes their website, web servers, and employees who can access them.

Listen to webhooks to determine if your user needs to sign PCI questionnaires. You must generate the required secruity questionnaires and ask your user to sign them.

Step 7: Determine the terms of service

Your users must accept Adyen's Terms of Service before they can perform particular actions in your . The type of the Terms of Service agreement depends on your specific integration.

Listen to webhooks to determine if your user needs to accept the Terms of Service. You must generate the required agreement type and present it to your user, then ask them to accept it.

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

Resolve verification errors

If the webhook has a problems array, check remediatingActions. In this array, you'll find the actions that you can take to resolve the error, such as updating the data or uploading documents. Refer to verification error codes for a list of verification errors.

Let's say that the legal entity's name changed and now their data must be updated. To do this, send a PATCH /legalEntities/{id} request.

After you update the data, Adyen sends another webhook with the verificationStatus set to pending.

Once again, you will get updates about the status of the verification from the webhook or by making an API request.

Step 10 (Optional): Upload 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. Make sure your onboarding flow supports the collection of documents from users.

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.