# Merchant Category Codes API
> ISO 18245 Merchant Category Codes (MCC) as an API — the 981 four-digit codes that Visa, Mastercard and other card networks use to classify a merchant's line of business. Look up any code (e.g. 5812 → Eating places and Restaurants, 5411 → Grocery Stores/Supermarkets, 3000 → United Airlines), search by description (e.g. "hotel", "airline", "pharmacy"), filter by IRS-reportable status, or list them all. Each record carries the network/edited description, USDA and IRS descriptions and whether the category is IRS 1099-reportable. Ideal for payments, fintech, expense management, fraud analysis and transaction enrichment.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/mcc-api/..."
```

## Pricing
- **Free** (Free) — 15,000 calls/Mo, 2 req/s
- **Starter** ($3/Mo) — 120,000 calls/Mo, 8 req/s
- **Pro** ($8/Mo) — 600,000 calls/Mo, 20 req/s
- **Mega** ($22/Mo) — 3,000,000 calls/Mo, 50 req/s

## Endpoints

### MCC

#### `GET /v1/code` — A single merchant category code

**Parameters:**
- `mcc` (query, required, string) — 4-digit MCC, e.g. 5812 Example: `5812`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/mcc-api/v1/code?mcc=5812"
```

**Response:**
```json
{
    "data": {
        "mcc": "5812",
        "description": "Eating places and Restaurants",
        "irs_reportable": false,
        "irs_description": "Eating Places, Restaurants",
        "usda_description": "Eating places and Restaurants",
        "combined_description": "Eating places and Restaurants"
    },
    "meta": {
        "timestamp": "2026-05-31T05:48:03.301Z",
        "request_id": "1f50b00a-2457-4a82-ae03-641f0747e34e"
    },
    "status": "ok",
    "message": "MCC retrieved",
    "success": true
}
```

#### `GET /v1/list` — All MCCs (paginated)

**Parameters:**
- `limit` (query, optional, string) — Max results (1-200, default 50) Example: `50`
- `offset` (query, optional, string) — Pagination offset Example: `0`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/mcc-api/v1/list?limit=50&offset=0"
```

**Response:**
```json
{
    "data": {
        "count": 50,
        "limit": 50,
        "total": 981,
        "offset": 0,
        "results": [
            {
                "mcc": "0742",
                "description": "Veterinary Services",
                "irs_reportable": true,
                "irs_description": "Veterinary Services",
                "usda_description": "Veterinary Services",
                "combined_description": "Veterinary Services"
            },
            {
                "mcc": "0763",
                "description": "Agricultural Co-operatives",
                "irs_reportable": true,
                "irs_description": "Agricultural Cooperative",
                "usda_description": "Agricultural Co-operatives",
                "combined_description": "Agricultural Co-operatives"
            },
            {
                "mcc": "0780",
                "description": "Horticultural Services, Landscaping Services",
                "irs_reportable": true,
                "irs_description": "Landscaping Services",
                "usda_description": "Horticultural Services",
                "combined_description": "Horticultural Services, Landscaping Services"
            },
            {
                "mcc": "1520",
                "description": "General Contractors-Residential and Commercial",
                "irs_reportable": true,
                "irs_description": "General Contractors",
                "usda_description": "General Contractors-Residential and Co
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/search` — Search MCCs by description

**Parameters:**
- `q` (query, required, string) — Keyword, e.g. restaurant Example: `restaurant`
- `irs_reportable` (query, optional, string) — true/false to filter by IRS-reportable
- `limit` (query, optional, string) — Results per page (1-100, default 20) Example: `20`
- `offset` (query, optional, string) — Pagination offset Example: `0`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/mcc-api/v1/search?q=restaurant&limit=20&offset=0"
```

**Response:**
```json
{
    "data": {
        "count": 2,
        "limit": 20,
        "query": "restaurant",
        "total": 2,
        "offset": 0,
        "results": [
            {
                "mcc": "5812",
                "description": "Eating places and Restaurants",
                "irs_reportable": false,
                "irs_description": "Eating Places, Restaurants",
                "usda_description": "Eating places and Restaurants",
                "combined_description": "Eating places and Restaurants"
            },
            {
                "mcc": "5814",
                "description": "Fast Food Restaurants",
                "irs_reportable": false,
                "irs_description": "Fast Food Restaurants",
                "usda_description": "Fast Food Restaurants",
                "combined_description": "Fast Food Restaurants"
            }
        ],
        "irs_reportable": null
    },
    "meta": {
        "timestamp": "2026-05-31T05:48:03.450Z",
        "request_id": "69d4617f-756d-4331-8b31-343e3eb73c2d"
    },
    "status": "ok",
    "message": "MCCs listed",
    "success": true
}
```

### Meta

#### `GET /v1/meta` — Totals & standard

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/mcc-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "note": "MCCs are 4-digit codes assigned by card networks (Visa/Mastercard) to classify a merchant's business type.",
        "total": 981,
        "fields": [
            "mcc",
            "description",
            "combined_description",
            "usda_description",
            "irs_description",
            "irs_reportable"
        ],
        "source": "Merchant Category Codes (greggles/mcc-codes, ISO 18245)",
        "standard": "ISO 18245",
        "irs_reportable": 810
    },
    "meta": {
        "timestamp": "2026-05-31T05:48:03.525Z",
        "request_id": "80bbcc1c-2adb-49fa-b414-54c3ea9ec2ee"
    },
    "status": "ok",
    "message": "Meta retrieved",
    "success": true
}
```


---
Marketplace page: https://www.oanor.com/api/mcc-api
OpenAPI spec: https://www.oanor.com/api/mcc-api/openapi.json