/
15 minute read
March 24, 2022

MCC Groups

A merchant category code (MCC) is a four-digit number assigned by the 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.

See Controlling Spending for a tutorial that walks you through the creation of a spend control 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:

An existing config object

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:

Existing config.authorization_controls object

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:

An existing config.authorization_controls.hold_increase object

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, 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

name

string
Required

The name of the group.

Allowable Values:

255 char max

token

string
Optional

The 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

Response body
Fields Description

active

boolean
Conditionally returned

Indicates if the group is active or inactive.

Allowable Values:

true, 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:

An existing config object

config.authorization_controls

object
Conditionally returned

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

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

config.authorization_controls.hold_increase

object
Conditionally returned

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

Allowable Values:

An existing config.authorization_controls.hold_increase object

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

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 included in the group.

Allowable Values:

Existing merchant category codes

name

string
Returned

The name of the group.

Allowable Values:

255 char max

token

string
Conditionally returned

The unique identifier of the MCC group.

Allowable Values:

1–36 chars

Sample request body
JSON
Copied

Is this helpful?

Yes
No
Sample response body
JSON
Copied

Is this helpful?

Yes
No

List MCC groups

Action: GET
Endpoint: /mccgroups

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.

URL query parameters
Fields Description

mcc

string
Optional

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

Allowable Values:

A merchant category code

count

integer
Optional

The number of resources to retrieve.

Allowable Values:

1-10

start_index

integer
Optional

The sort order index of the first resource in the returned array.

Allowable Values:

Any integer

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:

lastModifiedTime, createdTime, or any field in the resource model

Response body
Fields Description

count

integer
Conditionally returned

The number of resources to retrieve.

Allowable Values:

1-10

data

array of objects
Conditionally returned

An array of MCC group objects.

Allowable Values:

A valid MCC group array

data[].active

boolean
Conditionally returned

Indicates if the group is active or inactive.

Allowable Values:

true, 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:

An existing config object

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.

Allowable Values:

Existing config.authorization_controls object

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

data[].config.authorization_controls.hold_increase

object
Conditionally returned

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

Allowable Values:

An existing config.authorization_controls.hold_increase object

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

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 included in the group.

Allowable Values:

Existing merchant category codes

data[].name

string
Returned

The name of the group.

Allowable Values:

255 char max

data[].token

string
Conditionally returned

The unique identifier of the group.

Allowable Values:

1–36 chars

end_index

integer
Conditionally returned

The sort order index of the last resource in the returned array.

Allowable Values:

Any integer

is_more

boolean
Conditionally returned

A value of true indicates that more unreturned resources exist.

Allowable Values:

true, false

start_index

integer
Conditionally returned

The sort order index of the first resource in the returned array.

Allowable Values:

Any integer

Sample response body
JSON
Copied

Is this helpful?

Yes
No

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

The unique identifier of the MCC group.

Allowable Values:

1–36 chars

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

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:

An existing config object

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:

Existing config.authorization_controls object

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:

An existing config.authorization_controls.hold_increase object

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

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.

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:

Existing merchant category codes

name

string
Optional

The name of the MCC group.

Allowable Values:

255 char max

Response body
Fields Description

active

boolean
Conditionally returned

Indicates whether the MCC group is active or inactive.

Allowable Values:

true, 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:

An existing config object

config.authorization_controls

object
Conditionally returned

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

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

config.authorization_controls.hold_increase

object
Conditionally returned

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

Allowable Values:

An existing config.authorization_controls.hold_increase object

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

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

The set of merchant category codes included in the group.

Allowable Values:

Existing merchant category codes

name

string
Conditionally returned

The name of the MCC group.

Allowable Values:

255 char max

Sample request body
JSON
Copied

Is this helpful?

Yes
No
Sample response body
JSON
Copied

Is this helpful?

Yes
No

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

The unique identifier of the MCC group.

Allowable Values:

1–36 chars

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

Response body
Fields Description

active

boolean
Conditionally returned

Indicates if the group is active or inactive.

Allowable Values:

true, 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:

An existing config object

config.authorization_controls

object
Conditionally returned

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

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

config.authorization_controls.hold_increase

object
Conditionally returned

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

Allowable Values:

An existing config.authorization_controls.hold_increase object

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

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 included in the group.

Allowable Values:

Existing merchant category codes

name

string
Returned

The name of the group.

Allowable Values:

255 char max

token

string
Conditionally returned

The unique identifier of the MCC group.

Allowable Values:

1–36 chars

Sample response body
JSON
Copied

Is this helpful?

Yes
No
Join our developer newsletter