> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fyatu.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Merchant Category Restrictions

> The merchant categories the card issuer has been observed declining, as MCC plus description. GET /merchant-category-restrictions. Requires cards:read scope.

## Overview

Some payments are declined with a merchant-restriction reason that carries no list, no effective
date and no reason code. This endpoint returns the merchant categories in which we have observed
those declines — the MCC and a plain-language description — so you can answer a cardholder with
something better than a guess.

It covers the two BINs issued on this programme: `537100` (Mastercard Elite) and `486555` (VISA
Classic).

> [!WARNING]
>
> **This is not the same thing as [Get Restricted Merchants](https://docs.fyatu.com/v3.20/api-reference/programs/restricted-merchants.md).**
> That endpoint returns merchants restricted **at the provider** — a configuration, and every card
> you issue is checked against it at authorization time. This one is an **observation** of declines
> nobody configured and that nothing enforces. One is a rule; the other is a measurement.

> [!WARNING]
>
> **A listed category is not a blocked category.** The restriction is applied per merchant, not per
> category, so most categories on this list still approve most of their payments: in the measurement
> behind it, MCC `5816` carried 620 declines alongside hundreds of approvals, and `7311` carried 150
> declines against 1,852 approvals. Reading this list as "these categories will fail" will have you
> tell a cardholder something false. Read it as "declines have been seen here" — the right next step
> is almost always a retry or a different merchant in the same category.

## What this list is, and is not

| It is | It is not |
| - | - |
| Observed from authorizations that were actually declined | A list published by the card issuer — we have never been given one |
| The categories affected | The merchants affected. Those are deliberately not returned |
| Scoped to the two BINs on this programme | Per program, or per currency |
| Read-only reporting | A control. Nothing here is used to decide an authorization |

## Ordering and change detection

Entries are ordered by MCC, and that order is stable. A category leaves the list once the merchants
in it have started succeeding again and stayed quiet, so diffing two fetches shows real movement
rather than a reshuffle — which is what makes it worth caching and re-fetching on a schedule
rather than per request.

## Example Usage

```bash cURL theme={null}
curl -s 'https://api.fyatu.com/api/v3.20/merchant-category-restrictions' \
  -H "X-API-Key: $FYATU_API_KEY"
```

```javascript Node.js theme={null}
const res = await fetch(
  'https://api.fyatu.com/api/v3.20/merchant-category-restrictions',
  { headers: { 'X-API-Key': process.env.FYATU_API_KEY } }
);
const { data } = await res.json();

const affected = new Set(data.categories.map((c) => c.mcc));
if (affected.has(declinedTransaction.mcc)) {
  // Declines have been seen in this category — but it is not blocked.
  console.log('Known category. Suggest a retry or another merchant in the same category.');
}
```

```python Python theme={null}
import requests

r = requests.get(
    "https://api.fyatu.com/api/v3.20/merchant-category-restrictions",
    headers={"X-API-Key": api_key},
    timeout=30,
)
data = r.json()["data"]

print(f"{data['count']} categories affected")
for c in data["categories"]:
    print(c["mcc"], c["category"])
```

## Example Response

```json theme={null}
{
  "success": true,
  "status": 200,
  "message": "Merchant category restrictions retrieved",
  "data": {
    "categories": [
      {
        "mcc": "0742",
        "category": "Veterinary services"
      },
      {
        "mcc": "4121",
        "category": "Taxis and ride-hailing"
      },
      {
        "mcc": "5411",
        "category": "Grocery stores and supermarkets"
      },
      {
        "mcc": "5816",
        "category": "Digital goods — games"
      },
      {
        "mcc": "7311",
        "category": "Advertising services"
      }
    ],
    "count": 159,
    "bins": [
      {
        "bin": "537100",
        "network": "MASTERCARD",
        "product": "Mastercard Elite"
      },
      {
        "bin": "486555",
        "network": "VISA",
        "product": "VISA Classic"
      }
    ],
    "note": "Merchant categories in which authorisations have been observed declined as restricted. Observed by us, not a list published by the card issuer. The restriction is applied per merchant rather than per category, so most of these categories still approve most payments — a listed category is a reason to expect some declines, not a block. Nothing here is used to decide an authorisation."
  },
  "meta": {
    "requestId": "req_c41b70ea9d6f4832",
    "platform": "LIVE",
    "timestamp": "2026-11-02T11:42:07+02:00"
  }
}
```

> [!NOTE]
>
> A `503` with code `RESTRICTION_LIST_UNAVAILABLE` means the list is not configured on the
> environment you are calling. It is returned deliberately in place of an empty array, because an
> empty array reads as "nothing is restricted".

## Keeping it current

The list updates continuously from live authorization outcomes and is reconciled hourly, which is
when a category whose merchants have started working again drops off. A merchant has to stay quiet
for several hours after a successful payment before it counts as recovered, so a category does not
appear and disappear while merchants inside it are behaving inconsistently.


## OpenAPI

````yaml v3.20/openapi.json GET /merchant-category-restrictions
openapi: 3.1.0
info:
  title: FYATU CaaS API v3.20
  description: >-
    FYATU Cards-as-a-Service API â€” API key authentication, Cardholder
    lifecycle, Card issuance, Transactions, Webhooks, and Programs.
  version: 3.20.0
  contact:
    name: FYATU Support
    url: https://fyatu.com
    email: support@fyatu.com
servers:
  - url: https://sandbox-api.fyatu.com/api/v3.20
    description: 'Public sandbox: free, test money only. Keys from sandbox.fyatu.com'
  - url: https://api.fyatu.com/api/v3.20
    description: >-
      Production. Keys from platform.fyatu.com; the key's environment (LIVE or
      SANDBOX) selects the data
