MCC Groups

A merchant category code (MCC) is a four-digit number assigned by a card network (Visa or Mastercard) to a business, based on the goods or services the business offers. On the Marqeta platform, an MCC group defines a set of MCCs. You can include an MCC group within a spend control to limit user spending at a set of merchants. An MCC group also allows you to automatically increase authorization amounts and to control the expiration of authorizations for the specified MCCs. By default, these controls apply to all cards in your program. An MCC group authorization control can have exceptions defined at the card product level. See Controlling Spending for a tutorial that walks you through the creation of a spend control, as well as links to more information about merchant category codes.

Create MCC group

Action: POST
Endpoint: /mccgroups Use this endpoint to create an MCC group.

Request body

Fields	Description
active boolean Optional	Indicates if the group is active or inactive. Allowable Values: `true`, `false` Default value: `false`
config object Optional	Allows for configuration options for this group, including control over the expiration of authorizations and automatic increases to the authorization amount. Allowable Values: `authorization_controls`
config.authorization_controls object Optional	Controls the expiration of authorizations and automatic increases to the authorization amount for MCCs specified in this group. By default, these authorization controls apply program-wide, meaning that they apply to every card in your program. You can, however, exempt cards associated with any particular card product by setting that card product’s `allow_mcc_group_authorization_controls` field to `false`. Allowable Values: `hold_expiration_days`, `hold_increase`
config.authorization_controls.hold_expiration_days integer Optional	Specifies the number of days after which an authorization associated with this group expires. Allowable Values: 1–100 Default value: 7
config.authorization_controls.hold_increase object Optional	Controls automatic increases to the authorization amount for MCCs specified in this group. Allowable Values: `type`, `value`
config.authorization_controls.hold_increase.type string Required	Controls whether the `value` field represents a fixed amount or a percentage of the authorization amount. Allowable Values: `AMOUNT`, `PERCENT`, `UP_TO_LIMIT` Default value: `AMOUNT`
config.authorization_controls.hold_increase.value decimal Required	Specifies the amount of the automatic increase to the authorization amount. The `type` field controls whether this amount is a fixed amount or a percentage. Allowable Values: Format: 0.00
mccs array of objects Required	The set of merchant category codes that you want to include in this group. For each element, valid characters are 0-9, and the length must be 4 digits. You can also specify a range such as “9876-9880”. An MCC can belong to more than one group. Allowable Values: Existing merchant category codes
name string Required	Name of the MCC group. Allowable Values: 255 char max
token string Optional	Unique identifier of the MCC group. If you do not include a token, the system will generate one automatically. This token is necessary for use in other API calls, so we recommend that rather than let the system generate one, you use a simple string that is easy to remember. This value cannot be updated. Allowable Values: 1–36 chars

Sample request body

JSON

{
  "token": "my_mccgroup_01",
  "name": "My MCC Group 01",
  "mccs": [
    "0123",
    "2224-2230",
    "3876"
  ],
  "active": true,
  "config": {
    "authorization_controls": {
      "hold_increase": {
        "type": "PERCENT",
        "value": 20
      },
      "hold_expiration_days": 2
    }
  }
}

Response body

Fields	Description
active boolean Conditionally returned	Indicates if the group is active or inactive. Allowable Values: `true`, `false` Default value: `false`
config object Conditionally returned	Allows for configuration options for this group, including control over the expiration of authorizations and automatic increases to the authorization amount. Allowable Values: `authorization_controls`
config.authorization_controls object Conditionally returned	Controls the expiration of authorizations and automatic increases to the authorization amount for MCCs specified in this group. By default, these authorization controls apply program-wide, meaning that they apply to every card in your program. You can, however, exempt cards associated with any particular card product by setting that card product’s `allow_mcc_group_authorization_controls` field to `false`. Allowable Values: `hold_expiration_days`, `hold_increase`
config.authorization_controls.hold_expiration_days integer Conditionally returned	Specifies the number of days after which an authorization associated with this group expires. Allowable Values: 1–100 Default value: 7
config.authorization_controls.hold_increase object Conditionally returned	Controls automatic increases to the authorization amount for MCCs specified in this group. Allowable Values: `type`, `value`
config.authorization_controls.hold_increase.type string Returned	Controls whether the `value` field represents a fixed amount or a percentage of the authorization amount. Allowable Values: `AMOUNT`, `PERCENT`, `UP_TO_LIMIT` Default value: `AMOUNT`
config.authorization_controls.hold_increase.value decimal Returned	Specifies the amount of the automatic increase to the authorization amount. The `type` field controls whether this amount is a fixed amount or a percentage. Allowable Values: Format: 0.00
mccs array of objects Returned	The set of merchant category codes that you want to include in this group. For each element, valid characters are 0-9, and the length must be 4 digits. You can also specify a range such as “9876-9880”. An MCC can belong to more than one group. Allowable Values: Existing merchant category codes
name string Returned	Name of the MCC group. Allowable Values: 255 char max
token string Conditionally returned	Unique identifier of the MCC group. If you do not include a token, the system will generate one automatically. This token is necessary for use in other API calls, so we recommend that rather than let the system generate one, you use a simple string that is easy to remember. This value cannot be updated. Allowable Values: 1–36 chars

