Setting Account-Level Authorization Controls

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

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

Result of following these procedures

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

General ALC characteristics

These are the general characteristics of ALCs:

  • Because ALCs are set at the account level, not the card level, the controls apply to all cards that are associated with the same PRN.
  • 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.

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:

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 Set Account-Level Auth Control 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.

Effective timespanstartDateendDate
Start now, no endblankblank
Start now, end in seven daysblank2022-03-17 23:59:59
Next week only, starting Monday2022-03-13 00:00:002022-03-19 23:59:59
Start next Monday, no end2022-03-13 00:00:00blank
End now (disable the control)blank2022-03-10 13:00:00

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 Velocity controls 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 GCC and CST, or you can call Get Auth Control with these parameters:

  • controlId: blank
  • prodId: Product ID
  • accountNo: blank

Open the Recipes below to see example responses. Consult the Get Auth Control reference material for the response schema.

Galileo recommends that you call Get Auth Control 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

To set an account-level velocity control, follow these steps:

  1. Obtain the control ID by calling Get Auth Control or by consulting your lookup table.
  2. Call Set Account-Level Auth Control with these parameters:
ParameterValue
accountNoPRN of the account. Do not use PAN or CAD
controlIdIdentifier for the control to set.
startDateLeave blank to the current system time as the starting time, or set a time up to six months in the future.
endDateLeave blank to set 3000-01-01 (no end) as the end date, or specify a date that is later than startDate.
amountPass a maximum amount for the control or leave blank to set no amount limit. If this parameter is blank, then transactionCount must be populated.
transactionCountPass a maximum number of transactions per control period or leave blank to set no transaction count limit. If this parameter is blank, then amount must be populated.

Given the example controls in the Recipe above, this table shows how you would populate the parameters in the Set Account-Level Auth Control 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.

New limitcontrolIdstartDateendDateamounttransactionCount
Daily domestic ATM withdrawal limit increased to $800 and count increased to 20. Starts now and does not end.1blankblank80020
Daily international ATM transaction count increased to 25. Starts next week and ends one week after that.22022-03-17 00:00:002022-03-24 23:59:5930025
Per-transaction ATM limit increased to $400, starting now and ending in an hour.3blank2022-03-10 14:00:00400blank

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 Get Auth Control with these parameters:

  • accountNo: PAN of the account
  • prodId: blank

Open the Recipe below to see an example response. Consult the Get Auth Control reference material for the response schema.

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 Set Account-Level Auth Control 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

You cannot delete an existing ALC instead, you expire it to disable 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 Set Account-Level Auth Control 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

MCC controls

It is not necessary to set product-level 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 MCC controls 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 GCC and the CST, and you can also retrieve the product-level MCC controls by calling the Get MCC Controls endpoint with these parameters:

  • accountNo: blank
  • prodId: Product ID

Open the Recipes below to see sample responses.

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

Setting MCC ALCs

Verify that the control you intend to create does not violate any of the MCC control conventions. If it does violate a convention, the endpoint will return an error.

To set an account-level control, call the Set Account-Level MCC Control endpoint with these parameters:

ParameterValue
accountNoPRN of the account. Do not use the PAN or CAD.
startDateLeave blank to set the current date-time as the starting time, or set a time up to six months in the future. Must be earlier than endDate. Cannot be earlier than the current time.
endDateLeave blank to set 3000-01-01 (no end) as the end date, or specify a time that is later than startDate.
begMccBeginning MCC of the range.
endMccEnding MCC of the range. To specify only one MCC for the control, leave this parameter blank or pass the same value as begMcc.
allowDenyPass a for ALLOW or d for DENY.
onlineOnlyPass Y to apply this control only to online transactions or leave blank (or pass N) to apply to all transactions.

To set another MCC range, call Set Account-Level MCC Controls again, while ensuring that the range does not overlap other MCC controls and that the ALLOW or DENY property is the same.

Updating account-level MCC controls

If you already have an account-level control for MCC 2000–2999, for example, and you want to expand the range to MCC 2000–3500, you have two options:

  • Update the control by setting endMcc to 3500
  • Create a second control for MCC 3000–3500

