Search

Are you looking for test card numbers?

Would you like to contact support?

Marketpay icon

Build your own onboarding implementation

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

To build your own onboarding flow, you need to know the additional information that Adyen requires and collect this information from your account holder.

The onboarding process follows these main steps:

  1. Collect additional information to enable payouts.
  2. Pass in-depth verification to continue payment processing and payouts.
  3. (Optional) For account holders in the EU, or as a last effort verification, carry out a final Photo ID verification.

After completing in-depth verification, your account holder will be able to process payments and pay out freely.

Collect additional information to enable payouts

After you create an account holder, you can immediately start processing payments. However, to pay out your account holder, Adyen needs additional information about the account holder to be able to pay out. The information that Adyen will require from the account holder depends on their legal entity type. This information needs to be provided within 30 days of the account holder's first transaction.

  1. Refer to the KYC requirements list to know what you need to collect from your account holder.
  2. Collect the information and provide the data in a POST /updateAccountHolder call.

    For example, here is how you would provide the full address of an existing account holder.

    Provide information for KYC checks
    curl https://cal-test.adyen.com/cal/services/Account/v6/updateAccountHolder \
    -H "x-API-key: YOUR_X-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 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.

If your account holder has already processed a few thousand dollars, they will additionally need to complete In-depth verification to enable payouts.

Missing the 30 day timeline

If you are unable to collect the information required by the verification checks within 30 days of the first transaction, the account holder's status will be updated to inactive and payouts will be temporarily disabled.

Missing the 30 day deadline will trigger the 6 week deadline.

In-depth verification

Adyen may perform additional verification, based on a variety of risk elements, using the already collected information of your account holder. If your account holder has already processed a few thousand dollars, they will additionally need to complete In-depth verification to enable payouts.

Adyen sends an ACCOUNT_HOLDER_VERIFICATION notification webhook to your server containing the status of the KYC checks. Some of the status values you might receive are:

  • PASSED: The previously collected information passed our in-depth verification. There will be no interruption to your account holder's ability to process payments and pay out.
  • INVALID_DATA: The information from the account holder did not pass the in-depth verification. Payouts will be temporarily disabled.

For each verification check that did not pass, you have 30 days to collect the required information again. After you provide the information and the verification checks pass, we will re-enable payouts and update the verification check status to PASSED.

Missing the 30 day deadline will trigger the 6 week deadline.

If your account holder is based in the EU, they may need to provide Photo ID verification to enable payouts.

Photo ID verification

In the EU, we may require photo identification (such as passport) of your account holders. In all countries, if the account holder's identity can not be validated, the photo ID verification is used as the ultimate verification.

If photo identification is needed, payouts will be disabled. Adyen sends a corresponding ACCOUNT_HOLDER_VERIFICATION notification webhook with status AWAITING_DATA. You have 30 days after the status change to collect photo identification from your account holder.

For individuals, you must collect the account holder's passport or government-issued ID. Your account holder can also use their driver's license.

To provide a Photo ID, make a /uploadDocument call. You need to specify the accountHolderCode of the account holder and provide the appropriate documentType: the type is determined by the type of document you collected from you account holder. In this example, we use a PASSPORT.

The photo must be a .jpeg, .jpg, .pdf, or .png file, encoded as a Base64 string, and passed as the documentContent parameter.

Upload a photo ID
curl https://cal-test.adyen.com/cal/services/Account/v6/uploadDocument \
-H "x-API-key: YOUR_X-API-KEY" \
-H "content-type: application/json" \
-d '{
   "documentContent":"dGVzdCBkb2N1bWVudCBjb250ZW50...VcdCB=",
   "documentDetail":{
      "accountHolderCode":"YOUR_ACCOUNT_HOLDER_CODE",
      "documentType":"PASSPORT",
      "filename": "passport.png"
   }
}'
Response
{
    "invalidFields": [],
    "pspReference": "8515658815512840",
    "accountHolderCode": "YOUR_ACCOUNT_HOLDER_CODE",
    ...
    "verification": {}
}

Photo IDs are validated asynchronously, and on average, will take about 30 seconds to validate. Wait for the ACCOUNT_HOLDER_VERIFICATION notification to confirm the validation status. When the photo ID is validated, the photo ID check will be updated to a status of PASSED.

If we are unable to validate, the account holder will go into manual review.

Missing the 30 day deadline will disable processing and trigger the 6 week deadline.

See also