You can integrate the transfer instrument components in your user interface to let your platform's users enter their bank account details. The components then use the entered data to create a transfer instrument resource, so you do not have to make any API calls yourself.
This page provides information on:
- The available transfer instrument components, which include the Create Transfer Instrument component and the Manage Transfer Instrument component.
- The steps needed to integrate these components into your platform.
Create Transfer Instrument component
The Create Transfer Instrument component enables users to add information about their bank accounts, also known as transfer instruments. Users can either give permission for the instant verification of their bank account, or upload documents which Adyen uses to validate the bank account.
Manage Transfer Instrument component
The Manage Transfer Instrument component enables users to add a new bank account (a transfer instrument) or delete an existing one if it is no longer needed. Any changes made are applied immediately, ensuring that payouts are delivered to the correct transfer instrument.
This component shows a list of all bank accounts that have been added, along with their corresponding verification statuses and error messages, if applicable. If a bank account still needs to be added, users will be prompted to do so when accessing the component.
Before you begin
Before you begin to integrate the transfer instrument components, make sure that:
- You followed the API-only onboarding guide to complete all necessary steps before creating transfer instruments.
- You have API credentials for the Legal Entity Management API, Configuration API.
- You have verified that the components are available in the countries/regions, languages, and browser versions that apply to your situation.
- You have reviewed the verification process and the required information for your users.
How it works
Follow these steps to integrate the transfer instrument components:
- Get resource IDs and roles
- Get an authentication session token
- Install and import the npm package
- Initialize components
- Customize components
Step 1: Get resource IDs and roles
To ensure a component is used by an authorized user, you need to gather one or more resource IDs linked to the user, and know which role is required for the use of the component. You then use these values to generate an authentication session token in the next step.
The resource ID refers to legal entity ID whose data you want to collect using the components. The role determines the actions that are allowed for the legal entity resource in the component.
- Get the legal entity ID of the user.
- Determine what role is required for the component you want to use:
- The Create Transfer Instrument component requires the createTransferInstrumentComponent role.
- The Manage Transfer Instrument component requires the manageTransferInstrumentComponent role.
Step 2: Create an authentication session token
To ensure secure communication between backend and frontend, a session token is required. To create a session token:
-
Make a POST request to the
/sessions
endpoint of the Authentication API using basic authentication that you set up for the Legal Entity Management API.-
Use the following URLs for this API:
Environment API URL test https://test.adyen.com/authe/api/v1/sessions
live https://authe-live.adyen.com/authe/api/v1/sessions
-
In the request body, specify these parameters:
Parameter Required DescriptionExample allowOrigin
The URL where the component will appear. Supported URL formats: https://www.yourcompany.com
andhttps://*.yourcompany.com
.On live, only HTTPS protocol is supported.Note, you may not use asterisk (*) as a literal value of the parameter.product
The component type. Set this to onboarding. policy
An object that contains: resources
: An object that contains:legalEntityId
: The 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.type
: The type of resource.
roles
: The role required to use the component. Set this to createTransferInstrumentComponent and/or manageTransferInstrumentComponent.
Here is an example request to create a session token.
-
-
From the response, save the token created. You need this token in the next step to initialize the library and components.
Step 3: Install and import the npm package
Use the Adyen KYC Components npm package in your application as follows:
-
Install the node package.
npm install @adyen/kyc-components --save
-
Import the package and the style sheet in your application. To customize the component styling, see Step 5.
import AdyenKyc from '@adyen/kyc-components'; import '@adyen/kyc-components/styles.css';
Step 4: Initialize components
To initialize components:
-
Gather the following information to be passed when initializing the library and its components.
-
Library
Parameter Required DescriptionExample locale
The language of the component. See the list of supported languages. Use en-US for English. 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.sdkToken
The token received from the create session token API response. getSdkToken
The function callback for refreshing/extending the current session. -
Create Transfer Instrument component
Property Required DescriptionExample legalEntityId
The unique identifier of the legal entity to which the transfer instrument belongs. LE123123123123123 openBankingPartnerConfigId
For US, CA
The unique identifier of your brand name shown to your user during instant bank account verification. They can initiate the verification process through open banking providers, like Plaid or Tink. To customize the parameter value, reach out to your Adyen contact. settings
An object that contains: allowIntraRegionCrossBorderPayout
: if set to true, users can select a payout account in a different EU/EEA country (including Switzerland and the UK) than the country of their legal entity.allowBankAccountFormatSelection
: if set to true, users can choose between a local format or IBAN for their payout account, if applicable.
allowIntraRegionCrossBorderPayout:true
allowBankAccountFormatSelection:false
transferInstrumentId
The unique identifier of the transfer instrument. When the parameter is passed, the component shows information about this transfer instrument. SE123123123123123 onSubmitSuccess
The callback function triggered when the transfer instrument is successfully submitted. (submittedData) => {}
-
Manage Transfer Instrument component
Property Required DescriptionExample legalEntityId
The unique identifier of the legal entity to which the transfer instrument belongs. LE123123123123123 onAdd
The callback function triggered when the user clicks on Add bank account. (legalEntityId) => {}
onEdit
The callback function triggered when the user clicks on Edit details. (transferInstrumentId, legalEntityId) => {}
onRemoveSuccess
The callback function triggered when the transfer instrument is removed. (transferInstrumentId, legalEntityId) => {}
-
-
Create a DOM element on your UI page where you want the component to be rendered and give it a descriptive ID.
Select the tab for the component you want to use:
-
Add a function that calls your API to generate a new authentication session token. The API call itself is described in Step 2.
Select the tab for the component you want to use:
-
Initialize the library, then create and mount the component to the container you created. At this step, you can localize the components by setting a preferred language.
Select the tab for the component you want to use:
Step 5: (Optional) Customize components
You can customize the appearance of components by overriding the default style to change colors, fonts, borders, and more. To see which classes and properties are available, inspect the components using your browser's developer tools. Then, define the desired styles in your style sheet file.
Here is an example you can use as a starting point.
Callback functions
When integrating components, you can utilize callback functions to handle two scenarios:
- Adding bank account details
- Editing bank account details
See the example data for the onSubmitSuccess
callback function below.