Overview

The Velocity Control API provides a unified way to manage user funds, spending allocation, and consumption limits across different card and account structures. It is suitable for platforms that require fine-grained spending control at the individual card level and support both independently funded cards and shared fund pool models.

This guide explains how Velocity Control works under different card funding structures and how various transactionLimitsType configurations affect available spending limits.

1. Prepaid Card

Fund Management Model

For Prepaid Cards, funds are maintained at the individual card level.

Each prepaid card has its own balance.
Funds must be topped up to the card before spending.
The card can only spend the amount that has been loaded.
Velocity Control is applied per card.
The maximum spending amount cannot exceed the card balance.

This model is typically used when each card independently manages its own funds.

Supported transactionLimitsType

transactionLimitsType	Description
DAY	Daily spending limit, resets on a daily cycle
WEEK	Weekly spending limit, resets every week
MONTH	Monthly spending limit, resets every month
QUARTER	Quarterly spending limit, resets every quarter
YEAR	Yearly spending limit, resets every year
TRANSACTION	Per-transaction spending limit
LIFETIME	Lifetime cumulative spending limit for the card
NA	No spending limit applied

2. Budget Card

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.

Supported transactionLimitsType

2.1 Periodic Limits

Periodic limits apply when transactionLimitsType is set to DAY, WEEK, MONTH, QUARTER, or YEAR. In this case, a spending limit is enforced on the card and resets on the corresponding cycle.

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

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

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