Marketplace icon

Transfer instrument components

Create a transfer instrument resource using Onboarding 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 us permission for instant verification of their bank account, or they upload documents that we then use 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 that is no longer required. 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:

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: Get 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 -white_check_mark- 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 -white_check_mark- The component type. Set this to onboarding.
      policy -white_check_mark- An object that contains:
      • resources: 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.
      • roles: the role required to use the component.
      Set this to createTransferInstrumentComponent and manageTransferInstrumentComponent respectively.

    Here is an example request to create a session token.

  2. From the response, save the generated token. 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 -white_check_mark- The language of the component. See the list of supported languages. Use en-US for English.
      country -white_check_mark- The two-letter ISO 3166-1 alpha-2 country code of the legal entity. Use US for the United States of America.
      environment -white_check_mark- 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 -white_check_mark- The token received from the create session token API response.
      getSdkToken -white_check_mark- The function callback for refreshing/extending the current session.
    • Create Transfer Instrument component

      Property Required
      Description
      Example
      legalEntityId -white_check_mark- The unique identifier of the legal entity to which the transfer instrument belongs. LE123123123123123
      openBankingPartnerConfigId -white_check_mark-
      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 -white_check_mark- The unique identifier of the legal entity to which the transfer instrument belongs. LE123123123123123
      onAdd -white_check_mark- The callback function triggered when the user clicks on Add bank account. (legalEntityId) => {}
      onEdit -white_check_mark- 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: 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

The illustrated flow is as follows:

  1. When integrating the Manage Transfer Instrument component, use the onEdit callback function. Within this function, you can load the Create Transfer Instrument component, where users can enter their data.
  2. Users can enter their bank account details.
  3. When integrating the Create Transfer Instrument Component, provide an onSubmitSuccess callback function. This function will then load the Manage Transfer Instrument Component to show the status of the provided bank account details.

See the example data for the onSubmitSuccess callback function below.

See also