Reports component

You can use the Reports Overview component to let your users access reports generated by Adyen for their balance accounts. The reports show the movement of funds within their balance accounts, such as payouts. This information can help your users with their bookkeeping and reconciliation processes.

The component automatically generates report data every day, so users do not have to ask for reports from you and always have access to the most current data.

This page provides information on:

• The features of the Reports Overview component.
• The steps needed to integrate the Reports Overview component into your marketplace's user interface (UI).

Reports Overview component

The Reports Overview component shows a list of downloadable reports for a specific balance account within a specified time period. Additionally, the component allows for custom data integration, such as your own fields, icons, links, and buttons.

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

The component enables users to:

• Download a generated report in CSV format. The downloaded file name will be similar to this: balanceaccount_payout_report_YYYY_MM_DD.csv.
• Filter the generated reports by time period and balance account (if applicable). See the available filters for more details.

Supported report types

Available filters

The following sections shows the available filters and their values for the Reports Overview component.

Requirements

How it works

Follow these steps to integrate the reports component:

1. Create an authentication session from your server
2. Install component library in your front end
3. Initialize components
4. Customize component appearance
5. Customize component data (from library version 1.4.0)

1. Create an authentication session from your server

To ensure secure communication between the component 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 Reports Overview Component: View role in your Customer Area. Read more in Requirements.

   Parameter	Required	Description
   allowOrigin		The URL where the component will appear. Must follow the format of https://www.yourcompany.com or https://*.yourcompany.com, where yourcompany.com is the actual web address of your marketplace. On live, only the HTTPS protocol is supported.
   product		The type of product the component belongs to. 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 Reports Overview Component: View.	_

   Here is an example request for creating a session token.

   Create a session token

   Expand view

   Copy link to code block

   Copy code

   Copy code

   curl https://test.adyen.com/authe/api/v1/sessions \
   -H 'content-type: application/json' \
   -H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \
   -D '{
      "allowOrigin":"YOUR_DOMAIN",
      "product":"platform",
      "policy": {
         "resources": [
           {
               "accountHolderId": "AH00000000000000000000001",
               "type": "accountHolder"
           }
         ],
         "roles": [
           "Reports Overview Component: View"
         ]
      }
   }'

2. Note the API response. Later, when initializing the component, you need to create and call a function that passes the entire session object from the response to your front end.

   Session token created

   Expand view

   Copy link to code block

   Copy code

   Copy code

   {
     "id": "EC1234-1234-1234-1234",
     "token": "xxxxx.yyyyy.zzzzzz"
   }

2. Install component library in your front end

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

1. Install the npm package.

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

2. Import the library, the component, and the style sheet.

   Copy code
   import { AdyenPlatformExperience, ReportsOverview } from '@adyen/adyen-platform-experience-web';
   import "@adyen/adyen-platform-experience-web/adyen-platform-experience-web.css";

3. Initialize component

To initialize the component:

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

   1. Gather these parameters to initialize the library.

      Parameter	Required	Description
      availableTranslations		An array containing the names of the imported locale files used for localizing the component. For example, [es_ES, nl_NL, fr_FR].
      environment		Specifies the environment for the component integration. The default value is test. Set the parameter to live when you are ready to go live.
      locale		Specifies the locale code, which determines the desired language of the component. This code must correspond to one of the locale files listed in availableTranslations. For example, use es-ES for Spanish.
      onSessionCreate		The callback function that retrieves an authentication session token and refreshes the current session.

   2. Gather these parameters to initialize the component.

      Parameter	Required	Description
      allowLimitSelection		Determines whether the user can change the number of report records shown per page. Default value: true.
      balanceAccountId		Set this parameter to a specific balance account ID to show reports for the given account only. If specified, the Balance Account filter will be hidden.
      core		The instance of the library.
      dataCustomization		Available from library version 1.4.0. An object that contains both the list and details objects, which include customization specifications for dashboard fields, allowing for additional data integration from your database.
      hideTitle		Determines whether to show the component title Reports. Default value: false. Set this to true to hide the component title.
      onContactSupport		The callback function triggered when an error occurs on the reports table. If the function is defined, the component will show the default error screen, which includes the error code ID and a contact support button. You can provide the URL to which you want to redirect the user when they click the button. For example, onContactSupport: () => {window.open('https://your-platform-domain/support');}
      onError		The callback function triggered when an error occurs on the reports table. You can define the function based on how you want to handle the errors. For example, you can log the errors on the console using onError: (error) => {console.log(error)}.
      onFiltersChanged		The callback function triggered when the user changes the filter selection. The function receives the current filter selection as an argument, including the balance account ID and time period.
      preferredLimit		The number of report records shown per page. Default value: 10.

