Authorization Controls

An authorization control limits spending by specified users at specified merchants. You can limit spending at a single merchant or at a group of merchants, and you can limit spending by a single user, users with a particular card product, or all users. You can block spending at all merchants by default and then allow it for specific merchants, or you can allow spending at all merchants by default and block it at specific merchants.

Tip
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 authorization control

Action: POST
Endpoint: /authcontrols Limit where a user can make transactions to a single merchant or group of merchants. If multiple authorization controls apply to the same user, the limits of all controls are combined.

Request body

Fields	Description
active boolean Optional	Indicates whether the authorization control is active. Allowable Values: `true`, `false` Default value: `true`
association object Optional	Defines the group of users to which the authorization control applies. This object is required if the `merchant_scope` object is not included in your request. Your request can include both the `association` and `merchant_scope` objects. If you include this object in your request, you must populate one or more of its fields. If no fields are populated, the authorization control applies to all users. Allowable Values: `card_product_token`, `user_token`
association.card_product_token string Optional	Unique identifier of a card product. Specify a card product token in the `card_product_token` field to apply the authorization control to all users holding active cards associated with the card product. Pass either `card_product_token` or `user_token`, not both. Allowable Values: 1–36 chars
association.user_token string Optional	Unique identifier of a user. Specify a user token in the `user_token` field to apply the authorization control to a single user. Pass either `card_product_token` or `user_token`, not both. Allowable Values: 1–36 chars
end_time datetime Optional	Date and time when the exception ends, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
merchant_scope object Optional	Defines the group of merchants to which the authorization control applies. This object is required if the `association` object is not included in your request. Your request can include both the `merchant_scope` and `association` objects. If you include this object in your request, you must populate one or more of its fields. If no fields are populated, the authorization control applies to all merchants. Allowable Values: `mcc`, `mcc_group`, `merchant_group_token`, `mid`
merchant_scope.mcc string Optional	Merchant Category Code (MCC). Identifies the type of goods or services provided by the merchant. Enter a value to control access to a particular type of product or service. See Controlling Spending for links to more information about merchant category codes. Allowable Values: 1–4 chars
merchant_scope.mcc_group string Optional	Token identifying a group of MCCs. Enter a value to control access to a group of product or service types. Allowable Values: 1–36 chars
merchant_scope.merchant_group_token string Optional	Unique identifier of a merchant group. Enter a value to control access to a group of merchants. Allowable Values: 1–36 chars
merchant_scope.mid string Optional	Merchant identifier (MID). Identifies a specific merchant. Enter a value to control access to a particular merchant. Allowable Values: 1–36 chars
name string Required	Name of the authorization control. Allowable Values: 255 char max
start_time datetime Optional	Date and time when the exception goes into effect, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
token string Optional	Unique identifier of the authorization control. 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

{
  "merchant_scope": {
    "mid": "98765"
  },
  "association": {
    "user_token": "my_user_01"
  },
  "token": "my_authcontrol",
  "name": "My Auth Control"
}

Response body

