MCC Codes for Developers: Building Transaction Categorization

{
  "mcc_code": "5411",
  "category": "Grocery Stores",
  "description": "Grocery Stores, Supermarkets",
  "classification": "A"  // A=Allowable, R=Restricted, P=Prohibited
}

// Fetch MCC code details
const response = await fetch(
  'https://mccexplorer.com/api/v2.1/mcc-codes/5411',
  {
    headers: { 'X-API-Key': 'your_api_key' }
  }
);

const data = await response.json();
// { mcc_code: "5411", category: "Grocery Stores", ... }

// Lookup merchant by name
const response = await fetch(
  'https://mccexplorer.com/api/v2.1/lookup?merchant=walmart',
  {
    headers: { 'X-API-Key': 'your_api_key' }
  }
);

const data = await response.json();
// Returns merchant with MCC codes and regions

class TransactionCategorizer {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.cache = new Map();
  }

  async categorize(transaction) {
    // If MCC is already in transaction, use it
    if (transaction.mcc) {
      return this.getMccDetails(transaction.mcc);
    }

    // Otherwise, lookup by merchant name
    return this.lookupMerchant(transaction.merchantName);
  }

  async getMccDetails(mccCode) {
    if (this.cache.has(mccCode)) {
      return this.cache.get(mccCode);
    }

    const response = await fetch(
      `https://mccexplorer.com/api/v2.1/mcc-codes/${mccCode}`,
      { headers: { 'X-API-Key': this.apiKey } }
    );

    const data = await response.json();
    this.cache.set(mccCode, data);
    return data;
  }

  async lookupMerchant(name) {
    const response = await fetch(
      `https://mccexplorer.com/api/v2.1/lookup?merchant=${encodeURIComponent(name)}`,
      { headers: { 'X-API-Key': this.apiKey } }
    );

    return response.json();
  }
}