Search

Are you looking for test card numbers?

Would you like to contact support?

Marketpay icon

Account holders and accounts

Create account holders and accounts for sub-merchants that sign up on your platform.

To create an account holder and account, you need to get the sub-merchant's legal entity type, collect the minimum required information, and send the information in an API request. Adyen informs you of the results through webhooks.

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

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 KYC verification checks.

An account holder can be one of the following legal entities:

  • Individual: The account holder is an individual.
  • Business: The account holder is registered as a business in the country they are operating in (which they may be required to do, depending on their local governmental regulations).
  • Nonprofit: The account holder has obtained a nonprofit status in the country they are operating in. You can onboard nonprofits operating in the US, Canada, Germany, Spain, France, United Kingdom, and Italy.

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.

To create an account holder for an individual or sole proprietor, get:

  • Their name.
  • Their email.
  • The country they are in to start the verification process required for the specific country.

To create an account holder for a business, get:

  • The legal business name.
  • Their email.
  • The country they are in to start the verification process required for the specific country.
  • The name and the residence country of at least one of their shareholders or ultimate beneficial owners (UBO) who own 25% or more of the business. If there are none who own 25% or more of the business, get information about a person authorised to sign up the company as an account holder.

To create an account holder for a nonprofit, get:

  • The legal organization name.
  • Their email.
  • The country they are in to start the verification process required for the specific country.
  • The name and the residence country of at least one control officer responsible for managing the organization.

Step 3: Create an account holder

After you collect the required information from the sub-merchant, submit it with the /createAccountHolder endpoint. The fields that you need to include depend on their legal entity type.

Make a /createAccountHolder request specifying:

  • A unique accountHolderCode. This is the identifier that you will use in the Platforms API whenever referencing the account holder.
  • The legalEntity type set to Individual.
  • The minimum required information you've collected from the sub-merchant, such as name.firstName, name.lastName, email, and address.country. You also need to provide name.gender though if you do not want to request it from your account holder, you can set the value to UNKNOWN.

When collecting the name, make sure they provide the name shown on their Photo ID.

Create an individual account holder
curl https://cal-test.adyen.com/cal/services/Account/v6/createAccountHolder \
-H "x-API-key: YOUR_X-API-KEY" \
-H "content-type: application/json" \
-d '{
   "accountHolderCode":"YOUR_UNIQUE_ACCOUNT_HOLDER_CODE",
   "accountHolderDetails":{
      "address": {
        "country": "US"
      },
      "email":"tim@green.com",
      "individualDetails":{
         "name":{
            "firstName":"Tim",
            "gender":"MALE",
            "lastName":"Green"
         }
      }
   },
   "legalEntity":"Individual"
}'
Response
{
   "invalidFields": [],
   "pspReference":"8815214563869136",
   "accountCode":"138215709",
   "accountHolderCode":"YOUR_UNIQUE_ACCOUNT_HOLDER_CODE",
   "legalEntity":"Individual",
   "accountHolderDetails":{
      "address":{
         "country":"US"
      },
      ...
   },
    "accountHolderStatus": {
      "status": "Active",
    ...
   },
   ...
}

Make a /createAccountHolder request specifying:

Create a business account holder
curl https://cal-test.adyen.com/cal/services/Account/v6/createAccountHolder \
-H "x-API-key: YOUR_X-API-KEY" \
-H "content-type: application/json" \
-d '{
  "accountHolderCode": "YOUR_UNIQUE_ACCOUNT_HOLDER_CODE",
  "accountHolderDetails": {
    "address": {
        "country": "US"
    },
    "businessDetails": {
      "legalBusinessName": "Real Good Restaurant Inc.",
      "shareholders": [
        {
            "name": {
              "firstName": "Maria",
              "gender": "FEMALE",
              "lastName": "Green"
            },
            "address": {
              "country": "US"
            }
        }
      ]
    },
    "email": "maria@green.com"
  },
  "legalEntity": "Business"
}'
Response
{
   "invalidFields": [],
   "pspReference":"8815214563869136",
   "accountCode":"138215709",
   "accountHolderCode":"YOUR_UNIQUE_ACCOUNT_HOLDER_CODE",
   "legalEntity":"Business",
   "accountHolderDetails":{
      "address":{
         "country":"US"
      },
      ...
   },
    "accountHolderStatus": {
      "status": "Active",
    ...
   },
   ...
}

You can onboard nonprofits operating in the US, Canada, Germany, Spain, France, United Kingdom, and Italy.

Make a /createAccountHolder request specifying:

Create a nonprofit account holder
curl https://cal-test.adyen.com/cal/services/Account/v6/createAccountHolder \
-H "x-API-key: YOUR_X-API-KEY" \
-H "content-type: application/json" \
-d '{
  "accountHolderCode": "YOUR_UNIQUE_ACCOUNT_HOLDER_CODE",
  "accountHolderDetails": {
    "address": {
        "country": "US"
    },
    "businessDetails": {
      "legalBusinessName": "Real Good Company",
      "shareholders": [
        {
            "name": {
              "firstName": "Maria",
              "gender": "FEMALE",
              "lastName": "Green"
            },
            "address": {
              "country": "US"
            }
        }
      ]
    },
    "email": "maria@green.com"
  },
  "legalEntity": "NonProfit"
}'
Response
{
   "invalidFields": [],
   "pspReference":"8815214563869136",
   "accountCode":"138215709",
   "accountHolderCode":"YOUR_UNIQUE_ACCOUNT_HOLDER_CODE",
   "legalEntity":"NonProfit",
   "accountHolderDetails":{
      "address":{
         "country":"US"
      },
      ...
   },
    "accountHolderStatus": {
      "status": "Active",
    ...
   },
   ...
}

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 a full list of statuses, 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.

Create an additional account

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.

Account holder statuses

The account holder status indicates whether a given account holder can process payments and payouts:

Status Updating data
allowed?
Payments
allowed?
Payouts
allowed?
Description
Active -white_check_mark- -white_check_mark- -white_check_mark- The default status of an account holder. Payment processing and payouts are enabled.
Inactive -white_check_mark- -white_check_mark- -x- The account holder did not provide information required for verification checks within the 30-day time limit.

When the account holder provides the required information, their status is restored to Active.
Suspended -x- -x- -x- The account holder did not provide information required for verification checks within the 6-week time  limit or they failed KYC checks (checks.status FAILED).

When an account holder is suspended, make sure to hide or remove the account holder from your platform to prevent processing of funds.

Once suspended, you can only unsuspend or close the account holder if none of the KYC checks have a failed status. When you unsuspend them, the status goes back to Inactive.
Closed -x- -x- -x- The account holder has been closed and no operations are allowed. This status is final.

Next steps