Fields	Description
active boolean Conditionally returned	Indicates whether the authorization control is active. This field is returned if it exists in the resource. Allowable Values: `true`, `false`
association object Conditionally returned	Defines the group of users to which the authorization control applies. This object is required if the `merchant_scope` object is not included in your request. Your request can include both the `association` and `merchant_scope` objects. If you include this object in your request, you must populate one or more of its fields. If no fields are populated, the authorization control applies to all users. Allowable Values: `card_product_token`, `user_token`
association.card_product_token string Conditionally returned	Unique identifier of a card product. Specify a card product token in the `card_product_token` field to apply the authorization control to all users holding active cards associated with the card product. Pass either `card_product_token` or `user_token`, not both. Allowable Values: 1–36 chars
association.user_token string Conditionally returned	Unique identifier of a user. Specify a user token in the `user_token` field to apply the authorization control to a single user. Pass either `card_product_token` or `user_token`, not both. Allowable Values: 1–36 chars
end_time datetime Conditionally returned	Date and time when the exception ends, in UTC. This field is returned if it exists in the resource. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
merchant_scope object Conditionally returned	Defines the group of merchants to which the authorization control applies. This object is required if the `association` object is not included in your request. Your request can include both the `merchant_scope` and `association` objects. If you include this object in your request, you must populate one or more of its fields. If no fields are populated, the authorization control applies to all merchants. Allowable Values: `mcc`, `mcc_group`, `merchant_group_token`, `mid`
merchant_scope.mcc string Conditionally returned	Merchant Category Code (MCC). Identifies the type of goods or services provided by the merchant. Enter a value to control access to a particular type of product or service. See Controlling Spending for links to more information about merchant category codes. Allowable Values: 1–4 chars
merchant_scope.mcc_group string Conditionally returned	Token identifying a group of MCCs. Enter a value to control access to a group of product or service types. Allowable Values: 1–36 chars
merchant_scope.merchant_group_token string Conditionally returned	Unique identifier of a merchant group. Enter a value to control access to a group of merchants. Allowable Values: 1–36 chars
merchant_scope.mid string Conditionally returned	Merchant identifier (MID). Identifies a specific merchant. Enter a value to control access to a particular merchant. Allowable Values: 1–36 chars
name string Returned	Name of the authorization control. Allowable Values: 255 char max
start_time datetime Conditionally returned	Date and time when the exception goes into effect, in UTC. This field is returned if it exists in the resource. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
token string Conditionally returned	Unique identifier of the authorization control. This field is returned if it exists in the resource. Allowable Values: 1–36 chars

Sample response body

JSON

{
  "token": "my_authcontrol",
  "name": "My Auth Control",
  "active": true,
  "association": {
    "user_token": "my_user_01"
  },
  "merchant_scope": {
    "mid": "98765"
  }
}

List authorization controls

Action: GET
Endpoint: /authcontrols List all authorization controls associated with a specific user or card product, or list all authorization controls defined in your program. Include either a user or a card_product query parameter to indicate the user or card product whose associated authorization controls you want to retrieve (do not include both). To list all authorization controls for your program, omit the user and card_product query parameters from your request.

URL query parameters

