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
Copy section link
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
Copy section link
| Fields | Description |
|---|---|
active
boolean
|
Indicates whether the authorization control is active. Allowable Values:
Default value: |
association
object
|
Defines the group of users to which the authorization control applies.
This object is required if the 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:
|
association.card_product_token
string
|
Unique identifier of a card product. Specify a card product token in the Pass either Allowable Values: 1–36 chars |
association.user_token
string
|
Unique identifier of a user. Specify a user token in the Pass either Allowable Values: 1–36 chars |
end_time
datetime
|
Date and time when the exception ends, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
merchant_scope
object
|
Defines the group of merchants to which the authorization control applies.
This object is required if the 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:
|
merchant_scope.mcc
string
|
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
|
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
|
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
|
Merchant identifier (MID). Identifies a specific merchant. Enter a value to control access to a particular merchant. Allowable Values: 1–36 chars |
name
string
|
Name of the authorization control. Allowable Values: 255 char max |
start_time
datetime
|
Date and time when the exception goes into effect, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
token
string
|
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 |
Response body
Copy section link
| Fields | Description |
|---|---|
active
boolean
|
Indicates whether the authorization control is active. This field is returned if it exists in the resource. Allowable Values:
|
association
object
|
Defines the group of users to which the authorization control applies. Allowable Values:
|
association.card_product_token
string
|
Unique identifier of a card product. Allowable Values: 1–36 chars |
association.user_token
string
|
Unique identifier of a user. Allowable Values: 1–36 chars |
end_time
datetime
|
Date and time when the exception ends, in UTC. This field is returned if it exists in the resource. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
merchant_scope
object
|
Defines the group of merchants to which the authorization control applies. Allowable Values:
|
merchant_scope.mcc
string
|
Merchant Category Code (MCC). Identifies the type of goods or services provided by the merchant. Allowable Values: 1–4 chars |
merchant_scope.mcc_group
string
|
Token identifying a group of MCCs. Allowable Values: 1–36 chars |
merchant_scope.merchant_group_token
string
|
Unique identifier of a merchant group. Allowable Values: 1–36 chars |
merchant_scope.mid
string
|
Merchant identifier (MID). Identifies a specific merchant. Allowable Values: 1–36 chars |
name
string
|
Name of the authorization control. Allowable Values: 255 char max |
start_time
datetime
|
Date and time when the exception goes into effect, in UTC. This field is returned if it exists in the resource. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
token
string
|
Unique identifier of the authorization control. This field is returned if it exists in the resource. Allowable Values: 1–36 chars |
List authorization controls
Copy section link
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
Copy section link
| Fields | Description |
|---|---|
card_product
string
|
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 |
user
string
|
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 |
count
integer
|
The number of resources to retrieve. Allowable Values: 1-10 Default value: |
start_index
integer
|
Sort order index of the first resource in the returned array. Allowable Values: Any integer |
fields
string
|
Comma-delimited list of fields to return ( Allowable Values: Comma-delimited list of fields, or blank |
sort_by
string
|
Field on which to sort.
Use any field in the resource model, or one of the system fields Allowable Values:
Default value: |
Response body
Copy section link
| Fields | Description |
|---|---|
count
integer
|
Number of resources retrieved. This field is returned if there are resources in your returned array. Allowable Values: 1-10 |
data
array of objects
|
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
|
Indicates whether the authorization control is active. This field is returned if it exists in the resource. Allowable Values:
|
data[].association
object
|
Defines the group of users to which the authorization control applies.
This object is required if the 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:
|
data[].association.card_product_token
string
|
Unique identifier of a card product. Specify a card product token in the Pass either Allowable Values: 1–36 chars |
data[].association.user_token
string
|
Unique identifier of a user. Specify a user token in the Pass either Allowable Values: 1–36 chars |
data[].end_time
datetime
|
Date and time when the exception ends, in UTC. This field is returned if it exists in the resource. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
data[].merchant_scope
object
|
Defines the group of merchants to which the authorization control applies.
This object is required if the 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:
|
data[].merchant_scope.mcc
string
|
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
|
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
|
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
|
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
|
Name of the authorization control. Allowable Values: 255 char max |
data[].start_time
datetime
|
Date and time when the exception goes into effect, in UTC. This field is returned if it exists in the resource. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
data[].token
string
|
Unique identifier of the authorization control. This field is returned if it exists in the resource. Allowable Values: 1–36 chars |
end_index
integer
|
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
|
A value of This field is returned if there are resources in your returned array. Allowable Values:
|
start_index
integer
|
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 |
Retrieve authorization control
Copy section link
Action: GET
Endpoint: /authcontrols/{token}
Retrieve a specific authorization control.
URL path parameters
Copy section link
| Fields | Description |
|---|---|
token
string
|
Existing authorization control token. Send a Allowable Values: Existing |
URL query parameters
Copy section link
| Fields | Description |
|---|---|
fields
string
|
Comma-delimited list of fields to return ( Allowable Values: Comma-delimited list of fields, or blank |
Response body
Copy section link
| Fields | Description |
|---|---|
active
boolean
|
Indicates whether the authorization control is active. This field is returned if it exists in the resource. Allowable Values:
|
association
object
|
Defines the group of users to which the authorization control applies. Allowable Values:
|
association.card_product_token
string
|
Unique identifier of a card product. Allowable Values: 1–36 chars |
association.user_token
string
|
Unique identifier of a user. Allowable Values: 1–36 chars |
end_time
datetime
|
Date and time when the exception ends, in UTC. This field is returned if it exists in the resource. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
merchant_scope
object
|
Defines the group of merchants to which the authorization control applies. Allowable Values:
|
merchant_scope.mcc
string
|
Merchant Category Code (MCC). Identifies the type of goods or services provided by the merchant. Allowable Values: 1–4 chars |
merchant_scope.mcc_group
string
|
Token identifying a group of MCCs. Allowable Values: 1–36 chars |
merchant_scope.merchant_group_token
string
|
Unique identifier of a merchant group. Allowable Values: 1–36 chars |
merchant_scope.mid
string
|
Merchant identifier (MID). Identifies a specific merchant. Allowable Values: 1–36 chars |
name
string
|
Name of the authorization control. Allowable Values: 255 char max |
start_time
datetime
|
Date and time when the exception goes into effect, in UTC. This field is returned if it exists in the resource. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
token
string
|
Unique identifier of the authorization control. This field is returned if it exists in the resource. Allowable Values: 1–36 chars |
Update authorization control
Copy section link
Action: PUT
Endpoint: /authcontrols/{token}
Update a specific authorization control.
URL path parameters
Copy section link
| Fields | Description |
|---|---|
token
string
|
Existing authorization control token. Send a Allowable Values: Existing |
Request body
Copy section link
| Fields | Description |
|---|---|
active
boolean
|
Indicates whether the authorization control is active. Allowable Values:
Default value: |
association
object
|
Defines the group of users to which the authorization control applies.
This object is required if the 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:
|
association.card_product_token
string
|
Unique identifier of a card product. Specify a card product token in the Pass either Allowable Values: 1–36 chars |
association.user_token
string
|
Unique identifier of a user. Specify a user token in the Pass either Allowable Values: 1–36 chars |
end_time
datetime
|
Date and time when the exception ends, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
merchant_scope
object
|
Defines the group of merchants to which the velocity control applies. Populate no more than one field of the Allowable Values:
|
merchant_scope.mcc
string
|
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
|
Token identifying a group of MCCs. Enter a value to control spending on a group of product or service types. Send a Allowable Values: 1–36 chars |
merchant_scope.mid
string
|
Merchant identifier (MID). Identifies a specific merchant. Enter a value to control spending with a particular merchant. Allowable Values: 1–36 chars |
name
string
|
Name of the authorization control. Allowable Values: 255 char max |
start_time
datetime
|
Date and time when the exception goes into effect, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
token
string
|
Unique identifier of the authorization control. Allowable Values: 1–36 chars |
Response body
Copy section link
| Fields | Description |
|---|---|
active
boolean
|
Indicates whether the authorization control is active. This field is returned if it exists in the resource. Allowable Values:
|
association
object
|
Defines the group of users to which the authorization control applies. Allowable Values:
|
association.card_product_token
string
|
Unique identifier of a card product. Allowable Values: 1–36 chars |
association.user_token
string
|
Unique identifier of a user. Allowable Values: 1–36 chars |
end_time
datetime
|
Date and time when the exception ends, in UTC. This field is returned if it exists in the resource. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
merchant_scope
object
|
Defines the group of merchants to which the authorization control applies. Allowable Values:
|
merchant_scope.mcc
string
|
Merchant Category Code (MCC). Identifies the type of goods or services provided by the merchant. Allowable Values: 1–4 chars |
merchant_scope.mcc_group
string
|
Token identifying a group of MCCs. Allowable Values: 1–36 chars |
merchant_scope.merchant_group_token
string
|
Unique identifier of a merchant group. Allowable Values: 1–36 chars |
merchant_scope.mid
string
|
Merchant identifier (MID). Identifies a specific merchant. Allowable Values: 1–36 chars |
name
string
|
Name of the authorization control. Allowable Values: 255 char max |
start_time
datetime
|
Date and time when the exception goes into effect, in UTC. This field is returned if it exists in the resource. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
token
string
|
Unique identifier of the authorization control. This field is returned if it exists in the resource. Allowable Values: 1–36 chars |
Create a merchant identifier (MID) exemption
Copy section link
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
Copy section link
| Fields | Description |
|---|---|
association
object
|
Defines the group of users to which the authorization control applies.
This object is required if the 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:
|
association.card_product_token
string
|
Unique identifier of a card product. Specify a card product token in the Pass either Allowable Values: 1–36 chars |
association.user_token
string
|
Unique identifier of a user. Specify a user token in the Pass either Allowable Values: 1–36 chars |
end_time
datetime
|
Date and time when the exception ends, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
merchant_group_token
string
|
Unique identifier of the merchant group to be exempted.
This field is required if there is no entry in the For information about merchant groups, see Merchant Groups. Allowable Values: 1–36 chars |
mid
string
|
Merchant to be exempted.
This field is required if there is no entry in the Allowable Values: 1–36 chars |
name
string
|
Name of the merchant identifier authorization control exemption. Allowable Values: 255 char max |
start_time
datetime
|
Date and time when the exception starts, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
token
string
|
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 |
Response body
Copy section link
| Fields | Description |
|---|---|
active
boolean
|
Indicates whether the merchant identifier authorization control exception is active. This field is returned if it exists in the resource. Allowable Values:
|
association
object
|
Defines the group of users to which the authorization control applies. Allowable Values:
|
association.card_product_token
string
|
Unique identifier of a card product. Allowable Values: 1–36 chars |
association.user_token
string
|
Unique identifier of a user. Allowable Values: 1–36 chars |
created
datetime
|
Date and time when the resource was created, in UTC. This field is returned if it exists in the resource. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
end_time
datetime
|
Date and time when the exception ends, in UTC. This field is returned if it exists in the resource. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
last_updated
datetime
|
Date and time when the resource was last updated, in UTC. This field is returned if it exists in the resource. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
merchant_group_token
string
|
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
|
Merchant to be exempted. This field is returned if it exists in the resource. Allowable Values: 1–36 chars |
name
string
|
Name of the merchant identifier authorization control exemption. Allowable Values: 255 char max |
start_time
datetime
|
Date and time when the exception starts, in UTC. This field is returned if it exists in the resource. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
token
string
|
Unique identifier of the merchant identifier authorization control exemption. This field is always returned. Allowable Values: Existing merchant identifier authorization control exemption token |
List merchant identifier (MID) exemptions
Copy section link
Action: GET
Endpoint: /authcontrols/exemptmids
Retrieve a list of all merchant (MID) exemptions.
URL query parameters
Copy section link
| Fields | Description |
|---|---|
card_product
string
|
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 |
user
string
|
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 |
count
integer
|
The number of resources to retrieve. Allowable Values: 1-10 Default value: |
start_index
integer
|
The sort order index of the first resource in the returned array. Allowable Values: Any integer Default value: |
fields
string
|
Comma-delimited list of fields to return ( Allowable Values: Comma-delimited list of fields, or blank |
sort_by
string
|
Field on which to sort.
Use any field in the resource model, or one of the system fields Allowable Values:
Default value: |
Response body
Copy section link
| Fields | Description |
|---|---|
count
integer
|
Number of resources retrieved. This field is returned if there are resources in your returned array. Allowable Values: 1-10 |
data
array of objects
|
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
|
Indicates whether the merchant identifier authorization control exception is active. This field is returned if it exists in the resource. Allowable Values:
|
data[].association
object
|
Defines the group of users to which the authorization control applies. Allowable Values:
|
data[].association.card_product_token
string
|
Unique identifier of a card product. Allowable Values: 1–36 chars |
data[].association.user_token
string
|
Unique identifier of a user. Allowable Values: 1–36 chars |
data[].created
datetime
|
Date and time when the resource was created, in UTC. This field is returned if it exists in the resource. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
data[].end_time
datetime
|
Date and time when the exception ends, in UTC. This field is returned if it exists in the resource. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
data[].last_updated
datetime
|
Date and time when the resource was last updated, in UTC. This field is returned if it exists in the resource. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
data[].merchant_group_token
string
|
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
|
Merchant to be exempted. This field is returned if it exists in the resource. Allowable Values: 1–36 chars |
data[].name
string
|
Name of the merchant identifier authorization control exemption. Allowable Values: 255 char max |
data[].start_time
datetime
|
Date and time when the exception starts, in UTC. This field is returned if it exists in the resource. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
data[].token
string
|
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
|
Sort order index of the last resource in the returned array. Allowable Values: Any integer |
is_more
boolean
|
A value of This field is returned if there are resources in your returned array. Allowable Values:
|
start_index
integer
|
Sort order index of the first resource in the returned array. Allowable Values: Any integer |
Retrieve a merchant identifier (MID) exemption
Copy section link
Action: GET
Endpoint: /authcontrols/exemptmids/{token}
Retrieve a merchant (MID) exemption.
URL path parameters
Copy section link
| Fields | Description |
|---|---|
token
string
|
Unique identifier of the authorization control resource. Allowable Values: Existing authorization control resource token |
Response body
Copy section link
| Fields | Description |
|---|---|
active
boolean
|
Indicates whether the merchant identifier authorization control exception is active. This field is returned if it exists in the resource. Allowable Values:
|
association
object
|
Defines the group of users to which the authorization control applies. Allowable Values:
|
association.card_product_token
string
|
Unique identifier of a card product. Allowable Values: 1–36 chars |
association.user_token
string
|
Unique identifier of a user. Allowable Values: 1–36 chars |
created
datetime
|
Date and time when the resource was created, in UTC. This field is returned if it exists in the resource. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
end_time
datetime
|
Date and time when the exception ends, in UTC. This field is returned if it exists in the resource. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
last_updated
datetime
|
Date and time when the resource was last updated, in UTC. This field is returned if it exists in the resource. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
merchant_group_token
string
|
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
|
Merchant to be exempted. This field is returned if it exists in the resource. Allowable Values: 1–36 chars |
name
string
|
Name of the merchant identifier authorization control exemption. Allowable Values: 255 char max |
start_time
datetime
|
Date and time when the exception starts, in UTC. This field is returned if it exists in the resource. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
token
string
|
Unique identifier of the merchant identifier authorization control exemption. This field is always returned. Allowable Values: Existing merchant identifier authorization control exemption token |
Update a merchant identifier (MID) exemption
Copy section link
Action: PUT
Endpoint: /authcontrols/exemptmids/{token}
Update a merchant identifier exemption.
URL path parameters
Copy section link
| Fields | Description |
|---|---|
token
string
|
Unique identifier of the authorization control resource. Allowable Values: Existing authorization control resource token |
Request body
Copy section link
| Fields | Description |
|---|---|
active
boolean
|
Indicates whether the merchant identifier authorization control exception is active. Allowable Values:
Default value: |