security:
  - BearerAuth: []
tags:
  - name: Meta
    description: Liveness, account info, and supported event types
  - name: Account
    description: Account-level balance and funding status
  - name: Programs
    description: Read card program configuration
  - name: Cardholders
    description: Create and manage cardholder profiles
  - name: Cards
    description: Issue, fund, freeze, and terminate virtual cards
  - name: Transactions
    description: Read-only card transaction history
  - name: Webhooks
    description: Manage webhook endpoints for real-time event delivery
  - name: Products
    description: Read card product configurations
paths:
  /merchant-category-restrictions:
    get:
      tags:
        - Cards
      summary: Get merchant category restrictions
      description: >-
        The merchant categories in which authorisations have been observed being
        declined by the card issuer, as MCC plus description, so you can answer
        a cardholder instead of guessing.


        **This is not `GET /restricted-merchants`.** That endpoint returns
        merchants restricted *at the provider* — a configuration, which an
        authorisation is actually checked against. This one is an observation of
        refusals nobody configured and that nothing on the platform enforces.


        **Observed by us, not published by the issuer.** Every entry is derived
        from authorisations that were actually declined with a
        merchant-restriction reason.


        **A listed category is not a blocked category.** The restriction is
        applied per merchant rather than per category, so most of these
        categories still approve most of their payments — in the measurement
        behind this list, MCC 5816 carried 620 refusals alongside hundreds of
        approvals and 7311 carried 150 against 1,852. Treat a listed category as
        a reason to expect some declines, not as a statement that payments there
        will fail.


        The merchants themselves are deliberately not returned. Not per program
        and not per currency: the refusals are a property of the BINs the cards
        are issued on, which is why the response names them — `537100`
        (Mastercard Elite) and `486555` (VISA Classic).
      operationId: getMerchantCategoryRestrictions
      responses:
        '200':
          description: Merchant category restrictions retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  status:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: Merchant category restrictions retrieved
                  data:
                    type: object
                    properties:
                      categories:
                        type: array
                        description: >-
                          Every merchant category with an observed restriction
                          decline that has not since recovered, ordered by MCC.
                          The order is stable so a diff between two fetches
                          shows a real change rather than a reshuffle.
                        items:
                          type: object
                          properties:
                            mcc:
                              type: string
                              description: Merchant category code
                              example: '5816'
                            category:
                              type: string
                              description: Plain-language description of the code
                              example: Digital goods — games
                      count:
                        type: integer
                        description: Number of categories returned
                        example: 159
                      bins:
                        type: array
                        description: The BINs this list covers
                        items:
                          type: object
                          properties:
                            bin:
                              type: string
                              example: '537100'
                            network:
                              type: string
                              example: MASTERCARD
                            product:
                              type: string
                              example: Mastercard Elite
                      note:
                        type: string
                        description: >-
                          Returned on every response, because a bare list of
                          MCCs read as a block list would have you tell a
                          cardholder something false
        '401':
          description: Missing or invalid API key
        '403':
          description: The API key lacks the cards:read scope
        '503':
          description: >-
            The list is not available on this deployment. Returned instead of an
            empty array, which would read as "nothing is restricted".
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: >-
        API key from the FYATU CaaS portal. Pass as `Authorization: Bearer
        <key>`.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.