To integrate the individual legal entity components, the minimum required library version is 3.32.0.
You can speed up the process of creating legal entity resources for your users with Adyen's web components. You only need to create a legal entity using the POST /legalEntities request with the minimum required information, then integrate the legal entity components into your marketplaceās user interface (UI).
After you have integrated the components, your users can enter other necessary verification information themselves. The component will then send this information to Adyen for verification checks and show your users their verification status.
This page provides information on:
- The available individual legal entity components, which include the Create Individual component and the Manage Individual component.
- The steps needed to integrate these components into your marketplace's UI.
Create Individual component
The Create Individual component enables your users to:
- Enter their personal details and upload any additional documents required for onboarding.
- Submit the entered information to Adyen for verification.
The following tabs illustrate how the component appears on various screen sizes.
Manage Individual component
The Manage Individual component enables your users to see their current verification status when used as a standalone component. You can also link the Manage Individual component to the Create Individual component by using a callback function to enable users to update their information if needed.
The following tabs illustrate how the component appears on various screen sizes.
Requirements
Requirement | Description |
---|---|
Integration type | You must have the Adyen for Platforms platform integration. |
API credentials | You must have a Legal Entity Management API key (for example, ws[_123456]@Scope.Company_[YourCompanyAccount]) to access the Session authentication API. |
Setup steps | Before you begin:
|
User flow and callback functions
You can use each component independently to serve its primary purpose, such as to enable users to enter and submit their information and view their verification status.
Alternatively, you can integrate the two components into a single user flow by using the following callback functions:
- When integrating the Create Individual component, you can include the
onSubmitSuccess
callback function. This function is triggered when the user submits their personal details. It returns the user details in a payload and loads the Manage Individual component. This enables the user to view the verification status of the information they provided. - When integrating the Manage Individual component, you can include the
onClick
callback function. This function is triggered when the user selects their user profile in the component, and it loads the Create Individual component. This enables the user to view their prefilled personal details and any outstanding errors. The user can then update and submit the new information in the component.
See the example data for the onSubmitSuccess
callback function below.
How it works
Follow these steps to integrate the individual legal entity components:
- Create an authentication session from your server
- Install the component library on your front end
- Initialize the components
- Customize the components
1. Create an authentication session from your server
To ensure secure communication between components and Adyen server, you must configure your server for authentication and create a session token. To create the token:
-
From your server, make a POST /legalEntities request to create a legal entity for your user first. In your request, specify the following minimum required information.
To make this request, you must only use version 3 of the Legal Entity Management API.
Parameter Required DescriptionfirstName The individual's first name. Must not be blank. lastName The individual's last name. Must not be blank. residentialAddress.country The two-letter ISO 3166-1 alpha-2 country code. -
From the response, save the generated
legalEntityId
. -
From your server, make a POST /sessions request using the API key that you set up for the Legal Entity Management API. In the request body, specify these parameters:
Parameter Required DescriptionExample allowOrigin
The URL where the component will appear. Must follow the format of https://www.yourcompany.com
, whereyourcompany.com
is the actual web address of your marketplace. Can include a subdomain.On live, only the HTTPS protocol is supported.policy
An object that contains: resources
: An object that contains:legalEntityId
: The unique identifier of the legal entity associated with the user that has a contractual relationship with your marketplace and whose data you want to collect using the components. Set this to the legal entity ID value you created in step 1.1.type
: The type of resource. Set this to legalEntity.
roles
: The role(s) required to use the component(s). Set this to createIndividualComponent and/or manageIndividualComponent.
product
The type of product the component belongs to. Set this to onboarding. Here is an example request for creating a session token.
-
Note the API response. Later, when initializing the components, you need to create and call a function that passes the entire session object from the response to your front end. Additionally, you need to pass the
token
value to thesdkToken
parameter.
2. Install the component library on your front end
Install the Adyen KYC Components library in your front-ent application as follows:
-
Install the npm package.
npm install @adyen/kyc-components --save
-
Import the library, the components, and the style sheet.
import AdyenKyc from '@adyen/kyc-components'; import '@adyen/kyc-components/styles.css';
3. Initialize the components
To initialize components:
-
Gather the following information to be passed when initializing the library and its components.
-
Gather these parameters to initialize the library.
Parameter Required DescriptionExample country
The two-letter ISO 3166-1 alpha-2 country code of the legal entity. Use US for the United States of America. environment
The URL of the environment for the component integration. Use https://test.adyen.com/
for the test environment andhttps://onboardingcomponents-live.adyen.com/
for the live environment.getSdkToken
The callback function that retrieves an authentication session token and refreshes the current session. locale
The language of the component. See the list of supported languages. Use en-US for English. sdkToken
The token received from the create session token API response. -
Gather these parameters to initialize each component.
Select the tab for the component you want to use:
-
-
Create a DOM element on your UI page where you want the component to be rendered.
Assign the element a unique and descriptive ID. This unique ID is important to avoid any misconfigurations when integrating multiple components into your UI.
Select the tab for the component you want to use:
-
Add a function that calls your API to retrieve and refresh an authentication session token.
Select the tab for the component you want to use:
-
Initialize the component and mount it to the container you created.
Be sure to include the function for retrieving and refreshing the session token that you added in the previous step.
In this step, you can also configure the components to use one of the supported languages by setting the
locale
parameter. If no localization settings are provided, the components will default to English.Select the tab for the component you want to use:
If you use callback functions to integrate the two components into a single user flow, refer to the following example implementation:
4. (Optional) Customize the components
The individual legal entity components have a default appearance with pre-defined styles, such as colors, fonts, and borders. You can customize the appearance of your components by overriding the default values of CSS variables:
- Inspect the components using your browser's developer tools.
- Modify the styles in your style sheet file.
For the best user experience when customizing components, we recommend the following:
- Choose color combinations that complement each other well and provide enough contrast for readability, especially for text and navigation elements.
- Follow accessibility guidelines to ensure that the color palette is inclusive and usable for individuals with visual impairments.
- Test your customizations before implementing them live.
The following tabs show the available CSS variables and their default values.
The following tabs show examples of how to style the components.