Setting Account-Level Authorization Controls

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

• Velocity ALCs
  • Get Auth Control
  • Set Account-Level Auth Control
  • Delete Account-Level Auth Control
• MCC ALCs
  • Get MCC Controls
  • Set Account-Level MCC Controls
  • Delete Account-Level MCC Control
• Merchant ID ALCs
  • Get Merchant Controls
  • Set Account-Level Merchant Control
  • Delete Account-Level Merchant Control

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:

• 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 Galileo system time
• 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 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.

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

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

• In the CST, under Account Info.
• With the Program API. 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:

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.

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

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 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 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: 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 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:

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 Set Account-Level MCC Controls 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 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 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 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 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 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:

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 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 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).

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:

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:

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.

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.

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: