---
title: "Custom onboarding"
description: "Onboard your account holders and move them through the verification process."
url: "https://docs.adyen.com/classic-platforms/onboard-users/custom-onboarding"
source_url: "https://docs.adyen.com/classic-platforms/onboard-users/custom-onboarding.md"
canonical: "https://docs.adyen.com/classic-platforms/onboard-users/custom-onboarding"
last_modified: "2020-09-08T13:38:00+02:00"
language: "en"
---

# Custom onboarding

Onboard your account holders and move them through the verification process.

[View source](/classic-platforms/onboard-users/custom-onboarding.md)

This page is for classic Adyen for Platforms integrations. If you are just starting your implementation, refer to our [new integration guide](/adyen-for-platforms-model) instead.

We recommend that you use the [Hosted Onboarding Page](/classic-platforms/onboard-users/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.](#create-account-holder)
2. [Update the account holder](#update-account-holder) with additional details, depending on the verification check you are trying to pass.
3. [Keep track of the verification results](#get-the-kyc-results) through notification webhooks.
4. [Upload additional documents](#upload-documents) if necessary.

## Requirements

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](/classic-platforms/onboard-users#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](/classic-platforms/onboard-users#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](/classic-platforms/verification-process/required-information) 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](/classic-platforms/account-holders-and-accounts#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](https://docs.adyen.com/api-explorer/#/NotificationService/latest/ACCOUNT_HOLDER_VERIFICATION) notification to your server containing the [`status` ](/classic-platforms/verification-process/check-verification-results#verification-statuses)of the verification checks.

If you have chosen the [staggered verification method](/classic-platforms/onboard-users#staggered-verification) or if the previously collected data is missing or invalid, payouts will be disabled and Adyen sends an [ACCOUNT\_HOLDER\_STATUS\_CHANGE](https://docs.adyen.com/api-explorer/#/NotificationService/latest/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](https://docs.adyen.com/api-explorer/Notification/latest/post/ACCOUNT_HOLDER_UPDATED) and [ACCOUNT\_HOLDER\_VERIFICATION](https://docs.adyen.com/api-explorer/Notification/latest/post/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](https://docs.adyen.com/api-explorer/#/Account/updateAccountHolder) call.

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

**Provide information for verification**

```bash
curl https://cal-test.adyen.com/cal/services/Account/v6/updateAccountHolder \
-H 'x-api-key: ADYEN_API_KEY' \
-H 'content-type: application/json' \
-d '{
    "accountHolderCode": "YOUR_UNIQUE_ACCOUNT_HOLDER_CODE",
    "accountHolderDetails": {
      "address": {
        "city": "NY",
        "country": "US",
        "postalCode": "12345",
        "stateOrProvince": "NH",
        "street": "Teststreet 1",
        "houseNumberOrName": "100"
     }
    }
  }'
```

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](https://docs.adyen.com/api-explorer/Notification/latest/post/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](https://docs.adyen.com/api-explorer/Notification/latest/post/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](/classic-platforms/verification-process#inactivation-suspension-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](https://docs.adyen.com/api-explorer/Notification/latest/post/ACCOUNT_HOLDER_VERIFICATION) notification webhooks.

For more information, refer to [verification results](/classic-platforms/verification-process/check-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](/classic-platforms/verification-process/document-requirements#upload-photo-id) (such as passport) of your account holders. If the account holder's identity cannot 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](https://docs.adyen.com/api-explorer/Account/latest/post/uploadDocument) request with the following:

* [documentContent](https://docs.adyen.com/api-explorer/Account/latest/post/uploadDocument#request-documentContent): The document in base64-encoded string format.

* [documentDetail.accountHolderCode](https://docs.adyen.com/api-explorer/Account/6/post/uploadDocument#request-documentDetail-accountHolderCode): The code of the account holder that owns the document.

* [documentDetail.documentType](https://docs.adyen.com/api-explorer/Account/latest/post/uploadDocument#request-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.

**Upload a document**

```bash
curl https://cal-test.adyen.com/cal/services/Account/v6/uploadDocument \
-H 'x-api-key: ADYEN_API_KEY' \
-H 'content-type: application/json' \
-d '{
   "documentContent":"dGVzdCBkb2N1bWVudCBjb250ZW50...VcdCB=",
   "documentDetail":{
      "accountHolderCode":"YOUR_ACCOUNT_HOLDER_CODE",
      "documentType":"PASSPORT",
      "filename": "passport.png"
   }
}'
```

**Response**

```json
{
    "invalidFields": [],
    "pspReference": "8515658815512840",
    "accountHolderCode": "YOUR_ACCOUNT_HOLDER_CODE",
    ...
    "verification": {}
}
```

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

* [Notifications](/classic-platforms/notifications)
* [Verification requirements](/classic-platforms/verification-process/required-information)
* [Verification process](/classic-platforms/verification-process)