Fields	Description
card_product string Optional	Unique identifier of the card product whose associated authorization controls you want to retrieve. Enter the string “null” to list authorization controls that are not associated with a card product. Allowable Values: Existing `card_product` token, or “null”
user string Optional	Unique identifier of the user whose associated authorization controls you want to retrieve. Enter the string “null” to list authorization controls that are not associated with a user. Allowable Values: Existing user token, or “null”
count integer Optional	The number of resources to retrieve. Allowable Values: 1-10 Default value: 5
start_index integer Optional	Sort order index of the first resource in the returned array. Allowable Values: Any integer
fields string Optional	Comma-delimited list of fields to return (`field_1,field_2`, and so on). Leave blank to return all fields. Allowable Values: Comma-delimited list of fields, or blank
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 retrieved. This field is returned if there are resources in your returned array. Allowable Values: 1-10
data array of objects Conditionally returned	Array of objects in a returned resource. Objects are returned as appropriate to your query. Allowable Values: Valid array of one or more authorization control objects
data[].active boolean Conditionally returned	Indicates whether the authorization control is active. This field is returned if it exists in the resource. Allowable Values: `true`, `false`
data[].association object Conditionally returned	Defines the group of users to which the authorization control applies. This object is required if the `merchant_scope` object is not included in your request. Your request can include both the `association` and `merchant_scope` objects. If you include this object in your request, you must populate one or more of its fields. If no fields are populated, the authorization control applies to all users. Allowable Values: `card_product_token`, `user_token`
data[].association.card_product_token string Conditionally returned	Unique identifier of a card product. Specify a card product token in the `card_product_token` field to apply the authorization control to all users holding active cards associated with the card product. Pass either `card_product_token` or `user_token`, not both. Allowable Values: 1–36 chars
data[].association.user_token string Conditionally returned	Unique identifier of a user. Specify a user token in the `user_token` field to apply the authorization control to a single user. Pass either `card_product_token` or `user_token`, not both. Allowable Values: 1–36 chars
data[].end_time datetime Conditionally returned	Date and time when the exception ends, in UTC. This field is returned if it exists in the resource. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
data[].merchant_scope object Conditionally returned	Defines the group of merchants to which the authorization control applies. This object is required if the `association` object is not included in your request. Your request can include both the `merchant_scope` and `association` objects. If you include this object in your request, you must populate one or more of its fields. If no fields are populated, the authorization control applies to all merchants. Allowable Values: `mcc`, `mcc_group`, `merchant_group_token`, `mid`
data[].merchant_scope.mcc string Conditionally returned	Merchant Category Code (MCC). Identifies the type of goods or services provided by the merchant. Enter a value to control access to a particular type of product or service. See Controlling Spending for links to more information about merchant category codes. Allowable Values: 1–4 chars
data[].merchant_scope.mcc_group string Conditionally returned	Token identifying a group of MCCs. Enter a value to control access to a group of product or service types. Allowable Values: 1–36 chars
data[].merchant_scope.merchant_group_token string Conditionally returned	Unique identifier of a merchant group. Enter a value to control access to a group of merchants. Allowable Values: 1–36 chars
data[].merchant_scope.mid string Conditionally returned	Merchant identifier (MID). Identifies a specific merchant. Enter a value to control access to a particular merchant. Allowable Values: 1–36 chars
data[].name string Returned	Name of the authorization control. Allowable Values: 255 char max
data[].start_time datetime Conditionally returned	Date and time when the exception goes into effect, in UTC. This field is returned if it exists in the resource. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
data[].token string Conditionally returned	Unique identifier of the authorization control. This field is returned if it exists in the resource. 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": 1,
  "start_index": 0,
  "end_index": 0,
  "is_more": false,
  "data": [
    {
      "token": "my_authcontrol",
      "name": "My Auth Control",
      "active": true,
      "association": {
        "user_token": "my_user_01"
      },
      "merchant_scope": {
        "mcc": "5111"
      }
    }
  ]
}

Retrieve authorization control

Action: GET
Endpoint: /authcontrols/{token} Retrieve a specific authorization control.

URL path parameters

Fields	Description
token string Required	Existing authorization control token. Send a `GET` request to `/authcontrols` to retrieve authorization control tokens. Allowable Values: Existing `authcontrol` token

URL query parameters

Fields	Description
fields string Optional	Comma-delimited list of fields to return (`field_1,field_2`, and so on). Leave blank to return all fields. Allowable Values: Comma-delimited list of fields, or blank

Response body

Fields	Description
active boolean Conditionally returned	Indicates whether the authorization control is active. This field is returned if it exists in the resource. Allowable Values: `true`, `false`
association object Conditionally returned	Defines the group of users to which the authorization control applies. This object is required if the `merchant_scope` object is not included in your request. Your request can include both the `association` and `merchant_scope` objects. If you include this object in your request, you must populate one or more of its fields. If no fields are populated, the authorization control applies to all users. Allowable Values: `card_product_token`, `user_token`
association.card_product_token string Conditionally returned	Unique identifier of a card product. Specify a card product token in the `card_product_token` field to apply the authorization control to all users holding active cards associated with the card product. Pass either `card_product_token` or `user_token`, not both. Allowable Values: 1–36 chars
association.user_token string Conditionally returned	Unique identifier of a user. Specify a user token in the `user_token` field to apply the authorization control to a single user. Pass either `card_product_token` or `user_token`, not both. Allowable Values: 1–36 chars
end_time datetime Conditionally returned	Date and time when the exception ends, in UTC. This field is returned if it exists in the resource. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
merchant_scope object Conditionally returned	Defines the group of merchants to which the authorization control applies. This object is required if the `association` object is not included in your request. Your request can include both the `merchant_scope` and `association` objects. If you include this object in your request, you must populate one or more of its fields. If no fields are populated, the authorization control applies to all merchants. Allowable Values: `mcc`, `mcc_group`, `merchant_group_token`, `mid`
merchant_scope.mcc string Conditionally returned	Merchant Category Code (MCC). Identifies the type of goods or services provided by the merchant. Enter a value to control access to a particular type of product or service. See Controlling Spending for links to more information about merchant category codes. Allowable Values: 1–4 chars
merchant_scope.mcc_group string Conditionally returned	Token identifying a group of MCCs. Enter a value to control access to a group of product or service types. Allowable Values: 1–36 chars
merchant_scope.merchant_group_token string Conditionally returned	Unique identifier of a merchant group. Enter a value to control access to a group of merchants. Allowable Values: 1–36 chars
merchant_scope.mid string Conditionally returned	Merchant identifier (MID). Identifies a specific merchant. Enter a value to control access to a particular merchant. Allowable Values: 1–36 chars
name string Returned	Name of the authorization control. Allowable Values: 255 char max
start_time datetime Conditionally returned	Date and time when the exception goes into effect, in UTC. This field is returned if it exists in the resource. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
token string Conditionally returned	Unique identifier of the authorization control. This field is returned if it exists in the resource. Allowable Values: 1–36 chars

