Skip to main content
GET
List 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).
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

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

Example Response

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 for what a specific decline said, and card.transaction.declined to be told about declines as they happen.

Authorizations

Authorization
string
header
required

JWT access token obtained from /auth/token

Response

Merchant category restrictions retrieved

success
boolean
Example:

true

status
integer
Example:

200

message
string
Example:

"Merchant category restrictions retrieved"

data
object