Are you looking for test card numbers?

Would you like to contact support?

No momento, esta página não está disponível em português
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:

A legal entity resource holds information required for the verification checks. You 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. Make sure you collect the required information for each legal entity.

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.
Create organization legal entity
curl https://kyc-test.adyen.com/lem/v2/legalEntities \
-u "ws123456@Scope.BalancePlatform_YourBalancePlatform":"YourWsPassword" \
-H "content-type: application/json" \
-X POST \
-d '{
    "type" : "organization",
    "organization" : {
      "legalName" : "Example Company",
      "registrationNumber": "101002749",
      "type" : "privateCompany",
      "registeredAddress" : {
        "city": "San Francisco",
        "country": "US",
        "postalCode": "94107",
        "stateOrProvince": "CA",
        "street": "Brannan Street",
        "street2": "Example Building"
       }
     }
   }'
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.
Response
{
    "organization": {
        "legalName": "Example Company",
        "registrationNumber": "101002749",
        "registeredAddress": {
            "city": "San Francisco",
            "country": "US",
            "postalCode": "94107",
            "stateOrProvince": "CA",
            "street": "Brannan Street",
            "street2": "Example Building"
        },
        "taxExempt": false,
        "type": "privateCompany"
    },
    "type": "organization",
    "id": "LE00000000000000000000001"
}

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. For example, if the main legal entity conducting business with your platform is an organization, then the legal entities of the owners of the organization must be linked to the legal entity of the organization.

To associate legal entities, update the main legal entity by making a PATCH /legalEntities/{id} request, specifying the entityAssociations array.

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.
The example below shows how you can associate an ultimate beneficial owner (UBO) to an organization. Update the legal entity of the organization by making a PATCH /legalEntities/{id} request. 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, or signatory.
Associate UBOs to an organization
curl https://kyc-test.adyen.com/lem/v2/legalEntities/LE00000000000000000000001 \
-u "ws123456@Scope.BalancePlatform_YourBalancePlatform":"YourWsPassword" \
-H "content-type: application/json" \
-X PATCH \
-d '{
    "entityAssociations": [
      {
        "jobTitle": "CEO",
        "legalEntityId": "LE00000000000000000000002",
        "type": "uboThroughControl"
      },
      {
        "legalEntityId": "LE00000000000000000000003",
        "type": "uboThroughOwnership"
      },
      {
        "jobTitle": "Country Manager",
        "legalEntityId": "LE00000000000000000000004",
        "type": "signatory"
      }
    ]
    }'

The response contains the updated legalEntity resource.

Step 3: 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.
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:

Add bank account as a transfer instrument
curl https://kyc-test.adyen.com/lem/v2/transferInstruments \
-u "ws123456@Scope.BalancePlatform_YourBalancePlatform":"YourWsPassword" \
-H "content-type: application/json" \
-X POST \
-d '{
    "legalEntityId" : "LE00000000000000000000001",
    "type" : "bankAccount",
    "bankAccount" : {
      "countryCode" : "US",
      "currencyCode" : "USD",
      "accountNumber": "1234567890",
      "branchCode": "121202211",
      "accountType": "checking"
    }
 }'

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

Response
{
  "bankAccount": {
    "accountNumber": "1234567890",
    "accountType": "checking",
    "branchCode": "121202211",
    "countryCode": "US",
    "currencyCode": "USD"
  },
  "legalEntityId": "LE00000000000000000000001",
  "type": "bankAccount",
  "id": "SE00000000000000000000001"
}

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

Step 4 (Conditional): Create business lines

For additional financial products, such as business bank accounts, or to configure a specific platform setup, Adyen also requires information about the legal entity's business line. A business line resource contains information about the user's line of business, such as their industry, source of funds, and sales channels.

To submit your user's business line for a platform setup, make a POST /businessLines request specifying the additional required information.
Parameter Required Description
capability -white_check_mark- Set this to receivePayments.
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 Array of channels in which your user sells goods or services. When specifying ecommerce or point of sale, you need to create separate business lines.
Possible values: eCommerce, ecomMoto, pos, posMoto, and payByLink.
webData Required when salesChannel is eCommerce. The user's web address or app URL.
Example request for a platform setup
curl https://kyc-test.adyen.com/lem/v2/businessLines \
-u "ws123456@Scope.BalancePlatform_YourBalancePlatform":"YourWsPassword" \
-H "content-type: application/json" \
-X POST \
-d '{
  "capability": "receivePayments",
  "salesChannels": ["eCommerce", "ecomMoto"],
  "industryCode": "339E",
  "legalEntityId": "LE00000000000000000000001",
  "webData" : [
    {
      "webAddress": "https://yoururl.com"
    }
  ]
}'
In the response, you receive the id of the business line. You will use this ID to create stores and add payment methods.
Example response for platform setup
{
  "capability": "receivePayments",
  "industryCode": "339E",
  "legalEntityId": "LE00000000000000000000001",
  "salesChannels": [
    "eCommerce",
    "ecomMoto"
  ],
  "webData" : [
    {
      "webAddress": "https://yoururl.com"
    }
  ],
  "id": "SE00000000000000000000001"
}