Sample response body

JSON

{
  "token": "my_mccgroup_01",
  "name": "My MCC Group 01",
  "mccs": [
    "0123",
    "2224-2230",
    "3876"
  ],
  "active": true,
  "config": {
    "authorization_controls": {
      "hold_increase": {
        "type": "PERCENT",
        "value": 20
      },
      "hold_expiration_days": 2
    }
  }
}

List MCC groups

Action: GET
Endpoint: /mccgroups Use this endpoint to either list all MCC groups defined in your program or list all MCC groups that contain a specified code. This endpoint supports field filtering and pagination.

URL query parameters

Fields	Description
mcc string Optional	Returns all MCC groups that contain the specified merchant category code. Allowable Values: Valid merchant category code
count integer Optional	Number of resources to retrieve. Allowable Values: 1-10
start_index integer Optional	Sort order index of the first resource in the returned array. Allowable Values: Any integer Default value: 0
sort_by string Optional	Field on which to sort. Use any field in the resource model, or one of the system fields `lastModifiedTime` or `createdTime`. Prefix the field name with a hyphen (`-`) to sort in descending order. Omit the hyphen to sort in ascending order. Allowable Values: `createdTime`, `lastModifiedTime`, or any field in the resource model Default value: `-lastModifiedTime`

Response body

Fields	Description
count integer Conditionally returned	Number of resources to retrieve. This field is returned if there are resources in your returned array. Allowable Values: 1-10
data array of objects Conditionally returned	Array of MCC group objects. Objects are returned as appropriate to your query. Allowable Values: Valid array of one or more MCC group objects
data[].active boolean Conditionally returned	Indicates if the group is active or inactive. Allowable Values: `true`, `false` Default value: `false`
data[].config object Conditionally returned	Allows for configuration options for this group, including control over the expiration of authorizations and automatic increases to the authorization amount. Allowable Values: `authorization_controls`
data[].config.authorization_controls object Conditionally returned	Controls the expiration of authorizations and automatic increases to the authorization amount for MCCs specified in this group. By default, these authorization controls apply program-wide, meaning that they apply to every card in your program. You can, however, exempt cards associated with any particular card product by setting that card product’s `allow_mcc_group_authorization_controls` field to `false`. Allowable Values: `hold_expiration_days`, `hold_increase`
data[].config.authorization_controls.hold_expiration_days integer Conditionally returned	Specifies the number of days after which an authorization associated with this group expires. Allowable Values: 1–100 Default value: 7
data[].config.authorization_controls.hold_increase object Conditionally returned	Controls automatic increases to the authorization amount for MCCs specified in this group. Allowable Values: `type`, `value`
data[].config.authorization_controls.hold_increase.type string Returned	Controls whether the `value` field represents a fixed amount or a percentage of the authorization amount. Allowable Values: `AMOUNT`, `PERCENT`, `UP_TO_LIMIT` Default value: `AMOUNT`
data[].config.authorization_controls.hold_increase.value decimal Returned	Specifies the amount of the automatic increase to the authorization amount. The `type` field controls whether this amount is a fixed amount or a percentage. Allowable Values: Format: 0.00
data[].mccs array of objects Returned	The set of merchant category codes that you want to include in this group. For each element, valid characters are 0-9, and the length must be 4 digits. You can also specify a range such as “9876-9880”. An MCC can belong to more than one group. Allowable Values: Existing merchant category codes
data[].name string Returned	Name of the MCC group. Allowable Values: 255 char max
data[].token string Conditionally returned	Unique identifier of the MCC group. If you do not include a token, the system will generate one automatically. This token is necessary for use in other API calls, so we recommend that rather than let the system generate one, you use a simple string that is easy to remember. This value cannot be updated. Allowable Values: 1–36 chars
end_index integer Conditionally returned	Sort order index of the last resource in the returned array. This field is returned if there are resources in your returned array. Allowable Values: Any integer
is_more boolean Conditionally returned	A value of `true` indicates that more unreturned resources exist. A value of `false` indicates that no more unreturned resources exist. This field is returned if there are resources in your returned array. Allowable Values: `true`, `false`
start_index integer Conditionally returned	Sort order index of the first resource in the returned array. This field is returned if there are resources in your returned array. Allowable Values: Any integer

Sample response body

JSON

