DOCS

New!

Support
Sign in to get developer support

Marqeta Home

/
Developer Guides
Core API Reference
DiVA API Reference
Core API Explorer

10 minute read

February 3, 2020

MCC Groups

A merchant category code (MCC) is a four-digit number assigned by card networks to a business based on the goods or services offered by the business. 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 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.

Note
See Controlling Spending for a tutorial that walks you through the creation of a spend control.

Create MCC group
Copy section link

Action: POST
Endpoint: /mccgroups

Develop Now!

Sign in and use your sandbox to access the API Explorer

Use this endpoint to create an MCC group.

Body field details
Copy section link

Fields Description

token

string
Optional

The unique identifier of the 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:

36 char max

name

string
Required

The name of the group.

Allowable Values:

40 char max

mccs

array
Required

The set of merchant category codes that you want to include in this group. For each element, valid characters are 0-9, length must be 4. You can also specify a range like "9876-9880". An MCC can belong to more than one group.

Allowable Values:

Existing merchant category codes

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:

Existing config object.

The config object
Copy section link

Fields Description

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:

Existing config.authorization_controls object.

The config.authorization_controls object
Copy section link

Fields Description

hold_increase

object
Optional

Controls automatic increases to the authorization amount for MCCs specified in this group.

Allowable Values:

Existing config/authorization_controls.hold_increase object.

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

The config.authorization_controls.hold_increase object
Copy section link

Fields Description

type

string
Required

Controls whether the value field represents a fixed amount or a percentage of the authorization amount.

Allowable Values:

AMOUNT, PERCENT

Default value: AMOUNT

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

Sample request body
Copy section link

{
  "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
    }
  }
}

Is this helpful?

Sample response body
Copy section link

{
  "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
    }
  }
}

Is this helpful?

Retrieve MCC group
Copy section link

Action: GET
Endpoint: /mccgroups/{token}

Develop Now!

Sign in and use your sandbox to access the API Explorer

Use this endpoint to retrieve a specific MCC group.

URL path parameters
Copy section link

Fields Description

token

string
Required

Identifies the MCC group.

Allowable Values:

Existing MCC group token.

Send a GET request to /mccgroups to retrieve MCC group tokens.

Sample response body
Copy section link

{
  "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
    }
  }
}

Is this helpful?

Update MCC group
Copy section link

Action: PUT
Endpoint: /mccgroups/{token}

Develop Now!

Sign in and use your sandbox to access the API Explorer

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
Copy section link

Fields Description

token

string
Required

Identifies the MCC group.

Allowable Values:

Existing MCC group token.

Send a GET request to /mccgroups to retrieve MCC group tokens.

Body field details
Copy section link

Fields Description

name

string
Optional

The name of the MCC group.

Allowable Values:

40 char max

mccs

array
Optional

The set of merchant category codes to include in the MCC group.

A merchant category code can belong to more than one group.

Allowable Values:

Array of existing merchant category codes.

Each code is a four-digit number. You can also specify ranges such as "9876-9880".

Note
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. You delete a code by simply not specifying it in the update.

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:

Existing config object.

The config object
Copy section link

Fields Description

authorization_controls

object
Optional

Controls the expiration of authorizations and automatic increases to the authorization amount for MCCs specified in this group.

Allowable Values:

Existing config.authorization_controls object.

The config.authorization_controls object
Copy section link

Fields Description

hold_increase

object
Optional

Controls automatic increases to the authorization amount for MCCs specified in this group.

Allowable Values:

Existing config/authorization_controls.hold_increase object.

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

The config.authorization_controls.hold_increase object
Copy section link

Fields Description

type

string
Required

Controls whether the value field represents a fixed amount or a percentage of the authorization amount.

Allowable Values:

AMOUNT, PERCENT

Default value: AMOUNT

value

decimal
Required

Specifies the amount of the automatic increase to the authorization amount.

The type field controls whether this amount is a flat amount or percentage.

Allowable Values:

Format: 0.00

Sample request body
Copy section link

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

Is this helpful?

Sample response body
Copy section link

{
  "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
    }
  }
}

Is this helpful?

List MCC groups
Copy section link

Action: GET
Endpoint: /mccgroups

Develop Now!

Sign in and use your sandbox to access the API Explorer

Use this endpoint to list all MCC groups defined in your program or list MCC groups that contain a specified code.

This endpoint supports field filtering and pagination.

Query parameters
Copy section link

Fields Description

mcc

string
Optional

Returns all MCC groups that contain the specified merchant category code.

Allowable Values:

A merchant category code.

Sample response body
Copy section link

{
  "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
        }
      }
    }
  ]
}

Is this helpful?

Related Materials

Have any feedback on this page?

If you feel we can do anything better, please let our team know.

We strive for the best possible developer experience.