# Transaction Enrichment source: https://developer.mastercard.com/open-finance-data/documentation/features/transaction-enrichment/index.md ### Overview {#overview} The Transaction Enrichment functionality enhances raw transaction data with categorisation, extracted entities, and enrichment that makes transactions easier to understand, categorise, and present in downstream experiences. All enrichment data is returned as part of the standard `GetTransactions` response, under a single `enrichment` object. Each transaction item may include an enrichment object alongside the original transaction fields. Conceptually, enrichment sits on top of the bank-provided transaction data. Nothing in the original transaction is modified or removed; enrichment adds clarity and structure based on analysis of the transaction text and related signals. Enrichment applies a structured taxonomy to each transaction, assigning a single super category, category, and subcategory that reflect the overall intent of the transaction. This consistent classification enables partners to group spending and income meaningfully across accounts, banks, and markets, while maintaining transparency and explainability. **All enrichment data is additive, leaving the original transaction details unchanged, and is designed to balance clarity, accuracy, and regulatory alignment.** ### Endpoints used {#endpoints-used} API Reference: `GET /accounts/{account_id}/transactions/{transaction_id}` API Reference: `GET /accounts/{account_id}/transactions` ### How to Use Enrichment: {#how-to-use-enrichment} The enrichment object contains five main components: 1. Metadata about the enrichment itself 2. A display name 3. A confidence score 4. A hierarchical category classification 5. One or more resolved real‑world entities Each is described in detail below. ##### Enrichment Metadata `enrichmentDate` {#enrichment-metadata-enrichmentdate} This timestamp indicates **when enrichment was applied** to the transaction. * It does not represent when the transaction occurred * It reflects processing time within the enrichment pipeline * It is always provided in a standard, UTC-based date‑time format Common uses include auditing refresh cycles, tracking data availability, and understanding enrichment recency. ##### Display Name {#display-name} A simplified, cleaned transaction text value derived only from existing transaction text inputs. The field removes common noise and preserves the most meaningful recognisable transaction descriptor while avoiding speculative or low-confidence merchant resolution. Banks often provide descriptions that are noisy or system‑formatted. `displayText` represents the best available, presentation‑ready name derived from that input. Typical uses include transaction lists, detail views, and search or filtering experiences. ##### Categorisation Confidence `categorisationConfidenceScore` {#categorisation-confidence-categorisationconfidencescore} This numeric score indicates how confident the enrichment service is in the assigned classification for that transaction. * Scores range from **0 to 100** * Higher values indicate greater certainty * Lower values indicate ambiguity or limited signals and may warrant cautious use, depending on your application Common uses include identifying low‑confidence transactions, driving fallback behavior, and monitoring quality. ##### Transaction-Level and Entity-Level Classification {#transaction-level-and-entity-level-classification} Each transaction maps to **exactly one** super category, category, and subcategory, ensuring clarity and mutual exclusivity at the transaction level. Every entity within the transaction is also assigned a super category, one category, and one subcategory. Every enriched transaction and entity is classified using a three‑level taxonomy: ```json }, "enrichment": { "enrichmentDate": "2026-02-22T17:42:11Z", "displayText": "McDonald's", "categorizationConfidenceScore": 100, "supercategory": { "id": "FDD_01", "text": "Food & Dining" }, "category": { "id": "PFD_01", "text": "Prepared Food & Dining" }, "subcategory": { "id": "FSF_01", "text": "Fast Food" }, "entities": [ { "id": "bXlkYXRhYmFzZTEyMw==", "name": "McDonald's", "supercategory": { "id": "FDD_01", "text": "Food & Dining" }, "category": { "id": "PFD_01", "text": "Prepared Food & Dining" }, "subcategory": { "id": "FSF_01", "text": "Fast Food" }, "websiteUrl": "https://www.mcdonalds.com" }, ``` 1. Supercategory -- a broad spending domain 2. Category -- a more specific grouping 3. Subcategory -- the most granular classification Each level includes a stable identifier\*, for reporting and logic, and a human‑readable label, for display. The transaction‑level classification represents the **overall intent of the transaction**. The entity‑level classification represents the intent of that entity. \*Identifier is added incrementally. ### Taxonomy and Availability {#taxonomy-and-availability} **Market availability:** Transaction Enrichment is currently available in Germany and France. All other EU countries are currently in Beta. Integrators typically use the taxonomy in three complementary ways: * **Display:** Use the labels (supercategory, category, subcategory) to group and label transactions consistently in user interfaces. * **Analytics and reporting:** Use the stable category structure to roll up spend, income, or activity across time, users, and products. * **Logic and workflows:** Use categories as inputs to rules or downstream processes (for example, filtering, alerts, or summaries), optionally considering the confidence score. The enrichment tier uses a standardised, customer‑facing taxonomy. There are **75 subcategories available today** across the enrichment taxonomy. All remaining subcategories are added incrementally. To learn more about the super categories, categories, and sub categories we have today, call the Category ID API. ### Field Reference {#field-reference} ##### Transaction Enrichment-- Field Reference {#transaction-enrichment-field-reference} | **Field** | \***Type** | **Required / Optional** | **Constraints** | **Description** | **Example** | |-------------------------------|---------------------------|-------------------------|------------------|----------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------| | `enrichmentDate` | string (date-time) | Required | ISO 8601 UTC | Timestamp when the transaction was enriched by Pipeline Gateway | 2026-02-22T17:42:11Z | | displayText | string | Required | --- | Cleansed, human-readable merchant name for UI display | McDonald's | | categorizationConfidenceScore | number (double) | Required | min: 0, max: 100 | ML confidence score for the assigned category. Values below 50 indicate low confidence | 100.0 | | supercategory | EnrichmentTaxonomyItem | Required | --- | Top-level taxonomy group | { id: "FDD_01", text: "Food \& Dining" } | | category | EnrichmentTaxonomyItem | Required | --- | Mid-level taxonomy group | { id: "PFD_01", text: "Prepared Food \& Dining" } | | subcategory | EnrichmentTaxonomyItem | Required | --- | Granular taxonomy classification | { id: "FSF_01", text: "Fast Food" } | | entities | array of EnrichmentEntity | Required | min 1 item | Resolved real-world entities. Single entity for most transactions; 2+ for delivery/marketplace platforms | See below | | location | --- | Optional | - | Location information extracted from the transaction text | "location": { "address": { "country": "FR", "locality": "Paris", "countrySubdivision": "IDF", "phoneNumber": "+33-1-23-45-67-89" | ##### EnrichmentTaxonomyItem {#enrichmenttaxonomyitem} Used for supercategory, category, subcategory --- at both transaction level and inside each entity. | **Field** | \***Type** | **Required / Optional** | **Constraints** | **Description** | **Example** | |-----------|------------|-------------------------|-----------------|----------------------------|-----------------| | Id\* | string | Required | --- | Stable taxonomy identifier | FDD_01 | | text | string | Required | --- | Human-readable label | Food and Dining | ##### EnrichmentEntity {#enrichmententity} One entry per resolved real-world business associated with the transaction. | **Field** | \***Type** | **Required / Optional** | **Constraints** | **Description** | **Example** | |---------------|------------------------|-------------------------|-----------------|-------------------------------------------------------------------------------------------|-----------------------------------------------------------------| | id | string | Required | base64-encoded | Unique entity identifier | bXlkYXRhYmFzZTEyMw== | | name | string | Required | --- | Display name of the entity | McDonald's | | supercategory | EnrichmentTaxonomyItem | Optional | --- | Entity-level taxonomy --- may differ from transaction-level for multi-entity transactions | { id: "FDD_01", text: "Food \& Dining" } | | category | EnrichmentTaxonomyItem | Optional | --- | Entity-level category | { id: "MKD_01", text: "Meal Kits \& Food Delivery" } | | subcategory | EnrichmentTaxonomyItem | Optional | --- | Entity-level subcategory | { id: "FDL_01", text: "Food Delivery (platforms or services)" } | | websiteUrl | string (uri) | Optional | Valid URI | Public website URL | | | logoUrl | string (uri) | Optional | Valid URI | URL to entity logo image | | \*id coming incrementally ### Example Response {#example-response} ```json { "count": 5, "offset": 7, "limit": 5, "total": 1000, "items": [ { "id": "dd24e14b-d5cc-4c3e-994e-c8bff7d3502c", "amount": 250, "currency": "EUR", "status": "BOOKED", "providerStatus": "booked", "type": "BANK_TRANSFER", "description": "SEPA Credit Transfer - Invoice 2025/0145", "providerTransactionId": "20250301-SEPA-987654", "date": "2025-03-01T09:45:00+01:00", "createdAt": "2025-03-01T09:45:00+01:00", "lastRefreshedAt": "2025-03-01T10:00:00+01:00", "balance": { "amount": 1750.5, "currency": "EUR", "lastRefreshedAt": "2025-03-01T10:00:00+01:00", "providerLastUpdatedAt": { "dateTime": "2025-03-01T10:00:00+01:00" } }, "additionalInformation": { "region": "EUROPE", "bookingDate": { "date": "2025-03-01" }, "valueDate": { "date": "2025-03-01" }, "merchantDetail": { "merchantName": "N/A", "merchantCategoryCode": "0000" }, "remittanceInformationUnstructured": "Payment for Invoice 2025/0145", "remittanceInformationStructured": "Invoice 2025/0145", "bankTransactionCode": "PMNT.CRED.TRF", "proprietaryBankTransactionCode": "ATM_WDL_INTL", "currencyConversion": { "originalCurrency": "EUR", "targetCurrency": "USD", "exchangeRate": 1, "quotationDate": { "dateTime": "2025-02-28T11:40:40Z" } }, "identifier": { "categoryPurposeCode": "SUPP", "paymentPurposeCode": "SUPP", "endToEndId": "SEPA2025-INV145-XYZ123", "reference": "INV-2025-0145", "sequenceNumber": "1" }, "source": { "name": "Joe Doe", "identifiers": [ { "type": "IBAN", "value": "DE89370400440532013000" } ], "address": { "description": "Account holder address", "type": "HOME_ADDRESS", "street": "Hauptstrasse 10", "buildingNumber": "10", "postalCode": "80331", "city": "München", "countrySubDivision": "Bavaria", "country": "Germany" }, "card": { "schemeName": "MasterCard", "authorizationType": "CONTACTLESS", "holderName": "Joe Doe", "maskedNumber": "**** **** **** 6543" } }, "destination": { "name": "ABC Consulting Ltd", "identifiers": [ { "type": "IBAN", "value": "FR7630006000011234567890189" } ], "address": { "description": "Business address", "type": "BUSINESS_ADDRESS", "street": "25 Rue de la République", "buildingNumber": "25", "postalCode": "75001", "city": "Paris", "countrySubDivision": "Île-de-France", "country": "France" } }, "ultimateDebtor": { "name": "Joe Doe", "address": { "description": "Account holder address", "type": "HOME_ADDRESS", "street": "Hauptstrasse 10", "buildingNumber": "10", "postalCode": "80331", "city": "München", "countrySubDivision": "Bavaria", "country": "Germany" }, "billerCode": "5967" }, "ultimateCreditor": { "name": "ABC Consulting Ltd", "address": { "description": "Business address", "type": "BUSINESS_ADDRESS", "street": "25 Rue de la République", "buildingNumber": "25", "postalCode": "75001", "city": "Paris", "countrySubDivision": "Île-de-France", "country": "France" }, "payeeCode": "4392" } }, "enrichment": { "enrichmentDate": "2026-02-22T17:42:11Z", "displayText": "McDonald's", "categorizationConfidenceScore": 100, "supercategory": { "id": "FDD_01", "text": "Food & Dining" }, "category": { "id": "PFD_01", "text": "Prepared Food & Dining" }, "subcategory": { "id": "FSF_01", "text": "Fast Food" }, "entities": [ { "id": "bXlkYXRhYmFzZTEyMw==", "name": "McDonald's", "supercategory": { "id": "FDD_01", "text": "Food & Dining" }, "category": { "id": "PFD_01", "text": "Prepared Food & Dining" }, "subcategory": { "id": "FSF_01", "text": "Fast Food" }, "websiteUrl": "https://www.mcdonalds.com" }, { "id": "kfeDMDkjkdaqweimJJ==", "name": "Deliveroo", "supercategory": { "id": "FDD_01", "text": "Food & Dining" }, "category": { "id": "MKD_01", "text": "Meal Kits & Food Delivery (platforms or services)" }, "subcategory": { "id": "FDL_01", "text": "Food Delivery (platforms or services)" }, "websiteUrl": "https://www.example.com" } ], "location": { "address": { "country": "FR", "locality": "Paris", "countrySubdivision": "IDF" } } } } ] } ``` Note: If a value is null in the public API response, the field is omitted entirely. ##### Summary {#summary} With Transaction Enrichment, each transaction includes a cleaned display text, a structured three‑level taxonomy classification, found entities, and a confidence score. The taxonomy above represents the complete set of supported categories.