# Card Controls: Elements and Attributes source: https://developer.mastercard.com/commercial-connect-api/documentation/api-reference/card-controls/index.md Card controls set the spending boundaries of the purchase requests. Users can add one or more sets of controls on your cards. Users can also apply multiple limit controls in the same control set, such as two monthly limits. In this case, the system will use the control with the higher limit during authorization. This rule applies to the controls marked with an asterisk in the card controls table. Some card controls follow inclusion/exclusion logic to set spending boundaries. As a result, it is possible to set up card controls in a way that renders the card unusable. To understand fully how to set up card controls to meet specific needs, carefully review use case documentation, elements, and attributes for card controls. ## Card controls {#card-controls} | Control | Description | Suggested Usage | |----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [alias]() | Name provided for the control set. | You can use an alias on each control set. It is especially useful when multiple control sets exist for a single card. | | [transactionLimit](https://developer.mastercard.com/commercial-connect-api/documentation/api-reference/card-controls/index.md#transactions-control-elements) | Sets the spend amount limit for each transaction. | You can use this control with all other controls, provided the spend amount per transaction set here does not conflict with other spend amount limits that were set using the other controls. | | [continuousLimit](https://developer.mastercard.com/commercial-connect-api/documentation/api-reference/card-controls/index.md#continuouslimit-control-elements) | Limits the number of transactions and the cumulative spend amount on those transactions. | You can use this control with all other controls, provided the spend amount per transaction set here does not conflict with other spend amount limits that were set using the other controls. | | [dailyLimit\*](https://developer.mastercard.com/commercial-connect-api/documentation/api-reference/card-controls/index.md#dailylimit-control-elements) | Limits authorization activity to a certain number of transactions and their cumulative spend limits on a given day. | You can use this control with all other controls, provided the spend amount per transaction set here does not conflict with other spend amount limits that were set using the other controls. | | [weeklyLimit\*](https://developer.mastercard.com/commercial-connect-api/documentation/api-reference/card-controls/index.md#weeklylimit-control-elements) | Limits authorization activity to a certain number of transactions and their spend limits on a given week. | You can use this control with all other controls, provided the spend amount per transaction set here does not conflict with other spend amount limits that were set using the other controls. | | [monthlyLimit\*](https://developer.mastercard.com/commercial-connect-api/documentation/api-reference/card-controls/index.md#monthlylimit-control-elements) | Limits authorization activity to a certain number of transactions and their spend limits on a given month. | You can use this control with all other controls, provided the spend amount per transaction set here does not conflict with other spend amount limits that were set using the other controls. | | [quarterlyLimit\*](https://developer.mastercard.com/commercial-connect-api/documentation/api-reference/card-controls/index.md#quarterlylimit-control-elements) | Limits authorization activity to a certain number of transactions and their spend limits on a given quarter. | You can use this control with all other controls, provided the spend amount per transaction set here does not conflict with other spend amount limits that were set using the other controls. | | [yearlyLimit\*](https://developer.mastercard.com/commercial-connect-api/documentation/api-reference/card-controls/index.md#yearlylimit-control-elements) | Limits authorization activity to a certain number of transactions and their spend limits on a given year. | You can use this control with all other controls, provided the spend amount per transaction set here does not conflict with other spend amount limits that were set using the other controls. | | [agingLimit](https://developer.mastercard.com/commercial-connect-api/documentation/api-reference/card-controls/index.md#aginglimit-control-elements) | Sets a credit line with the spendAmount attribute. | This control tracks the current remaining available credit and approves a transaction only if the requested amount is less than or equal to the remaining available credit. When you set this control, the available credit is set to the value of the spendAmount. | | [timeOfDay](https://developer.mastercard.com/commercial-connect-api/documentation/api-reference/card-controls/index.md#timeofday-control-elements) | Limits the authorization requests to defined time periods for specific days. | Because this control does not set a spend amount limit, you can use it with any of the spend amount controls. | | [countries](https://developer.mastercard.com/commercial-connect-api/documentation/api-reference/card-controls/index.md#countries-control-elements) | Limits authorization activity to specific countries. | The negate flag allows users to exclude authorizations from a specific country or countries. | | [merchantCategoryCodes](https://developer.mastercard.com/commercial-connect-api/documentation/api-reference/card-controls/index.md#merchantcategorycodes-control-elements) | Limits authorization activity to specific merchant categories. | The negate flag allows users to exclude authorizations from a specific merchant category or categories. | | [validityPeriod](https://developer.mastercard.com/commercial-connect-api/documentation/api-reference/card-controls/index.md#validityperiod-control-elements) | Limits authorization activity to a period that is determined by a range between the start and end dates. | Set the end date earlier than the expiration date. | | [merchantId](https://developer.mastercard.com/commercial-connect-api/documentation/api-reference/card-controls/index.md#merchantid-control-elements) | Limits authorization activity to a specific merchant ID. | The negate flag allows users to exclude authorizations from a specific merchant ID or merchant IDs. | | [merchantNames](https://developer.mastercard.com/commercial-connect-api/documentation/api-reference/card-controls/index.md#merchantnames-control-elements) | Limits authorization activity to a specific merchant name. | The negate flag allows users to exclude authorizations from a specific merchant or merchants. | | [amountRange](https://developer.mastercard.com/commercial-connect-api/documentation/api-reference/card-controls/index.md#amountrange-control-elements) | Limits authorization activity to a specific amount that is determined by a range between minimum and maximum amount elements. | You can use this control with other spend amount controls provided those controls are not conflicting. The system will always use the lower amount. | ## transactions control elements {#transactions-control-elements} Transactions control sets the maximum number of transactions that can be charged to a card. | Names | Description | |---------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `spendAmount` | * Maximum spend amount in the period. * The commercial Connect API does not support setting this value to 0. This applies to all spend amount attributes across the various controls that use them. | ### Sample control {#sample-control} ```json "alias": "Control Rule Alias", "transactions": { "spendAmount": 500 } ``` ## continuousLimit control elements {#continuouslimit-control-elements} The continuous limit controls the number of transactions in a period from the time that the control is set with no end date. | Names | Description | |--------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `transactionCount` | * Number of transactions. | | `spendAmount` | * Maximum spend amount in the period. * The commercial Connect API does not support setting this value to 0. This statement is true for all spend amount attributes across the various controls that use them. | ### Sample control {#sample-control-1} ```json "continuousLimit": { "transactionCount": 12, "spendAmount": 500 } ``` ## dailyLimit control elements {#dailylimit-control-elements} The daily limit controls the number of transactions occurring on a daily basis. | Names | Description | |--------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `transactionCount` | * Number of transactions. | | `spendAmount` | * Maximum spend amount in the period. * The commercial Connect API does not support setting this value to 0. This statement is true for all spend amount attributes across the various controls that use them. | ### Sample control {#sample-control-2} ```json "dailyLimit": { "transactionCount": 12, "spendAmount": 500 } ``` ## weeklyLimit control elements {#weeklylimit-control-elements} The weekly limit controls the number of transactions occurring on a weekly basis. | Names | Description | |--------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `transactionCount` | * Number of transactions. | | `spendAmount` | * Maximum spend amount in the period. * The commercial Connect API does not support setting this value to 0. This statement is true for all spend amount attributes across the various controls that use them. | ### Sample control {#sample-control-3} ```json "weeklyLimit": { "transactionCount": 12, "spendAmount": 500 } ``` ## monthlyLimit control elements {#monthlylimit-control-elements} The monthly limit controls the number of transactions occurring on a monthly basis. | Names | Description | |--------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `transactionCount` | * Number of transactions. | | `spendAmount` | * Maximum spend amount in the period. * The commercial Connect API does not support setting this value to 0. This statement is true for all spend amount attributes across the various controls that use them. | ### Sample control {#sample-control-4} ```json "monthlyLimit": { "transactionCount": 12, "spendAmount": 500 } ``` ## quarterlyLimit control elements {#quarterlylimit-control-elements} The quarterly limit controls the number of transactions occurring on a quarterly basis. | Names | Description | |--------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `transactionCount` | * Number of transactions. | | `spendAmount` | * Maximum spend amount in the period. * The commercial Connect API does not support setting this value to 0. This statement is true for all spend amount attributes across the various controls that use them. | ### Sample control {#sample-control-5} ```json "quarterlyLimit": { "transactionCount": 12, "spendAmount": 500 } ``` ## yearlyLimit control elements {#yearlylimit-control-elements} The yearly limit controls the number of transactions occurring on a yearly basis. | Names | Description | |--------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `transactionCount` | * Number of transactions. | | `spendAmount` | * Maximum spend amount in the period. * The commercial Connect API does not support setting this value to 0. This statement is true for all spend amount attributes across the various controls that use them. | ### Sample control {#sample-control-6} ```json "yearlyLimit": { "transactionCount": 12, "spendAmount": 500 } ``` ## agingLimit control elements {#aginglimit-control-elements} The aging limit sets a credit line through the spendAmount attribute. The aging limit also allows the requestor to age off the approved authorization requests: * Aging off a request means to remove the request that the merchant has not cleared after a defined number of days, as set in the authorizationHoldDays attribute. * Tracks available credit and approves a transaction only if the requested amount is less than or equal to the remaining available credit. | Names | Description | |---------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `authorizationOnHoldDays` | * Number of days that authorization holds before aging off. This attribute resets after midnight on the hold expiry date in the time zone specified for this control. For example, an authorization processed on 1 January at 11:00 a.m. CST on a virtual card with a control set in UTC and a hold of 2 days, resets at 00:00:01 UTC on 4 January. * authorizationOnHoldDays set to 0 means that the authorization ages off at midnight at the end of the same day that the authorization occurred. * authorizationOnHoldDays set to 1 means that the authorization ages off at midnight at the end of the next days after the authorization has occurred. | | `spendAmount` | * Cumulative spend amount within the period. * spendAmount value must be greater than 0. | | `timeZone` | * Specifies the timezone in which the transactions are taking place. | | `currencyType` | * Specifies the currency. | | `currencyCode` | * Specifies the currency code. | ### Sample control {#sample-control-7} ```json "agingLimit": { "authorizationHoldDays": 1234, "spendAmount": 1000, "timeZone": "UTC-06:00", "currencyType": "MERCHANT", "currencyCode": "825" } ``` ## timeOfDay control elements {#timeofday-control-elements} The time of day control allows you to specify the day, time, and time zone when transactions can occur or not occur based on whether you have set the negate flag to true or false. If set to true, the transactions can occur within the specified day, time, and timezone. When set to false, the system will decline transactions within the specified day, time, and time zone. | Names | Description | |------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `times` | * Specifies the day and time range of transactions. | | `timeZone` | * Specifies the timezone in which the transactions are taking place. | | `negate` | * Possible values: True, false * If the negate flag is false, the transactions cannot occur within the specified day, time, and time zone. When the negate flag is true, the transactions can occur within the specified day, time, and time zone. | ### times subnodes {#times-subnodes} | Names | Description | |------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------| | `day` | * Days of the week that the control can apply to. Valid values are: SUNDAY, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, WEEKDAYS, WEEKEND, and ALL. | | `fromTime` | Start time of the day in HH:mm. | | `toTime` | End time of the day in HH:mm. | ### Sample control {#sample-control-8} ```json "timeOfDay": { "times": [ { "day": "SUNDAY", "fromTime": "08:21", "toTime": "1260" } ], "timeZone": "UTC", "negate": true } ``` ## countries control elements {#countries-control-elements} The countries control limits the countries in which transactions can either occur or are declined, depending on whether the negate flag is set to true or false. If set to true, transactions can occur within the specified country or countries. When set to false, the system will decline transactions in the specified country or countries. | Names | Description | |---------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `countryCode` | * A three letter code that identifies the country where the control can apply. Multiple country codes are supported. * All 246 country codes available, separated using the pipe character. | | `negate` | * Possible values: True, false * If set to true, transactions can occur within the specified country or countries. If set to false, transactions in the specified country or countries will be declined. | ### Sample control {#sample-control-9} ```json "countries": { "countryCodes": [ "123", "456" ], "negate": true } ``` ## merchantCategoryCodes control elements {#merchantcategorycodes-control-elements} Merchant category codes specify the merchant categories that the transactions can either occur in or are declined, depending on whether the negate flag is set to true or false. If set to true, transactions can occur for the specified merchant categories. When set to false, transactions for those merchant categories will be declined. For details about how the codes populate, refer to the *Quick Reference Booklet for MCC Codes* on Mastercard Connect. | Names | Description | |----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `mccs` | * Specifies merchant category codes. Multiple merchant category codes are supported. | | `negate` | * Possible values: True, false * If set to true, transactions can occur for the specified merchant categories. If set to false, transactions for those merchant categories will be declined. | ### Sample control {#sample-control-10} ```json "merchantCategoryCodes": { "mccs": [ "3001", "3005" ], "negate": true } ``` ## validityPeriod control elements {#validityperiod-control-elements} The validity period limits the authorization activity to a specific time period, as designated by start and end dates. | Names | Description | |-------------|-----------------------------------------------------------------| | `startDate` | * Specifies the start date when the controls become valid. | | `endDate` | * Specifies the end date when the controls are no longer valid. | ### Sample control {#sample-control-11} ```json "validityPeriod": { "startDate": "2020-10-06T11:09:42.000Z", "endDate": "2020-11-06T11:09:42.000Z" } ``` ## merchantId control elements {#merchantid-control-elements} The merchant ID limits the transactions to specific merchants and acquirers. If the negate flag is set to true, transactions can occur for the specified merchants and acquirers. When the negate flag is set to false, the system will decline transactions for the specified merchants and acquirers. | Names | Description | |--------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `merchantId` | * Specifies the merchant ID. | | `acquirerId` | * Specifies the acquirer ID. | | `negate` | * Possible values: True, false * If the negate flag is set to true, transactions can occur for the specified merchants and acquirers. When the negate flag is set to false, the system will decline transactions for the specified merchants and acquirers. | ### Sample control {#sample-control-12} ```json "merchantId": { "acceptorId": "123456789012345", "acquirerId": "3", "negate": true } ``` ## merchantNames control elements {#merchantnames-control-elements} Merchant names limit the transactions to a specific merchant, as designated by the control. The merchantNames attribute is case-sensitive and must be an exact match. If the negate flag is set to true, transactions can occur only for the specified merchants. When the negate flag is set to false, the system will decline transactions for the specified merchants. | Names | Description | |-----------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `negate` | * Possible values: True, false * If the negate flag is set to true, transactions can occur only for the specified merchants. If the negate flag is set to false, transactions for the specified merchants will not occur. | | `merchantNames` | * Specifies the name of the merchant that the control is imposed on. Multiple merchant names are supported. | ### Sample control {#sample-control-13} ```json "merchantName": { "negate": true, "merchantNames": [ "Amazon" ] } ``` ## amountRange control elements {#amountrange-control-elements} The amount range control allows setting the minimum and maximum amounts for each transaction. Transactions will only occur if the requested amount is equal to or greater than the minimum amount and less than or equal to the maximum amount. | Names | Description | |-------------|------------------------------------------------------------------------| | `minAmount` | Sets a minimum amount for a transaction. | | `maxAmount` | * Sets a maximum amount for a transaction. * Maximum length: 12 digits | ### Sample control {#sample-control-14} ```json "amountRange": { "minAmount": 1000, "maxAmount": 10000 } ```