Integrate capital components

This page explains how to integrate the capital components into your platform's user interface (UI).

Requirements

Component instance methods and parameters

By default, the Capital Offer component is embedded in the Capital Overview component, creating a standard user flow. This flow consists of a series of interactive screens that users engage with, all rendered within a single component element on the same UI page.

You can modify this standard user flow to create a more tailored and relevant experience for your users. For example, you may want to show a message about their eligibility for a grant on one page while directing users to complete the remaining steps on another page in your UI. To do this, you can use additional methods and parameters that enable you to register and unregister events, making it easier to manage multiple instances of components. There are various approaches you can take for each of the components.

When integrating the Capital Overview component, you can:

• Change how the component is rendered according to its state. For example, if the state is isUnqualified, then the component is not rendered.
• Interrupt the standard user flow at certain points to redirect a user to a different page in your interface to continue their flow.

When integrating the Capital Offer component, you can:

• Render it as standalone component and place it on a separate page in your UI.
• Configure the component to only show a specific screen.

You can specify the necessary methods and parameters when initializing components. Refer to the use case examples for more details.

How it works

Follow these steps to integrate the capital 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

Step 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 specifying the following parameters:

   To make this API request, your API key must have the Capital Component: Manage role in your Customer Area. Read more in Requirements.

   Parameter	Required	Description
   allowOrigin		The URL where the component will appear. Must follow the format: https://www.yourcompany.com, where yourcompany.com is the actual web address of your platform. Can also include a subdomain. On live, only the HTTPS protocol is supported.
   product		The type of component. Set this to platform.
   policy		An object that contains: resources: An object that contains: accountHolderId: The unique identifier of the account holder that is linked to the balance account shown in the component. type: The type of resource. Set this to accountHolder. roles: The role required to use the component. Set this to Capital Component: Manage.

   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.

Step 2: Install the component library on your front end

Use the Adyen Platform Experience library in your front-end application as follows:

1. Install the node package.

   npm install @adyen/adyen-platform-experience-web

2. Import the node package, the components, and the style sheet.

   import { AdyenPlatformExperience, CapitalOverview, CapitalOffer } from '@adyen/adyen-platform-experience-web';
   import "@adyen/adyen-platform-experience-web/adyen-platform-experience-web.css";

Step 3: Initialize the components

To initialize the 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
      environment		The environment for the component integration. The default value is test. Set the parameter to live when you are ready to go live.
      locale		The language of the component. See the list of the supported languages. For example, use en-US for English.
      onSessionCreate		The callback function that retrieves an authentication session token and refreshes the current session.

   2. Gather these parameters to initialize each component.

      Select the tab for the component you want to use:

   3. (Optional) Define the following component instance method.

      Method	Description
      getState	Retrieves the state of the component, which is an object containing a state field. The possible values of this field are: isUnqualified: The user is not yet qualified for a grant. isPreQualified: The user is pre-qualified for a grant. hasRequestedGrants: The user has previously received and repaid grants. Read more

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.

   By default, the Capital Offer component is embedded in the Capital Overview component. In this scenario, you only need to create a DOM element for the Capital Overview component. If you want to render the Capital Offer component outside the Capital Overview component, you need to create a separate DOM element for it.

   If you are using JavaScript frameworks such as Vue or React, make sure that you use references instead of selectors and that you do not re-render the DOM element.

   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.

   The following code is the same for both capital components.

4. Initialize the component and mount it to the container you created. In this step, you can localize the components by setting a preferred language.

   Select the tab for the component you want to use:

Step 4: (Optional) Customize the components

The capital 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 and the class styles:

1. Inspect the components using your browser's developer tools.
2. Modify the styles in your style sheet file.

The following tabs show examples of how to style the components. The first example shows how to override predefined CSS variables to use different colors and values. The second example demonstrates how to update the CSS class setting to change the layout of the info box element from a prominent blue background to an inline view with a bottom border.

Use case examples

Here you can find code examples demonstrating how to use the component instance methods and parameters for specific use cases in the components' implementation.

See also