Card Controls

Card Controls objects are used to configure the restrictions and capabilities of associated Card and 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 or 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. 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. 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 and 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

$ 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

{
  "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

$ 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

{
  "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 object, post an empty control configuration:

Example Request

$ 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

{
  "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
}