This guide explains how to implement account-level authorization controls (ALCs) using these endpoints:

• Velocity ALCs

  • <a href="ref:post_getauthcontrol" target="_blank">Get Auth Control</a>

  • <a href="ref:post_setaccountlevelauthcontrol" target="_blank">Set Account-Level Auth Control</a>

  • <a href="ref:post_deleteaccountlevelauthcontrol" target="_blank">Delete Account-Level Auth Control</a>

• MCC ALCs

  • <a href="ref:post_getmcccontrols" target="_blank">Get MCC Controls</a>

  • <a href="ref:post_setaccountlevelmcccontrols" target="_blank">Set Account-Level MCC Controls</a>

  • <a href="ref:post_deleteaccountlevelmcccontrol" target="_blank">Delete Account-Level MCC Control</a>

• Merchant ID ALCs

  • <a href="ref:post_getmerchantcontrols" target="_blank">Get Merchant Controls</a>

  • <a href="ref:post_setaccountlevelmerchantcontrol" target="_blank">Set Account-Level Merchant Control</a>

  • <a href="ref:post_deleteaccountlevelmerchantcontrol" target="_blank">Delete Account-Level Merchant Control</a>

This guide assumes that you are familiar with the concepts in these guides:

• <a href="doc:about-account-level-auth-controls" target="_blank">**About Account-Level Auth Controls**</a> — General explanation of ALCs, including use cases.

• <a href="doc:designing-authorization-controls" target="_blank">**Designing Authorization Controls**</a> — How to design authorization controls at the product and account levels.

• <a href="page:mcc-and-merchant-id-alc-examples" target="_blank">**MCC and Merchant ID ALC Examples**</a> — Tables that show how MCC and merchant ID controls are applied.

## Result of following these procedures

An ALC is created, modified, disabled, or deleted. The authorization controls can also be retrieved per account or per product. You can set three types of ALC:

• [Velocity](🔗)

• [MCC](🔗)

• [Merchant ID](🔗)

## General ALC characteristics

These are the general characteristics of ALCs:

• To update an existing ALC, send another Set Account-Level X Control call with the new values.

• After setting or updating an ALC, there is a delay of a few minutes before the control is applied to live transactions.

• ALCs are applied to PRNs, not to card IDs or balance IDs:

  • All cards that have the same PRN are affected by the ALC. If card1 and card2 have the same PRN, it is not possible to put an ALC on card1 but not card2.

  • When two or more PRNs share an account balance (`bal_id`), the ALC applies only to the individual PRNs, not to the `bal_id`. For example, if PRN1 and PRN2 share a balance, an ALC that is applied to PRN1 will not affect PRN2.

## Setting time limits

All ALCs can be set either permanently or for only a limited time. The `startDate` and `endDate` endpoint parameters have these defaults:

• `startDate:` Current <a href="ref:galileo-system-time" target="_blank">Galileo system time</a>

• `endDate:` 1 Jan 3000 (no expiry)

When you pass nothing or `Null` for these values, the defaults are applied in these circumstances:

• The control is being created for the first time

• _Velocity ALCs only_. The control was disabled and you are reactivating it.

For example, if a velocity control has expired, then the next time you call <a href="ref:post_setaccountlevelauthcontrol" target="_blank">Set Account-Level Auth Control</a> for that control—and you pass nothing or `Null` for the start or end dates—the default values will be applied. However, if a control has not expired, and you want to update one of its parameters, passing nothing or `Null` for `startDate` or `endDate` will not change the values in those fields.

For MCC or merchant ID controls that have expired, you cannot pass nothing or `Null` to get the default date values; instead, you must enter new values.

You can set `startDate` up to six months in the future. `endDate` must always be later than `startDate`.

🚧

Warning

Do not pass a time for `startDate` or `endDate` that is in the past, even if it is the time that was previously set. Instead, pass no value to keep the same value, or pass a value that is equal to or later than the current system time.

This table shows some examples of setting the dates in a Set Account-Level X Control endpoint, assuming that today is Thursday March 10, 2022 at 1:00 pm.

## Velocity controls

