Transfer instrument components

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:

1. Get resource IDs and roles
2. Get an authentication session token
3. Install and import the npm package
4. Initialize components
5. 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.

1. Get the legal entity ID of the user.
2. 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:

1. 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.

   1. 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

   2. In the request body, specify these parameters:

      Parameter	Required	Description	Example
      allowOrigin		The URL where the component will appear.	Supported URL formats: https://www.yourcompany.com and https://*.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.

2. 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:

1. Install the node package.

   npm install @adyen/kyc-components --save

2. 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:

1. Gather the following information to be passed when initializing the library and its components.

   • Library

     Parameter	Required	Description	Example
     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 and https://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	Description	Example
     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	Description	Example
     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) => {}

2. 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:

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

4. 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.

See also