Marketpay icon

Custom onboarding

Build your own UI and collect information from your users.

To onboard users on your platform, you need to build your own UI where you collect data from your users and submit this data to Adyen. You can onboard users operating in any of the following countries. On this page, we explain how you can onboard and verify your users using the Legal Entity Management API and Configuration API.

Before you begin

Make sure that:

Overview

The diagrams below show the steps you need to follow to onboard different types of legal entities.

Step 1: Set up webhooks

Before you start collecting the required information from users, we recommend that you configure your system to accept our webhooks. Webhooks keep you updated on the progress of your users' verification process, merchant account and capability status changes, notify you of errors and contain instructions on how resolve them. Webhooks are crucial for a successful integration with Adyen, and the only way you'll receive automatic updates.

For instructions on how to configure webhooks, see Webhooks.

A legal entity resource holds information required for the verification checks. You first need to create a legal entity for the user that has a contractual relationship with your platform. You may also need to create legal entities to represent entities connected to the main user.

For example, for organizations you need to create legal entities for all individuals associated with the organization. We refer to these as ultimate beneficial owners (UBOs), directors, and signatories.

Make sure you collect the required information for each legal entity.

For sole proprietorships, the legal entity of the individual owner is the main legal entity. You need to first create an individual legal entity and then a legal entity for the sole proprietorship. You will associate them in a later step.

For trusts, a trustee is the main legal entity. You need to first create an individual legal entity for the trustee and a legal entity for the trust. You also need to create legal entities for individuals associated with the trust. You will associate them in a later step.

Select a tab below to create different types of legal entities:

To create a legal entity for an organization, provide all the required information in a POST /legalEntities request, specifying:

Parameter Required Description
type -white_check_mark- Set to organization.
organization -white_check_mark- Object that contains required information about the organization such as the type, the legalName, and its registeredAddress.

The following is an example of how to create a legal entity for a private company operating in the US. The request contains the minimum required information for a marketplace setup. To know the additional requirements for other platform setups or financial products, refer to required information.

The response returns the legalEntity resource for the organization, identified by its unique id. You will need this ID in the next step when you link the legal entity to the legal entity of its owner.

Create an exempt organization settlor for a trust

If the trust has a settlor that is an organization who meets any of the following criteria, the settlor is considered exempt.

  • The material contribution of the settlor to the trust was less than AUD 10,000 at the time the trust was established.
  • The trust is verified using the simplified trustee verification procedure.

Create an organization legal entity for the exempt settlor. You do not need to provide the full registered address in your request.

Parameter Required Description
type -white_check_mark- Set to organization.
organization -white_check_mark- Object that contains required information about the organization. This includes the legalName and registeredAddress.

The user that holds a contractual relationship with your platform is the main legal entity. You also need to create legal entities for other entities associated with this user and link them to the main legal entity.

For example:

  • If the main legal entity conducting business with your platform is an organization, then the legal entities of the ultimate beneficial owners (UBOs) of the organization must be linked to the legal entity of the organization.
  • If the legal entity conducting business with your platform is an sole proprietorship, then the legal entity of the individual owner is the main legal entity. This must be linked to the legal entity representing the sole proprietorship.

The example below shows how you can associate an ultimate beneficial owner (UBO), signatory, or director to an organization.

Update the legal entity of the organization by making a PATCH /legalEntities/{id} request, specifying the entityAssociations array.

The array must include:

  • legalEntityId: Unique identifier of the individual legal entity being associated.
  • type: The relationship of the individual with the organization. Possible values: uboThroughControl, uboThroughOwnership, director, or signatory.

When updating the entityAssociations, note that a PATCH request replaces the whole array. If you only want to update one array item, make sure you include all existing items along with the specific change in your request.

If a person holds multiple roles in an organization, use their individual legal entity id to link them to each type or jobTitle.

The response contains the updated legal entity resource, identified by its unique id.

Step 4: Create transfer instruments

Adyen must perform checks on the bank account where your user will receive their payouts. We refer to this bank account as a transfer instrument resource.

Collect the required information and provide this in a POST /transferInstruments request, specifying:

Parameter Required Description
type -white_check_mark- Set to bankAccount.
legalEntityId -white_check_mark- Unique identifier of the legal entity that has the contractual relationship with your platform and owns the bank account. For sole proprietorships, this is the legal entity ID of the individual owner.
bankAccount -white_check_mark- Object that contains required information about the legal entity's bank account.

Here is an example request to add a transfer instrument for a bank account in the US:

The response returns the transferInstrument resource, identified by its unique id.

If we are not able to verify the bank account details, you will need to provide additional documents.

Step 5 (Conditional): Create business lines

Adyen requires information about your user's line of business, such as their industry and sales channels, if you:

To submit the details of your user's business line information for a platform setup, make a POST /businessLinesrequest specifying the following:

Parameter Required Description
service -white_check_mark- The service for which you are creating the business line. Set this to paymentProcessing.
industryCode -white_check_mark- The industry code.
legalEntityId -white_check_mark- The unique identifier of the legal entity that has a contractual relationship with your platform. For example, for an individual who has a sole proprietorship business, this must be the legal entity ID of the individual.
salesChannels -white_check_mark- Array of channels in which your user sells goods or services.
Possible values: eCommerce, ecomMoto, pos, posMoto, and payByLink. Sales channels may have different PCI DSS requirements. We recommend that you be familiar with these requirements before creating business lines for your user.
webData Required when salesChannel is eCommerce. The user's web address or the app store URL.

In the response, you receive the id of the business line. You will use this ID to create stores and add payment methods.

Step 6: Create account holders

An account holder resource holds the capabilities that your user can do in your platform, such as the capability to process split payments and pay out their funds to their bank accounts. Capabilities are requested for them by default. If you want a user to have a capability that is not part of the default configuration, you need to request the specific capability. The verification process starts after you create an account holder.

To create an account holder, make a POST /accountHolders request specifying:

Parameter Required Description
legalEntityId -white_check_mark- The unique identifier of the account holder's corresponding legal entity. For sole proprietorships, this is the individual legal entity ID of the owner.
balancePlatform The unique identifier of the balance platform. Required only if your API credentials has access to multiple balance platforms.
description A human-readable description for the account holder, which can be useful for your staff and support agents.

Here is an example of how you can create an account holder.

The response returns the new accountHolder resource, identified by its unique id. The response also includes a capabilities array. This shows the capabilities that are assigned to the account holder automatically based on how your platform was configured during the design phase. To add a specific capability for an account holder, you need to request an additional capability.

Step 7 (Conditional): Create stores

Creating stores is required only if you have a platform setup.

Stores are linked to the legal entity of your user through business lines. Stores ensure that payments are processed in a compliant manner and each processed transaction has an accurate payer statement. You must create separate stores for point-of-sale and ecommerce payments.

For every payment processed through your user's store, you can split the funds between the balance accounts in your platform, including your liable balance account. You can split funds manually for each payment, or you can add a split configuration profile to your user's store to automatically split all payments processed through that store.

Before you begin

Before you create a store, you must:

  • Have access to API credentials for the Management API and the Management API-Stores read and write role to create the store.
  • Collect from your user the address and phone number of the store, and the name of the store that will appear on the bank and credit card statements of shoppers.
  • Know the merchant account ID and the business lines that the store will be associated with.

Create a store

  1. To create a store, make a POST /stores, specifying:

    Parameter Required Description
    address -white_check_mark- An object that contains:
    • city: the city of the store.
    • country: the country of the store.
    • line1 line2 line3: up to three lines can be used for the street name, street number, and other information. Only the first line is mandatory.
    • postalCode: the postal code of the store.
    • stateOrProvince: Required only for the United States. The state or province of the store as defined in ISO 3166-2. For example, IL in the United States.
    description -white_check_mark- A description for the store.
    businessLineIds An array that contains business line IDs. Required if you have a platform setup. Must be part of the same legal entity as the merchant account. If not specified, the business line of the merchant account is used. Required when there are multiple business lines under the merchant account.
    merchantId -white_check_mark- The merchant account ID.
    phoneNumber -white_check_mark- The complete phone number of the store, beginning with + and the country code.
    reference A reference to recognize the store by. Allowed characters: Lowercase and uppercase letters without diacritics, numbers 0 through 9, hyphen (-), and underscore (_).
    If you do not provide a reference in your POST request, it is populated with the Adyen-generated id.
    shopperStatement -white_check_mark- The store name shown on the shopper's bank or credit card statement and the shopper receipt. Maximum length: 22 characters. Cannot be all numerals.

    You can also make a POST request to /merchants/{merchantId}/stores using the same parameters. In that case you do not need to include the merchant account ID in the request body.

    The following example shows how to create a store:

  1. In the response, note that this includes the Adyen-generated id for the store. You can use this as a path parameter to update the store.

    You will need to use the store reference when making a /payments or /paymentMethods request. For more information, see route a payment to a store.

  1. After you create a store, you must add payment methods to the store. To manage a store, such as update a store's details, see manage stores.