{
  "count": 2,
  "start_index": 0,
  "end_index": 1,
  "is_more": false,
  "data": [
    {
      "token": "my_mccgroup_02",
      "name": "My MCC Group 02",
      "mccs": [
        "0123",
        "2224-2230"
      ],
      "active": true,
      "config": {
        "authorization_controls": {
          "hold_increase": {
            "type": "AMOUNT",
            "value": 10,
            "hold_expiration_days": 3
          }
        }
      }
    },
    {
      "token": "my_mccgroup_01",
      "name": "My MCC Group 01",
      "mccs": [
        "0123",
        "2224-2230",
        "3876"
      ],
      "active": true,
      "config": {
        "authorization_controls": {
          "hold_increase": {
            "type": "PERCENT",
            "value": 20
          },
          "hold_expiration_days": 2
        }
      }
    }
  ]
}

Update MCC group

Action: PUT
Endpoint: /mccgroups/{token} Use this endpoint to update an MCC group. Include the token path parameter to identify the MCC group to update. You must pass all the merchant category codes you want included in the group, including existing ones you want to retain.

URL path parameters

Fields	Description
token string Required	Unique identifier of the MCC group. Send a `GET` request to `/mccgroups` to retrieve MCC group tokens. Allowable Values: Existing MCC group token

Request body

Fields	Description
active boolean Optional	Indicates whether the MCC group is active or inactive. Allowable Values: `true`, `false` Default value: `false`
config object Optional	Allows for configuration options for this group, including control over the expiration of authorizations and automatic increases to the authorization amount. Allowable Values: `authorization_controls`
config.authorization_controls object Optional	Controls the expiration of authorizations and automatic increases to the authorization amount for MCCs specified in this group. By default, these authorization controls apply program-wide, meaning that they apply to every card in your program. You can, however, exempt cards associated with any particular card product by setting that card product’s `allow_mcc_group_authorization_controls` field to `false`. Allowable Values: `hold_expiration_days`, `hold_increase`
config.authorization_controls.hold_expiration_days integer Optional	Specifies the number of days after which an authorization associated with this group expires. Allowable Values: 1–100 Default value: 7
config.authorization_controls.hold_increase object Optional	Controls automatic increases to the authorization amount for MCCs specified in this group. Allowable Values: `type`, `value`
config.authorization_controls.hold_increase.type string Required	Controls whether the `value` field represents a fixed amount or a percentage of the authorization amount. Allowable Values: `AMOUNT`, `PERCENT`, `UP_TO_LIMIT` Default value: `AMOUNT`
config.authorization_controls.hold_increase.value decimal Required	Specifies the amount of the automatic increase to the authorization amount. The `type` field controls whether this amount is a fixed amount or a percentage. Allowable Values: Format: 0.00
mccs array of strings Optional	Set of merchant category codes that you want to include in this group. For each element, valid characters are 0-9, and the length must be 4 digits. You can also specify a range such as “9876-9880”. An MCC can belong to more than one group. Updating the merchant category codes for the group completely replaces the group’s existing codes. For example, if the current MCC group is `["1234"]` and you want to add the 2345 code (while retaining the existing code), you must specify `["1234", "2345"]` in this field. Allowable Values: Valid merchant category codes
name string Optional	Name of the MCC group. Allowable Values: 255 char max

Sample request body

JSON

{
  "mccs": [
    "0123",
    "2224-2230"
  ]
}

Response body

Fields	Description
active boolean Conditionally returned	Indicates whether the MCC group is active or inactive. Allowable Values: `true`, `false` Default value: `false`
config object Conditionally returned	Allows for configuration options for this group, including control over the expiration of authorizations and automatic increases to the authorization amount. Allowable Values: `authorization_controls`
config.authorization_controls object Conditionally returned	Controls the expiration of authorizations and automatic increases to the authorization amount for MCCs specified in this group. By default, these authorization controls apply program-wide, meaning that they apply to every card in your program. You can, however, exempt cards associated with any particular card product by setting that card product’s `allow_mcc_group_authorization_controls` field to `false`. Allowable Values: `hold_expiration_days`, `hold_increase`
config.authorization_controls.hold_expiration_days integer Conditionally returned	Specifies the number of days after which an authorization associated with this group expires. Allowable Values: 1–100 Default value: 7
config.authorization_controls.hold_increase object Conditionally returned	Controls automatic increases to the authorization amount for MCCs specified in this group. Allowable Values: `type`, `value`
config.authorization_controls.hold_increase.type string Returned	Controls whether the `value` field represents a fixed amount or a percentage of the authorization amount. Allowable Values: `AMOUNT`, `PERCENT`, `UP_TO_LIMIT` Default value: `AMOUNT`
config.authorization_controls.hold_increase.value decimal Returned	Specifies the amount of the automatic increase to the authorization amount. The `type` field controls whether this amount is a fixed amount or a percentage. Allowable Values: Format: 0.00
mccs array of strings Conditionally returned	Set of merchant category codes that you want to include in this group. For each element, valid characters are 0-9, and the length must be 4 digits. You can also specify a range such as “9876-9880”. An MCC can belong to more than one group. Updating the merchant category codes for the group completely replaces the group’s existing codes. For example, if the current MCC group is `["1234"]` and you want to add the 2345 code (while retaining the existing code), you must specify `["1234", "2345"]` in this field. Allowable Values: Valid merchant category codes
name string Conditionally returned	Name of the MCC group. Allowable Values: 255 char max

