greggles/mcc-codes

A public repository of Merchant Category Codes (MCC) in formats easier to read than most places (i.e. not a PDF)

mcc-codes

A public repository of Merchant Category Codes (MCC) in formats easier to read than most places (i.e. not a PDF).

The same data is available in several formats:

• csv
• small json - no whitespace characters
• formatted json - indented for legibility
• jsonlines - newline delimited json objects jsonlines
• ods (LibreOffice and OpenOffice.org compatible)
• xls (Microsoft Office & useful with many other systems that can read xls)

Fields

• Derived MCC - mcc
• edited_description - manually edited, modern text
• combined_description - uses either USDA or IRS
• usda_description - Description from the USDA
• irs_description - Description from IRS
• irs_reportable - Reportable under 6041/6041A and Authority for Exception

Future plans and workflow

I hope that folks will create pull requests to make this information easier to read and use. Specifically, the "Edited Description" field is a place where we can collaboratively go through and fix things like upper case vs. title case.

Preferences for the "Edited Description":

• Shorter is better
• Use descriptions that make the most sense to someone in 2024
• Use title case

If the pull request is against the CSV I'll gladly update the binary formats. Or see below for how to update everything in one shot.

Credits

I built this out of curiosity about MCC codes.

Other folks (e.g. Expensify) are contributing fixes too. Thanks!

Updating the files

1. Start with a csv file that is in a good state.
2. Open it with LibreOffice using only commas as field separators.
3. "Save as" to ods.
4. "Save as" to xls.
5. Convert the csv to an array of json objects on a single line php -f csv-to-json.php mcc_codes.csv mcc_codes.small.json
6. Convert the single line json to easier-to-read multiline array jq mcc_codes.small.json > mcc_codes.json
7. Convert the single line to a "jsonlines" formatted file: jq -c '.[]' mcc_codes.small.json > mcc_codes.jsonl

Step 5 depends on php-cli. Steps 6 and 7 depend on jq.

mcc-codes's Issues

Add in SIC/NAICS data

Breaking this off from a comment from @jbroquist in #3.

We should add in SIC/NAICS data.

I couldn't find a public-domain table that combines any of this information currently. Anyone aware of one?

MCC 3012 (QUANTAS) is misspelt - should be QANTAS

MCC 3012 (QUANTAS) is misspelt - should be QANTAS.

Missing mcc 8479

8479 Skipass Cable Railway Ski

software/data licence

Hi,

What is the software/data licence on mcc-codes? I would like to use it in another open source project (https://github.com/jseutter/ofxparse) if it has a public licence (e.g. mit license, etc).

Thanks,

Andrew

Description of code 3563 is wrong

JOURNEY’S END MOTLS

=> motels

Another source of CSVs

Hi, thanks for your work on this repo!

I recently had to deal with MCCs from Python and decided to publish a python package for iso18245.

I got curious about pulling the data from first-party sources; I also needed range data, not just the list of MCCs, so I worked on generating new CSVs.

I grabbed the official ISO 18245 PDF, as well as the most recent Visa list, the USDA list, and even Stripe Issuing's list. I used Tabula to extract the data, and had to do some extra manual + scripted clean up (especially with Visa's PDF; the rest was pretty clean).

Wanted to share it here in case it's useful for someone:

• Ranges - directly from ISO18245
• Official ISO18245:2003 list of MCCs
• USDA list - this is pulled from this PDF. It's riddled with typos, as can be seen in other issues on this repo…
• VISA list, pulled from this PDF.
• Stripe list - non-exhaustive, pulled from this page, and contains stripe's internal codes as well.

Specifically, I needed to match cut text descriptions to the original MCCs:

It's a wonder why this was standardized on 4-digit codes at all if banking APIs are just going to use mangled english descriptions… but whatever. The python library itself exposes all that data. I've attached all the combined MCCs as JSON here if anyone needs them:

mccs.json

MCC Code '5948 - Leather Goods Stores' typo

Typo:

5948 - Leather Foods Stores

