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 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). Or, leave both fields blank to apply the control to all users in the program.

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.

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 No Defines the group of users to which the authorization control applies.

Populate no more than one field. If no fields are populated, the control applies to all users in the program.

merchant_scope

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.

association

Name Type Required? Description Allowable Values
card_product_token string No Token identifying a card product.

Enter a value to apply the authorization control to all users holding active cards associated with the card product.
Existing cardproduct token.

Issue a GET to /cardproducts to retrieve card product tokens.
user_token string No Token identifying a user.

Enter a value to apply the authorization control to a single user.
Existing user token.

Issue a GET 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.

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 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). Or, leave both fields blank to apply the control to all users in the program.

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.

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 No Defines the hierarchical level at which the authorization control is created: either user-level or card product-level, specified by way of a user token or card product token.

Specify only one value. If no values are specified, the authorization control is associated with the program.

merchant_scope

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.

association

Name Type Required? Description Allowable Values
card_product_token string No Token identifying a card product.

Enter a value to apply the authorization control to all users holding active cards associated with the card product.
Existing cardproduct token.

Issue a GET to /cardproducts to retreive card product tokens.
user_token string No Token identifying a user.

Enter a value to apply the authorization control to a single user.
Existing user token.

Issue a GET to /users to retreive 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 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). Or, leave both fields blank to apply the control to all users in the program.

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 that the usage_limit and amount_limit fields have meaning only in relation to the number_of_days field. The number_of_days field defines the size of a rolling summation window, within which the amount and usage limits apply.

If you want to place a simple maximum on the transaction amount per authorization (and with unlimited frequency of transactions), you can do so by setting usage_limit=0 and number_of_days=0 and then setting amount_limit to your desired maximum transaction amount.

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 defined number_of_days.

For example, if amount_limit is set to $20 and number_of_days is set to 2, then you may spend a sum of $20 over any 2 consecutive days. For example, if you spent $15 yesterday and $5 today, then you could spend no more today and up to $15 tomorrow.

Note: If usage_limit=0 and number_of_days=0 then amount_limit specifies the maximum transaction amount per authorization (in this case, the frequency of transactions is unlimited).
0.00
number_of_days decimal Yes Specifies the number of consecutive days to which a usage_limit and amount_limit applies.

This value defines a moving timeframe. For example, if you set it to 2 days, the current timeframe would include today plus yesterday. Note that 1 day is defined as midnight to midnight.
0-100

0 is a special value used for setting up a simple maximum transaction amount.
usage_limit decimal Yes Maximum number of times a card can be used within a given timeframe (defined by number_of_days).

For example, if number_of_days is set to 2 and usage_limit is set to 3, then the card can be used no more than 3 times within any 2 consecutive days.
0-100

0 is a special value used for setting up a simple maximum transaction amount.
currency code string Yes The currency code. 3 digit ISO code.

840 is 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 No Defines the group of users to which the velocity control applies.

Populate no more than one field. If no fields are populated, the control applies to all users in the program.

merchant_scope

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.

association

Name Type Required? Description Allowable Values
card_product_token string No Token identifying a card product.

Enter a value to apply the velocity control to all users holding active cards associated with the card product.
Existing cardproduct token.

Issue a GET to /cardproducts to retrieve card product tokens.
user_token string No Token identifying a user.

Enter a value to apply the velocity control to a single user.
Existing user token.

Issue a GET to /users to retrieve user tokens.

Sample Request Body

{
"usage_limit": 15,
"amount_limit": 500,
"number_of_days": 3,
"association": {
"user_token": "bigbird_token"
},
"currency_code": "840",
"token": "my_velocitycontrol"
}

Sample Response Body

{
"token": "my_velocitycontrol",
"active": true,
"association": {
"user_token": "bigbird_token"
},
"merchant_scope": {},
"usage_limit": 15,
"approvals_only": true,
"include_purchases": true,
"include_withdrawals": true,
"include_transfers": true,
"currency_code": "840",
"amount_limit": 500,
"number_of_days": 3
}


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",
"active": true,
"association": {
"user_token": "bigbird_token"
},
"merchant_scope": {},
"usage_limit": 15,
"approvals_only": true,
"include_purchases": true,
"include_withdrawals": true,
"include_transfers": true,
"currency_code": "840",
"amount_limit": 500,
"number_of_days": 3
}


Update Velocity Control

Action: PUT
Endpoint: /velocitycontrols/{token}

To update a velocity control, issue a PUT request to /velocitycontrols/{token} and include the token path parameter to specify the velocity control to update.