In-person payments

If you are offering in-person payments, you need to order, assign, and configure terminals. Follow the Terminal API integration checklist.

Step 8: Determine the terms of service

Your users must accept Adyen's Terms of Service before they can perform particular actions in your platform. The type of the Terms of Service agreement depends on your specific integration.

Listen to webhooks to determine if your user needs to accept the Terms of Service. You must generate the required agreement type and present it to your user, then ask them to accept it.

Step 9 (Conditional): Check security requirements

Required if you have a platform setup.

Because your users have a direct connection with card schemes, they must comply with the requirements laid down in the Payment Card Industry Data Security Standards (PCI DSS) for collecting, processing, storing, and transmitting cardholder data in a secure environment. To prove their compliance, they must sign a Self-Assessment Questionnaire (SAQ) before they can start processing card payments. The questionnaire asks them to confirm the security of their cardholder data environment, which typically includes their website, web servers, and employees who can access them.

Listen to webhooks to determine if your user needs to sign PCI questionnaires. You must generate the required security questionnaires and ask your user to sign them.

Step 10: Get verification updates

To get updates about the verification status and results, you can:

If you are using a staggered verification process, Adyen informs you when an account holder is moved to a higher tier and what data they need to provide. After the data is verified by Adyen, their payouts are enabled again.

The webhook and the API response provides the status of the verification: valid, invalid, or rejected. If the verification is unsuccessful, you must resolve the verification errors.

The webhook examples below show when the verification is successful and when the capability is not allowed because the verification is invalid.

Verification valid

When the checks are completed successfully, Adyen sends a balancePlatform.accountHolder.updated webhook with:

Verification invalid

When there are problems with the verification, Adyen sends a balancePlatform.accountHolder.updated webhook.

This section is for platforms that have completed their integration.

The webhook contains the following information:

  • verificationStatus: Set to invalid.
  • allowed: Set to false.
  • problems: Contains verificationErrors, subErrors, and remediatingActions arrays returned on the linked legal entity. If there are verification errors, you must resolve them.

To see any problems also returned on the transfer instrument resource, reach out to your Adyen contact to enable the feature. For example, if your users have multiple transfer instruments, this can help them identify the errors and on which transfer instrument they need to be resolved.

Verification rejected

When the verification is unsuccessful and the capability is rejected, for example due to fraudulent activity, Adyen sends a balancePlatform.accountHolder.updated webhook containing the following information:

If the capability is rejected, any errors cannot be resolved by updating data or uploading documents.

Resolve verification errors

If the webhook or the API response has a problems array, check remediatingActions. In this array, you'll find the actions that you can take to resolve the error, such as updating the data or uploading documents. Refer to verification error codes for a list of verification errors.

Let's say that the legal entity's name changed and now their data must be updated. To do this, send a PATCH /legalEntities/{id} request.

After you update the data, Adyen sends another webhook with the verificationStatus set to pending.

Once again, you will get updates about the status of the verification from the webhook or by making an API request.

Step 11 (Conditional): Upload documents

Adyen attempts to verify the data that you provide. However, in some cases, the automatic verification might fail. This could be due to incorrect data or when the data can't be verified. In these cases, Adyen may ask you to provide additional documents. Make sure your onboarding flow supports the collection of documents from users.

For example, a remediating action code 1_301 indicates that you need to upload an ID document for the user.

To submit a document to Adyen:

  1. Collect the document from the account holder.
  2. Upload the document with a POST /documents request, specifying:
Parameter Required Description
attachments -white_check_mark- Array that contains the document.
owner -white_check_mark- Object that contains the owner.id of the resource that owns the document and the owner.type of resource. For type legalEntity, the id is the unique identifier of the legal entity. For type bankAccount, the id is the unique identifier of the transfer instrument.
type -white_check_mark- The type of document that you can upload depends on the legal entity type. Refer to types for a full list.

The combination of owner.id, type, and attachments.content must be unique. If you have already submitted the same combination, you'll receive an error message. Either update the existing document resource, or delete the resource and create a new one.

Here is an example of how to upload an identity document for an individual:

The response returns the document resource, identified by its unique id.

Adyen returns the results of the verification and the available capabilities on the accountHolder resource. After you successfully upload the additional documents, wait for Adyen to inform you of the verification results. Adyen validates documents asynchronously. On average, it takes about 30 seconds to validate a photo ID, and two days for registration documents and bank statements.

Next steps