Skip to main content
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

ParameterTypeDescription
namestringName for the card controls.
controlsarray[objects]An array of control configurations, as outlined below

​
Card Control Configuration Types

All card controls configuration objects must have these attributes:
ParameterTypeDescription
typestringThe type of control configuration, e.g. merchant_restriction.
versionnumberA 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.
ParameterTypeRequired?Description
typestringRequiredName of this card controls object.
versionnumberRequiredVersion of configuration (currently: 2)
restrictionstringRequiredEither allow or disallow, for allowing or disallowing the list of mccs
mccsarray[string]An array of four digit numeric strings, representing the merchant categories to allow or disallow. Required if mids are not passed.
midsarray[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).
ParameterTypeRequired?Description
typestringRequiredName of this card controls object.
versionnumberRequiredVersion of configuration (currently: 1).
amountstringRequiredTotal amount of authorizated transactions to allow within the window.
intervalstringRequiredType of interval for calculating total amount of transactions. One of: rolling, daily, or monthly.
windownumberNumber of hours for calculating rolling window. Required if interval is rolling.
timezonestringTimezone 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_timestringTimestamp 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).
ParameterTypeRequired?Description
typestringRequiredName of this card controls object.
versionnumberRequiredVersion of configuration (currently: 1).
amountstringRequiredTotal amount of ATM transactions to allow within the window.
intervalstringRequiredType of interval for calculating total amount of transactions. One of: rolling, daily, or monthly.
windownumberNumber of hours for calculating rolling window. Required if interval is rolling.
timezonestringTimezone 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_timestringTimestamp 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 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
}