Step 5: 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 them 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.
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.

Create an account holder
curl https://balanceplatform-api-test.adyen.com/bcl/v2/accountHolders \
-H "x-api-key: YOUR_BALANCE_PLATFORM_API_KEY" \
-H "content-type: application/json" \
-d '{
  "{hint:Required if you have multiple balance platforms}balancePlatform{/hint}": "YOUR_BALANCE_PLATFORM_ACCOUNT",
  "{hint:Free-text field}description{/hint}":"Test Account holder",
  "{hint:Unique legal entity ID}legalEntityId{/hint}":"LE00000000000000000000001"
}'

The response returns the new accountHolder resource, identified by its unique id. The response also includes a capabilities array. In most cases, default capabilities are configured for your platform during the design phase. To add a specific capability for an account holder, you need to request it.

Response
{
   "balancePlatform":"YOUR_BALANCE_PLATFORM_ACCOUNT",
   "capabilities":{
      "receiveFromBalanceAccount":{
         "allowed": false,
         "enabled": true,
         "requested": true,
         "verificationStatus":"pending"
      },
      "receiveFromPlatformPayments":{
         "allowed": false,
         "enabled": true,
         "requested": true,
         "verificationStatus": "pending"
      },
      "sendToBalanceAccount":{
         "allowed": false,
         "enabled": true,
         "requested": true,
         "verificationStatus":"pending"
      },
      "sendToTransferInstrument":{
         "allowed": false,
         "enabled": true,
         "requested": true,
         "verificationStatus":"pending"
      }
   },
   "description":"Test Account holder",
   "id":"AH00000000000000000000001",
   "legalEntityId":"LE00000000000000000000001",
   "reference":"YOUR_INTERNAL_IDENTIFIER",
   "status":"active"
}

Step 6: Get verification updates

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

The webhook and the API response provides the status of the verification. 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.

When the checks are completed successfully, Adyen sends a balancePlatform.accountHolder.updated webhook with:
balancePlatform.accountHolder.updated webhook - verification completed
{
   "data":{
      "accountHolder":{
         "capabilities":{
            "sendToTransferInstrument":{
               "allowed":"true",
               "enabled":"true",
               "requested":"true",
               "verificationStatus":"valid"
            }
         },
         "description":"Test Account holder",
         "id":"AH00000000000000000000001",
         "legalEntityId":"LE00000000000000000000001",
         "reference":"YOUR_INTERNAL_IDENTIFIER",
         "status":"active"
      },
      "balancePlatform":"YOUR_BALANCE_PLATFORM"
   },
   "environment":"test",
   "type":"balancePlatform.accountHolder.updated"
}

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.
From our webhook example, 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 balancePlatform.accountHolder.updated 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 7 (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 upload documents. Make sure your onboarding flow supports the collection of documents from users.
In the example from the previous step, the remediating action code 1_301 indicates that you need to upload an ID document for the user.

To submit a document to Adyen, upload the document by making 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 id of the resource that owns the document and the 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. The type of document that you can upload depends on the legal entity type. Refer to type 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 a registration document for an organization:

Upload documents
curl https://kyc-test.adyen.com/lem/v2/documents \
-u "ws123456@Scope.BalancePlatform_YourBalancePlatform":"YourWsPassword" \
-H "content-type: application/json" \
-X POST \
-d '{
      "owner" : {
        "id" : "LE00000000000000000000001",
        "type" : "legalEntity"
      },
      "description" : "ID for individual",
      "type" : "identityCard",
      "attachments" : [
        {
          "content": "AAQSkZJRgABAQEAYABgAAD/s.."
        }
      ]
   }'

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

Response
{
  "type": "identityCard",
  "attachments": [
    {
      "content": "AAQSkZJRgABAQEAYABgAAD/s.."
    }
  ],
  "description": "ID for individual",
  "owner": {
    "id": "LE00000000000000000000001",
    "type": "legalEntity"
  },
  "id": "SE00000000000000000000001"
}

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.

Próximas etapas