Set Velocity Controls

This guide explains how to set and manage velocity account-level controls (ALCs) using these endpoints:

• Get Auth Control
• Set Account-Level Auth Control
• Delete Account-Level Auth Control

Result of following this procedure

This procedure includes instructions for achieving these results:

• Retrieval of product-level controls
• Retrieval of ALCs
• Creation of an ALC
  • With and without MCCs
  • With and without time constraints
• Modification of an ALC
• Disabling of an ALC
• Deletion of an ALC

Product-level 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. Consult Velocity Control Design to see how velocity controls are represented in the Galileo system and to review guidelines on how to create velocity ALCs.

Product-level velocity 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 Recipe below to see an example response. Consult the Get Auth Control response schema for field descriptions.

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.

Retrieving velocity limits

Consult this table to see how to use the Get Auth Control endpoint to retrieve different limits. When retrieving account-level controls, the endpoint also returns the current usage and available balance for amount and transaction count.

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 to use the Program API:

1. Obtain the product-level control ID by calling Get Auth Control with prodId populated or by consulting your lookup table.
2. Call Set Account-Level Auth Control with these parameters:

🚧

Warning

When you set MCCs for velocity ALCs, the MCCs must be allowed by both the product-level and account-level MCC controls. If you attempt to create an ALC with MCCs that are not allowed, the endpoint returns status_code: 599-08.

The MCCs for a velocity ALC must also not overlap existing velocity ALCs. If you attempt to create an overlapping velocity MCC control, the endpoint returns status_code: 599-07.

Given the example controls in Product-level velocity controls in Velocity Control Design (and also in the Recipe above), this table shows how you would populate the parameters in the Set Account-Level Auth Control endpoint calls to create the ALCs shown in the ALCs and timespans section of that same guide, assuming that today is March 10, 2024 at 1:00 pm.

Control ID 1

Daily domestic ATM withdrawal limit increased to $1000 and count reduced to 6. Starts now and does not end.

• controlId: 1
• startDate: blank
• endDate: blank
• amount: 1000
• transactionCount: 6

Control ID 2

Daily international ATM amount raised to 600 and transaction count increased to 24. Starts next week and ends one week after that.

• accountNo: PRN
• controlId: 2
• startDate: 2024-03-17 00:00:00
• endDate: 2024-03-24 23:59:59
• amount: 600
• transactionCount: 24

Control ID 3

Per-transaction ATM limit increased to $500, starting now and ending in an hour.

• accountNo: PRN
• controlId: 3
• startDate: blank
• endDate: 2024-03-10 14:00:00
• amount: 300
• transactionCount: 3

Control ID 4

Create three versions of Control ID 4, starting now and not expiring:

• Without MCCs, amount 2000 and transaction count 24
• MCC range 5541–5542, amount 300 and transaction count 10
• MCC range 3000–3299, amount 1500 and transaction count 1

Control ID 5

Create two versions of Control ID 5:

• Without MCCs, same amount but add a 40 transaction count, starting now and ending on Mar 31
• MCCs 5812–5814, amount 1000 but no transaction count, starting now but no expiry

ALC results

Open this Recipe to see the ALCs that would be created by following the steps above and then calling Get Auth Control with only the accountNo populated:

Updating velocity ALCs

To update an existing account-level velocity control, follow these rules when populating Set Account-Level Auth Control:

• Positive value — Set the control to this value
• Blank — Do not change the value
• Null — Nullify the existing value
  • Null nullifies startDate and endDate only when creating the ALC for the first time or when reactivating an ALC that has expired (including when it was manually disabled). Otherwise, passing Null does not change the existing value.

Get existing ALCs

To see all of the ALCs that are already set for an account, call Get Auth Control with these parameters:

• accountNo: PRN of the account
• prodId: blank

To retrieve specific ALCs, set these parameters:

• accountNo: PRN of the account
• prodId: blank
• controlId: Control ID to retrieve.
• beginningMcc: First MCC in the range of the control to retrieve, or leave blank to retrieve all ALCs with the specified control ID.
• endMcc: Last MCC in the range of the control to retrieve. If beginningMcc is populated then this parameter is required. If beginningMcc is not populated, then do not populate this parameter.

👍

Tip

If you have multiple control IDs with the same MCC range, you can specify only the MCC range to retrieve all controls with that range.

Change the amount

To change the amount on Control ID 1 to 1200 without changing the transaction count, populate Set Account-Level Auth Control like this:

• accountNo: PRN of the account
• controlId: 1
• amount: 1200
• transactionCount: 6 or leave blank
• mccControls: blank

Change the transaction count

To change the transaction count for Control ID 2 to 12 without changing the amount, pass these values:

• accountNo: PRN
• controlId: 2
• amount: 600 or leave blank
• transactionCount: 12

Change the timespan

To change the timespan on Control ID 4 (for gas stations) to expire on Mar 17, pass these values:

• accountNo: PRN
• controlId: 4
• beginningMcc: 5541
• endMcc: 5542
• startTime: blank
• endTime: 2024-03-17 00:00:00

Consult Setting time limits in Setting ALCs for details on timespan modification.

Change the MCC range

You can modify only the ending MCC of an MCC range. For example, if you create an ALC with Control ID 2 and the range MCC 6010-6010, you can change the second MCC to 6012 by passing these values in the Set Account-Level Auth Control call:

• accountNo: PRN
• controlId: 2
• mccControls: 6010-6012

If the existing ALC had the range 6012-6012 and you wanted to change it to 6010-6012, you would have to delete the existing control and create a new one with mccControls: 6010-6012.

If you have an existing ALC with no MCC range, and you add an MCC range in the Set Account-Level Auth Control request, you will end up with two ALCs for that control ID: one with the MCCs and one without. As desired, you can delete the old ALC.

You cannot remove an MCC range by passing Null for mccControls. If you want to remove the MCC range from an ALC, you have to create a new ALC without MCC controls and then delete the control with the MCC range.

Change multiple ALCs

If you have multiple ALCs with different control IDs but the same MCC range, you can change all of those ALCs with one endpoint request.

For example, you have these ALCs:

You could set the same amount, transaction count, start date, or end date for all of these ALCs in the same request. If you wanted to expire all of these controls on May 10, for example, you would pass these values with Set Account-Level Auth Control:

• accountNo: PRN
• controlID: blank
• amount: blank
• transactionCount: blank
• startDate: blank
• endDate: 2024-05-10
• mccControls: 2000-2020

Delete one limit of a velocity ALC

To delete either amount or transactionCount of 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.

To remove the transaction count for ALC Control ID 1, pass these values:

• controlId: 1
• startDate: blank
• endDate: blank
• amount: blank
• transactionCount: Null

Disable a velocity ALC

To disable a velocity ALC without deleting it, call Set Account-Level Auth Control and populate the current date-time in endDate. When a velocity ALC has been disabled, the control reverts back to the product-level values, provided that there are no more ALCs with the same control ID.

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
• controlId: Control ID
• 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
• beginningMcc: First MCC in the range of the control to reactivate, if any
• endMcc: Last MCC in the range of the control to reactivate, if any

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
• beginningMcc: First MCC in the range of the control to delete, if any
• endMcc: Last MCC in the range of the control to delete. If beginningMcc is populated then this parameter is required. If beginningMcc is not populated, then do not populate this parameter.

Inputting multiple values

For the mccControls parameter in Set Account-Level Auth Control, you can input multiple MCCs or MCC ranges.

You have two options to input multiple values: repeat the parameter or use a JSON list. Each option requires a different Content-Type header.

Repeated parameter

For this method, specify Content-Type: application/x-www-form-urlencoded in the header. In the body of the request, pass one parameter/value pair for each value. For example:

POST /intserv/4.0/[endpoint] HTTP/1.1
Host: [URL]
response-content-type: json
Content-Type: application/x-www-form-urlencoded
Content-Length: 174

apiLogin=[redacted]&apiTransKey=[redacted]&providerId=19&transactionId=45d7ecbd-3e53-4a69-8971-af3bbaf17956&groupId=1001&param1=777777777777&param1=888888888888

JSON list

For this method, specify Content-Type: application/json in the header. In the body of the request, specify the values as a JSON list. For example:

POST /intserv/4.0/[endpoint] HTTP/1.1
Host: [URL]
response-content-type: json
Content-Type: application/json
Content-Length: 179

{
    "apiLogin": [redacted],
    "apiTransKey": [redacted],
    "providerId": "19",
    "transactionId": "d3914a0b-ce55-4d95-9926-2c8f3a3a9f10",
    "param1": ["1", "2", "5"]
}

In your ALC table, the Galileo system will create one control for each MCC range in mccControls, so for example if you pass the following values, the result is three separate ALCs:

• accountNo: PRN
• controlId: 7
• amount: 500
• mccControls: ['2222, '3000-3299', '5500-5550'],

Notice that all of the properties are identical except the MCC columns, because you called Set Account-Level Auth Control only one time. As desired, you can update any of the controls separately to change the amount or transaction count.