# Card Controls
source: https://developer.mastercard.com/commercial-connect-api/documentation/use-cases/card-controls/index.md

Card controls can ensure that card usage is limited to specific use cases. A single control set or multiple sets of controls can be associated with any real or any virtual card.

Use a single set of card controls to limit the card usage to a specific use case only, such as:

* You want to use your card only for quarterly recurring payments. In this case, use the quarterly limit control and set the transactionCount = 1. Include controls such as countries and merchant category codes to limit countries and industry verticals.

Use the multiple sets of controls on a card to limit the card usage to multiple expenses within a limited scope. These examples show how you can use multiple sets of card controls on a single card:

* You want to use a card for booking and paying for a work trip. In this case, set up one set of controls with a validity period and other relevant controls for when hotel and airfare reservations are made. Set up a second set of controls with a validity period and other relevant controls so the card can be used for expenses during the business trip.

* You want to use the same card to pay multiple suppliers at different times in the quarter. In this case, set up a control set for each supplier using the merchant category control or merchantId control. Set up the validity period that matches the time frame when the payments need to happen.

Note: In the following diagrams, optional steps are denoted with dashed arrows instead of solid arrows.

## Manage real card authorization controls {#manage-real-card-authorization-controls}

Partners use these endpoints to update or remove the authorization controls of a real card.
Diagram rccontrols
API Reference: `PUT /accounts/real-cards/{account_id}/card-controls`


API Reference: `DELETE /accounts/real-cards/{account_id}/card-controls`

## Update virtual card controls {#update-virtual-card-controls}

Partners use this endpoint to modify virtual card authorization controls for a specific virtual card.
Diagram vcnupdatecontrols
API Reference: `PUT /accounts/virtual-cards/{account_id}/card-controls`

## How to use the aging limit and period limit controls {#how-to-use-the-aging-limit-and-period-limit-controls}

Both `agingLimit` and period limits (such as weekly or quarterly) have a `spendAmount` element that limits how much can be charged to a card. Determining when to use the `agingLimit.spendAmount` or period limit `spendAmount` depends on your use case.

The main difference between the `spendAmount` in the period limits and the `agingLimit` is the time frame that the `spendAmount` is evaluated for. For example, the system evaluates the `spendAmount` for a weekly limit within the context of each week. However, to use the `agingLimit.spendAmount`, you need to set `authorizationHoldDays`, which allows you set the number of days each authorization is counted against the `spendAmount` set in the control.

### Available balance {#available-balance}

Available balance is an element of both `agingLimit` and period limit controls. The system calculates the available balance based on the `spendAmount` limit and the duration of the limit that you have specified, and the amount spent.

The system evaluates the `agingLimit.availableBalance` in the context of the `agingLimit.authorizationHoldDays`, and in combination with the `agingLimit.spendAmount`. In this case, the available balance represents the amount that can be spent within the time frame that you have specified in `authorizationHoldDays`, before it resets to the amount you have specified in the `agingLimit.spendAmount`.

Consider this example:

|               If ...               |                And ...                 |                And ...                 |                            Then ...                            |
|------------------------------------|----------------------------------------|----------------------------------------|----------------------------------------------------------------|
| `agingLimit.spendAmount` = USD 100 | `agingLimit.authorizationHoldDays` = 5 | authorization is made today for USD 40 | `agingLimit.availableBalance` is USD 60 for the next five days |

If no other authorizations are made on the card, on the sixth day the available balance of USD 40 resets to USD 100, which is the value you have set in the `agingLimit.spendAmount`.

Available balance in the context of period limit controls represents the remaining balance within your period limit. For example, `weeklyLimit.availableBalance` represents the remaining balance within the current weekly period.

Consider this example:

|                 If ...                  |                                 Then ...                                  |
|-----------------------------------------|---------------------------------------------------------------------------|
| `weeklyLimit.availableBalance` = USD 50 | total authorizations in the current week can't add up to more than USD 50 |

In other words, `weeklyLimit.availableBalance` reflects the spendAmount for all authorizations in the current week.

### Example of when to use the aging limit spend amount {#example-of-when-to-use-the-aging-limit-spend-amount}

The `agingLimit.spendAmount` element allows you to set the maximum amount that can be spent on the card, either at one time or in multiple transactions within the time frame defined by `agingLimit.authorizationHoldDays`.

Consider this example:

|              If ...               |                And ...                 |                And ...                 |                            Then ...                            |
|-----------------------------------|----------------------------------------|----------------------------------------|----------------------------------------------------------------|
| `agingLimit.spendAmount` = USD 50 | `agingLimit.authorizationHoldDays` = 4 | authorization is made today for USD 35 | `agingLimit.availableBalance` is USD 15 for the next four days |

