Custom onboarding

We recommend that you use the Hosted Onboarding Page, because it requires less implementation effort on your side and account holders can send the necessary information directly to Adyen. However, it is also possible to build your own onboarding flow. If you choose to build your own onboarding implementation, you need to set up a way to collect data from your account holder to pass the verification checks required by Adyen.

Your onboarding process must follow these main steps:

1. Create an account holder.
2. Update the account holder with additional details, depending on the verification check you are trying to pass.
3. Keep track of the verification results through notification webhooks.
4. Upload additional documents if necessary.

Before you begin

1. Before you start the verification process, you must decide whether to collect all required information once in the beginning, or later in stages as they become necessary.

   • Upfront verification unlocks all payment processing and payouts tiers. It requires you to collect all necessary data at the beginning of the onboarding flow.
   • Staggered verification requires you to collect additional information from the account holder whenever the funds processed exceed their current processing tier.

2. Get the verification requirements based on the country and legal entity type.

Step 1: Create an account holder

Before you start the verification process, you must create an account holder, taking note of the accountHolderCode in the response.

After an account holder is created, they can immediately start processing payments.

Step 2: Update the account holder

When the account holder starts processing a larger volume of funds than what their current processing tier allows, they automatically advance to higher processing tier. This triggers additional verification checks.

If you have chosen the upfront verification approach, the verification checks run automatically without any request for additional information from you, unlocking higher payout tiers when necessary. Adyen sends an ACCOUNT_HOLDER_VERIFICATION notification webhook to your server containing the status of the verification checks.

If you have chosen the staggered verification method or if the previously collected data is missing or invalid, payouts will be disabled and Adyen sends an ACCOUNT_HOLDER_STATUS_CHANGE notification. You need to ask the account holder for more information at this point. The information that Adyen requires from the account holder depends on their legal entity type.

1. Listen to the ACCOUNT_HOLDER_UPDATED and ACCOUNT_HOLDER_VERIFICATION notifications to learn what information you need to collect from your account holder.
2. Collect the information and provide the data in a POST /updateAccountHolder call.

The following example shows how to provide the full address of an existing account holder.

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_UPDATED notification webhook before performing any business logic. The notification webhooks confirm when the resources have been updated in 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_UPDATED notification webhook to confirm if the account holder has been successfully updated.

For each verification check that did not pass, the account holder needs to provide information within a deadline. After you send the information to Adyen and the verification is successful, we will re-enable payouts in a higher tier and update the verification check status to PASSED.

Step 3: Get the verification results

You receive all the subsequent verification results in ACCOUNT_HOLDER_VERIFICATION notification webhooks.

For more information, refer to verification results.

Step 4: Upload documents

Additional documents, such as a passport, bank statement, or a business registration document, may be required by some countries or regions to verify the account holder's identity, or if the automatic verification of the provided information fails.

For example, in the EU, we may require photo identification (such as passport) of your account holders. If the account holder's identity can't be validated, the photo ID verification is used as the ultimate verification.

Once you have collected the required document, submit the document to Adyen. To do this, make a POST /uploadDocument request with the following:

• documentContent: The document in base64-encoded string format.
• documentDetail.accountHolderCode: The code of the account holder that owns the document.

• documentDetail.documentType: The corresponding type of document.

  documentType	Description
  BANK_STATEMENT	Bank statement or other document proving ownership of a specific bank account.
  COMPANY_REGISTRATION_SCREENING	A company registration document. Supported from v5 and later.
  CONSTITUTIONAL_DOCUMENT	A document containing information about the account holder's legal arrangement.
  PASSPORT	The identity page(s) of a passport.
  DRIVING_LICENCE_FRONT	The front of a driver's licence. When provided, the DRIVING_LICENCE_BACK is also required.
  DRIVING_LICENCE_BACK	The back of a driver's licence. When provided, the DRIVING_LICENCE_FRONT is also required.
  ID_CARD_FRONT	The front of a government-issued ID card. When this is provided, the ID_CARD_FRONT is also required.
  ID_CARD_BACK	The back of a government-issued ID card. When this is provided, the ID_CARD_FRONT is also required.

The following example shows how to upload a scan of a passport.

Adyen validates documents asynchronously. On average, it takes Adyen about 30 seconds to validate a photo ID, and two days for registration documents and bank statements.

See also