> ## Documentation Index
> Fetch the complete documentation index at: https://docs.context.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Transaction Categorization & Enrichment
> Transform raw credit card and bank transactions into rich, branded experiences with company logos, names, and details
## Documentation Index
Fetch the complete documentation index at: [https://docs.context.dev/llms.txt](https://docs.context.dev/llms.txt)
Use this file to discover all available pages before exploring further.
## Overview
Raw transaction data from credit card statements and bank feeds is notoriously messy - cryptic merchant codes, truncated names, and missing context make it difficult for users to understand their spending. Context.dev's Transaction Enrichment endpoint transforms this chaos into clean, visually appealing transaction records complete with:
* **Company logos** for instant visual recognition
* **Clean company names** replacing cryptic merchant codes
* **Industry categorization** for spending insights
* **Social media profiles** for merchant verification
* **Brand colors** for themed UI experiences
The Transaction Enrichment endpoint helps you identify brands from transaction information by using optional geographic and industry context to improve accuracy. These optional parameters work together to provide more precise brand identification, especially when dealing with ambiguous merchant names or international brands.
For complete endpoint documentation, request/response schemas, and code examples, see the [full API reference](/api-reference/retrieve-brand/identify-brand-from-transaction-data).
We'll walk through the system design and best practices for implementing transaction enrichment in banking apps, budgeting tools, and financial dashboards.
### Prerequisites
1. A [Context.dev](https://context.dev) API key
2. Access to transaction data (bank feeds, credit card statements, or payment processor data)
### Concept
Context.dev's [Transaction Enrichment endpoint](/api-reference/retrieve-brand/identify-brand-from-transaction-data) takes messy transaction titles like `AMZN MKTP US*2X7Y8Z` and identifies the underlying brand, returning structured data including logos, company name, colors, and more.
## Context Parameters
The following optional parameters can be provided to improve brand identification accuracy:
### MCC (Merchant Category Code)
**Type:** `string` (4-digit code)\
**Parameter:** `mcc`
The Merchant Category Code provides business category context to improve brand identification accuracy. MCC codes are standardized 4-digit numbers used by credit card companies to classify businesses by type.
**Example:** `"5200"` (Retail), `"5814"` (Fast Food), `"0742"` (Veterinary Services)
The system maintains a comprehensive database of MCC codes with specific descriptions. If a code exists in the database, it uses the specific description; otherwise, it falls back to genre classification based on code ranges.
### City
**Type:** `string`\
**Parameter:** `city`
The city name helps prioritize search results for local branches or regional variations of brands.
**Example:** `"New York"`, `"London"`, `"Seattle"`
No specific formatting is required, but using standard city names will yield better results.
### Country GL
**Type:** `string` (ISO 3166-1 alpha-2 country code)\
**Parameter:** `country_gl`
The country code specifies the geographic location for search results, helping prioritize brands operating in the specified country.
**Example:** `us`, `gb`, `ca`, `au`
All ISO 3166-1 alpha-2 country codes are supported (e.g., `us` for United States, `gb` for United Kingdom).
| Country | Code |
| -------------------------------------------- | ---- |
| Afghanistan | `af` |
| Albania | `al` |
| Algeria | `dz` |
| American Samoa | `as` |
| Andorra | `ad` |
| Angola | `ao` |
| Anguilla | `ai` |
| Antarctica | `aq` |
| Antigua and Barbuda | `ag` |
| Argentina | `ar` |
| Armenia | `am` |
| Aruba | `aw` |
| Australia | `au` |
| Austria | `at` |
| Azerbaijan | `az` |
| Bahamas | `bs` |
| Bahrain | `bh` |
| Bangladesh | `bd` |
| Barbados | `bb` |
| Belarus | `by` |
| Belgium | `be` |
| Belize | `bz` |
| Benin | `bj` |
| Bermuda | `bm` |
| Bhutan | `bt` |
| Bolivia | `bo` |
| Bosnia and Herzegovina | `ba` |
| Botswana | `bw` |
| Bouvet Island | `bv` |
| Brazil | `br` |
| British Indian Ocean Territory | `io` |
| Brunei Darussalam | `bn` |
| Bulgaria | `bg` |
| Burkina Faso | `bf` |
| Burundi | `bi` |
| Cambodia | `kh` |
| Cameroon | `cm` |
| Canada | `ca` |
| Cape Verde | `cv` |
| Cayman Islands | `ky` |
| Central African Republic | `cf` |
| Chad | `td` |
| Chile | `cl` |
| China | `cn` |
| Christmas Island | `cx` |
| Cocos (Keeling) Islands | `cc` |
| Colombia | `co` |
| Comoros | `km` |
| Congo | `cg` |
| Congo, The Democratic Republic of the | `cd` |
| Cook Islands | `ck` |
| Costa Rica | `cr` |
| Côte d'Ivoire | `ci` |
| Croatia | `hr` |
| Cuba | `cu` |
| Cyprus | `cy` |
| Czech Republic | `cz` |
| Denmark | `dk` |
| Djibouti | `dj` |
| Dominica | `dm` |
| Dominican Republic | `do` |
| Ecuador | `ec` |
| Egypt | `eg` |
| El Salvador | `sv` |
| Equatorial Guinea | `gq` |
| Eritrea | `er` |
| Estonia | `ee` |
| Ethiopia | `et` |
| Falkland Islands (Malvinas) | `fk` |
| Faroe Islands | `fo` |
| Fiji | `fj` |
| Finland | `fi` |
| France | `fr` |
| French Guiana | `gf` |
| French Polynesia | `pf` |
| French Southern Territories | `tf` |
| Gabon | `ga` |
| Gambia | `gm` |
| Georgia | `ge` |
| Germany | `de` |
| Ghana | `gh` |
| Gibraltar | `gi` |
| Greece | `gr` |
| Greenland | `gl` |
| Grenada | `gd` |
| Guadeloupe | `gp` |
| Guam | `gu` |
| Guatemala | `gt` |
| Guinea | `gn` |
| Guinea-Bissau | `gw` |
| Guyana | `gy` |
| Haiti | `ht` |
| Heard Island and McDonald Islands | `hm` |
| Holy See (Vatican City State) | `va` |
| Honduras | `hn` |
| Hong Kong | `hk` |
| Hungary | `hu` |
| Iceland | `is` |
| India | `in` |
| Indonesia | `id` |
| Iran, Islamic Republic of | `ir` |
| Iraq | `iq` |
| Ireland | `ie` |
| Israel | `il` |
| Italy | `it` |
| Jamaica | `jm` |
| Japan | `jp` |
| Jordan | `jo` |
| Kazakhstan | `kz` |
| Kenya | `ke` |
| Kiribati | `ki` |
| Korea, Democratic People's Republic of | `kp` |
| Korea, Republic of | `kr` |
| Kuwait | `kw` |
| Kyrgyzstan | `kg` |
| Lao People's Democratic Republic | `la` |
| Latvia | `lv` |
| Lebanon | `lb` |
| Lesotho | `ls` |
| Liberia | `lr` |
| Libyan Arab Jamahiriya | `ly` |
| Liechtenstein | `li` |
| Lithuania | `lt` |
| Luxembourg | `lu` |
| Macao | `mo` |
| Macedonia, The Former Yugoslav Republic of | `mk` |
| Madagascar | `mg` |
| Malawi | `mw` |
| Malaysia | `my` |
| Maldives | `mv` |
| Mali | `ml` |
| Malta | `mt` |
| Marshall Islands | `mh` |
| Martinique | `mq` |
| Mauritania | `mr` |
| Mauritius | `mu` |
| Mayotte | `yt` |
| Mexico | `mx` |
| Micronesia, Federated States of | `fm` |
| Moldova, Republic of | `md` |
| Monaco | `mc` |
| Mongolia | `mn` |
| Montserrat | `ms` |
| Morocco | `ma` |
| Mozambique | `mz` |
| Myanmar | `mm` |
| Namibia | `na` |
| Nauru | `nr` |
| Nepal | `np` |
| Netherlands | `nl` |
| Netherlands Antilles | `an` |
| New Caledonia | `nc` |
| New Zealand | `nz` |
| Nicaragua | `ni` |
| Niger | `ne` |
| Nigeria | `ng` |
| Niue | `nu` |
| Norfolk Island | `nf` |
| Northern Mariana Islands | `mp` |
| Norway | `no` |
| Oman | `om` |
| Pakistan | `pk` |
| Palau | `pw` |
| Palestinian Territory, Occupied | `ps` |
| Panama | `pa` |
| Papua New Guinea | `pg` |
| Paraguay | `py` |
| Peru | `pe` |
| Philippines | `ph` |
| Pitcairn | `pn` |
| Poland | `pl` |
| Portugal | `pt` |
| Puerto Rico | `pr` |
| Qatar | `qa` |
| Réunion | `re` |
| Romania | `ro` |
| Russian Federation | `ru` |
| Rwanda | `rw` |
| Saint Helena | `sh` |
| Saint Kitts and Nevis | `kn` |
| Saint Lucia | `lc` |
| Saint Pierre and Miquelon | `pm` |
| Saint Vincent and the Grenadines | `vc` |
| Samoa | `ws` |
| San Marino | `sm` |
| Sao Tome and Principe | `st` |
| Saudi Arabia | `sa` |
| Senegal | `sn` |
| Serbia and Montenegro | `rs` |
| Seychelles | `sc` |
| Sierra Leone | `sl` |
| Singapore | `sg` |
| Slovakia | `sk` |
| Slovenia | `si` |
| Solomon Islands | `sb` |
| Somalia | `so` |
| South Africa | `za` |
| South Georgia and the South Sandwich Islands | `gs` |
| Spain | `es` |
| Sri Lanka | `lk` |
| Sudan | `sd` |
| Suriname | `sr` |
| Svalbard and Jan Mayen | `sj` |
| Swaziland | `sz` |
| Sweden | `se` |
| Switzerland | `ch` |
| Syrian Arab Republic | `sy` |
| Taiwan, Province of China | `tw` |
| Tajikistan | `tj` |
| Tanzania, United Republic of | `tz` |
| Thailand | `th` |
| Timor-Leste | `tl` |
| Togo | `tg` |
| Tokelau | `tk` |
| Tonga | `to` |
| Trinidad and Tobago | `tt` |
| Tunisia | `tn` |
| Turkey | `tr` |
| Turkmenistan | `tm` |
| Turks and Caicos Islands | `tc` |
| Tuvalu | `tv` |
| Uganda | `ug` |
| Ukraine | `ua` |
| United Arab Emirates | `ae` |
| United Kingdom | `gb` |
| United States | `us` |
| United States Minor Outlying Islands | `um` |
| Uruguay | `uy` |
| Uzbekistan | `uz` |
| Vanuatu | `vu` |
| Venezuela | `ve` |
| Viet Nam | `vn` |
| Virgin Islands, British | `vg` |
| Virgin Islands, U.S. | `vi` |
| Wallis and Futuna | `wf` |
| Western Sahara | `eh` |
| Yemen | `ye` |
| Zambia | `zm` |
| Zimbabwe | `zw` |
## Architecture
### 1. Parsing Raw Transaction Data
Transaction data from banks and credit card processors typically includes:
* **Transaction title/description** - Often truncated or encoded (e.g., `SQ *COFFEE SHOP NYC`)
* **Amount** - The transaction value
* **MCC code** - Merchant Category Code (4-digit industry classifier)
* **Location data** - City, country (when available)
The Transaction Enrichment endpoint accepts all of these as inputs to improve identification accuracy:
```typescript theme={null}
const { brand } = await client.brand.identifyTransaction({
transaction: "AMZN MKTP US*2X7Y8Z",
mcc: "5942", // Optional: Book stores
city: "Seattle", // Optional: Geographic context
country_gl: "us" // Optional: Country code
});
```
The more context you provide (MCC code, city, country), the more accurate the brand identification will be - especially for common names or regional businesses.
### 2. Batch Processing vs. Real-time
Choose your processing strategy based on your use case:
**Real-time enrichment** - Enrich transactions as they stream in from your banking provider. Best for:
* Live transaction notifications
* Real-time spending alerts
* Interactive transaction feeds
**Batch processing** - Process transactions in bulk during off-peak hours. Best for:
* Historical transaction import
* Daily/weekly statement processing
* Cost optimization (process after user engagement is confirmed)
For high-volume batch processing, implement rate limiting and exponential backoff to stay within API limits.
### 3. Handling Identification Confidence
Not all transactions can be definitively matched to a brand. Your implementation should handle varying confidence levels:
| Scenario | Recommendation |
| ---------------------- | ---------------------------------------------------------------- |
| **Strong match** | Display enriched data with logo and clean name |
| **Weak/no match** | Fall back to cleaned transaction title and generic category icon |
| **Personal transfers** | Display as peer-to-peer with appropriate icon and service |
```typescript theme={null}
function displayTransaction(transaction, brandData) {
if (brandData?.brand) {
return {
name: brandData.brand.title,
logo: brandData.brand.logos[0]?.url,
color: brandData.brand.colors[0]?.hex
};
}
// Fallback to original transaction data
return {
name: cleanTransactionTitle(transaction.description),
logo: getCategoryIcon(transaction.mcc),
color: "#6B7280" // Neutral gray
};
}
```
### 4. Caching for Performance
Transaction enrichment benefits significantly from caching since users often transact with the same merchants repeatedly:
```typescript theme={null}
const enrichmentCache = new Map();
async function enrichTransaction(transaction) {
const cacheKey = normalizeTransactionKey(transaction.description);
if (enrichmentCache.has(cacheKey)) {
return enrichmentCache.get(cacheKey);
}
const brandData = await client.brand.identifyTransaction({
transaction: transaction.description,
mcc: transaction.mcc,
country_gl: transaction.country
});
enrichmentCache.set(cacheKey, brandData);
return brandData;
}
```
Cache by normalized merchant name rather than exact transaction string—`STARBUCKS #12345` and `STARBUCKS #67890` should share the same cache entry.
### 5. Displaying Enriched Transactions
Transform your transaction list from plain text to a rich, branded experience:
**Before enrichment:**
```
AMZN MKTP US*2X7Y8Z -$47.99
SQ *COFFEE SHOP NYC -$5.50
UBER *TRIP HELP.UBER. -$23.45
```
**After enrichment:**
* Display the merchant's logo alongside the transaction
* Show the clean company name (e.g., "Amazon Marketplace")
* Use brand colors for visual accents or category theming
* Link to merchant website or social profiles when helpful
## Best Practices
### 1. Use MCC Codes When Available
> MCC (Merchant Category Codes) significantly improve identification accuracy. These 4-digit codes are standard in credit card processing and help disambiguate common names. For example, "Apple" with MCC `5732` (Electronics Stores) identifies Apple Inc., while MCC `5411` (Grocery Stores) might indicate a local fruit market.
### 2. Implement Graceful Fallbacks
> Always have a fallback display for unidentified transactions. Show a cleaned version of the original transaction title with a category-appropriate icon based on the MCC code. Never show raw, encoded transaction strings to users.
### 3. Respect User Corrections
> Allow users to manually categorize or rename transactions that weren't identified correctly. Store these corrections and use them as overrides for future transactions from the same merchant pattern.
### 4. Handle Edge Cases
> Some transactions will never match a brand (peer-to-peer transfers, ATM withdrawals, generic payment processors). Detect these patterns and apply appropriate generic categorization rather than attempting brand identification.
## Example Use Cases
### Personal Finance Apps
Display spending breakdowns with merchant logos, making it easy for users to recognize where their money goes at a glance.
### Business Expense Management
Automatically categorize and enrich employee expenses for cleaner reports and easier reconciliation.
### Banking Applications
Transform plain statement views into modern, visual transaction feeds that improve user engagement.
### Subscription Tracking
Identify recurring merchant charges and display them with brand logos for easy subscription management.
## Related Resources
Learn about MCC codes, geographic context, and API parameters
Full endpoint documentation and examples
Understanding brand data structure and logo types
Pre-fill user data with brand information