Sample response body

JSON

{
  "token": "my_authcontrol",
  "name": "My Auth Control",
  "active": true,
  "association": {
    "user_token": "my_user_01"
  },
  "merchant_scope": {
    "mid": "98765"
  }
}

Update authorization control

Action: PUT
Endpoint: /authcontrols/{token} Update a specific authorization control.

URL path parameters

Fields	Description
token string Required	Existing authorization control token. Send a `GET` request to `/authcontrols` to retrieve authorization control tokens. Allowable Values: Existing `authcontrol` token

Request body

Fields	Description
active boolean Optional	Indicates whether the authorization control is active. Allowable Values: `true`, `false` Default value: `true`
association object Optional	Defines the group of users to which the authorization control applies. This object is required if the `merchant_scope` object is not included in your request. Your request can include both the `association` and `merchant_scope` objects. If you include this object in your request, you must populate one or more of its fields. If no fields are populated, the authorization control applies to all users. Allowable Values: `card_product_token`, `user_token`
association.card_product_token string Optional	Unique identifier of a card product. Specify a card product token in the `card_product_token` field to apply the authorization control to all users holding active cards associated with the card product. Pass either `card_product_token` or `user_token`, not both. Allowable Values: 1–36 chars
association.user_token string Optional	Unique identifier of a user. Specify a user token in the `user_token` field to apply the authorization control to a single user. Pass either `card_product_token` or `user_token`, not both. Allowable Values: 1–36 chars
end_time datetime Optional	Date and time when the exception ends, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
merchant_scope object Optional	Defines the group of merchants to which the velocity control applies. Populate no more than one field of the `merchant_scope` object. If no fields are populated, the velocity control applies to all merchants. Allowable Values: `mcc`, `mcc_group`, `mid`, or null (no value)
merchant_scope.mcc string Optional	Merchant Category Code (MCC). Identifies the type of products or services provided by the merchant. Enter a value to control spending on a particular type of product or service. Allowable Values: 1–4 chars
merchant_scope.mcc_group string Optional	Token identifying a group of MCCs. Enter a value to control spending on a group of product or service types. Send a `GET` request to `/mccgroups` to retrieve MCC group tokens. Allowable Values: 1–36 chars
merchant_scope.mid string Optional	Merchant identifier (MID). Identifies a specific merchant. Enter a value to control spending with a particular merchant. Allowable Values: 1–36 chars
name string Optional	Name of the authorization control. Allowable Values: 255 char max
start_time datetime Optional	Date and time when the exception goes into effect, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
token string Required	Unique identifier of the authorization control. Allowable Values: 1–36 chars

Sample request body

JSON

{
  "token": "my_authcontrol",
  "merchant_scope": {
    "mcc": "5111"
  }
}

Response body

Fields	Description
active boolean Conditionally returned	Indicates whether the authorization control is active. This field is returned if it exists in the resource. Allowable Values: `true`, `false`
association object Conditionally returned	Defines the group of users to which the authorization control applies. This object is required if the `merchant_scope` object is not included in your request. Your request can include both the `association` and `merchant_scope` objects. If you include this object in your request, you must populate one or more of its fields. If no fields are populated, the authorization control applies to all users. Allowable Values: `card_product_token`, `user_token`
association.card_product_token string Conditionally returned	Unique identifier of a card product. Specify a card product token in the `card_product_token` field to apply the authorization control to all users holding active cards associated with the card product. Pass either `card_product_token` or `user_token`, not both. Allowable Values: 1–36 chars
association.user_token string Conditionally returned	Unique identifier of a user. Specify a user token in the `user_token` field to apply the authorization control to a single user. Pass either `card_product_token` or `user_token`, not both. Allowable Values: 1–36 chars
end_time datetime Conditionally returned	Date and time when the exception ends, in UTC. This field is returned if it exists in the resource. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
merchant_scope object Conditionally returned	Defines the group of merchants to which the authorization control applies. This object is required if the `association` object is not included in your request. Your request can include both the `merchant_scope` and `association` objects. If you include this object in your request, you must populate one or more of its fields. If no fields are populated, the authorization control applies to all merchants. Allowable Values: `mcc`, `mcc_group`, `merchant_group_token`, `mid`
merchant_scope.mcc string Conditionally returned	Merchant Category Code (MCC). Identifies the type of goods or services provided by the merchant. Enter a value to control access to a particular type of product or service. See Controlling Spending for links to more information about merchant category codes. Allowable Values: 1–4 chars
merchant_scope.mcc_group string Conditionally returned	Token identifying a group of MCCs. Enter a value to control access to a group of product or service types. Allowable Values: 1–36 chars
merchant_scope.merchant_group_token string Conditionally returned	Unique identifier of a merchant group. Enter a value to control access to a group of merchants. Allowable Values: 1–36 chars
merchant_scope.mid string Conditionally returned	Merchant identifier (MID). Identifies a specific merchant. Enter a value to control access to a particular merchant. Allowable Values: 1–36 chars
name string Returned	Name of the authorization control. Allowable Values: 255 char max
start_time datetime Conditionally returned	Date and time when the exception goes into effect, in UTC. This field is returned if it exists in the resource. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
token string Conditionally returned	Unique identifier of the authorization control. This field is returned if it exists in the resource. Allowable Values: 1–36 chars

Sample response body

JSON

{
  "token": "my_authcontrol",
  "name": "My Auth Control",
  "active": true,
  "association": {
    "user_token": "my_user_01"
  },
  "merchant_scope": {
    "mcc": "5111"
  }
}

Create a merchant identifier (MID) exemption

Action: POST
Endpoint: /authcontrols/exemptmids Exempt an individual merchant from authorization controls by merchant identifier (MID). Transactions originating from this MID ignore any otherwise applicable authorization controls.

Note
You can create MID exemptions in your user sandbox. However, you must work with your Marqeta representative to create MID exemptions in a production environment.

Request body

Fields	Description
association object Optional	Defines the group of users to which the authorization control applies. This object is required if the `merchant_scope` object is not included in your request. Your request can include both the `association` and `merchant_scope` objects. If you include this object in your request, you must populate one or more of its fields. If no fields are populated, the authorization control applies to all users. Allowable Values: `card_product_token`, `user_token`
association.card_product_token string Optional	Unique identifier of a card product. Specify a card product token in the `card_product_token` field to apply the authorization control to all users holding active cards associated with the card product. Pass either `card_product_token` or `user_token`, not both. Allowable Values: 1–36 chars
association.user_token string Optional	Unique identifier of a user. Specify a user token in the `user_token` field to apply the authorization control to a single user. Pass either `card_product_token` or `user_token`, not both. Allowable Values: 1–36 chars
end_time datetime Optional	Date and time when the exception ends, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
merchant_group_token string Optional	Unique identifier of the merchant group to be exempted. This field is required if there is no entry in the `mid` field. Pass either this field or the `mid` field, not both. For information about merchant groups, see Merchant Groups. Allowable Values: 1–36 chars
mid string Optional	Merchant to be exempted. This field is required if there is no entry in the `merchant_group_token` field. Use either this field or the `merchant_group_token` field, not both. Allowable Values: 1–36 chars
name string Required	Name of the merchant identifier authorization control exemption. Allowable Values: 255 char max
start_time datetime Optional	Date and time when the exception starts, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
token string Optional	Unique identifier of the merchant identifier authorization control exemption. 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