2. Create a DOM element on your UI page where you want the component to be rendered and assign it a unique and descriptive ID. This unique ID is important to avoid any misconfigurations when integrating multiple components into your UI.

   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.

   Create DOM element

   Expand view

   Copy link to code block

   Copy code

   Copy code

   <div id="reports-overview-container"></div>

3. Add a function that calls your API to retrieve and refresh an authentication session token.

   Add function to retrieve and refresh an authentication session token

   Expand view

   Copy link to code block

   Copy code

   Copy code

   async function handleSessionCreate() {
      const response = await fetch('YOUR_IMPLEMENTATION_OF_CREATE_SESSION_ENDPOINT');
      return response.json();
   }

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.

   Initialize library and create component

   Expand view

   Copy link to code block

   Copy code

   Copy code

   import { AdyenPlatformExperience, ReportsOverview } from '@adyen/adyen-platform-experience-web';
   import "@adyen/adyen-platform-experience-web/adyen-platform-experience-web.css";
    
   const core = await AdyenPlatformExperience({
       onSessionCreate: handleSessionCreate,
   });
   const reportsOverview = new ReportsOverview({ core });
    
   reportsOverview.mount('#reports-overview-container');

   In this step, you can also configure the component to use one of the supported languages.

   Update your code for initializing components to include the localization settings. If no localization settings are provided, the components will default to English.

   Localize component

   Expand view

   Copy link to code block

   Copy code

   Copy code

   import { AdyenPlatformExperience, es_ES, nl_NL, fr_FR, all_locales } from '@adyen/adyen-platform-experience-web';
   // ...
    
   // Only selected languages are available
   const core = await AdyenPlatformExperience({
       availableTranslations: [es_ES, nl_NL, fr_FR],
       locale: 'es-ES', // You can also set this to nl-NL, fr-FR, or en-US (default)
       // ....
   })
    
   // All supported languages are available
   const core = await AdyenPlatformExperience({
       availableTranslations: [all_locales],
       locale: 'es_ES' // You can also set this to any of the supported languages
       // ....
   })

4. (Optional) Customize component appearance

The reports component has 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 settings:

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 component. 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 modal window from a pop-up window to a side panel view.

:root {
    --adyen-sdk-border-radius-s: 10px;
    --adyen-sdk-border-radius-m: 20px;
    --adyen-sdk-border-radius-l: 30px;
    --adyen-sdk-color-background-disabled: #9ecdb1;
    --adyen-sdk-color-background-inverse-primary: #0abf53;
    --adyen-sdk-color-background-inverse-primary-hover: #57d389;
    --adyen-sdk-color-decorative-blue: #0abf53;
    --adyen-sdk-color-outline-primary-active: #0abf53;
}

5. (Optional) Customize component data

The reports component allows you to include a diverse range of data types and sources to showcase within your user dashboard. You can:

• Integrate custom data, such as your own fields, icons, links, and buttons.
• Define the settings for each dashboard field, including their names and visibility.

When initializing your component:

1. Specify the dataCustomization parameter, including:

   Parameter	Required	Description	Example
   list		An object that includes customization settings for dashboard fields in the reports overview.	dataCustomization: { list: { } }

2. Within the list and/or details objects, define the customization settings, such as field names or visibility.
   Be sure to include all default fields. If you add custom fields, they will be positioned immediately after the default fields in the dashboard.

   Parameter	Required	Description	Example
   fields		Defines the settings of dashboard fields in the reports overview. Default fields: 'createdAt', 'dateAndReportType', 'reportType', 'reportFile'.	dataCustomization: { list: { fields: [] } details: { fields: [] } }
   onDataRetrieve		The callback function that retrieves a Promise object resolved with an array of extended records and custom data. Required if adding a custom field.	dataCustomization: { list: { fields: [], onDataRetrieve: () => { } } details: { fields: [], onDataRetrieve: () => { } } }

   1. Define the settings for each dashboard field using the following parameters.

      Parameter	Type	Required	Description	Example
      align	String		Determines how the content in a field is aligned. Possible values: left, center, right. If not specified, it defaults to left.	{ key: 'amount', align: 'right' }
      flex	Number		Determines the width of a field in relation to other fields. It uses a numeric value that represents the flex-grow factor in the CSS Flexbox layout. A higher value means that the field occupies more space compared to others. If not specified, it defaults to 1.	{ key: '_store', flex: 2 }
      key	String		Specifies the name of a field. To prevent conflicts with the default field names, always start the names of your custom fields with an underscore (_) character.	fields: [ { key: '_store' }, { key: '_product' } ]
      visibility	String		Determines whether a field should be shown or not. Possible values: visible, hidden. If not specified, it defaults to visible.	{ key: 'amount', visibility: 'hidden' }

   2. If adding a custom field, you must include the onDataRetrieve parameter.

      `onDataRetrieve` parameter

      Expand view

      Copy link to code block

      Copy code

      Copy code

      onDataRetrieve: async (data: Reports) => {
          const ids = data.map(report => report.createdAt);
       
          const additionalData = await getMyDataByIds(ids);
       
          return additionalData;
      },

      Make sure to include the received data object in the return object by using the spread syntax. The component can then use this as matching keys to map your custom data with the existing one.

      `additionalData` object

      Expand view

      Copy link to code block

      Copy code

      Copy code

      const fields: [
          { key: '_summary' },
          { key: '_sendEmail' },
      ];
       
      function onDataRetrieve(data: Report) {
          return [
              {
                  ...data,
                  _summary: {
                      value: 'Summary',
                      type: 'link',
                      config: {
                          href: CUSTOM_URL_EXAMPLE,
                      },
                  },
                  _sendEmail: {
                      type: 'button',
                      value: 'Send email',
                      config: {
                          action: () => sendEmail(),
                      },
                  }
              }
          ];
      }

   3. Specify the type of your custom data.

      Parameter	Type	Required	Description
      type	String		Determines how the custom data value should look and behave. Possible values: text, icon, link, button. If not specified, it defaults to text.

      TextIconLinkButtonTextIconLinkButton

      `text` data type

      Expand view

      Copy link to code block

      Copy code

      Copy code

      const fields: [{key: _store}]
       
      function onDataRetrieved() {
          return [
                 {_store: { value: 'New york', type: 'text',  config: { className: 'my-value' } } ,
                 {_store: { value: 'New york', type: 'text',  config: { className: 'my-value my-value--strong' } } ,
                 ];
          }

   Here is an example dataCustomization object:

   Example `dataCustomization` object

   Expand view

   Copy link to code block

   Copy code

   Copy code

   {
       dataCustomization: {
           list: {
               fields: [
                   { key: 'reportType', visibility: 'hidden' },
                   { key: '_summary' },
                   { key: '_sendEmail', align: 'right' },
                   { key: 'reportFile', flex: 0.8 },
               ],
               onDataRetrieve: reports => {
                   return getCustomReportsData(reports);
               },
           },
       },
   }

3. If you are localizing components, remember to include translations for your custom fields in the library initializer.

   `translations` object

   Expand view

   Copy link to code block

   Copy code

   Copy code

   const core = await AdyenPlatformExperience({
       translations: {
           en_US: {
               _summary: 'Summary',
               _sendEmail:'Send email',
           },
           es_ES: {
               _summary: 'Resumen',
               _sendEmail: 'Enviar correo electrónico',
           },
       }
   });

See also