Overview

The Velocity Control API provides a way to manage spending allocation and consumption limits at the card level. It is specifically designed for budget cards, where funds are managed through a shared budget and additional spending controls are required.

This guide explains how Velocity Control works for budget cards and how different transactionLimitsType configurations affect available spending limits.

How Available Spending Is Calculated

Available spending represents the remaining spendable amount under the configured limit, rather than the topped-up balance. It is calculated as: Available spending = Configured limit − Net consumption

Configured limit is the amountLimit set via Velocity Control (e.g., DAY / WEEK / MONTH / QUARTER / YEAR / LIFETIME), and net consumption is returned by Get Card Summary. For budget cards, available spending is additionally capped by the remaining budget balance. In some cases, netConsumption may include applicable service fees charged on card activity. These fees (if any) are configured per client and may vary by program and transaction type.

Example: If the limit is USD 500 and netConsumption is USD 120, the card’s available spending is USD 380.

Fund Management Model

For Budget Cards, funds are managed through a budget, which acts as a shared fund pool.

Funds are topped up to the budget, not to individual cards.
All budget cards under the same budget share the total available balance.
Velocity Control is applied per card.
Once the budget balance is exhausted, spending is restricted for all associated cards.

This model is commonly used when multiple cards draw from a centralized fund pool and require configurable spending limits.

Supported transactionLimitsType

1. Periodic Limits

Periodic limits apply when transactionLimitsType is set to DAY, WEEK, MONTH, QUARTER, or YEAR. In this case, spending limits are based on calendar periods rather than rolling windows, meaning the limit applies to the current day, week, month, quarter, or year and is reset at 00:00 (GMT+8) at the start of each corresponding calendar period.

The effective available limit for each period is determined by comparing the configured cyclic limit with the remaining budget balance. If the configured limit exceeds the remaining budget balance, the card's available spending amount is capped at the remaining budget balance. Otherwise, the configured cyclic limit applies.

2. Per-Transaction Limit

The per-transaction limit applies when transactionLimitsType is set to TRANSACTION. This limit controls the maximum amount allowed for a single transaction.

For each authorization request, the configured transaction limit is evaluated against the remaining budget balance. If the configured limit exceeds the remaining budget balance, the per-transaction available amount is restricted to the remaining budget balance. Otherwise, the configured transaction limit applies.

3. Lifetime Limit

The lifetime limit applies when transactionLimitsType is set to LIFETIME and is used to control the total cumulative amount a card can spend over its entire lifecycle.

The effective lifetime spending limit is determined by comparing the configured lifetime limit with the remaining budget balance. If the configured lifetime limit exceeds the remaining budget balance, the available lifetime amount is capped at the remaining budget balance. Otherwise, the configured lifetime limit applies.

4. No Limit

When transactionLimitsType is set to NA, no card-level spending limit is applied. In this case, the card is allowed to spend freely as long as sufficient funds remain in the budget. The remaining budget balance therefore serves as the final and ultimate upper limit on spending.