Sample request body

JSON

{
  "token": "my_exempt_token",
  "name": "my_exempt_mid",
  "association": {
    "card_product_token": "my_card_product"
  },
  "mid": "12345678901"
}

Response body

Fields	Description
active boolean Conditionally returned	Indicates whether the merchant identifier authorization control exception is active. This field is returned if it exists in the resource. Allowable Values: `true`, `false`
association object Conditionally returned	Defines the group of users to which the authorization control applies. This object is required if the `merchant_scope` object is not included in your request. Your request can include both the `association` and `merchant_scope` objects. If you include this object in your request, you must populate one or more of its fields. If no fields are populated, the authorization control applies to all users. Allowable Values: `card_product_token`, `user_token`
association.card_product_token string Conditionally returned	Unique identifier of a card product. Specify a card product token in the `card_product_token` field to apply the authorization control to all users holding active cards associated with the card product. Pass either `card_product_token` or `user_token`, not both. Allowable Values: 1–36 chars
association.user_token string Conditionally returned	Unique identifier of a user. Specify a user token in the `user_token` field to apply the authorization control to a single user. Pass either `card_product_token` or `user_token`, not both. Allowable Values: 1–36 chars
created datetime Conditionally returned	Date and time when the resource was created, in UTC. This field is returned if it exists in the resource. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
end_time datetime Conditionally returned	Date and time when the exception ends, in UTC. This field is returned if it exists in the resource. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
last_updated datetime Conditionally returned	Date and time when the resource was last updated, in UTC. This field is returned if it exists in the resource. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
merchant_group_token string Conditionally returned	Unique identifier of the merchant group to be exempted. This field is returned if it exists in the resource. Allowable Values: 1–36 chars
mid string Conditionally returned	Merchant to be exempted. This field is returned if it exists in the resource. Allowable Values: 1–36 chars
name string Returned	Name of the merchant identifier authorization control exemption. Allowable Values: 255 char max
start_time datetime Conditionally returned	Date and time when the exception starts, in UTC. This field is returned if it exists in the resource. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
token string Conditionally returned	Unique identifier of the merchant identifier authorization control exemption. This field is always returned. Allowable Values: Existing merchant identifier authorization control exemption token

Sample response body

JSON

{
  "token": "my_exempt_token",
  "name": "my_exempt_mid",
  "association": {
    "card_product_token": "my_card_product"
  },
  "mid": "12345678901",
  "active": true,
  "created_time": "2022-06-19T13:22:07Z",
  "last_modified_time": "2022-06-19T13:22:07Z"
}

List merchant identifier (MID) exemptions

Action: GET
Endpoint: /authcontrols/exemptmids Retrieve a list of all merchant (MID) exemptions.

URL query parameters

Fields	Description
card_product string Optional	Unique identifier of the card product whose associated MID exemptions you want to retrieve. Enter the string “null” to list MID exemptions that are not associated with a card product. Allowable Values: Existing `card_product` token, or “null”
user string Optional	Unique identifier of the user whose associated MID exemptions you want to retrieve. Enter the string “null” to list MID exemptions that are not associated with a user. Allowable Values: Existing user token, or “null”
count integer Optional	The number of resources to retrieve. Allowable Values: 1-10 Default value: 5
start_index integer Optional	The sort order index of the first resource in the returned array. Allowable Values: Any integer Default value: 0
fields string Optional	Comma-delimited list of fields to return (`field_1,field_2`, and so on). Leave blank to return all fields. Allowable Values: Comma-delimited list of fields, or blank
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 retrieved. This field is returned if there are resources in your returned array. Allowable Values: 1-10
data array of objects Conditionally returned	Array of objects in a returned resource. Objects are returned as appropriate to your query. Allowable Values: Valid data array of one or more authorization control objects
data[].active boolean Conditionally returned	Indicates whether the merchant identifier authorization control exception is active. This field is returned if it exists in the resource. Allowable Values: `true`, `false`
data[].association object Conditionally returned	Defines the group of users to which the authorization control applies. This object is required if the `merchant_scope` object is not included in your request. Your request can include both the `association` and `merchant_scope` objects. If you include this object in your request, you must populate one or more of its fields. If no fields are populated, the authorization control applies to all users. Allowable Values: `card_product_token`, `user_token`
data[].association.card_product_token string Conditionally returned	Unique identifier of a card product. Specify a card product token in the `card_product_token` field to apply the authorization control to all users holding active cards associated with the card product. Pass either `card_product_token` or `user_token`, not both. Allowable Values: 1–36 chars
data[].association.user_token string Conditionally returned	Unique identifier of a user. Specify a user token in the `user_token` field to apply the authorization control to a single user. Pass either `card_product_token` or `user_token`, not both. Allowable Values: 1–36 chars
data[].created datetime Conditionally returned	Date and time when the resource was created, in UTC. This field is returned if it exists in the resource. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
data[].end_time datetime Conditionally returned	Date and time when the exception ends, in UTC. This field is returned if it exists in the resource. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
data[].last_updated datetime Conditionally returned	Date and time when the resource was last updated, in UTC. This field is returned if it exists in the resource. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
data[].merchant_group_token string Conditionally returned	Unique identifier of the merchant group to be exempted. This field is returned if it exists in the resource. Allowable Values: 1–36 chars
data[].mid string Conditionally returned	Merchant to be exempted. This field is returned if it exists in the resource. Allowable Values: 1–36 chars
data[].name string Returned	Name of the merchant identifier authorization control exemption. Allowable Values: 255 char max
data[].start_time datetime Conditionally returned	Date and time when the exception starts, in UTC. This field is returned if it exists in the resource. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
data[].token string Conditionally returned	Unique identifier of the merchant identifier authorization control exemption. This field is always returned. Allowable Values: Existing merchant identifier authorization control exemption token
end_index integer Conditionally returned	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. 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. Allowable Values: Any integer

Sample response body

JSON

{
  "count": 2,
  "start_index": 0,
  "end_index": 1,
  "is_more": false,
  "data": [
    {
      "token": "my_exempt_authcontrol",
      "name": "My Exempt Auth Control",
      "active": true,
      "mid": "984226812886",
      "created_time": "2022-07-03T13:22:07Z",
      "last_modified_time": "2022-07-03T17:22:07Z"
    },
    {
      "token": "my_exempt_authcontrol_2",
      "name": "My Exempt Auth Control 2",
      "active": true,
      "association": {
        "card_product_token": "my_card_product"
      },
      "mid": "1234567891",
      "created_time": "2022-07-03T17:22:07Z",
      "last_modified_time": "2022-07-03T17:22:07Z"
    }
  ]
}

Retrieve a merchant identifier (MID) exemption

Action: GET
Endpoint: /authcontrols/exemptmids/{token} Retrieve a merchant (MID) exemption.

URL path parameters

Fields	Description
token string Required	Unique identifier of the authorization control resource. Allowable Values: Existing authorization control resource token

Response body

