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 integrating the components, make sure that you:

• Followed the API-only onboarding guide to complete all necessary steps before creating transfer instruments.
• Created API credentials for the Legal Entity Management API.
• Verified that the components are available in the countries/regions, languages, and browser versions that apply to your situation.
• 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 the resource IDs and roles
2. Get an authentication session token
3. Install and import the npm package
4. Initialize the components
5. Customize the components

Step 1: Get the resource IDs and roles

To ensure a component is used by an authorized user, you must:

1. Get the legal entity ID of the user whose data you want to collect using the components.
2. Know the role that is required for the use of the component:
   • The Create Transfer Instrument component requires the createTransferInstrumentComponent role.
   • The Manage Transfer Instrument component requires the manageTransferInstrumentComponent role.

You then use these values to generate an authentication session token in the next step.

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 Session authentication API using the API key that you set up for the Legal Entity Management API or the Configuration 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. An asterisk (*) cannot be used as a literal value for 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 for creating a session token.

2. In the response, note the token. Later, when you initialize the components, you need to create and call a function that passes the token value to the 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 the 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 the components

You can customize the appearance of components by overriding the default styles of colors, fonts, borders, and more. Adyen offers two different ways to do this:

• CSS variables (recommended): Customize styles across all components by providing custom values for global style variables.
• CSS classes: Modify specific elements of the component by changing the associated classes and properties. These changes will only apply to the particular component you are customizing.

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.

CSS variables

Adyen supports CSS variables that define default styles for the onboarding components. These variables enable you to apply global styles to your components, ensuring a consistent look and feel throughout your platform. For example, you can use the CSS variables to specify a custom font family or integrate brand colors into your components.

To override a default CSS value:

1. Identify the CSS variable you want to change. Select the corresponding tab to view the available CSS variables and their default values for fonts, background color, outline color, and border settings.

2. Set a new value for this CSS variable at the root level. Select the corresponding tab to view the examples.

CSS classes

By using CSS classes, you can customize a particular component:

1. Use your browser's developer tools to inspect the component and identify available classes and properties.

2. Define the desired styles in your style sheet file.

   Here is an example to help you get started.

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