On the fifth day assuming no other authorizations have been made on the card, the USD 35 authorization will "age off" and the `agingLimit.availableBalance` will go back to USD 50.

### Example of when to use the aging limit with other controls {#example-of-when-to-use-the-aging-limit-with-other-controls}

Consider that you want to limit the weekly spending to USD 50 and also that each quarter or month, the spend is no more than USD 200.

|          If ...          |                 And ...                 |                              Then ...                               |
|--------------------------|-----------------------------------------|---------------------------------------------------------------------|
| weekly spending = USD 50 | quarterly spend is no more than USD 200 | set the weekly control to USD 50 and the quarterly limit to USD 200 |

To limit weekly authorizations to USD 50 and to ensure that no more than USD 200 was authorized in the same 30-day window, use the weekly and aging limit controls, as shown in this table:

|           If ...            |                         Then ...                         |
|-----------------------------|----------------------------------------------------------|
| USD 50 was authorized today | no more than USD 150 could be spent for the next 30 days |

The authorization will be declined if any of the limit controls in a set of card controls fail. As a result, if you set both the weekly and aging limit and one passes but the other one does not, the system will decline the authorization.

## Example of card controls applied to both real card and virtual card {#example-of-card-controls-applied-to-both-real-card-and-virtual-card}

If you have applied controls on both the real card and related virtual cards and you have a transaction on a virtual card, In Control will:

1. Check the controls on the virtual card first.
2. If the validation on the virtual card controls passes, In Control will then check the controls on the underlying real card.
3. If the controls on the underlying real card pass the check, In Control responds to the issuer with advice to approve the transaction message.
4. If the controls on either the virtual card or the real card fail the validation, In Control responds to the issuer with advice to decline the transaction message.

### Budget example with card controls {#budget-example-with-card-controls}

For example, you are trying to set a monthly budget for USD 5000 for a department in your company and you want to have two virtual cards distributed within the department but want to maintain an overall budget of USD 5000.

In this case, you will set a `spendAmount` control on the real card, which acts as your overall budget for that department to USD 5000.

Any child virtual cards that are associated with the real card can then have individual spend limits. For example, you want to have two virtual cards with individual spend amounts of USD 3000.

However, the overall `spendAmount` control you have set on your real card will ensure that none of the individual `spendAmounts` on virtual cards can exceed the overall budget.

This scenario describes a step-by-step example of a sequence of transactions on virtual cards and the effect on the overall budget set on the real card:

1. First, the table shows the initial `spendAmount` controls you set on the real card and related virtual cards on a specific date, for example 1 July:

| Card type | Monthly limit spend amount |
|-----------|----------------------------|
| RCN1      | USD 5000                   |
| VCN1      | USD 3000                   |
| VCN2      | USD 3000                   |

2. Next, on 2 July your department makes a transaction on a VCN1 for USD 3000. In Control first checks the card controls on the VCN1 and because the `spendAmount` was initially set to USD 3000, this control passes the validation. Next, In Control checks the card controls on RCN1 and because the `spendAmount` was initially set to USD 5000, this control also passes the validation. As a result, In Control responds to the issuer with advice to approve the transaction message. The `spendAmount` on RCN1 adjusts to USD 2000, as shown in the table:

| Card type | Monthly limit spend amount |
|-----------|----------------------------|
| RCN1      | USD 2000                   |
| VCN1      | USD 0                      |
| VCN2      | USD 3000                   |

3. Then, on 5 July your department makes a transaction on a VCN2 for USD 2500. In Control first checks the card controls on the VCN2 and because the `spendAmount` was initially set to USD 3000, this control passes the validation. Next, In Control checks the card controls on RCN1 and because the `spendAmount` was already adjusted to USD 2000 as a result of a previous transaction on VCN1, this control fails the validation. As a result, In Control responds to the issuer with advice to decline the transaction message. Because the issuer declines the transaction, the `spendAmount` on RCN1 stays USD 2000. The `spendAmount` on VCN2 also stays USD 3000, as shown in the table:

| Card type | Monthly limit spend amount |
|-----------|----------------------------|
| RCN1      | USD 2000                   |
| VCN1      | USD 0                      |
| VCN2      | USD 3000                   |

4. On the first day of the next month, in this example 1 August, the card controls reset to their initial state, as shown in the table:

| Card type | Monthly limit spend amount |
|-----------|----------------------------|
| RCN1      | USD 5000                   |
| VCN1      | USD 3000                   |
| VCN2      | USD 3000                   |