Payout components

To help your users reconcile their payouts, you can integrate payout components into your platform's user interface (UI). These components offer a dashboard view of completed payouts for each user's balance account. Your users can use this information to match the payouts they receive in their bank account with the batches of payments and other related transactions.

The payout components are designed for users who receive automatic payouts. Unlike on-demand payouts, automatic payouts are initiated by Adyen based on your configured rules. This enables the payout components to show all relevant debit and credit transactions for the balance account.

This page provides information on:

• The available payout components, which include the Payouts Overview component and the Payout Details component.
• The steps needed to integrate these components into your platform.

Payouts Overview component

The Payouts Overview component shows a list of automatic payouts completed for a specific balance account within a specified time period. Each payout record includes details such as the date and time, funds captured, total adjustments, and net payout. Additionally, the component allows for custom data integration, such as your own fields, icons, links, and buttons.

The funds captured represent the initial amount in the balance account on the day when a payout is initiated. This amount may be adjusted due to factors like fees, commissions, refunds, business financing, or internal funds transfers. The component presents these adjustments in an aggregated view. If you need to provide your users with a detailed breakdown of the payout adjustments, refer to the Payout Details component.

After being adjusted, the funds captured amount results in the net payout amount, which is the final amount credited to the user's bank account.

All amounts are shown in the currency of the chosen balance account.

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

The Payouts Overview component enables users to:

• View a list of automatic payouts completed for a balance account, including funds captured, adjustments, and net payout amounts per payout.
• Filter payouts by time period and balance account (if applicable). See the available filters for more details.

By default, the Payouts Overview component includes the Payout Details component, which provides more details about a specific payout.

Available filters

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

Payout Details component

The Payout Details component shows specific information about a payout, including the date and time, breakdown of captured funds and adjustments, and the net payout amount. If there are any remaining funds in the balance account after the payout is completed, they will also be shown in the component. Additionally, the component allows for custom data integration, such as your own fields, icons, links, and buttons.

By default, the Payout Details component is embedded in the Payouts Overview component and is shown as a modal window on the overview page. You can also choose to show the Payout Details component on a separate page during the initialization of the components.

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

Requirements

How it works

Follow these steps to integrate the payout components:

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 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 Payouts 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 platform. On live, only the HTTPS protocol is supported.
   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 Payouts Overview Component: View.
   product		The type of product the component belongs to. Set this to platform.

   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": [
           "Payouts Overview Component: View"
         ]
      }
   }'

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.

   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 components, and the style sheet.

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

3. Initialize 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
      availableTranslations		An array containing the names of the imported locale files used for localizing the components. 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 components. 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 each component.

      Select the tab for the component you want to use:

      Payouts Overview componentPayout Details componentPayouts Overview componentPayout Details component

      Parameter	Required	Description
      allowLimitSelection		Determines whether the user can change the number of payouts shown per page. Default value: true.
      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.
      onRecordSelection		If defined, the event allows obtaining the payout date and the corresponding balance account ID when the user selects a specific payout from the overview. You can use the obtained values to show the Payout Details component in a different location within your UI, outside the Payouts Overview component.
      preferredLimit		The number of payouts shown per page. Default value: 10.

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 Payout Details component is shown as a modal window within the Payouts Overview component. In this scenario, you only need to create a DOM element for the Payouts Overview component. If you want to use the Payout Details component on its own, 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:

   Payouts Overview componentPayout Details componentPayouts Overview componentPayout Details component

   Create DOM element

   Expand view

   Copy link to code block

   Copy code

   Copy code

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

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

   The following code, including the role, is the same for both payout components.

   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.

   To implement the Payout Details component as a modal window within the Payouts Overview component, use the following code examples. In this implementation, when the user selects a specific payout from the overview page, the payout date and the corresponding balance account ID are automatically passed to the Payout Details component, and the modal window opens.

   Select the tab for the component you want to use:

   Payouts Overview componentPayout Details componentPayouts Overview componentPayout Details component

   Initialize library and create component

   Expand view

   Copy link to code block

   Copy code

   Copy code

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

   To use the Payout Details component outside of the Payouts Overview component, define the onRecordSelection event as shown below.

   Payouts Overview componentPayout Details componentPayouts Overview componentPayout Details component

   Define `onRecordSelection` event

   Expand view

   Copy link to code block

   Copy code

   Copy code

   const payoutsOverview = new PayoutsOverview({
       core,
       onRecordSelection: ({ id, date }) => {
       }
   });

   In this step, you can also configure the components 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 components

   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 payout 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 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 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 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 payout components allow 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:

   Payouts Overview componentPayout Details componentPayouts Overview componentPayout Details component

   Parameter	Required	Description	Example
   list		An object that includes customization settings for dashboard fields in the payouts overview.	dataCustomization: { list: { } }
   details		An object that includes customization settings for dashboard fields in the payout detail view.	dataCustomization: { list: { } details: { } }

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.

   Payouts Overview componentPayout Details componentPayouts Overview componentPayout Details component

   Parameter	Required	Description	Example
   fields		Defines the settings of dashboard fields in the payouts overview. Default fields: 'createdAt', 'fundsCapturedAmount', 'adjustmentAmount', 'payoutAmount'.	dataCustomization: { list: { fields: [] } details: { fields: [] } }
   onDataRetrieve		The callback function that retrieves a Promise object resolved with an array of extended records and custom data.	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: Payouts) => {
          const ids = data.map(payout => payout.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: Payout) {
          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:

   Payouts Overview componentPayout Details componentPayouts Overview componentPayout Details component

   Example `dataCustomization` object

   Expand view

   Copy link to code block

   Copy code

   Copy code

   {
       dataCustomization: {
           list: {
               fields: [
                   { key: 'adjustmentAmount', visibility: 'hidden' },
                   { key: '_summary' },
                   { key: '_country', flex: 0.5 },
                   { key: '_sendEmail', align: 'right' },
               ],
               onDataRetrieve: payouts => {
                   return getCustomPayoutsData(payouts);
               },
           },
           details: {
               fields: [{ key: '_summary' }, { key: '_country' }, { key: '_sendEmail' }],
               onDataRetrieve: payout => {
                   return getCustomPayoutsDataById(payout);
               },
           },
       },
   }

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