Correction:

5948 - Leather Goods Stores

Prime sign (’) is less compatible than single quote (')

Although the prime sign (’), for example, "Man’s" as opposed to "Man's" , is semantically more accurate than single quote ('), in many cases, single quotes are easier to handle when it comes to ASCII code system (even in Excel on MAC). So it would be easier to use your great efforts if all the primes are replaced by single quotes.

Add newline separated json (JSONL) format

Would be nice to see a newline separated JSON format added... though the JSON size isn't too bad, it's still relatively big and newline-separated JSON is a bit easier for import.

Also, not sure if there are other updates as it looks like this repository is about 5 years from the last commit.

missing codes from updated Visa merchant guide

Hi @greggles - I did a side by side on this file and the updated Visa manual and thought I would share the diff.

New codes and deleted codes below.

I can prepare as a PR if there is interest in updating this data set, but I thought I would ping before doing so as there are a few existing PRs outstanding.

Thanks!
Andrew

New:

{
  "columns": [
    "mcc",
    "mcc_title",
    "mcc_description"
  ],
  "data": [
    [
      "3300",
      "AZUL AIR",
      "AZUL AIR"
    ],
    [
      "3301",
      "WIZZ AIR",
      "WIZZ AIR"
    ],
    [
      "3791",
      "STAYBRIDGE SUITES",
      null
    ],
    [
      "3792",
      "CLARIDGE CASINO HOTEL",
      null
    ],
    [
      "3793",
      "FLAMINGO HOTELS",
      null
    ],
    [
      "3794",
      "GRAND CASINO HOTELS",
      null
    ],
    [
      "3795",
      "PARIS LAS VEGAS HOTEL",
      null
    ],
    [
      "3796",
      "PEPPERMILL HOTEL CASINO",
      null
    ],
    [
      "3797",
      "ATLANTIC CITY HILTON RESORTS",
      null
    ],
    [
      "3798",
      "EMBASSY VACATION RESORT",
      null
    ],
    [
      "3799",
      "HALE KOA HOTEL",
      null
    ],
    [
      "3800",
      "HOMESTEAD SUITES",
      null
    ],
    [
      "3801",
      "WILDERNESS HOTEL AND RESORT",
      null
    ],
    [
      "3802",
      "THE PALACE HOTEL",
      null
    ],
    [
      "3807",
      "ELEMENT",
      null
    ],
    [
      "3808",
      "LXR",
      null
    ],
    [
      "3811",
      "PREMIER INN",
      null
    ],
    [
      "3815",
      "NICKELODEON FAMILY SUITES BY HOLIDAY INN",
      null
    ],
    [
      "3816",
      "HOME2SUITES",
      null
    ],
    [
      "3818",
      "MAINSTAY SUITES",
      null
    ],
    [
      "3819",
      "OXFORD SUITES",
      null
    ],
    [
      "3820",
      "JUMEIRAH ESSEX HOUSE",
      null
    ],
    [
      "3821",
      "CARIBE ROYALE",
      null
    ],
    [
      "3822",
      "CROSSLAND",
      null
    ],
    [
      "3823",
      "GRAND SIERRA RESORT",
      null
    ],
    [
      "3824",
      "ARIA",
      null
    ],
    [
      "3825",
      "VDARA",
      null
    ],
    [
      "3827",
      "GALT HOUSE",
      null
    ],
    [
      "3828",
      "COSMOPOLITAN OF LAS VEGAS",
      null
    ],
    [
      "3829",
      "COUNTRY INN BY CARLSON",
      null
    ],
    [
      "3830",
      "PARK PLAZA HOTEL",
      null
    ],
    [
      "3831",
      "WALDORF",
      null
    ],
    [
      "3832",
      "CURIO HOTELS",
      null
    ],
    [
      "3833",
      "CANOPY",
      null
    ],
    [
      "3834",
      "BAYMONT INN & SUITES",
      null
    ],
    [
      "3836",
      "HAWTHORN BY WYNDHAM",
      null
    ],
    [
      "5817",
      "Digital Goods \\u2013 Applications (Excludes Games)",
      "Merchants classified with this MCC sell applications or software (excludes games) that are delivered in electronic format."
    ],
    [
      "7801",
      "Government Licensed On-Line Casinos (On-Line Gambling) (US Region only)",
      "Merchants classified with this MCC are licensed by a US government entity (and\\/or sanctioned and regulated by applicable legislation) and registered with Visa to sell virtual gambling chips or offer online gambling."
    ],
    [
      "7802",
      "Government-Licensed Horse\\/Dog Racing (US Region only)",
      "Merchants classified with this MCC are licensed by a US government entity (and\\/or sanctioned and regulated by applicable legislation) and registered with Visa to sell on- or off-track wagers at horse- or dog-racing facilities."
    ],
    [
      "9702",
      "Emergency Services (GCAS) (Visa use only)",
      "This MCC is used only by Visa to enable members and processors to identify emergency transactions from the Global Customer Assistance Services (GCAS)."
    ],
    [
      "9950",
      "Intra-Company Purchases",
      "Merchants classified with this MCC process purchasing card transactions representing internal unit-to-unit transfers of goods and services."
    ]
  ]
}

Deleted:

{
  "columns": [
    "mcc",
    "edited_description"
  ],
  "data": [
    [
      "3019",
      "Airlines"
    ],
    [
      "3070",
      "Airlines"
    ],
    [
      "3073",
      "Airlines"
    ],
    [
      "3074",
      "Airlines"
    ],
    [
      "3080",
      "Airlines"
    ],
    [
      "3081",
      "NORDAIR"
    ],
    [
      "3091",
      "Airlines"
    ],
    [
      "3092",
      "Airlines"
    ],
    [
      "3093",
      "Airlines"
    ],
    [
      "3095",
      "Airlines"
    ],
    [
      "3101",
      "Airlines"
    ],
    [
      "3104",
      "Airlines"
    ],
    [
      "3105",
      "Airlines"
    ],
    [
      "3107",
      "Airlines"
    ],
    [
      "3108",
      "Airlines"
    ],
    [
      "3109",
      "Airlines"
    ],
    [
      "3113",
      "Airlines"
    ],
    [
      "3114",
      "Airlines"
    ],
    [
      "3116",
      "Airlines"
    ],
    [
      "3119",
      "Airlines"
    ],
    [
      "3120",
      "Airlines"
    ],
    [
      "3121",
      "Airlines"
    ],
    [
      "3122",
      "Airlines"
    ],
    [
      "3123",
      "Airlines"
    ],
    [
      "3124",
      "Airlines"
    ],
    [
      "3128",
      "Airlines"
    ],
    [
      "3134",
      "Airlines"
    ],
    [
      "3139",
      "Airlines"
    ],
    [
      "3140",
      "Airlines"
    ],
    [
      "3141",
      "Airlines"
    ],
    [
      "3142",
      "Airlines"
    ],
    [
      "3147",
      "Airlines"
    ],
    [
      "3149",
      "Airlines"
    ],
    [
      "3150",
      "Airlines"
    ],
    [
      "3152",
      "Airlines"
    ],
    [
      "3153",
      "Airlines"
    ],
    [
      "3155",
      "Airlines"
    ],
    [
      "3157",
      "Airlines"
    ],
    [
      "3158",
      "Airlines"
    ],
    [
      "3160",
      "Airlines"
    ],
    [
      "3162",
      "Airlines"
    ],
    [
      "3163",
      "Airlines"
    ],
    [
      "3166",
      "Airlines"
    ],
    [
      "3168",
      "Airlines"
    ],
    [
      "3169",
      "Airlines"
    ],
    [
      "3173",
      "Airlines"
    ],
    [
      "3179",
      "Airlines"
    ],
    [
      "3189",
      "Airlines"
    ],
    [
      "3192",
      "IRAN AIR"
    ],
    [
      "3194",
      "Airlines"
    ],
    [
      "3195",
      "Airlines"
    ],
    [
      "3198",
      "Airlines"
    ],
    [
      "3199",
      "Airlines"
    ],
    [
      "3201",
      "Airlines"
    ],
    [
      "3202",
      "Airlines"
    ],
    [
      "3205",
      "Airlines"
    ],
    [
      "3207",
      "Airlines"
    ],
    [
      "3208",
      "Airlines"
    ],
    [
      "3209",
      "Airlines"
    ],
    [
      "3210",
      "Airlines"
    ],
    [
      "3214",
      "Airlines"
    ],
    [
      "3224",
      "Airlines"
    ],
    [
      "3225",
      "Airlines"
    ],
    [
      "3227",
      "Airlines"
    ],
    [
      "3230",
      "Airlines"
    ],
    [
      "3232",
      "Airlines"
    ],
    [
      "3237",
      "Airlines"
    ],
    [
      "3244",
      "Airlines"
    ],
    [
      "3249",
      "Airlines"
    ],
    [
      "3250",
      "Airlines"
    ],
    [
      "3253",
      "AMERICA WEST"
    ],
    [
      "3255",
      "Airlines"
    ],
    [
      "3257",
      "Airlines"
    ],
    [
      "3258",
      "Airlines"
    ],
    [
      "3264",
      "Airlines"
    ],
    [
      "3265",
      "Airlines"
    ],
    [
      "3268",
      "Airlines"
    ],
    [
      "3269",
      "Airlines"
    ],
    [
      "3270",
      "Airlines"
    ],
    [
      "3271",
      "Airlines"
    ],
    [
      "3272",
      "Airlines"
    ],
    [
      "3273",
      "Airlines"
    ],
    [
      "3274",
      "Airlines"
    ],
    [
      "3275",
      "Airlines"
    ],
    [
      "3276",
      "Airlines"
    ],
    [
      "3277",
      "Airlines"
    ],
    [
      "3278",
      "Airlines"
    ],
    [
      "3279",
      "Airlines"
    ],
    [
      "3281",
      "Airlines"
    ],
    [
      "3283",
      "Airlines"
    ],
    [
      "3288",
      "Airlines"
    ],
    [
      "3289",
      "Airlines"
    ],
    [
      "3290",
      "Airlines"
    ],
    [
      "3291",
      "ARIANA AFGHAN"
    ],
    [
      "3356",
      "Car Rental"
    ],
    [
      "3358",
      "Car Rental"
    ],
    [
      "3363",
      "Car Rental"
    ],
    [
      "3365",
      "Car Rental"
    ],
    [
      "3367",
      "Car Rental"
    ],
    [
      "3369",
      "Car Rental"
    ],
    [
      "3371",
      "Car Rental"
    ],
    [
      "3372",
      "Car Rental"
    ],
    [
      "3373",
      "Car Rental"
    ],
    [
      "3375",
      "Car Rental"
    ],
    [
      "3377",
      "Car Rental"
    ],
    [
      "3378",
      "Car Rental"
    ],
    [
      "3379",
      "Car Rental"
    ],
    [
      "3382",
      "Car Rental"
    ],
    [
      "3383",
      "Car Rental"
    ],
    [
      "3384",
      "Car Rental"
    ],
    [
      "3392",
      "Car Rental"
    ],
    [
      "3397",
      "Car Rental"
    ],
    [
      "3399",
      "Car Rental"
    ],
    [
      "3401",
      "Car Rental"
    ],
    [
      "3402",
      "Car Rental"
    ],
    [
      "3403",
      "Car Rental"
    ],
    [
      "3404",
      "Car Rental"
    ],
    [
      "3406",
      "Car Rental"
    ],
    [
      "3407",
      "Car Rental"
    ],
    [
      "3408",
      "Car Rental"
    ],
    [
      "3410",
      "Car Rental"
    ],
    [
      "3411",
      "Car Rental"
    ],
    [
      "3413",
      "Car Rental"
    ],
    [
      "3415",
      "Car Rental"
    ],
    [
      "3416",
      "Car Rental"
    ],
    [
      "3417",
      "Car Rental"
    ],
    [
      "3418",
      "Car Rental"
    ],
    [
      "3419",
      "ALPHA RENT-A-CAR"
    ],
    [
      "3422",
      "Car Rental"
    ],
    [
      "3424",
      "Car Rental"
    ],
    [
      "3426",
      "Car Rental"
    ],
    [
      "3440",
      "VIA ROUTE RENT-A-CAR"
    ],
    [
      "3547",
      "Hotels\\/Motels\\/Inns\\/Resorts"
    ],
    [
      "3605",
      "Hotels\\/Motels\\/Inns\\/Resorts"
    ],
    [
      "3606",
      "Hotels\\/Motels\\/Inns\\/Resorts"
    ],
    [
      "3610",
      "Hotels\\/Motels\\/Inns\\/Resorts"
    ],
    [
      "3611",
      "Hotels\\/Motels\\/Inns\\/Resorts"
    ],
    [
      "3616",
      "Hotels\\/Motels\\/Inns\\/Resorts"
    ],
    [
      "3733",
      "BOCA RATON RESORT"
    ],
    [
      "3756",
      "SOUTH SEAS RESORTS"
    ],
    [
      "4815",
      "VisaPhone"
    ],
    [
      "5531",
      "Automobile Supply Stores"
    ],
    [
      "5832",
      "Antique Shops - Sales, Repairs, and Restoration Services"
    ],
    [
      "5961",
      "Mail Order Houses Including Catalog Order Stores, Book\\/Record Clubs (No longer permitted for U.S. original presentments)"
    ],
    [
      "6381",
      "Insurance Premiums, (no longer valid for first presentment work)"
    ],
    [
      "6399",
      "Insurance, Not Elsewhere Classified ( no longer valid forfirst presentment work)"
    ],
    [
      "7332",
      "Blueprinting and Photocopying Services"
    ],
    [
      "7511",
      "Truck Stop"
    ],
    [
      "8044",
      "Opticians, Optical Goods, and Eyeglasses (no longer validfor first presentments)"
    ],
    [
      "6555",
      "Miscellaneous Personal Services ( rebate)"
    ]
  ]
}

simplify column headings, remove spaces

I just used the json formatted data for the first time and realized the "column" headings in the csv are not great as json array keys - they are long which makes the data bigger than necessary and they have some spaces, both of which makes code handling them look odd.

I propose cutting them down as follows:

• Derived MCC - mcc
• Edited description - edited_description
• Combined Description - combined_description
• USDA Description - usda_description
• IRS Description - irs_description
• Reportable under 6041/6041A and Authority for Exception - irs_reportable

Then the README.txt should be updated to describe each field in more detail.

@genintho any thoughts on that idea?

Missing mccs -

I have found following mccs which are not defined in your list. I've included the source of the details for each.
3303 TIGERAIR https://usa.visa.com/content/dam/VCOM/download/merchants/visa-merchant-data-standards-manual.pdf
3308 China Southern: CSAIR https://www.mastercard.us/content/dam/public/mastercardcom/na/global-site/documents/quick-reference-booklet-merchant.pdf
3839 Kyoritsu Hotels https://usa.visa.com/content/dam/VCOM/download/merchants/visa-merchant-data-standards-manual.pdf
8082 Home Health Care Services https://empower2.fisglobal.com/rs/092-EMI-875/images/Summer%202022%20NUNL.pdf
9751 UK Supermarkets, Electronic Hot File https://www.citibank.com/tts/solutions/commercial-cards/assets/docs/govt/Merchant-Category-Codes.pdf
9752 UK Petrol Stations, Electronic Hot File https://www.citibank.com/tts/solutions/commercial-cards/assets/docs/govt/Merchant-Category-Codes.pdf
7322 Debt Collection Agencies https://empower2.fisglobal.com/rs/092-EMI-875/images/Summer%202022%20NUNL.pdf