Transaction Categorization & Enrichment

​

Overview

• 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

​

Prerequisites

1. A Brand.dev API key
2. Access to transaction data (bank feeds, credit card statements, or payment processor data)

​

Concept

​

Context Parameters

​

MCC (Merchant Category Code)

​

City

​

Country GL

​

Architecture

​

1. Parsing Raw Transaction Data

• 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)

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
});

​

2. Batch Processing vs. Real-time

• Live transaction notifications
• Real-time spending alerts
• Interactive transaction feeds

• Historical transaction import
• Daily/weekly statement processing
• Cost optimization (process after user engagement is confirmed)

​

3. Handling Identification Confidence

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

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;
}

​

5. Displaying Enriched Transactions

AMZN MKTP US*2X7Y8Z         -$47.99
SQ *COFFEE SHOP NYC          -$5.50
UBER   *TRIP HELP.UBER.      -$23.45

• 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

​

Business Expense Management

​

Banking Applications

​

Subscription Tracking

​

Related Resources