> ## Documentation Index
> Fetch the complete documentation index at: https://docs.treasuryprime.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Overview
Card Controls objects are used to configure the restrictions and capabilities of associated [Card](/reference/card) and [Card Product](/reference/card-product) objects.
Card Controls may be configured to restrict the use of a debit card to a particular category of vendor, or to limit the amount of money spent or withdrawn in a particular time period.
## The Card Controls Object
| Parameter | Type | Description |
| --------- | --------------- | ----------------------------------------------------- |
| name | string | Name for the card controls. |
| controls | array\[objects] | An array of control configurations, as outlined below |
## Card Control Configuration Types
All card controls configuration objects must have these attributes:
| Parameter | Type | Description |
| --------- | ------ | --------------------------------------------------------------- |
| type | string | The type of control configuration, e.g. `merchant_restriction`. |
| version | number | A version number. |
### Merchant Restriction
`merchant_restriction` configurations allow you to `allow` or `disallow` the use of a [Card](/reference/card) or [Card Product](/reference/card-product) at specific categories of merchants.
When a merchant restriction is created to `allow` certain merchant category codes (MCCs) or merchant IDs (MIDs), only transaction at vendors listed with those MCCs or MIDs in the card network will be approved. All other transactions will be declined. The call must have an array of MCCs or MIDs passed, or a combination of the two.
| Parameter | Type | Required? | Description |
| ----------- | -------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| type | string | Required | Name of this card controls object. |
| version | number | Required | Version of configuration (currently: 2) |
| restriction | string | Required | Either `allow` or `disallow`, for allowing or disallowing the list of mccs |
| mccs | array\[string] | | An array of four digit numeric strings, representing the merchant categories to allow or disallow. Required if `mids` are not passed. |
| mids | array\[string] | | An array of alphanumeric strings, representing the merchant id to allow or disallow. Required if `mccs` are not passed. |
### Spend Velocity Restriction
`spend_limit` configurations allow you to configure a maximum spending amount within a timeframe (e.g. no more than \$1000 in authorized transactions within 24 hours).
| Parameter | Type | Required? | Description |
| -------------- | ------ | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| type | string | Required | Name of this card controls object. |
| version | number | Required | Version of configuration (currently: 1). |
| amount | string | Required | Total amount of authorizated transactions to allow within the window. |
| interval | string | Required | Type of interval for calculating total amount of transactions. One of: `rolling`, `daily`, or `monthly`. |
| window | number | | Number of hours for calculating rolling window. Required if `interval` is `rolling`. |
| timezone | string | | Timezone for when `rollover_time` should reset. Acceptable values are tz database timezones and can be found [here](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). Commonly one of `America/Los_Angeles`, `America/Chicago`, `America/New_York`, and `UTC`. Required if `interval` is `daily` or `monthly`. |
| rollover\_time | string | | Timestamp of when `daily` or `monthly` limits reset. Timestamp is in military time and only accepts hours and minutes such as `18:30`. Required if `interval` is `daily` or `monthly`. |
### Withdrawal Velocity Restriction
`withdrawal_limit` configurations allow you to configure a maximum amount of ATM withdrawals within a timeframe (e.g. not more than \$400 in ATM transactions within 24 hours).
| Parameter | Type | Required? | Description |
| -------------- | ------ | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| type | string | Required | Name of this card controls object. |
| version | number | Required | Version of configuration (currently: 1). |
| amount | string | Required | Total amount of ATM transactions to allow within the window. |
| interval | string | Required | Type of interval for calculating total amount of transactions. One of: `rolling`, `daily`, or `monthly`. |
| window | number | | Number of hours for calculating rolling window. Required if `interval` is `rolling`. |
| timezone | string | | Timezone for when `rollover_time` should reset. Acceptable values are tz database timezones and can be found [here](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). Commonly one of `America/Los_Angeles`, `America/Chicago`, `America/New_York`, and `UTC`. Required if `interval` is `daily` or `monthly`. |
| rollover\_time | string | | Timestamp of when `daily` or `monthly` limits reset. Timestamp is in military time and only accepts hours and minutes such as `18:30`. Required if `interval` is `daily` or `monthly`. |
## Adding Card Controls to a Card or Card Product
The `create` and `update` endpoints for [Card](/reference/card) and [Card Product](/reference/card-product) objects accept a `card_controls` attribute and will associate them with the resource being created or updated.
### Adding Merchant Restriction Card Control to a Card
The following example is a call that can be made to add a merchant restriction that will disallow `mccs` and `mids` on a specific card.
##### Example Request
```bash bash theme={null}
$ curl -u $API_KEY_ID:$API_SECRET_KEY https://api.treasuryprime.com/card/card_zuhqnmz7e085 \
-X PATCH \
-H 'Content-Type: application/json' \
-d '{
"card_controls": {
"name": "example_control",
"controls": [
{
"type": "merchant_restriction",
"version": 2,
"restriction": "disallow",
"mccs": [
"1234"
],
"mids": [
"000235030375123"
]
}
]
}
}'
```
##### Example Response
```bash bash theme={null}
{
"account_id": "acct_291u96075mva",
"card_controls": {
"name": "example_control",
"controls": [
{
"type": "merchant_restriction",
"version": 2,
"restriction": "disallow",
"mccs": [
"1234"
],
"mids": [
"000235030375123"
]
}
]
},
"card_product_id": "cdpt_w10r2sebv0nl",
"cvv": null,
"created_at": "2021-02-19T20:42:40Z",
"expiration": "0225",
"fulfillment": {
"status": "issued"
},
"id": "card_zuhqnmz7e085",
"last4": "3385",
"pan": null,
"person_id": "psn_5vyzn6sveupa",
"pin_is_set": false,
"status": "unactivated",
"updated_at": "2021-02-19T20:42:41Z",
"userdata": null
}
```
### Adding Spend Velocity Restriction Card Control to a Card
The following example is a call that can be made to add a spend velocity restriction of \$100 on a daily interval that resets at 11:00 PM Eastern Time.
##### Example Request
```bash bash theme={null}
$ curl -u $API_KEY_ID:$API_SECRET_KEY https://api.treasuryprime.com/card/card_zuhqnmz7e085 \
-X PATCH \
-H 'Content-Type: application/json' \
-d '{
"card_controls": {
"name": "example_control",
"controls": [
{
"type": "spend_limit",
"version": 1,
"amount": "100",
"interval": "daily",
"timezone": "America/New_York",
"rollover_time": "23:00"
}
]
}
}'
```
##### Example Response
```bash bash theme={null}
{
"account_id": "acct_291u96075mva",
"card_controls": {
"name": "example_control",
"controls": [
{
"type": "spend_limit",
"version": 1,
"amount": "100",
"interval": "daily",
"timezone": "America/New_York",
"rollover_time": "23:00"
}
]
},
"card_product_id": "cdpt_w10r2sebv0nl",
"cvv": null,
"created_at": "2021-02-19T20:42:40Z",
"expiration": "0225",
"fulfillment": {
"status": "issued"
},
"id": "card_zuhqnmz7e085",
"last4": "3385",
"pan": null,
"person_id": "psn_5vyzn6sveupa",
"pin_is_set": false,
"status": "unactivated",
"updated_at": "2021-02-19T20:42:41Z",
"userdata": null
}
```
## Remove Card Controls from a Card or Card Product
To remove the association of card controls from a [Card](/reference/card) or [Card Product](/reference/card-product) object, post an empty control configuration:
##### Example Request
```bash bash theme={null}
$ curl -u $API_KEY_ID:$API_SECRET_KEY https://api.treasuryprime.com/card/card_zuhqnmz7e085 \
-X PATCH \
-H 'Content-Type: application/json' \
-d '{
"card_controls": {
"name": "example_deletion",
"controls": []
}
}'
```
##### Example Response
```bash bash theme={null}
{
"account_id": "acct_y8l0jnm77y0v",
"card_controls": null,
"card_product_id": "cdpt_jy9olftde0i7",
"cvv": null,
"created_at": "2021-02-19T20:42:40Z",
"expiration": "0225",
"fulfillment": {
"status": "shipped"
},
"id": "card_zuhqnmz7e085",
"last4": "3416",
"pan": null,
"person_id": "psn_xggynxjga2up",
"pin_is_set": false,
"status": "active",
"updated_at": "2021-02-19T20:42:41Z",
"userdata": null
}
```