Fields	Description
active boolean Conditionally returned	Indicates whether the merchant identifier authorization control exception is active. This field is returned if it exists in the resource. Allowable Values: `true`, `false`
association object Conditionally returned	Defines the group of users to which the authorization control applies. This object is required if the `merchant_scope` object is not included in your request. Your request can include both the `association` and `merchant_scope` objects. If you include this object in your request, you must populate one or more of its fields. If no fields are populated, the authorization control applies to all users. Allowable Values: `card_product_token`, `user_token`
association.card_product_token string Conditionally returned	Unique identifier of a card product. Specify a card product token in the `card_product_token` field to apply the authorization control to all users holding active cards associated with the card product. Pass either `card_product_token` or `user_token`, not both. Allowable Values: 1–36 chars
association.user_token string Conditionally returned	Unique identifier of a user. Specify a user token in the `user_token` field to apply the authorization control to a single user. Pass either `card_product_token` or `user_token`, not both. Allowable Values: 1–36 chars
created datetime Conditionally returned	Date and time when the resource was created, in UTC. This field is returned if it exists in the resource. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
end_time datetime Conditionally returned	Date and time when the exception ends, in UTC. This field is returned if it exists in the resource. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
last_updated datetime Conditionally returned	Date and time when the resource was last updated, in UTC. This field is returned if it exists in the resource. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
merchant_group_token string Conditionally returned	Unique identifier of the merchant group to be exempted. This field is returned if it exists in the resource. Allowable Values: 1–36 chars
mid string Conditionally returned	Merchant to be exempted. This field is returned if it exists in the resource. Allowable Values: 1–36 chars
name string Returned	Name of the merchant identifier authorization control exemption. Allowable Values: 255 char max
start_time datetime Conditionally returned	Date and time when the exception starts, in UTC. This field is returned if it exists in the resource. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
token string Conditionally returned	Unique identifier of the merchant identifier authorization control exemption. This field is always returned. Allowable Values: Existing merchant identifier authorization control exemption token

Sample response body

JSON

{
  "token": "my_exempt_token",
  "name": "my_exempt_mid",
  "association": {
    "card_product_token": "my_card_product"
  },
  "mid": "12345678901",
  "active": true,
  "created_time": "2022-06-19T13:22:07Z",
  "last_modified_time": "2022-06-19T13:22:07Z"
}

Update a merchant identifier (MID) exemption

Action: PUT
Endpoint: /authcontrols/exemptmids/{token} Update a merchant identifier exemption.

URL path parameters

Fields	Description
token string Required	Unique identifier of the authorization control resource. Allowable Values: Existing authorization control resource token

Request body

Fields	Description
active boolean Optional	Indicates whether the merchant identifier authorization control exception is active. Allowable Values: `true`, `false` Default value: `false`

Sample request body

JSON

{
  "active": false
}

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 authorization control

​Request body

​Sample request body

​Response body

​Sample response body

​List authorization controls

​URL query parameters

​Response body

​Sample response body

​Retrieve authorization control

​URL path parameters

​URL query parameters

​Response body

​Sample response body

​Update authorization control

​URL path parameters

​Request body

​Sample request body

​Response body

​Sample response body

​Create a merchant identifier (MID) exemption

​Request body

​Sample request body

​Response body

​Sample response body

​List merchant identifier (MID) exemptions

​URL query parameters

​Response body

​Sample response body

​Retrieve a merchant identifier (MID) exemption

​URL path parameters

​Response body

​Sample response body

​Update a merchant identifier (MID) exemption

​URL path parameters

​Request body

​Sample request body

Create authorization control

Request body

Sample request body

Response body

Sample response body

List authorization controls

URL query parameters

Response body

Sample response body

Retrieve authorization control

URL path parameters

URL query parameters

Response body

Sample response body

Update authorization control

URL path parameters

Request body

Sample request body

Response body

Sample response body

Create a merchant identifier (MID) exemption

Request body

Sample request body

Response body

Sample response body

List merchant identifier (MID) exemptions

URL query parameters

Response body

Sample response body

Retrieve a merchant identifier (MID) exemption

URL path parameters

Response body

Sample response body

Update a merchant identifier (MID) exemption

URL path parameters

Request body

Sample request body