Building a fintech application that needs to categorize transactions? This technical guide covers how to implement MCC code lookup and transaction categorization in your software.
Understanding MCC Data Structure
MCC codes are standardized four-digit numbers with associated metadata:
MCC Data Structure
{
"mcc_code": "5411",
"category": "Grocery Stores",
"description": "Grocery Stores, Supermarkets",
"classification": "A" // A=Allowable, R=Restricted, P=Prohibited
}Using the MCC Explorer API
Our REST API provides programmatic access to MCC codes and merchant mappings:
GET /api/v1/mcc-codes/5411
// Fetch MCC code details
const response = await fetch(
'https://www.mccexplorer.com/api/v1/mcc-codes/5411',
{
headers: { 'X-API-Key': 'your_api_key' }
}
);
const data = await response.json();
// { mcc_code: "5411", category: "Grocery Stores", ... }Merchant Lookup Implementation
For transaction categorization, you often need to look up merchants by name:
GET /api/v1/lookup?merchant=walmart
// Lookup merchant by name
const response = await fetch(
'https://www.mccexplorer.com/api/v1/lookup?merchant=walmart',
{
headers: { 'X-API-Key': 'your_api_key' }
}
);
const data = await response.json();
// Returns merchant with MCC codes and regionsBest Practices for Transaction Categorization
- Use the transaction's MCC first: If available from your payment processor, the MCC in the transaction data is the most reliable source
- Fall back to merchant lookup: When MCC isn't available, use the merchant name to look up typical MCC codes
- Consider regional variations: Some merchants use different MCCs in different countries—filter by region when possible
- Handle multiple MCCs: Large merchants may have multiple valid MCCs; use the primary MCC or let users confirm
- Cache appropriately: MCC codes rarely change; cache lookups to reduce API calls
Sample Implementation
TransactionCategorizer.js
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://www.mccexplorer.com/api/v1/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://www.mccexplorer.com/api/v1/lookup?merchant=${encodeURIComponent(name)}`,
{ headers: { 'X-API-Key': this.apiKey } }
);
return response.json();
}
}Rate Limits and Pricing
Our API offers various tiers for different usage needs:
- Free: 100 requests/month, all MCC codes and basic merchant lookup
- Starter ($4.99/mo): 5,000 requests/month with full merchant mappings
- Pro ($29/mo): 100,000 requests/month, bulk lookup and confidence data
- Business ($149/mo): 1,000,000 requests/month and licensed dataset export