@adyen/kyc-components

Adyen KYC Monorepo

KYC components

Adyen Kyc-components provides the required forms/elements/dropins to build up an onboarding flow based on a legalentity.

Setup

1. Including the sdk

   • if using npm package

   import AdyenKyc from '@adyen/kyc-components';
   

   • if using umd format, include below in the html file

   <link href="/kycexternalapi/static/sdk/1.0.0/adyen-kyc-components.css" rel="stylesheet"/>
   <script src="/kycexternalapi/static/sdk/1.0.0/adyen-kyc-components.js"  type="text/javascript" ></script>
   

2. Initializing the sdk

      const kyc = new AdyenKyc({
          countryCode: 'US',
          clientKey: '',
          environment: 'https://kyc-test.adyen.com/kyc' OR 'https://kyc-live.adyen.com/kyc'
      });
   

3. Including form Components

   const form = kyc.create('personalDetails', {
     onChange: (val) => {
       console.log(val);
     },
   });
   
   form.mount('#container');
   

Configurations based on a country are underway, each form component will be capable of take in a country as prop based on which it will be rendered. If no country is provided the country value provided at initialization step will be used to configure.

Configuration

AdyenKyc(config: Config)

Config

Key	Default	Description
locale	en-US	the locale country code
country	US	the resident country code
clientKey		the client key to contact the KYC external API where the configuration API lives. In order for the SDK to work, your webpage needs to configure a clientKey that can be used by the SDK. The procedure for obtaining a clientKey for KYC Components are the same as for our other Web components. The details are listed on docs.adyen.com
environment		the domain where the KYC external api can be contacted.

AdyenKyc.create(dropinComponentName: ComponentName, options: Options)

ComponentName Possible values are:

Value	Description
'taskList' recommended	Let the SDK list the tasks that require completion. The navigation between each task will be handled internally. The rendering of drop-ins and navigation will be decided automatically.
'individualDropin'	KYC details for a natural person
'companyDropin'	KYC details for an organization
'payoutAccount'	KYC details for a transfer instrument

Options

Option	Required	Type	Remarks
isReview	Optional	boolean	Change all forms to be in review mode, essentially starting (and ending) every flow with a summary screen, with buttons changed to confirm and review.
legalEntityResponse	Required	Legal Entity object that is returned from the Legal Entities API	this now contains extended properties, see legal-entity.ts for more details
capabilities	Required	array	List of capabilities that are being requested, e.g. ['PSP_PAYOUT']
readOnly	Rrequired	boolean	to set form to read only mode
country	Optional	string	overrides resident country set in the Config that initialises the AdyenKyc
showInlineErrors	Optional	boolean	show errors inline or only above form
onChange	Optional	(state) => void	method that passes on the entire state when changes to the state of the forms have changed. state in the case of the Individual form will be of type IndividualSchema.
onSubmit	Optional	(state) => void	method that passed on the entire state after submitted data has been handled by the backend (successfully received a 200 response). i.e. User clicks form submit -> API handler promise fired -> promise resolves successfully -> fires onSubmit
handleGetLegalEntity	Required	(legalEntityId: string) => Promise<LegalEntity>	method for getting a Legal Entity using the legalEntities API.
handleCreateLegalEntity	Required	(data: LegalEntity) => Promise<LegalEntity>	method for creating a legal entity using the legalEntities API.
handleUpdateLegalEntity	Required	(data: LegalEntity, legalEntityId: string) => Promise<LegalEntity>	method for updating a legal entity using the legalEntities API.
handleCreateIdDocument	Required	(data: Document) => Promise<Document>	method for creating a document using the documents API.
handleUpdateIdDocument	Required	(data: Document, , documentId: string) => Promise<Document>	method for updating a document using the documents API.

Server configuration

To complete the setup of the Adyen SDK the following additional configurations are needed on your server. These configurations are listed below.

Content Security Policy

In order for the SDK to reach out to the Adyen servers for configuration requests and assets, additional Content Security Policy need to be configured. On top of your existing configration the following domains need to be added:

Environment	CSP Section	Value
Test	connect-src	https://kyc-test.adyen.com
Test	font-src	https://kyc-test.adyen.com
Test	img-src	https://kyc-test.adyen.com
Live	connect-src	https://kyc-live.adyen.com
Live	font-src	https://kyc-live.adyen.com
Live	img-src	https://kyc-live.adyen.com

Mock API

The server folder contains the mock API. It is used to develop without running the Adyen platform. It is also used during e2e testing in CI jobs.

End-to-end tests

End-to-end tests live in the tests folder. The E2E test framework we use is Playwright.

To run the e2e tests locally, simply do npm run test:e2e -- --project {browser}, where {browser} can be one of:

• local-chrome: uses the Google Chrome installation already present on your machine.
• chromium: uses the latest stable Chromium binary installed via playwright install. This is usually a major version ahead of Chrome & Edge.
• firefox: uses the latest stable Firefox binary installed via playwright install.
• webkit : uses the latest stable WebKit binary installed via playwright install (currently disabled)

For more info on the available browsers, see here.

By default, Playwright runs in headed mode in development, and headless in CI.

Debugging E2E tests

When you need to figure out why a test is (or isn't) failing, npm run test:e2e:debug is your friend. There are a few tools here which come in handy:

• Playwright Inspector: This tool allows you to explore the selectors Playwright is checking and see what user actions it is performing.
• .only(): Add this to any of your tests to make it the only test Playwright runs.
• page.pause(): You can use this to make Playwright pause execution (and open the inspector) at a specific point in any test.
• Dev Tools: You can use the browser's dev tools as normal when inspecting a Playwright test. For example, you can see what network requests are being made in the network tab. Playwright will also add a window.playwright object you can use to test out locators.

For more info on debugging Playwright tests, see here.

Viewing traces

When the E2E tests fail on CI, it can be quite difficult to figure out why. For that, we can use Playwright's trace viewer. This tool lets us view a recorded test run and "replay" what happened. It includes screenshots, logs of browser console & network requests, and more.

To use it, first download the report artifact for the given test run from GitHub:

1. Find your test run here (or click on the check from the PR).
2. If the tests failed, you should see playwright-report-{xxxxx} under Artifacts.
3. Download this file and unzip it. Inside, you will find a data directory which contains more .zips. Each of these is the trace for a single test.
4. To view a trace, upload the .zip xto trace.playwright.dev.

Static assets

Static assets are compiled and shipped separately to kycexternalapi every time a new asset is added or changed. For more information see the documentation for static assets.