> ## 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.

# List Merchant Category Restrictions

> The merchant categories the card issuer has been observed declining, as MCC plus description, so you can answer a cardholder instead of guessing. GET /cards/merchant-category-restrictions.

## Overview

Some payments on this card programme are declined with a merchant-restriction reason, and until
now the only way to find out was for a cardholder to try one. 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 support question with something better than a guess.

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

> [!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 authorisations 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 | A statement about any other card you hold |
| Read-only reporting | A control. Nothing here is used to decide an authorisation |

Because it is observed, absence is weak evidence and presence is moderate evidence. A category on
this list has had real declines; a category absent from it simply has not been seen failing.

## 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 you
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

```php PHP theme={null}
<?php
$url = 'https://api.fyatu.com/api/v3/cards/merchant-category-restrictions';
$response = file_get_contents($url, false, stream_context_create([
    'http' => [
        'method' => 'GET',
        'header' => 'Authorization: Bearer ' . $accessToken,
    ],
]));

$result = json_decode($response, true);
foreach ($result['data']['categories'] as $c) {
    printf("%-6s %s\n", $c['mcc'], $c['category']);
}
```

```javascript Node.js theme={null}
// Check one category before telling a cardholder anything
const res = await fetch(
  'https://api.fyatu.com/api/v3/cards/merchant-category-restrictions',
  { headers: { Authorization: `Bearer ${accessToken}` } }
);
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/cards/merchant-category-restrictions",
    headers={"Authorization": f"Bearer {access_token}"},
    timeout=30,
)
data = r.json()["data"]

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

```bash cURL theme={null}
curl -s 'https://api.fyatu.com/api/v3/cards/merchant-category-restrictions' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## 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_8f3c1d92b47a4e05",
    "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 authorisation 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.

Related: [Card Transactions](https://docs.fyatu.com/v3/api-reference/cards/transactions.md) for what a specific decline
said, and [`card.transaction.declined`](https://docs.fyatu.com/v3/webhooks/webhook-events/card-transaction-declined) to be told about declines as they happen.


## OpenAPI

````yaml v3/openapi.json GET /cards/merchant-category-restrictions
openapi: 3.1.0
info:
  title: FYATU API v3
  description: >-
    FYATU API v3 with JWT authentication for Collections, Payouts, and Card
    Issuing.
  version: 3.0.0
  contact:
    name: FYATU Support
    url: https://fyatu.com
    email: support@fyatu.com
servers:
  - url: https://api.fyatu.com/api/v3
    description: Production
security: []
tags:
  - name: Authentication
    description: JWT token management endpoints
  - name: Account
    description: Business account, wallet, and address management
  - name: Collections
    description: Accept payments from customers via checkout sessions
  - name: Refunds
    description: Issue refunds for completed collections
  - name: Payouts
    description: Send money to Fyatu account holders
  - name: Cardholders
    description: Cardholder management for card issuing programs
  - name: Cards
    description: Issue, fund, freeze, and manage virtual cards
  - name: Webhooks
    description: Webhook configuration and management
paths:
  /cards/merchant-category-restrictions:
    get:
      tags:
        - Cards
      summary: List 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.


        **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. Nothing on this
        list is used to decide an authorisation. It covers the two BINs issued
        on this programme: `537100` (Mastercard Elite) and `486555` (VISA
        Classic).
      operationId: listMerchantCategoryRestrictions
      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 access token
        '503':
          description: >-
            The list is not available on this deployment. Returned instead of an
            empty array, which would read as "nothing is restricted".
      security:
        - BearerAuth: []
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT access token obtained from /auth/token

````

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