Setting Account-Level Authorization Controls
This guide explains how to implement account-level authorization controls (ALCs) using these endpoints:
- Velocity ALCs
- MCC ALCs
- Merchant ID ALCs
This guide assumes that you are familiar with the concepts in these guides:
- About Account-Level Auth Controls — General explanation of ALCs, including use cases.
- Designing Authorization Controls — How to design authorization controls at the product and account levels.
- MCC and Merchant ID ALC Examples — 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:
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 thebal_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 Galileo system timeendDate:
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 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
orendDate
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 timespan | startDate | endDate |
---|---|---|
Start now, no end | blank | blank |
Start now, end in seven days | blank | 2022-03-17 23:59:59 |
Next week only, starting Monday | 2022-03-13 00:00:00 | 2022-03-19 23:59:59 |
Start next Monday, no end | 2022-03-13 00:00:00 | blank |
End now (disable the control) | blank | 2022-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:
blankprodId:
Product IDaccountNo:
blank
Open the Recipe below to see an example response. 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
You can set a velocity ALC in one of two ways:
- In the CST, under Account Info.
- With the Program API. Follow these steps:
- Obtain the control ID by calling Get Auth Control or by consulting your lookup table.
- Call Set Account-Level Auth Control with these parameters:
Parameter | Value |
---|---|
accountNo | PRN of the account. Do not use PAN or CAD |
controlId | Identifier for the control to set. |
startDate | Leave blank to the current system time as the starting time, or set a time up to six months in the future. |
endDate | Leave blank to set 3000-01-01 (no end) as the end date, or specify a date that is later than startDate . |
amount | Pass a maximum amount for the control or leave blank to set no amount limit. If this parameter is blank, then transactionCount must be populated. |
transactionCount | Pass 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 limit | controlId | startDate | endDate | amount | transactionCount |
---|---|---|---|---|---|
Daily domestic ATM withdrawal limit increased to $800 and count increased to 20. Starts now and does not end. | 1 | blank | blank | 800 | 20 |
Daily international ATM transaction count increased to 25. Starts next week and ends one week after that. | 2 | 2022-03-17 00:00:00 | 2022-03-24 23:59:59 | 300 | 25 |
Per-transaction ATM limit increased to $400, starting now and ending in an hour. | 3 | blank | 2022-03-10 14:00:00 | 400 | blank |
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 accountprodId:
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:
blankendDate:
blankamount: 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:
blankendDate:
blankamount:
blanktransactionCount: 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 Set Account-Level Auth Control endpoint with these parameters:
accountNo:
PRN of the accountstartDate:
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 thanstartDate
.amount
: Leave blanktransactionCount:
Leave blank
Deleting a velocity ALC
To delete a velocity ALC from the database, call Delete Account-Level Auth Control 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 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:
blankprodId:
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 controls you intend to create do not violate any of the MCC control conventions. If they do violate a convention, the endpoint will return an error.
To set one or more account-level controls, call the Set Account-Level MCC Controls endpoint with these parameters:
Parameter | Value |
---|---|
accountNo | PRN of the account. Do not use the PAN or CAD. |
startDate | Leave 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. |
endDate | Leave blank to set 3000-01-01 (no end) as the end date, or specify a time that is later than startDate . |
mccControls | A list of MCC ranges or single MCCs. Format: ['XXXX', 'YYYY-ZZZZ', 'AAAA-BBBB'] |
allowDeny | Pass a for ALLOW or d for DENY. |
onlineOnly | Pass Y to apply this control only to online transactions or leave blank (or pass N ) to apply to all transactions. |
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:
beginning_mcc | end_mcc |
---|---|
2000 | 2000 |
3000 | 3500 |
3580 | 4000 |
5555 | 5555 |
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 Set Account-Level MCC Controls endpoint with these parameters:
accountNo:
PRN of the accountstartDate:
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 passY
orN
to change it.
For example, to change the online-only property of the first and third controls in the table above to Y
, call Set Account-Level MCC Controls 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 Set Account-Level MCC Controls endpoint with these parameters:
accountNo:
PRN of the accountstartDate:
Pass the current time or a future date no more than six months in the future.endDate:
Pass a time that is later thanstartDate
.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 Delete Account-Level MCC Control with these parameters:
accountNo:
PRN of the account. Do not use PAN or CAD.beginMccControl:
First number in the MCC rangeendMccControl:
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 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:
Parameter | Value |
---|---|
accountNo | PRN of the account. Do not use PAN or CAD. |
startDate | Leave 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 . |
endDate | Leave blank to set 3000-01-01 (no end) as the end date, or specify a date that is later than startDate . |
merchantId | Merchant ID. Max 15 characters. Not case-sensitive. |
allowDeny | Pass 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.
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 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 thanstartDate
.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 passa
for ALLOW ord
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 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.
Deleting an account-level MID control
To delete an MID control from the database, call Delete Account-Level Merchant Control 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 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).
Parameter | Value |
---|---|
controlId | 1 |
startDate | blank |
endDate | blank |
amount | 3000 |
transactionCount | 20 |
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:
Parameter | Value |
---|---|
controlId | 2 |
startDate | 2022-03-20 00:00:00 |
endDate | 2022-03-26 23:59:59 |
amount | 800 |
transactionCount | 20 |
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:
Parameter | Value |
---|---|
controlId | 5 |
startDate | blank |
endDate | blank |
amount | 3000 |
transactionCount | 7 |
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.
Parameter | Value |
---|---|
controlId | 1 |
startDate | blank |
endDate | 2022-03-10 13:30:00 |
amount | blank |
transactionCount | 4 |
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 Controls endpoint with these parameters to allow the card to be used at hotels.
Parameter | Value |
---|---|
accountNo | PRN |
startDate | blank |
endDate | blank |
mccControls | 3500-3900 |
allowDeny | a |
onlineOnly | blank |
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:
Parameter | Value |
---|---|
accountNo | PRN |
startDate | blank |
endDate | 2022-03-10 14:00:00 |
merchantId | 0002454MRAC0001 |
allowDeny | a |
Updated 12 days ago