Include the velocity control details to update in JSON format in the body of the request. Only values of parameters in the request are modified; all others are left unchanged.

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). Or, leave both fields blank to apply the control to all users in the program.

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 that the usage_limit and amount_limit values have meaning only in relation to the value of number_of_days. The number_of_days value defines the size of a rolling summation window, within which the amount and usage limits apply.

If you want to place a simple maximum on the transaction amount per authorization (and with unlimited frequency of transactions), you can do so by setting usage_limit=0 and number_of_days=0 and then setting amount_limit to your desired maximum transaction amount.

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 defined number_of_days.

For example, if amount_limit is set to $20 and number_of_days is set to 2, then you may spend a sum of $20 over any 2 consecutive days. For example, if you spent $15 yesterday and $5 today, then you could spend no more today and up to $15 tomorrow.

Note: If usage_limit=0 and number_of_days=0 then amount_limit specifies the maximum transaction amount per authorization (in this case, the frequency of transactions is unlimited).
0.00
number_of_days decimal Yes Specifies the number of consecutive days to which a usage_limit and amount_limit applies.

This value defines a moving timeframe. For example, if you set it to 2 days, the current timeframe would include today plus yesterday. Note that 1 day is defined as midnight to midnight.
0-100

0 is a special value used for setting up a simple maximum transaction amount.
usage_limit decimal Yes Maximum number of times a card may be used within a given timeframe (defined by number_of_days).

For example, if number_of_days is set to 2 and usage_limit is set to 3, then the card can be used no more than 3 times within any 2 consecutive days.
0-100

0 is a special value used for setting up a simple maximum transaction amount.
currency code string Yes The currency code. 3 digit ISO code.

840 is 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 hierarchical level at which the velocity control is created: either user-level or card product-level, specified by way of a user_token or card_product_token.

Populate only one field. If no fields are populated, the velocity control is associated with the program.

merchant_scope

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.

association

Name Type Required? Description Allowable Values
card_product_token string No Token identifying a card product.

Enter a value to apply the velocity control to all users holding active cards associated with the card product.
Existing cardproduct token.

Issue a GET to /cardproducts to retrieve card product tokens.
user_token string No Token identifying a user.

Enter a value to apply the velocity control to a single user.
Existing user token.

Issue a GET to /users to retrieve user tokens.

Sample Request Body

{
"name": "My Velocity Control",
"merchant_scope": {
"mid": "98765"
}
}

Sample Response Body

{
"token": "my_velocitycontrol",
"name": "My Velocity Control",
"active": true,
"association": {
"user_token": "bigbird_token"
},
"merchant_scope": {
"mid": "98765"
},
"usage_limit": 15,
"approvals_only": true,
"include_purchases": true,
"include_withdrawals": true,
"include_transfers": true,
"currency_code": "840",
"amount_limit": 500,
"number_of_days": 3
}


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",
"name": "My Velocity Control",
"active": true,
"association": {
"user_token": "bigbird_token"
},
"merchant_scope": {
"mid": "98765"
},
"usage_limit": 15,
"approvals_only": true,
"include_purchases": true,
"include_withdrawals": true,
"include_transfers": true,
"currency_code": "840",
"amount_limit": 500,
"number_of_days": 3
}
]
}


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 for a specific velocity control. Depending on the control, the balance can include an available monetary amount, the number of transactions remaining, and the number of days remaining to use the card.

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": 5,
"start_index": 0,
"end_index": 4,
"is_more": true,
"data": [
{
"token": "d4a41e97-d4ad-481d-aa4c-f302814c22c2",
"name": "One usage per day",
"active": true,
"available": {
"uses": 1,
"amount": 100
},
"association": {
"card_product_token": "42586b00-f7ae-4e2a-829f-85fce68a1158"
},
"merchant_scope": {
"mcc_group": "Education"
},
"usage_limit": 1,
"approvals_only": true,
"include_purchases": true,
"include_withdrawals": true,
"include_transfers": true,
"currency_code": "840",
"amount_limit": 100,
"number_of_days": 1
},
{
"token": "48e7239f-484e-4ca7-bfbf-28ec071fb473",
"name": "Three dollars per day",
"active": true,
"available": {
"uses": 10,
"amount": 3
},
"association": {
"card_product_token": "3c0d9452-2cd9-4d2f-85ea-b1b5ef5e7573"
},
"merchant_scope": {
"mcc": "4112"
},
"usage_limit": 10,
"approvals_only": true,
"include_purchases": true,
"include_withdrawals": true,
"include_transfers": true,
"currency_code": "840",
"amount_limit": 3,
"number_of_days": 1
}
...
]
}