Sample response body

JSON

{
  "token": "my_mccgroup_02",
  "name": "My MCC Group 02",
  "mccs": [
    "0123",
    "2224-2230"
  ],
  "active": true,
  "config": {
    "authorization_controls": {
      "hold_increase": {
        "type": "AMOUNT",
        "value": 10
      },
      "hold_expiration_days": 3
    }
  }
}

Retrieve MCC group

Action: GET
Endpoint: /mccgroups/{token} Use this endpoint to retrieve a specific MCC group.

URL path parameters

Fields	Description
token string Required	Unique identifier of the MCC group. Allowable Values:

Response body

Fields	Description
active boolean Conditionally returned	Indicates if the group is active or inactive. Allowable Values: `true`, `false` Default value: `false`
config object Conditionally returned	Allows for configuration options for this group, including control over the expiration of authorizations and automatic increases to the authorization amount. Allowable Values: `authorization_controls`
config.authorization_controls object Conditionally returned	Controls the expiration of authorizations and automatic increases to the authorization amount for MCCs specified in this group. By default, these authorization controls apply program-wide, meaning that they impact every card in your program. You can, however, exempt cards associated with any particular card product by setting that card product’s `allow_mcc_group_authorization_controls` field to `false`. Allowable Values: `hold_expiration_days`, `hold_increase`
config.authorization_controls.hold_expiration_days integer Conditionally returned	Specifies the number of days after which an authorization associated with this group expires. Allowable Values: 1–100 Default value: 7
config.authorization_controls.hold_increase object Conditionally returned	Controls automatic increases to the authorization amount for MCCs specified in this group. Allowable Values: `type`, `value`
config.authorization_controls.hold_increase.type string Returned	Controls whether the `value` field represents a fixed amount or a percentage of the authorization amount. Allowable Values: `AMOUNT`, `PERCENT`, `UP_TO_LIMIT` Default value: `AMOUNT`
config.authorization_controls.hold_increase.value decimal Returned	Specifies the amount of the automatic increase to the authorization amount. The `type` field controls whether this amount is a fixed amount or a percentage. Allowable Values: Format: 0.00
mccs array of objects Returned	The set of merchant category codes that you want to include in this group. For each element, valid characters are 0-9, and the length must be 4 digits. You can also specify a range such as “9876-9880”. An MCC can belong to more than one group. Allowable Values: Existing merchant category codes
name string Returned	Name of the MCC group. Allowable Values: 255 char max
token string Conditionally returned	Unique identifier of the MCC group. If you do not include a token, the system will generate one automatically. This token is necessary for use in other API calls, so we recommend that rather than let the system generate one, you use a simple string that is easy to remember. This value cannot be updated. Allowable Values: 1–36 chars

Sample response body

JSON

{
  "token": "my_mccgroup_02",
  "name": "My MCC Group 02",
  "mccs": [
    "0123",
    "2224-2230"
  ],
  "active": true,
  "config": {
    "authorization_controls": {
      "hold_increase": {
        "type": "AMOUNT",
        "value": 10
      },
      "hold_expiration_days": 3
    }
  }
}

Core API Basics

SDKs

Credentials

Account Holders

Funding

Just-in-Time Funding

Cards

Digital Wallets

Spend Control

Accounts

Transactions

3D Secure

Real-Time Decisioning

Disputes

Digital Banking

Credit Programs

Credit Account Management

Credit Account Servicing

Credit Reward Accounts

Testing

Webhooks

​Create MCC group

​Request body

​Sample request body

​Response body

​Sample response body

​List MCC groups

​URL query parameters

​Response body

​Sample response body

​Update MCC group

​URL path parameters

​Request body

​Sample request body

​Response body

​Sample response body

​Retrieve MCC group

​URL path parameters

​Response body

​Sample response body

Create MCC group

Request body

Sample request body

Response body

Sample response body

List MCC groups

URL query parameters

Response body

Sample response body

Update MCC group

URL path parameters

Request body

Sample request body

Response body

Sample response body

Retrieve MCC group

URL path parameters

Response body

Sample response body