A velocity ALC must be based on an existing product-level velocity control. Each product-level control has a control ID that you must pass when creating the ALC. See <a href="doc:designing-authorization-controls#velocity-controls" target="_blank">Velocity controls</a> in the _Designing Authorization Controls_ guide to see how velocity controls are represented in the Galileo system.

The product-level controls are visible in the <<glossary:GCC>> and <<glossary:CST>>, or you can call <a href="ref:post_getauthcontrol" target="_blank">Get Auth Control</a> with these parameters:

• `controlId:` _blank_

• `prodId:` Product ID

• `accountNo:` _blank_

Open the Recipes below to see example responses. Consult the <a href="ref:post_getauthcontrol" target="_blank">Get Auth Control</a> reference material for the response schema.

<!--recipe: Get Auth Control response for product-->

Galileo recommends that you call <a href="ref:post_getauthcontrol" target="_blank">Get Auth Control</a> with `prodId` populated to create a lookup table for the product instead of calling Get Auth Control every time you want to set an ALC.

You can periodically update your lookup table by calling Get Auth Control again with the `prodId`. You can also pass `controlId` and `prodId` with Get Auth Control to retrieve the limits for a specific control.

📘

Note

Galileo will not make changes to your product-level controls except by your request.

### Setting velocity ALCs

You can set a velocity ALC in one of two ways:

• In the <<glossary: CST>>, under Account Info.

• With the Program API. Follow these steps:

  1. Obtain the control ID by calling <a href="ref:post_getauthcontrol" target="_blank">Get Auth Control</a> or by consulting your lookup table.

  2. Call <a href="ref:post_setaccountlevelauthcontrol" target="_blank">Set Account-Level Auth Control</a> with these parameters:

Given the example controls in the Recipe above, this table shows how you would populate the parameters in the <a href="ref:post_setaccountlevelauthcontrol" target="_blank">Set Account-Level Auth Control</a> endpoint calls to create an ALC for each of the first three controls, assuming that today is March 10, 2022 at 1:00 pm. Note that when only the transaction count is being altered, the amount from the product-level control must be passed; otherwise, the amount would be unlimited.

### Updating velocity ALCs

When updating an existing account-level velocity control, follow these rules:

• **Positive value** — Set the control to this value

• **Blank** — Do not change the value

• `Null` — Nullify the existing value

To see which ALCs are already set for an account, call <a href="ref:post_getauthcontrol" target="_blank">Get Auth Control</a> with these parameters:

• `accountNo:` PAN of the account

• `prodId:` _blank_

Open the Recipe below to see an example response. Consult the <a href="ref:post_getauthcontrol" target="_blank">Get Auth Control</a> reference material for the response schema.

<!--recipe: Get Auth Control response for account-->

For example, if you have already set a velocity ALC for the daily domestic ATM withdrawal limit (control ID 1), and you want to change the amount to $1000, you would call <a href="ref:post_setaccountlevelauthcontrol" target="_blank">Set Account-Level Auth Control</a> with these parameters:

• `controlId: 1`

• `startDate:` _blank_

• `endDate:` _blank_

• `amount: 1000`

• `transactionCount:` _blank_

#### Delete one limit of a velocity ALC

To delete either `amount` or `transactionCount` in a velocity ALC without deleting the other value, pass `Null` for the value to delete and pass nothing for the other value. In this example, the transaction count for daily domestic ATM withdrawals is removed but the amount is unchanged. Because the `startDate` and `endDate` parameters are left blank, and the ALC has not expired, the dates will remain unchanged. When the account-level transaction count is nullified, the transaction count becomes unlimited—the product-level limit is not used as long as the ALC is active.

• `controlId: 1`

• `startDate:` _blank_

• `endDate:` _blank_

• `amount:` _blank_

• `transactionCount: Null`

#### Disable a velocity ALC

To disable a velocity ALC without deleting it, follow the steps to update the control and set the current date-time for `endDate`. When a velocity ALC has been disabled, the account reverts back to the product-level control.

#### Reactivate a disabled velocity ALC

To reactivate an expired ALC, call the <a href="ref:post_setaccountlevelauthcontrol" target="_blank">Set Account-Level Auth Control</a> endpoint with these parameters:

• `accountNo:` PRN of the account

• `startDate:` Pass nothing to set the current system time or pass a future date no more than six months in the future.

• `endDate:` Pass nothing to set the end date to 3000-01-01 or set a time that is later than `startDate`.

• `amount`: Leave blank

• `transactionCount:` Leave blank

### Deleting a velocity ALC

To delete a velocity ALC from the database, call <a href="ref:post_deleteaccountlevelauthcontrol" target="_blank">Delete Account-Level Auth Control</a> with these parameters:

• `accountNo:` PRN of the account. Do not use PAN or CAD.

• `controlId:` ID of the control to delete

## MCC controls

It is not necessary to set product-level <<glossary:MCC>> controls before setting account-level MCC controls. However, if you do have product-level MCC controls set up, you must take them into account when setting MCC controls at the account level. Consult <a href="doc:designing-authorization-controls#mcc-controls" target="_blank">MCC controls</a> in the _Designing Authorization Controls_ guide to see how product-level MCC controls affect account-level MCC controls.

You can see the MCC blocklist and product-level controls in the <<glossary:GCC>> and the <<glossary:CST>>, and you can also retrieve the product-level MCC controls by calling the <a href="ref:post_getmcccontrols" target="_blank">Get MCC Controls</a> endpoint with these parameters:

• `accountNo:` _blank_

• `prodId:` Product ID

Open the Recipes below to see sample responses.

<!--recipe: Get MCC Controls response for product-->

To see existing account-level controls, pass the PRN in `accountNo`.

<!--recipe: Get MCC Controls response for account-->

### Setting MCC ALCs

Verify that the controls you intend to create do not violate any of the <a href="doc:designing-authorization-controls#account-and-product-level-mcc-control-conventions" target="_blank">MCC control conventions</a>. If they do violate a convention, the endpoint will return an error.

To set one or more account-level controls, call the <a href="ref:post_setaccountlevelmcccontrols" target="_blank">Set Account-Level MCC Controls</a> endpoint with these parameters:

When you pass multiple MCC ranges in a single endpoint call, the system creates a new control for every range or single MCC. For example, if you pass this value, `['2000', '3000-3500', '3580-4000', '5555']`, the system creates these four controls:

All four of these controls have the same properties for start and end dates, allow/deny, and online only.

📘

Note

If you pass one or more MCCs or MCC ranges that overlap with existing MCCs, the error message that the endpoint returns indicates only the first violation. When you send another request, the endpoint returns the second violation only, and so on.

### Updating account-level MCC controls