In the Galileo tables that contain account-level MCCs, each control occupies a separate row, and the row is identified by the begMcc value. (In database terms, it's the primary key.) A primary key cannot occur more than once in a table per product ID, and so it is not possible to use the API to change the begMcc value for a control. Instead, you must request that Galileo delete the control so that you can set a new one with a different begMcc value.

Likewise, if you decide to expire a control and create a new one, the begMcc value of the new control cannot be the same as the begMcc of an active or expired control unless you ask Galileo to make the adjustment. For example, if you create a control for MCC 5000–5500 and then you expire (deactivate) it, you cannot create another control with begMcc: 5000. However, if you want to create a control for MCC 5000-5100, you can set endMcc: 5100 and reactivate the control.

Update an existing MCC control

When updating an MCC 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.

To update the values in an existing, unexpired control, call the Set Account-Level MCC Control 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.
  • begMcc: Pass the same value that the existing control has. Do not pass a new value. As needed, call Get MCC Controls to retrieve the value.
  • endMcc: Leave blank to maintain the same value or pass a new MCC.
  • allowDeny: Leave blank. This value cannot be changed.
  • onlineOnly: Leave blank to maintain the same value or pass Y or N to change it.

Disable an account-level MCC control

You cannot delete an existing MCC control; instead, you expire it to disable 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 Set Account-Level MCC Control endpoint with these parameters:

  • accountNo: PRN of the account
  • startDate: Pass the current time or pass a future date no more than six months in the future.
  • endDate: Pass a time that is later than startDate.
  • begMcc: Pass the same value that the control had originally. As needed, call Get MCC Controls to retrieve the value.
  • endMcc: Leave blank.
  • allowDeny: Leave blank.
  • onlineOnly: Leave blank or pass a new value.

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 Merchant ID controls 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 GCC and CST, and you can retrieve them by calling the Get Merchant Controls 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.

Setting account-level merchant ID controls

To set an account-level merchant ID control, call Set Account-Level Merchant Control with these parameters:

ParameterValue
accountNoPRN of the account. Do not use PAN or CAD.
startDateLeave blank to set the current date-time as the starting time, or set a time in the future. Cannot be more than six months in the future. Must be earlier than endDate.
endDateLeave blank to set 3000-01-01 (no end) as the end date, or specify a date that is later than startDate.
merchantIdMerchant ID. Max 15 characters. Not case-sensitive.
allowDenyPass a for ALLOW or d for DENY.

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.

Update 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 Set Account-Level Merchant Control 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 Get Merchant Controls 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 existing, active MID control, 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 Set Account-Level Merchant Control 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 Get Merchant Controls to get the ID.
  • allowDeny: Leave blank or pass a new value to change it.

Use cases

These use cases are examples of how to set the ALCs in the Use cases section in About Account-Level Authorization Controls. All examples assume that today is March 10, 2022 at 1:00 pm in Galileo system time.

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 Set Account-Level Auth Control, 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).

ParameterValue
controlId1
startDateblank
endDateblank
amount3000
transactionCount20

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 Set Account-Level Auth Control with these parameters:

ParameterValue
controlId2
startDate2022-03-20 00:00:00
endDate2022-03-26 23:59:59
amount800
transactionCount20

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 Set Account-Level Auth Control with these parameters:

ParameterValue
controlId5
startDateblank
endDateblank
amount3000
transactionCount7

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 Set Account-Level Auth Control with these parameters.

ParameterValue
controlId1
startDateblank
endDate2022-03-10 13:30:00
amountblank
transactionCount4

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 Set Account-Level MCC Control endpoint with these parameters to allow the card to be used at hotels.

ParameterValue
accountNoPRN
startDateblank
endDateblank
begMcc3500
endMcc3900
allowDenya
onlineOnlyblank

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 Set Account-Level Merchant Control endpoint with these parameters:

ParameterValue
accountNoPRN
startDateblank
endDate2022-03-10 14:00:00
merchantId0002454MRAC0001
allowDenya

Did this page help you?