# Transaction Data
source: https://developer.mastercard.com/open-finance-us/documentation/products/manage/transaction-data/index.md

The Transaction Data Services provide account transaction data. Options vary depending on the length of transaction history required, and data refresh schedule.

Newly added customer accounts require a successful [refresh](https://developer.mastercard.com/open-finance-us/documentation/products/manage/account-aggregation/data-refresh/index.md) 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. Ensure you use the correct refresh endpoint depending on whether you are using data access tiers or not.

Although Transaction Aggregation data refreshes daily, you may sometimes need more recent data. Transaction Aggregation can be refreshed using the endpoints described in [Data Refresh](https://developer.mastercard.com/open-finance-us/documentation/products/manage/account-aggregation/data-refresh/index.md). After initiating the refresh endpoint, use Transaction Aggregation to retrieve any new transactions.

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.

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

The accounts that a customer grants access to during the Mastercard Data Connect flow determine what data you can access. The transaction data returned depends on the account type of the `accountId` referenced in the API call.

1. Generate the required credentials to call the API. See [Create a Sandbox Project](https://developer.mastercard.com/open-finance-us/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-us/documentation/quick-start-guide/index.md#step-1---create-access-token).
3. Create [a customer](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#welcome-your-first-customer) and [link them to at least one account via Connect](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#step-3---generate-mastercard-data-connect-url). See the different [Test Profiles](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md#bank-account-profiles) and account types available to test with.
4. You can now use the Transaction Data Services below for that customer.

## Transaction Data Services {#transaction-data-services}

After a customer has added accounts in Data Connect, transaction data can be retrieved using one of two Transaction Data Services.

* If you are using Data Access Tiers, you can use the Account Transaction Details (ATD) service (Tier 3)
* If you prefer a standalone service, you can subscribe to Transaction Aggregation (TAU)

The transaction details in the response, including Mastercard transaction categorization data, may vary depending on the account type and institution.
Warning: To accurately identify a specific transaction, best practice is to ensure you use the unique transaction ID (`uniqueTransactionId`) which is returned as part of the transaction data, rather than the simple transaction ID value (`id`).

This avoids any potential problems caused by the same transaction ID being used with more than one customer (you could also ensure such problems do not occur by ensuring you check both the `id` and `accountId` values.)

### Account Transaction Details (ATD) or Transaction Aggregation (TAU) {#account-transaction-details-atd-or-transaction-aggregation-tau}

ATD (Data Access Tier 3) and TAU (standalone) both provide historical transaction data for up to 180 days in addition to the full account data included in AFD (Tier 2) or ALA (standalone).

The transaction data is refreshed daily with the previous 15 days to accommodate any changes made to transactions reported earlier by the financial institutions. This standard 15 day transaction refresh window is called the Transaction Lookback Period, and may be longer for certain liability account types.

#### Get Customer Account Transactions {#get-customer-account-transactions}

Use Get Customer Account Transactions to retrieve transaction data from one of a customer's accounts.

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

#### Get Customer Transaction by Unique ID {#get-customer-transaction-by-unique-id}

Use Get Customer Transaction by ID to retrieve data from a specific transaction.

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

#### Get All Customer Transactions {#get-all-customer-transactions}

Use Get All Customer Transactions to retrieve transaction data from all of a customer's accounts, within a specified date range. This endpoint supports paging up to 1,000 records per request. If the value of `moreAvailable` in the response is `true`, the next page of results can be retrieved by increasing the value of the start parameter in the next request.

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

The transaction response is sorted based on the following hierarchy of date availability:

|                          Logic                          |  Sorting Value  |
|---------------------------------------------------------|-----------------|
| transactionDate is provided                             | transactionDate |
| transactionDate is not provided, postedDate is provided | postedDate      |
| transactionDate and postedDate are not provided         | effectiveDate   |

There is no maximum window between fromDate and toDate; however, the transactions that are returned after the initial aggregation are limited by the standard 180 day aggregation window, the financial institution, and the max 1,000 records. A minimum time period of 15 days, or otherwise matching the length of the Transaction Lookback Period, is recommended to pick up any changes to previously reported transactions. To extend the standard 180 day aggregation window, use the Load Historic Transactions endpoint, and then use the Get Customer Transactions All endpoint again.

Best practice is to pull Transaction Aggregation data daily to maintain current data. Another option is to subscribe to [TxPUSH](https://developer.mastercard.com/open-finance-us/documentation/products/manage/tx-push/index.md) notifications, which allows Mastercard to send changes to Transaction Aggregation data to the Partner's event listener. If you are caching transaction data use the transaction ID along with the `accountId` or `customerId` when querying cached data. This avoids any potential problems caused by the same transaction ID being used with more than one customer. It is common for traditional financial institutions to alter transaction data as far back as 15 days, to resolve balance changes, pending status, transaction errors, etc.

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

This service provides historical transaction data for up to 24 months, depending on the account type and whether the financial institution has made this level of historic data available. This service does not include a daily refresh or TxPUSH notifications; however, data may be refreshed by calling the endpoint again.

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

After using the endpoint, use [Get Customer Account Transactions](https://developer.mastercard.com/open-finance-us/documentation/products/manage/transaction-data/index.md#get-customer-account-transactions) or [Get All Customer Transactions](https://developer.mastercard.com/open-finance-us/documentation/products/manage/transaction-data/index.md#get-all-customer-transactions) to retrieve the data.