Adyen-for-platform icon

Transaction components

Let users view their transactional data using Platform Experience components.

You can use the transaction components to offer your users an interactive dashboard that shows their transactional data. With this dashboard, users can view and filter transactions for any of their balance accounts.

This page provides information on:

  • The available transaction components, which include the Transactions Overview component and the Transaction Details component with optional refund feature.
  • The steps needed to integrate these components into your platform.

Transactions Overview component

The Transactions Overview component shows a list of transactions processed for a specific balance account within a specified time period. Each transaction record includes details such as the date and time, payment method, transaction type, and amount.

The Transactions Overview component enables users to complete the following tasks:

  • View a list of transactions for a balance account.
  • Filter transactions by their type, amount, currency (for multi-currency accounts), and time period. See the available filters for more details.
  • View the total incoming and outgoing funds of the balance account. The total values are updated automatically whenever the user modifies the filters. For example, users may choose to filter out the total booked incoming and outgoing funds that were processed during the past month.
  • View the available balance of the balance account.

By default, the Transactions Overview component includes the Transaction Details component, which provides more details about a specific transaction.

Available filters

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

Users with multiple balance accounts can switch between them using the Balance Account filter.

The Time period filter specifies the date and time range for displaying transaction results. The specified time is determined by the time zone of the selected balance account.

Filter value
 Description
Last 7 days Includes transactions from the previous six days and from today until the current time. For example, if today is a Tuesday and the time is 8:00 PM, transactions from the previous Wednesday midnight until this Tuesday 8:00 PM are included.
This week Includes transactions for the current week, starting from Monday midnight until the present moment.
Last week Includes transactions from Monday midnight to Sunday 11:59:59 PM of the previous week.
Last 30 days The default setting. Includes transactions from the previous 29 days and from today until the current time.
This month Includes transactions for the current month, starting from the first day of the month until today's date.
Last month Includes transactions from the previous month, starting from the first day of the month until the end of the month at 11:59:59 PM.
Year to date Includes transactions from the first day of the current year up until today's date.
Custom Allows setting a custom time period.

The Type filter specifies which transaction types to show in the overview. The table below lists the available transaction types in the component along with their corresponding values returned in the Transfers API.

Filter value
 Value in the Transfers API
ATM atmWithdrawal, atmWithdrawalReversal.
Capital grant, repayment.
Correction manualCorrection, depositCorrection, leftover, balanceAdjustment, balanceRollover, installmentReversal, captureReversal, refundReversal, chargebackReversal , chargebackCorrection, chargebackReversalCorrection, secondChargebackCorrection, reserveAdjustment.
Fee fee, miscCost, paymentCost, cashOutFee.
Payment payment, capture, installment.
Refund refund
Chargeback chargeback, secondChargeback.
Transfer bankTransfer, internalTransfer, cardTransfer.
Other Includes all other transaction types.

The filter enables users to filter transactions by specifying a custom amount range.

For multi-currency accounts, users can select their preferred currency for transactions overview.

Transaction Details component

The Transaction Details component provides detailed information about a transaction, including its unique reference ID, the original amount, and any associated fees. For payment transactions, this component indicates whether a specific payment has been refunded. Additionally, it enables users to refund payments to their shoppers.

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

Processing refunds through the components

The refund feature is available starting from library version 1.2.0. It requires the Transactions Overview Component: Manage Refunds role to be assigned to your API credential and included in the session request.

Users can refund payments to their shoppers through the transaction components. When a user initiates a refund, the components automatically call Adyen's API to process the refund request. This means that no additional actions are needed on your part as a platform.

The transaction components support both full and partial refunds depending on the payment method. For partial refunds, users can issue multiple smaller refunds through the components, as long as the total amount of these refunds does not exceed the original payment amount.

The user flow for processing a refund through the components is as follows:

  1. In the payment details, the user selects the Refund payment button.
  2. In the Refund payment modal window, the user specifies a reason for the refund and the refund amount.
  3. The user confirms their refund request.
  4. After the refund request is processed, users can view the refund status message and label in the payment details.

The following tabs illustrate the user flow when processing a partial refund for a specific payment transaction:

After the refund has been issued and processed, users can view the refund transaction in their overview. Each refund transaction is linked to the corresponding payment transaction, making it easy for users to find relevant references and navigate between transaction records.

Requirements

Before integrating the components, make sure that you:

  • Followed the Get started guide to create your test account.
  • Created API credentials for the Configuration API or the Transfers API.
  • Asked your Adyen contact to assign the following roles to your API credential:
    • Transactions Overview Component: View
    • Transactions Overview Component: Manage Refunds (available from library version 1.2.0 and required to process refunds through the components)
  • Verified that the components are available in the languages and browser versions that apply to your situation.

How it works

Follow these steps to integrate the transaction 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 Transactions Overview Component: View role in your Customer Area.
    To enable users to process refunds through the components, ensure that your API key also has the Transactions Overview Component: Manage Refunds role.
    For more information, refer to the Requirements section.

    Parameter Required Description
    allowOrigin -white_check_mark- 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.
    An asterisk (*) cannot be used as a literal value for the parameter.
    product -white_check_mark- The component type. Set this to platform.
    policy -white_check_mark- 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 Transactions Overview Component: View.
      To enable users to process refunds through the components, also include the Transactions Overview Component: Manage Refunds role in your request. Available from library version 1.2.0.

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

    2. Gather these parameters to initialize each component.

      Select the tab for the component you want to use:

  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.

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

  3. Add a function that calls your API to generate a new authentication session token..

    The following code is the same for both transaction components.

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

    To implement the Transaction Details component as a modal window within the Transactions Overview component, use the following code examples. In this implementation, when a user selects a specific transaction from the overview page, the transaction ID is automatically passed to the Transaction Details component, and the modal window opens.

    Select the tab for the component you want to use:

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

Step 4: (Optional) Customize the components

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

See also