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.

The following tabs illustrate how the component appears on various screen sizes.

Manage Transfer Instrument component

The Manage Transfer Instrument component enables users to view a list of all bank accounts (transfer instruments) that have been added, along with their corresponding verification statuses and error messages, if applicable.

Users can also add a new bank account 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. If a bank account still needs to be added, users will be prompted to do so when accessing the component. Learn how to use callback functions to create a complete user flow.

The following tabs illustrate how the component appears on various screen sizes.

Requirements

User flow and callback functions

When integrating components, you can use callback functions to link the two components into a single user flow.

• When integrating the Create Transfer Instrument component, you can include the onSubmitSuccess callback function. This function is triggered when the user submits their bank account details. It returns the submitted bank account information in a payload and loads the Manage Transfer Instrument component. This enables the user to view the provided bank account details and their verification status after submitting the information.
• When integrating the Manage Transfer Instrument component, you can include:
  • the onAdd callback function. This function is triggered when the user selects Add bank account, and it loads the Create Transfer Instrument component. This enables the user to enter their bank account details.
  • the onEditcallback function. This function is triggered when the user selects Edit details, and it loads the Create Transfer Instrument component. This enables the user to view their prefilled bank account 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 transfer instrument components:

1. Create an authentication session from your server
2. Install the component library on your front end
3. Initialize the components
4. 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:

1. 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	Description	Example
   allowOrigin		The URL where the component will appear.	Must follow the format of https://www.yourcompany.com, where yourcompany.com is the actual web address of your platform. 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 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. Set this to legalEntity. roles: The role(s) required to use the component(s). Set this to createTransferInstrumentComponent and/or manageTransferInstrumentComponent.
   product		The type of product the component belongs to.	Set this to onboarding.

   Here is an example request for creating a session token.

2. 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 the sdkToken parameter.

2. Install the component library on your front end

Install the Adyen KYC Components library in your front-ent application as follows:

1. Install the npm package.

   npm install @adyen/kyc-components --save

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

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

   1. Gather these parameters to initialize the library.

      Parameter	Required	Description	Example
      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.
      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.

   2. Gather these parameters to initialize each component.

      Select the tab for the component you want to use:

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

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

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

4. (Optional) Customize the components

The transfer instrument 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 (recommended) and the class settings:

1. Inspect the components using your browser's developer tools.
2. 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.

See also