MCC Predict API

1. Before you start: onboarding checklist

An API application is provisioned for your organization when your account is set up — you do not need to create one. An account administrator (a portal user with the Owner role) completes these one-time steps in the customer portal’s Organization page:

1. Retrieve your API credentials. Your Client ID and Client Secret are shown on the Organization page. Store the secret in a secrets manager and treat it like a password — anyone with the pair can obtain API access as your organization.
2. Configure your IP allow-list. Add the public IPv4 addresses your servers will call the API from.
   Important: This step is required. API applications with an empty allow-list are blocked in production — every request will return 403 Forbidden until at least one IP is added.
   • Individual IPv4 addresses only. CIDR ranges and IPv6 are not currently supported.
3. Confirm your plan includes MCC Predict. API calls are metered against your account’s MCC Predict lookup quota. Contact your account manager if you’re unsure of your limits.

2. Authentication

The API uses the OAuth 2.0 client credentials flow. Exchange your Client ID and Client Secret for an access token, then send that token as a Bearer token on API requests.

Requesting a token

POSThttps://dev-t5az4tafbsmnglox.us.auth0.com/oauth/token
Content-Type: application/json

{
  "grant_type": "client_credentials",
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET",
  "audience": "https://merchantiqa.com/api"
}

Example with curl:

curl -s -X POST "https://dev-t5az4tafbsmnglox.us.auth0.com/oauth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "audience": "https://merchantiqa.com/api"
  }'

The response contains an access_token (a JWT) and expires_in (seconds).

Token handling rules

• Cache and reuse the token. Tokens are valid for 15 days. Do not request a new token per API call — fetch one, reuse it until shortly before expiry, then refresh.
• Send it on every API request:

  Authorization: Bearer <access_token>

• Tokens are bound to your organization and your IP allow-list. A valid token used from an IP not on your allow-list is rejected with 403.

3. Endpoint reference

Predict MCC for a merchant

POSThttps://merchantiqa.com/api/job/merchant-category-code
Content-Type: application/json
Authorization: Bearer <access_token>

The call is synchronous — the prediction is returned in the response. Typical latency is several seconds, so set your HTTP client timeout accordingly (we recommend at least 60 seconds).

Request body

Example request

curl -s -X POST "https://merchantiqa.com/api/job/merchant-category-code" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantURL": "www.dickssportinggoods.com",
    "currentMCC": "5999"
  }'

Response — 200 OK

The response is a JSON array of result rows (one row per merchant submitted; for this endpoint, one row). Each row contains the top five predicted MCCs, ranked from most to least likely, with a set of flags for each candidate.

[
  {
    "Merchant_Url": "www.dickssportinggoods.com",
    "Current_MCC": 5999,
    "MCC_Code_1": 5941,
    "Description_1": "Sporting Goods Stores",
    "High_Risk_1": 0,
    "Vamp_Flag_1": 0,
    "CEDP_Disc_avail_1": 0,
    "Client_block_1": 0,
    "Network_block_1": 0,
    "MCC_Code_2": 5661,
    "Description_2": "Shoe Stores",
    "High_Risk_2": 0,
    "Vamp_Flag_2": 0,
    "CEDP_Disc_avail_2": 0,
    "Client_block_2": 0,
    "Network_block_2": 0,
    "MCC_Code_3": 5655,
    "Description_3": "Sports and Riding Apparel Stores",
    "High_Risk_3": 0,
    "Vamp_Flag_3": 0,
    "CEDP_Disc_avail_3": 0,
    "Client_block_3": 0,
    "Network_block_3": 0,
    "MCC_Code_4": 5940,
    "Description_4": "Bicycle Shops - Sales and Service",
    "High_Risk_4": 0,
    "Vamp_Flag_4": 0,
    "CEDP_Disc_avail_4": 0,
    "Client_block_4": 0,
    "Network_block_4": 0,
    "MCC_Code_5": 5999,
    "Description_5": "Miscellaneous and Specialty Retail Shops",
    "High_Risk_5": 0,
    "Vamp_Flag_5": 0,
    "CEDP_Disc_avail_5": 0,
    "Client_block_5": 0,
    "Network_block_5": 0,
    "Top_MCC_Match": 0,
    "Any_MCC_Match": 1
  }
]

Response fields

For each candidate rank n (1–5, ordered most to least likely):

Row-level fields:

Error responses

4. Rate limits and quotas

• Rate limit: 10 requests per 30 seconds per API application on this endpoint. Exceeding it returns 429; apply exponential backoff.
• Usage quota: each successful call consumes 1 MCC Predict lookup from your plan’s allowance for the billing period. When a hard limit is reached, calls return 402 until the period resets or your plan is upgraded.

For high-volume batch processing (thousands of merchants), the portal’s bulk CSV upload is usually a better fit than looping over this endpoint — ask your account manager about bulk processing.

5. Managing credentials and the IP allow-list

All management is done by an Owner user in the customer portal’s Organization page:

• Rotate the secret if you suspect it has been exposed. Rotation invalidates the old secret immediately; the new secret is then shown on the Organization page. Note that access tokens already issued remain valid until they expire (up to 15 days) — if you are responding to a suspected compromise, contact support so the application can be blocked outright.
• Update the IP allow-list whenever your egress IPs change. On the Organization page you can add new IP addresses to the list at any time, and remove old ones by clicking the x next to an IP. Changes take effect the next time a token is issued — refresh your access token after changing the list.
• Rotate secrets periodically as a matter of hygiene (e.g. every 90 days), coordinating the swap so your services pick up the new secret before the old token expires.

6. Quick-start summary

# 1. Get a token (cache it — valid 15 days)
ACCESS_TOKEN=$(curl -s -X POST "https://dev-t5az4tafbsmnglox.us.auth0.com/oauth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "audience": "https://merchantiqa.com/api"
  }' | jq -r .access_token)

# 2. Predict
curl -s -X POST "https://merchantiqa.com/api/job/merchant-category-code" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"merchantURL": "www.example-merchant.com", "currentMCC": "5999"}'

Questions or issues? Contact your account manager or MIQA support.