Create authorization control

Action: POST
Endpoint: /authcontrols

To create an authorization control, send a POST request to the /authcontrols endpoint and include the control's details in JSON format in the body of the request.

Authorization controls work in conjunction with the default authorization setting to control transaction access by a specified group of users to a specified group of vendors. Marqeta sets the authorization default on your behalf to either "globally allow" or "globally deny" transactions. If the default is "globally allow", then an authorization control acts as a blacklist that denies transactions with the specified vendors. If the default is "globally deny", then the control acts as a whitelist that allows transactions with the specified vendors.

Use the association object to define the group of users affected by the authorization control. This object contains two fields; populate one, and only one. Populate the user_token field to apply the control to a single user. Populate the card_product_token field to apply the control to all users associated with the card product (this association is indirect by way of the card product's associated cards).

Use the merchant_scope object to define the group of vendors to which access is controlled. This object contains three fields; populate no more than one. You can specify a MID, MCC, or MCC group. If you specify none of these, the authorization control applies to all vendors.

Note: If you apply multiple authorization controls to the same user, then the merchant_scope objects from each of the controls essentially combine. In other words, the number of vendors in the blacklist increases (if the program default is "globally allow"), or the number of vendors in the whitelist increases (if the program default is "globally deny").

Body field details

Name Type Required? Description Allowable Values
token string No The 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.
36 char max
name string Yes The name of the authorization control. 255 char max
active boolean No Indicates whether the authorization control is active. true | false

Default: true
start_time string No The date and time the exception goes into effect. yyyy-MM-ddThh:mm:ssZ
end_time string No The date and time the exception ends. yyyy-MM-ddThh:mm:ssZ
merchant_scope object No Defines the group of vendors to which the authorization control applies.

Populate no more than one field. If no fields are populated, the control applies to all vendors.
association object Yes Defines the group of users to which the authorization control applies.

You must populate one, and only one, field.

The merchant_scope object

Name Type Required? Description Allowable Values
mid string No MID (Merchant ID). The unique identification number of a vendor.

Enter a value to control access to a particular vendor.
36 char max
mcc string No A single MCC (Merchant Category Code). Identifies the type of goods or services provided by the vendor.

Enter a value to control access to a particular type of product or service.
4 char max
mcc_group string No Token indentifying a group of MCCs.

Enter a value to control access to a group of product or service types.
Existing MCC group token.

Issue a GET to /mccgroups to retrieve MCC group tokens.

The association object

Name Type Required? Description Allowable Values
card_product_token

OR

user_token
string Yes Token identifying either a card product or user.

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. 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.
Existing card product or user token.

Issue a GET to /cardproducts to retrieve card product tokens or to /users to retrieve user tokens.

Sample request body

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

Sample response body

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


Retrieve authorization control

Action: GET
Endpoint: /authcontrols/{token}

To retrieve a specific authorization control, issue a GET to the /authcontrols/{token} endpoint. Include the token path parameter to indicate the control to return.

URL path parameters

Name Type Required? Description Allowable Values
token string Yes Identifies the authorization control to return. Existing authorization control token.

Issue a GET to /authcontrols to retrieve authorization control tokens.

Sample response body

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


Update authorization control

Action: PUT
Endpoint: /authcontrols/{token}

To update an authorization control, send a PUT request to the /authcontrols/{token} endpoint. Include the token path parameter to indicate the control to update, and include the modified or additional authorization control details in JSON format in the body of the request. Only values of parameters in the request are modified; all others are left unchanged. You must include the association object in your request even if you don't intend to update its values.

Authorization controls work in conjunction with the default authorization setting to control transaction access by a specified group of users to a specified group of vendors. Marqeta sets the authorization default on your behalf to either "globally allow" or "globally deny" transactions. If the default is "globally allow", then an authorization control acts as a blacklist that denies transactions with the specified vendors. If the default is "globally deny", then the control acts as a whitelist that allows transactions with the specified vendors.

Use the association object to define the group of users affected by the authorization control. This object contains two fields; populate one and only one. Populate the user_token field to apply the control to a single user. Populate the card_product_token field to apply the control to all users associated with the card product (this association is indirect by way of the card product's associated cards).

Use the merchant_scope object to define the group of vendors to which access is controlled. This object contains three fields; populate no more than one. You can specify a MID, MCC, or MCC group. If you specify none of these, the authorization control applies to all vendors.

Note: If you apply multiple authorization controls to the same user, then the merchant_scope objects from each of the controls essentially combine. In other words, the number of vendors in the blacklist increases (if the program default is "globally allow"), or the number of vendors in the whitelist increases (if the program default is "globally deny").

URL path parameters

Name Type Required? Description Allowable Values
token string Yes Identifies the authorization control to update. Existing authorization control token.

Issue a GET to /authcontrols to retrieve authorization control tokens.

Body field details

Name Type Required? Description Allowable Values
name string Yes The name of the authorization control. 255 char max
active boolean No Indicates whether the authorization control is active. true | false

Default: true
start_time string No The date and time the exception goes into effect. yyyy-MM-ddThh:mm:ssZ
end_time string No The date and time the exception ends. yyyy-MM-ddThh:mm:ssZ
merchant_scope object No Defines the group of vendors to which the exception applies.

Specify only one value. If no values are specified, the exception applies to all vendors.
association object Yes Defines the group of users to which the authorization control applies.

You must populate one, and only one, field.

Note: You must include this object in your request even if you don't intend to update its values.

The merchant_scope object

Name Type Required? Description Allowable Values
mid string No MID (Merchant ID). The unique identification number of a vendor.

Enter a value to control access to a particular vendor.
36 char max
mcc string No A single MCC (Merchant Category Code). Identifies the type of goods or services provided by the vendor.

Enter a value to control access to a particular type of product or service.
4 char max
mcc_group string No Token indentifying a group of MCCs.

Enter a value to control access to a group of product or service types.
Existing MCC group token.

Issue a GET to /mccgroups to retreive MCC group tokens.

The association object

Name Type Required? Description Allowable Values
card_product_token

OR

user_token
string Yes Token identifying either a card product or user.

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. 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.
Existing card product or user token.

Issue a GET to /cardproducts to retrieve card product tokens or to /users to retrieve user tokens.

Sample request body

{
"merchant_scope": {
"mcc": "5111"
}
}

Sample response body

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


List authorization controls

Action: GET
Endpoint: /authcontrols

To list all authorization controls for a specific user or cardproduct, send a GET request to the /authcontrols endpoint. Include either a user or a card_product query parameter to indicate the user or cardproduct whose associated authorization controls you want to retrieve (do not include both).

To list all authorization controls for a program, send a GET request to the /authcontrols endpoint without a user or card_product query parameter.

This endpoint supports field filtering and pagination.

Query parameters

Name Type Required? Description Allowable Values
user string No The token identifying 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.
Existing user token or the string "null".

Issue a GET to /users to retrieve existing tokens.
card_product string No The token identifying 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.
Existing card product token or the string "null".

Issue a GET to /cardproducts to retrieve existing tokens.

Sample response body

{
"count": 1,
"start_index": 0,
"end_index": 0,
"is_more": false,
"data": [
{
"token": "my_authcontrol",
"name": "My Auth Control",
"active": true,
"association": {
"user_token": "bigbird_token"
},
"merchant_scope": {
"mcc": "5111"
}
}
]
}


Create velocity control

Action: POST
Endpoint: /velocitycontrols

To create a velocity control, send a POST request to the /velocitycontrols endpoint and include the velocity control details in JSON format in the body of the request.

Use the association object to define the group of users affected by the velocity control. This object contains two fields; populate one and only one. Populate the user_token field to apply the control to a single user. Populate the card_product_token field to apply the control to all users associated with the card product (this association is indirect by way of the card product's associated cards).

Use the merchant_scope object to define the group of vendors at which spending is controlled. This object contains three fields; populate no more than one. You can specify a MID, MCC, or MCC group. If you specify none of these, the velocity control applies to all vendors.

Note: If you apply multiple velocity controls to a user, then the user is constrained by each and all of the controls and cannot exceed any of the defined spending limits.

Body field details

Name Type Required? Description Allowable Values
token string No The unique identifier of the velocity 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.
36 char max
name string No The name of the velocity control. 255 char max
amount_limit decimal Yes The maximum monetary sum that can be cleared within the time period defined by the velocity_window field. 0.00
usage_limit decimal Yes Maximum number of times a card can be used within the time period defined by the velocity_window field. 0-100
velocity_window string Yes Defines the time period to which the amount_limit and usage_limit fields apply:

DAY – one day; days begin at 00:00:00.
WEEK – one week; weeks begin Mondays at 00:00:00.
MONTH – one month; months begin on 1st of month at 00:00:00.
LIFETIME – forever; time period never expires.

Notes:

If set to DAY, WEEK, or MONTH, the velocity control takes effect retroactively from the beginning of the specified period. The amount and usage data already collected within the first period is counted toward the limits.

Editing any of the following fields on a velocity control resets its usage and amount count to 0:

merchant_scope.mcc
merchant_scope.mid
merchant_scope.mcc_group
association.user_token
association.card_product_token
velocity_window
DAY | WEEK | MONTH | LIFETIME
currency_code string Yes The currency code. The 3-character ISO 4217 currency code.

"USD" currently supported.
active boolean No Indicates whether the velocity control is active. true | false

Default: true
approvals_only boolean No If set to true, only approved transactions are subject to control. true | false

Default: true
include_withdrawals boolean No If set to true, ATM withdrawals are subject to control. true | false

Default: true
include_transfers boolean No If set to true, transfers are subject to control. true | false

Default: true
include_purchases boolean No If set to true, purchases are subject to control. true | false

Default: true
merchant_scope object No Defines the group of vendors to which the velocity control applies.

Populate no more than one field. If no fields are populated, the velocity control applies to all vendors.
association object Yes Defines the group of users to which the velocity control applies.

You must populate one, and only one, field.

The merchant_scope object

Name Type Required? Description Allowable Values
mid string No MID (Merchant ID). The unique identification number of a vendor.

Enter a value to control spending with a particular vendor.
36 char max
mcc string No A single MCC (Merchant Category Code). Identifies the type of goods or services provided by the vendor.

Enter a value to control spending on a particular type of product or service.
4 char max
mcc_group string No Token indentifying a group of MCCs.

Enter a value to control spending on a group of product or service types.
Existing MCC group token.

Issue a GET to /mccgroups to retrieve MCC group tokens.

The association object

Name Type Required? Description Allowable Values
card_product_token

OR

user_token
string Yes Token identifying either a card product or user.

Specify a card product token in the card_product_token field to apply the velocity control to all users holding active cards associated with the card product. Specify a user token in the user_token field to apply the velocity control to a single user.

Pass either card_product_token or user_token, not both.
Existing card product or user token.

Issue a GET to /cardproducts to retrieve card product tokens or to /users to retrieve user tokens.

Sample request body

{
"usage_limit": 10,
"amount_limit": 500,
"velocity_window": "DAY",
"association": {
"user_token": "my_user_04"
},
"currency_code": "USD",
"token": "my_velocitycontrol_01"
}

Sample response body

{
"token": "my_velocitycontrol_01",
"association": {
"user_token": "my_user_04"
},
"merchant_scope": {},
"usage_limit": 10,
"approvals_only": true,
"include_purchases": true,
"include_withdrawals": true,
"include_transfers": true,
"currency_code": "USD",
"amount_limit": 500,
"velocity_window": "DAY",
"active": true
}


Retrieve velocity control

Action: GET
Endpoint: /velocitycontrols/{token}

To return a specific velocity control, send a GET request to the /velocitycontrols/{token} endpoint. Include the token path parameter to specify the velocity control to retrieve.

URL path parameters

Name Type Required? Description Allowable Values
token string Yes Identifies the velocity control to retrieve. Existing velocity control token.

Issue a GET to /velocitycontrols to retrieve velocity controls tokens.

Sample response body

{
"token": "my_velocitycontrol_01",
"association": {
"user_token": "my_user_04"
},
"merchant_scope": {},
"usage_limit": 10,
"approvals_only": true,
"include_purchases": true,
"include_withdrawals": true,
"include_transfers": true,
"currency_code": "USD",
"amount_limit": 500,
"velocity_window": "DAY",
"active": true
}


Update velocity control

Action: PUT
Endpoint: /velocitycontrols/{token}

To update a velocity control, issue a PUT request to /velocitycontrols/{token}. Include the token path parameter to indicate the control to update, and include the modified or additional velocity control details in JSON format in the body of the request. Only values of parameters in the request are modified; all others are left unchanged. You must include the association object in your request even if you don't intend to update its values.

Use the association object to define the group of users affected by the velocity control. This object contains two fields; populate no more than one. Populate the user_token field to apply the control to a single user. Populate the card_product_token field to apply the control to all users associated with the card product (this association is indirect by way of the card product's associated cards).

Use the merchant_scope object to define the group of vendors to which spending is controlled. This object contains three fields; populate no more than one. You can specify a MID, MCC, or MCC group. If you specify none of these, the velocity control applies to all vendors.

Note: If you apply multiple velocity controls to a user, then the user is constrained by each and all of the controls and cannot exceed any of the defined spending limits.

URL path parameters

Name Type Required? Description Allowable Values
token string Yes Identifies the velocity control to update. Existing velocity control token.

Issue a GET to /velocitycontrol to retrieve velocity control tokens.

Body field details

Name Type Required? Description Allowable Values
name string No The name of the velocity control. 255 char max
amount_limit decimal Yes The maximum monetary sum that can be cleared within the time period defined by the velocity_window field. 0.00
usage_limit decimal Yes Maximum number of times a card can be used within the time period defined by the velocity_window field. 0-100
velocity_window string Yes Defines the time period to which the amount_limit and usage_limit fields apply:

DAY – one day; days begin at 00:00:00.
WEEK – one week; weeks begin Mondays at 00:00:00.
MONTH – one month; months begin on 1st of month at 00:00:00.
LIFETIME – forever; time period never expires.

Notes:

If set to DAY, WEEK, or MONTH, the velocity control takes effect retroactively from the beginning of the specified period. The amount and usage data already collected within the first period is counted toward the limits.

Editing any of the following fields on a velocity control resets its usage and amount count to 0:

merchant_scope.mcc
merchant_scope.mid
merchant_scope.mcc_group
association.user_token
association.card_product_token
velocity_window
DAY | WEEK | MONTH | LIFETIME
currency_code string Yes The currency code. The 3-character ISO 4217 currency code.

"USD" currently supported.
active boolean No Indicates whether the velocity control is active. true | false

Default: true
approvals_only boolean No If set to true, only approved transactions are subject to control. true | false

Default: true
include_withdrawals boolean No If set to true, ATM withdrawals are subject to control. true | false

Default: true
include_transfers boolean No If set to true, transfers are subject to control. true | false

Default: true
include_purchases boolean No If set to true, purchases are subject to control. true | false

Default: true
merchant_scope object No Defines the group of vendors to which the velocity control applies.

Populate only one field. If no fields are populated, the velocity control applies to all vendors.
association object No Defines the group of users to which the velocity control applies.

You must populate one, and only one, field.

Note: You must include this object in your request even if you don't intend to update its values.

The merchant_scope object

Name Type Required? Description Allowable Values
mid string No MID (Merchant ID). The unique identification number of a vendor.

Enter a value to control spending with a particular vendor.
36 char max
mcc string No A single MCC (Merchant Category Code). Identifies the type of goods or services provided by the vendor.

Enter a value to control spending on a particular type of product or service.
4 char max
mcc_group string No Token indentifying a group of MCCs.

Enter a value to control spending on a group of product or service types.
Existing MCC group token.

Issue a GET to /mccgroups to retrieve MCC group tokens.

The association object

Name Type Required? Description Allowable Values
card_product_token

OR

user_token
string Yes Token identifying either a card product or user.

Specify a card product token in the card_product_token field to apply the velocity control to all users holding active cards associated with the card product. Specify a user token in the user_token field to apply the velocity control to a single user.

Pass either card_product_token or user_token, not both.
Existing card product or user token.

Issue a GET to /cardproducts to retrieve card product tokens or to /users to retrieve user tokens.

Sample request body

{
"usage_limit": 20,
"amount_limit": 1000
}

Sample response body

{
"token": "my_velocitycontrol_01",
"association": {
"user_token": "my_user_04"
},
"merchant_scope": {},
"usage_limit": 20,
"approvals_only": true,
"include_purchases": true,
"include_withdrawals": true,
"include_transfers": true,
"currency_code": "USD",
"amount_limit": 1000,
"velocity_window": "DAY",
"active": true
}


List velocity controls

Action: GET
Endpoint: /velocitycontrols

To list all velocity controls for a specific user or cardproduct, send a GET request to the /velocitycontrols endpoint. Include either a user or a card_product query parameter to indicate the user or cardproduct whose associated velocity controls you want to retrieve (do not include both).

To list all velocity controls for a program, send a GET request to the /velocitycontrols endpoint without a user or card_product query parameter.

This endpoint supports field filtering and pagination.

Query parameters

Name Type Required? Description Allowable Values
user string No The token identifying the user whose velocity controls you want to retrieve.

Enter the string "null" to list velocity controls that are not associated with a user.
Existing user token.

Issue a GET to /users to retrieve user tokens.
card_product string No The token identifying the card product whose velocity controls you want to retrieve.

Enter the string "null" to list velocity controls that are not associated with a card product.
Existing card product token.

Issue a GET to /cardproducts to retrieve card product tokens.

Sample response body

{
"count": 1,
"start_index": 0,
"end_index": 0,
"is_more": false,
"data": [
{
"token": "my_velocitycontrol_01",
"association": {
"user_token": "my_user_04"
},
"merchant_scope": {},
"usage_limit": 10,
"approvals_only": true,
"include_purchases": true,
"include_withdrawals": true,
"include_transfers": true,
"currency_code": "USD",
"amount_limit": 500,
"velocity_window": "DAY",
"active": true
}
]
}


Retrieve user velocity-control balance

Action: GET
Endpoint: /velocitycontrols/user/{user_token}/available

To return the available balance of a user's velocity control, send a GET request to the /velocitycontrols/user/{user_token}/available endpoint. Include the user_token path parameter to identify the user whose balances you want to retrieve.

The available balance of a velocity control is what is left of a user's spend limits in the current time window (which is defined by the control's velocity_window field). Depending on the control, the balance can include an available monetary amount, the number of transactions remaining, and the number of days remaining in the time window.

This endpoint supports field filtering and pagination.

URL path parameters

Name Type Required? Description Allowable Values
user_token string Yes Identifies the user whose velocity control balance you want to retrieve. Existing user token.

Issue a GET to /users to retrieve user tokens.

Sample response body

{
"count": 1,
"start_index": 0,
"end_index": 0,
"is_more": false,
"data": [
{
"token": "my_velocitycontrol_01",
"association": {
"user_token": "my_user_04"
},
"merchant_scope": {},
"usage_limit": 20,
"approvals_only": true,
"include_purchases": true,
"include_withdrawals": true,
"include_transfers": true,
"currency_code": "USD",
"amount_limit": 1000,
"velocity_window": "DAY",
"active": true,
"available": {
"uses": 20,
"amount": 1000,
"days_remaining": 1
}
}
]
}