Create MCC group
Action:POSTEndpoint:
/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, falseDefault 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_LIMITDefault 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, falseDefault 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_LIMITDefault 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:GETEndpoint:
/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 modelDefault 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, falseDefault 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_LIMITDefault 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:PUTEndpoint:
/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, falseDefault 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_LIMITDefault 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, falseDefault 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_LIMITDefault 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:GETEndpoint:
/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, falseDefault 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_LIMITDefault 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
}
}
}