Are you looking for test card numbers?

Would you like to contact support?

Atenção, esta página não se encontra disponível em Português
Marketpay icon

Account holders and accounts

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

Start the onboarding process by creating an account holder. To create an account holder, you need to get the sub-merchant's legal entity type, collect the minimum required information, and send the information in an API request.

Once the account holder is created and active, you can start processing payments for them. However, to pay out their funds, they have to provide more information (such as their bank account details) and pass 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 verification checks.

An account holder can be one of the following legal entities: Individual, Business, Nonprofit, Partnership, or Public company.

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 operating in.

To create an account holder for a business, get:

  • The legal business name.
  • Their email.
  • The country they are operating in.
  • The name and the country of residence of at least one of their ultimate beneficial owners who own 25% or more of the business. If there are none who own 25% or more of the business, get information about a signatory.

To create an account holder for a nonprofit, get:

  • The legal organization name.
  • Their email.
  • The country they are operating in.
  • The name and the country of residence of at least one control officer responsible for managing the organization.

To create an account holder for a business, get:

  • The legal business name.
  • Their email.
  • The country they are operating in.
  • The name and the country of residence of at least one of their ultimate beneficial owners who own 25% or more of the business. If there are none who own 25% or more of the business, get information about a signatory.

To create an account holder for a business, get:

  • The legal business name.
  • Their email.
  • The country they are operating in.
  • The name and the country of residence of a signatory, and their job title.

Step 3: Create an account holder

Submit the information that you collected with the /createAccountHolder endpoint. The fields that you need to include depend on their legal entity type.

Make a /createAccountHolder request specifying:

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",
            "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",
              "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",
    ...
   },
   ...
}

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",
              "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",
    ...
   },
   ...
}

Make a /createAccountHolder request specifying:

Create a partnership 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 Partnership",
      "shareholders": [
        {
            "name": {
              "firstName": "Maria",
              "lastName": "Green"
            },
            "address": {
              "country": "US"
            }
        }
      ]
    },
    "email": "partnership@example.com"
  },
  "legalEntity": "Partnership"
}'
Response
{
   "invalidFields": [],
   "pspReference":"8815214563869136",
   "accountCode":"138215709",
   "accountHolderCode":"YOUR_UNIQUE_ACCOUNT_HOLDER_CODE",
   "legalEntity":"Partnership",
   "accountHolderDetails":{
      "address":{
         "country":"US"
      },
      ...
   },
    "accountHolderStatus": {
      "status": "Active",
    ...
   },
   ...
}

Make a /createAccountHolder request specifying:

Create a public company 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 Public Company",
      "signatories":[
      {
        "name":{
          "firstName":"Sam",
          "lastName":"Hopper"
        },
        "jobTitle": "Vice President",
        "address":
        {
          "country": "US"
        }
      }
     ]
    },
    "email": "publiccompany@example.com"
  },
  "legalEntity": "PublicCompany"
}'
Response
{
   "invalidFields": [],
   "pspReference":"8815214563869136",
   "accountCode":"138215709",
   "accountHolderCode":"YOUR_UNIQUE_ACCOUNT_HOLDER_CODE",
   "legalEntity":"PublicCompany",
   "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 more information, 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.

Próximos passos