In the Galileo tables that contain account-level MCCs, each control occupies a separate row, and the row is identified by the first value in the MCC range. (In database terms, it's the primary key when paired with the account number.) In the example above, the identifier for the first control is `2000`, the identifier for the second control is `3000`, and so on.

When updating controls, specify the entire range in `mccControls` along with the new values. If the existing range is 2000–3000 and you input `2000` only, the system will change the end value of the range to 2000.

For `startDate` and `endDate` you cannot pass a date-time in the past, even if it is the existing date-time. You should leave `startDate` and `endDate` blank unless you are changing them to the current date or to a date in the future.

To update the values in an existing, unexpired control, call the <a href="ref:post_setaccountlevelmcccontrols" target="_blank">Set Account-Level MCC Controls</a> endpoint with these parameters:

• `accountNo:` PRN of the account

• `startDate:` Leave blank to maintain the same value or pass a new date.

• `endDate:` Leave blank to maintain the same value or pass a new date.

• `mccControls:` Specify the entire range of the control to update: `['2000-2500']` or `['5555']`.

• `allowDeny:` Leave blank. This value cannot be changed.

• `onlineOnly:` Leave blank to maintain the same value or pass `Y` or `N` to change it.

For example, to change the online-only property of the first and third controls in the table above to `Y`, call <a href="ref:post_setaccountlevelmcccontrols" target="_blank">Set Account-Level MCC Controls</a> with these values:

• `mccControls: ['2000', '3580-4000']`

• `onlineOnly: Y`

To change the start and end dates on the fourth control to include all of January 2023, call Set Account-Level MCC Controls with these values:

• `mccControls: ['5555']`

• `startDate: 2023-01-01 00:00:00`

• `endDate: 2023-01-31 23:59:59`

To change the third control to include the 3580–4025 range, call Set Account-Level MCC Controls with these values:

• `mccControls: ['3580-4025']`

To change the second range to 2800–3500—which affects the beginning MCC value—you have two options:

• Create a second control for 2800–2999.

• Ask Galileo to delete the original control, and then set a new control for 2800–3500.

#### Disable an account-level MCC control

To disable an account-level MCC control without deleting it, follow the steps to update the control and set `endDate` to the current date-time.

#### Reactivate a disabled MCC control

To reactivate a disabled MCC control, call the <a href="ref:post_setaccountlevelmcccontrols" target="_blank">Set Account-Level MCC Controls</a> endpoint with these parameters:

• `accountNo:` PRN of the account

• `startDate:` Pass the current time or a future date no more than six months in the future.

• `endDate:` Pass a time that is later than `startDate`.

• `mccControls:` Specify the entire range of the control to update: `['2000-2500']` or `['5555']`.

• `allowDeny:` Leave blank.

• `onlineOnly:` Leave blank or pass a new value.

### Deleting an MCC control

To delete an MCC control from the database, call <a href="ref:post_deleteaccountlevelmcccontrol" target="_blank">Delete Account-Level MCC Control</a> with these parameters:

• `accountNo:` PRN of the account. Do not use PAN or CAD.

• `beginMccControl:` First number in the MCC range

• `endMccControl:` Last number in the MCC range

## Merchant ID controls

A merchant ID (MID) is a string that uniquely identifies a point of sale. MIDs have a maximum of 15 characters. They are usually all numeric but some contain letters. Go to <a href="doc:designing-authorization-controls#merchant-id-controls" target="_blank">Merchant ID controls</a> in the _Designing Authorization Controls_ guide for more information.

Because a DENY MID ALC can contradict MCC controls, it is not necessary to retrieve the MCC controls before setting a DENY MID ALC. However, the MCC blocklist will override any MID controls you set.

You can see existing MID controls in the <<glossary:GCC>> and <<glossary:CST>>, and you can retrieve them by calling the <a href="ref:post_getmerchantcontrols" target="_blank">Get Merchant Controls</a> endpoint with one of these parameters:

• `accountNo:` Populate to get the account-level MID controls.

• `prodId:` Populate to get the product-level MID controls.

Open the Recipes below for example responses.

<!--Recipe: Get Merchant Controls response for product-->

<!--Recipe: Get Merchant Controls response for account-->

### Setting account-level merchant ID controls

To set an account-level merchant ID control, call <a href="ref:post_setaccountlevelmerchantcontrol" target="_blank">Set Account-Level Merchant Control</a> with these parameters:

To set another merchant ID control, repeat the procedure to add to the list of MID controls. The additional MID controls can be either ALLOW or DENY.

### Updating account-level MID controls

When updating an MID control, you cannot pass a date-time in the past, even if it is the existing date-time. You should leave `startDate` and `endDate` blank unless you are changing them to the current date or to a date in the future.

If you already have an account-level MID control for 55555555555555 ALLOW, for example, and you want to deny that merchant ID from now on, you have two options:

• If the MCC controls already deny that merchant's MCC, you can expire (disable) the MID control, and the merchant will be blocked by the MCC controls. See [Disable an account-level MID control](🔗).

• If the MCC controls allow that merchant's MCC, update the existing control to `allowDeny: d`.

To update an existing, unexpired account-level MID control, call <a href="ref:post_setaccountlevelmerchantcontrol" target="_blank">Set Account-Level Merchant Control</a> with these parameters:

• `accountNo:` PRN of the account. Do not use PAN or CAD.

• `startDate:` Leave blank to keep the current value or pass a new value. Must be earlier than endDate.

• `endDate:` Leave blank to keep the current value or specify a new date that is later than `startDate`.

• `merchantId:` Pass the same merchant ID that the existing control has. If you pass a new value, a new MID control will be created. As needed, call <a href="ref:post_getmerchantcontrols" target="_blank">Get Merchant Controls</a> to get the ID.

• `allowDeny:` Leave blank to keep the current value or pass `a` for ALLOW or `d` for DENY.

#### Disable an account-level MID control

To disable an MID control without deleting it, you expire it. Follow the steps to update the control and set the current date-time for the end date.

#### Reactivate an account-level MID control

To reactivate an expired MID control, call <a href="ref:post_setaccountlevelmerchantcontrol" target="_blank">Set Account-Level Merchant Control</a> with these parameters:

• `accountNo:` PRN of the account. Do not use PAN or CAD.

• `startDate:` Pass a time up to six months in the future. Must be earlier than endDate.

• `endDate:` Specify a date that is later than startDate.

• `merchantId:` Pass the same merchant ID that the existing control has. As needed, call <a href="ref:post_getmerchantcontrols" target="_blank">Get Merchant Controls</a> to get the ID.

• `allowDeny:` Leave blank or pass a new value to change it.

### Deleting an account-level MID control

To delete an MID control from the database, call <a href="ref:post_deleteaccountlevelmerchantcontrol" target="_blank">Delete Account-Level Merchant Control</a> with these parameters:

• `accountNo:` PRN of the account. Do not use PAN or CAD.

• `merchantId:` The merchant ID

## Use cases

These use cases are examples of how to set the ALCs in the <a href="doc:about-account-level-auth-controls#use-cases" target="_blank">Use cases</a> section in _About Account-Level Authorization Controls_. All examples assume that today is March 10, 2022 at 1:00 pm in <a href="ref:galileo-system-time" target="_blank">Galileo system time</a>.

### Use case 1: Setting multiple cardholder tiers

You establish two tiers above the default level for cardholders who qualify for the increased limits. You have set up logic to determine which cardholder qualifies for which tier. When you determine that a cardholder qualifies, you set an ALC for each of the five product-level controls, and the limits do not expire. Because you are increasing the limits on five controls, you send five calls to <a href="ref:post_setaccountlevelauthcontrol" target="_blank">Set Account-Level Auth Control</a>, one for each control ID. This example shows how to set a new `amount` and `transactionCount` for the first control (Daily domestic ATM withdrawal limit).

### Use case 2: Raise international ATM limits

Raise international daily ATM limits to $800 with the transaction count raised to 20 during a cardholder's vacation, from March 20 to March 26. Call <a href="ref:post_setaccountlevelauthcontrol" target="_blank">Set Account-Level Auth Control</a> with these parameters:

### Use case 3: Reduce a limit

Reduce the total weekly amount to $3000 with transaction count set at 7. The change starts at 1:00 pm (now) and does not expire. Call <a href="ref:post_setaccountlevelauthcontrol" target="_blank">Set Account-Level Auth Control</a> with these parameters:

### Use case 4: Change count but not amount

Raise the domestic ATM transaction count limit to 4 but do not change the amount, starting now (1:00 pm) and ending in 30 minutes. After the ALC expires, the account reverts back to the product-level controls. Call <a href="ref:post_setaccountlevelauthcontrol" target="_blank">Set Account-Level Auth Control</a> with these parameters.

### Use case 5: Fleet-card controls

The fleet-card product has an MCC control of 5530–5549 ALLOW, which permits purchases at gas stations and auto parts stores only. For those drivers who regularly need to make overnight stays, call the <a href="ref:post_setaccountlevelmcccontrols" target="_blank">Set Account-Level MCC Controls</a> endpoint with these parameters to allow the card to be used at hotels.

### Use case 6: Food-delivery cards

The food-delivery driver cards have a product-level MCC control of 0000–0000 ALLOW, which means that all MCCs are denied. The merchant ID controls are valid for only one hour. When an order comes in for Restaurant A, you retrieve Restaurant A's merchant ID from a lookup table that you maintain for all affiliated restaurants. Call the <a href="ref:post_setaccountlevelmerchantcontrol" target="_blank">Set Account-Level Merchant Control</a> endpoint with these parameters: