# Transaction Aggregation
source: https://developer.mastercard.com/open-finance-au/documentation/products/transaction-agg/index.md

Tip: Accessing user data (account data, transactions, reports, etc.) requires user consent. For more about consent please check the [consent](https://developer.mastercard.com/open-finance-au/documentation/consent/index.md) page.

## Overview {#overview}

Use transaction aggregation to access transaction data from customer accounts.

Newly added customer accounts require a successful refresh before transaction data will be available. The refresh will occur automatically during Mastercard's overnight batch process, or a manual refresh can be performed by using the refresh endpoints if more recent data is required.

## How It Works {#how-it-works}

The accounts that a customer grants access to during the Connect flow determine what data you can access. The transaction data returned depends on the type of account.

1. Generate the required credentials to call the API. See [Create a Sandbox Project](https://developer.mastercard.com/open-finance-au/documentation/quick-start-guide/index.md#create-a-sandbox-project).
2. Generate an Access Token. See [Create Access Token](https://developer.mastercard.com/open-finance-au/documentation/quick-start-guide/index.md#step-1---create-access-token).
3. Create a customer and link them to at least one account via [Connect](https://developer.mastercard.com/open-finance-au/documentation/connect/index.md).
4. Request initial aggregation of transaction data.
   API Reference: `POST /aggregation/v1/customers/{customerId}/institutionLogins/{institutionLoginId}/accounts`

   When the first time aggregation occurs we retrieve the last 6 months worth of transaction data from the Financial Institution.
5. Retrieve transactions for all accounts or for a particular account.
   API Reference: `GET /aggregation/v2/customers/{customerId}/transactions/{transactionId}`


   API Reference: `GET /aggregation/v3/customers/{customerId}/transactions`

   Every night we aggregate transactions for all customer accounts. We recommend retrieving the last several days of transactions as sometimes transactions can be posted slightly delayed from their posted date. With the transaction ID, you can identify transactions you have already retrieved versus the new transactions.

Note: Ensure accounts are correctly aggregating with an aggregationStatusCode equal to 0 and a recent aggregationSuccessDate timestamp. Refresh may be unsuccessful if an account is not indicated as ready for aggregation.

## Understanding Transactions {#understanding-transactions}

Transaction records will have a posted transaction date, amount, description or memo. Other transaction fields will be present based on the account type and based on the availability of the data point at the Financial Institution. We will also include a normalized payee and categorization data for the transaction. You can see more details about the structure of a transaction, transaction types, and other models by opening the endpoint dropdowns below and visiting the **Model** tab.

API Reference: `GET /aggregation/v3/customers/{customerId}/accounts/{accountId}/transactions`

## Load Historic Transactions {#load-historic-transactions}

The Load Historic Transactions for Customer Account endpoint can be used to request additional aggregation of historical transaction data beyond the 6 month period normally retrieved. The availability of additional transaction data is dependent on your environment configuration and enabled products - please contact your solution engineer to determine the availabile transaction data history.

API Reference: `POST /aggregation/v1/customers/{customerId}/accounts/{accountId}/transactions/historic`

Note: This service requires the HTTP header `Content-Length: 0` to be included in the request because it is a POST request with no body.

The recommended timeout setting for this request is `180 seconds` in order to receive a response. However, you can terminate the connection after making the call and the operation will still complete. You will have to pull the account records to check for an updated aggregation attempt date to know when the refresh is complete.

The date range sent to the institution is calculated from the account's `createdDate`. This means that calling this service a second time for the same account normally will not add any new transactions for the account. For this reason, a second call to this service for a known accountId will usually return with `HTTP 204`. In a few specific scenarios, it may be desirable to attempt a second call. Some examples are:

* The institution's policy has changed, making more transactions available.
* We added a longer transaction history support for the institution.
* The first call encountered an error, and the resulting Aggregation Ticket has now been fixed by the Support Team.
* In these cases, the POST request can contain the parameter `force=true` in the request body to force the second connection.

## Pending Transactions {#pending-transactions}

A pending transaction is a transaction that has been initiated but has not been cleared or posted by the institution. For many institutions, we are now able to capture pending transactions when they are displayed or provided in the institution's data.

Pending transactions are ephemeral. Each connection to an institution will capture pending transactions that are available at that time; if any of those transactions are not found in a subsequent connection, they will be deleted from the data. In other words, an account will show the set of pending transactions which were found in the most recent aggregation of the account. Older pending transactions may disappear, and new transactions may appear.

There is no guarantee of continuity for transactions that move from pending to posted at the institution. When an institution changes a transaction from pending to posted, the pending transaction may disappear in our data, and a new transaction with status active may appear. In some circumstances (depending on the institution), the status of the original transaction in the data may just change from pending to active.

"Pending" transactions are identified in the transaction record, like this:
* Response

```Response
"transactions": [
  {
    "id": 102122887150,
    "amount": 3678.9,
    "accountId": 1014136057,
    "customerId": 1005061234,
    "status": "pending",
  ...
```

## Shadow Transactions {#shadow-transactions}

Some institutions continue to modify or delete transactions long after they are first posted to the institution's data feed. This practice can cause transactions to appear as duplicates, or to continue to appear in the data after they have disappeared from the institution's current website.

We've added the ability to identify transactions that were found in an earlier aggregation of an account, but are not found in the institution's current data source. These shadow transactions are identified in the transaction record, like this:
* Response

```Response
"transactions": [
  {
    "id": 102122887150,
    "amount": 3678.9,
    "accountId": 1014136057,
    "customerId": 1005061234,
    "status": "shadow",
  ...
```