# Understanding Transaction Data source: https://developer.mastercard.com/open-finance-us/documentation/products/manage/transaction-data/understanding-transaction-data/index.md [Transaction Data](https://developer.mastercard.com/open-finance-us/documentation/products/manage/transaction-data/index.md) provides detailed information about a specific account transaction. The data that is returned includes a transaction ID which when used on its own is not enough to accurately identify a transaction as this ID may not always be unique. If you are caching transaction data, you will therefore need to ensure you use the transaction ID along with an `accountId` or `customerId` when querying that cached data. This avoids any potential problems caused by the same transaction ID being used with more than one customer. The **Get Customer Transaction by ID** API takes both the `customerId` and transaction ID as a query parameter which returns specific transaction data. ## Transaction Data By Segment {#transaction-data-by-segment} There is one important difference in the way inflows and outflows are represented for different account types, in traditional transaction data such as for a checking account, a positive amount (credit) corresponds to inflow (salary), while a negative amount corresponds to outflow (paying a bill). However, with investment account or credit card transaction data this convention is the opposite, inflows are negative (stock sales / paying down a balance on credit card) and outflows are positive (stock purchases / purchase on a credit card). * Deposit * Line-of-Credit * Investment * Mortgage-Loans * Student-Loans ```Deposit { "found": 1, "displaying": 1, "moreAvailable": false, "fromDate": 1607450357, "toDate": 1607450357, "sort": "desc", "transactions": [ { "id": 21284820852, "amount": -54.42, "accountId": 5011648377, "customerId": 1005061234, "status": "active", "description": "Costco Gas Stations", "memo": "FIP COSTCO GAS 137 COSTCO GAS 137 EAST LYME CT9325", "type": "debit", "transactionDate": 1607450357, "createdDate": 1607450357, "checkNum": 589478, "feeAmount": 0.00, "interestAmount": 0.00, "categorization": { "normalizedPayeeName": "Costco Gas", "category": "Gas & Fuel", "bestRepresentation": "COSTCO GAS STATIONS FIP COSTCO GAS COSTCO GAS EAST LYME CT", "country": "USA", }, "runningBalanceAmount": 1521.48, "currencySymbol": "USD" } ] } ``` ```Line-Of-Credit { "found": 1, "displaying": 1, "moreAvailable": false, "fromDate": 1607450357, "toDate": 1607450357, "sort": "desc", "transactions": [ { "id": 21284820852, "amount": -20.04, "accountId": 5011648377, "customerId": 1005061234, "status": "active", "description": "EBAY", "memo": "EBAY O 22-10785-01239 SAN JOSE CA", "type": "debit", "createdDate": 1607450357, "transactionDate": 1607450357, "categorization": { "normalizedPayeeName": "Ebay", "category": "Shopping", "country": "USA", "bestRepresentation": "Ebay San Jose CA" } } ] } ``` ```Investment { "found": 1, "displaying": 1, "moreAvailable": false, "fromDate": 1607450357, "toDate": 1607450357, "sort": "desc", "transactions": [ { "id": 21284820852, "amount": -828.50, "accountId": 5011648377, "customerId": 1005061234, "status": "active", "description": "Buy Stock", "memo": "Purchase: NETFLIX COM INC CLIENT ENTERED. PRICE 390.000000", "type": "debit", "transactionDate": 1607450357, "postedDate": 1607450357, "createdDate": 1607450357, "optionExpireDate": 1607450357, "feeAmount": 0.00000000, "suspenseAmount": 0.25, "interestAmount": 132, "principalAmount": 32560, "optionStrikePrice": 10.00000000, "unitQuantity": 150.00000000, "unitPrice": 390.0000000, "runningBalanceAmount": 1000, "subaccountSecurityType": "MARGIN", "commissionAmount": 0.00000000, "ticker": "NFLX", "investmentTransactionType": "optionExercise", "taxesAmount": 0.00000000, "currencySymbol": "USD", "incomeType": "DIV", "splitDenominator": 152.00000000, "splitNumerator": 20.00000000, "sharesPerContract": 100, "subAccountFund": "MARGIN", "securityId": "316389303", "securityIdType": "CUSIP" } ] } ``` ```Mortgage-Loans { "found": 1, "displaying": 1, "moreAvailable": false, "fromDate": 1607450357, "toDate": 1607450357, "sort": "desc", "transactions": [ { "id": 21284820852, "amount": 1573.10, "accountId": 5011648377, "customerId": 1005061234, "status": "active", "description": "Payment Applied to OCT-01-23", "memo": "Payment", "type": "credit", "transactionDate": 1607450357, "postedDate": 1607450357, "createdDate": 1607450357, "escrowAmount": 459.58, "interestAmount": 2.52, "principalAmount": 210.73, "feeAmount": 41.68, "categorization": { "normalizedPayeeName": "Kwikpay", "category": "Loan Payment", "country": "USA", "bestRepresentation": "Kwikpay Loan" }, "runningBalanceAmount": -144.10, "effectiveDate": 1607450357, "firstEffectiveDate": 1607450357 } ] } ``` ```Student-Loans { "found": 1, "displaying": 1, "moreAvailable": false, "fromDate": 1607450357, "toDate": 1607450357, "sort": "desc", "transactions": [ { "id": 21284820852, "amount": 213.25, "accountId": 5011648377, "customerId": 1005061234, "status": "active", "description": "KwikPay", "memo": "Loan Payment", "type": "credit", "transactionDate": 1607450357, "postedDate": 1607450357, "createdDate": 1607450357, "suspenseAmount": 0.00, "interestAmount": 2.52, "principalAmount": 210.73, "feeAmount": 15.25, "categorization": { "normalizedPayeeName": "Kwikpay", "category": "Loan Payment", "country": "USA", "bestRepresentation": "Kwikpay Loan" }, "runningBalanceAmount": -144.10, "effectiveDate": 1607450357, "firstEffectiveDate": 1607450357 } ] } ``` ## Transaction Status {#transaction-status} The transaction status indicates the availability of the transaction from the financial institution. The status may be active, pending, or shadow. An individual transaction's status may fluctuate between these statuses, depending on the current reporting by the financial institution. * **Active Transactions** An active transaction is a transaction that is currently found on an institution's transaction record during the most recent refresh. * **Pending Transactions** A pending transaction is a transaction that has been initiated but has not been cleared or posted by the institution. Pending transactions are short-lived. Each refresh will capture all available pending transactions at the time; if any of those transactions are not found in a subsequent refresh, they will be removed from the transaction response. There is no continuity guarantee for transactions to move from pending to active. When an institution changes a transaction from pending to posted, the pending transaction may be updated to active, or may be marked as shadow and a new transaction record with an active status may appear. This behavior is determined by the financial institution's reporting. Pending transactions can only change to active or be removed from the response, they cannot change to shadow. * **Shadow Transactions** Mastercard added the ability to identify transactions found in an account in an earlier aggregation, but not in the institution's current data records. These "shadow" transactions have their status field set to `status: "shadow"`. A transaction record with a shadow status means the financial institution previously reported the transaction as `active`, but the transaction record was later removed from their reporting in a subsequent aggregation. It's also possible the financial institution does not provide unique IDs to identify the transaction, and has changed the transaction data from a previous reporting. These modifications or deletions can cause transactions to be duplicated in the Mastercard Open Finance data, or persist after being removed from the institution's data source. When Mastercard identifies such transactions they are designated with the "shadow" status. You can handle shadow transactions in one of the following ways: 1. Remove / do not display shadow transactions to the customer. 2. Display shadow transactions but provide the customer with a way to confirm whether the shadow transaction should be be removed or kept.
In most cases we recommend that you treat shadow transactions as though they have been deleted from the data source. ## Transaction Categorization {#transaction-categorization} Endpoints which return transaction data contain a `categorization` object which provides enriched data describing the transaction. ```json "categorization": { "normalizedPayeeName": "McDonald's", "category": "Fast Food", "city": "Clinton", "state": "SC", "postalCode": "", "country": "USA", "bestRepresentation": "checkcard mcdonalds clinton sc debit" } ``` When presenting transaction details in your user interface, prioritize the `normalizedPayeeName` field, which typically provides a clean and standardized merchant name that enhances readability and user comprehension. In some cases, `normalizedPayeeName` is unavailable or returns a placeholder value such as "No Entity Found". This can occur for internal transfers or ambiguous transactions. In these cases, you should display the `bestRepresentation` value which contains a description like "ATM Surcharge Rebate" to help your users understand the transaction.