Velocity limit query - DCS Technical Documentation

📄 Guide

Whether your users are making everyday purchases, paying across borders or withdrawing large amounts, you can look up the velocity limit rules and current usage of any card at any time, and use that to show the available headroom to the cardholder and monitor risk. As a licensed issuer with its own BINs, DCS writes the velocity limit rules onto the card at issuance and accumulates usage in real time for you to query. Velocity limits are a risk control mechanism that caps either the number of transactions or the transaction amount for a single card within a given period. Well-chosen limits help prevent fraud, contain spending risk, and give partners a lever for managing cash flow.

Mental model: one velocity limit rule = three dimensions

A card can carry several velocity limit rules at once, and each rule combines three dimensions:

Transaction type (e.g. R, retail purchase) × Time period (e.g. 4, calendar month) × Cap type (amount maxAmount / count maxCount)

For example, “retail purchase × calendar month × maximum amount of 5,000 USD” is one rule. DCS accumulates usedAmount in real time and derives remainingAmount, then approves or declines authorizations accordingly.

Who does it: velocity limit rules are defined in the card profile and applied automatically by DCS when the card is issued, so partners do not configure them card by card. This endpoint is read-only and cannot change a limit. To adjust the rules, contact the DCS team to update the card profile (see Card profile).

Transaction type (transactionType)

Code	Transaction type
R	Retail purchase
C	Cash withdrawal
I	Standard installment
L	Special-purpose installment
S	Cash installment
Q	Balance inquiry
P	Repayment
A	Proxy authorization

Time period (periodUnit)

Code	Period unit
1	Per-transaction limit
2	Calendar day limit
3	Calendar week limit
4	Calendar month limit
5	Calendar year limit
6	Billing cycle limit
7	Rolling period limit (monthly)

period unit 7 (rolling period limit) appears only in the API field definition, not in the body of the velocity limit guide. Both are documented as they stand; the API response is authoritative.

Query the velocity limits of a card

GET /open-api/card/v1/card-velocity-limits

All date fields on this endpoint are in UTC.

Request parameters

Field	In	Type	Required	Description
`cardId`	query	string	Required	Card ID, returned once the card has been issued. Maximum length 50

Request example

GET /open-api/card/v1/card-velocity-limits?cardId=CARD_xxx

Response

Every response uses the standard envelope { code, message, messageDetail, data }:

code / message: system-level return code and text.
messageDetail: a message you can show to the end user (title / message / type / action / linkUrl and similar), meant for frontend guidance.
data: an array of velocity limit rules, one element per rule.

Fields inside data[]:

Field	Type	Description
`transactionType`	string	Transaction type code (R/C/I/L/S/Q/P/A, see the table above)
`velocityCode`	string	Velocity check code identifying the specific rule
`periodUnit`	string	Period unit code (1-7, see the table above)
`startDate`	string	Start of the accumulation window, `yyyy-MM-dd`, UTC
`endDate`	string	End of the accumulation window, `yyyy-MM-dd`, UTC
`currencyCode`	string	Currency code
`maxAmount`	number	Maximum amount (used by amount-based rules)
`maxCount`	integer	Maximum number of transactions (used by count-based rules)
`usedAmount`	number	Amount already used
`usedCount`	integer	Number of transactions already used
`remainingAmount`	number	Remaining available amount
`remainingCount`	integer	Remaining available transactions

Response example

{
  "code": "SYS_SUCCESS",
  "message": "success",
  "messageDetail": null,
  "data": [
    {
      "transactionType": "R",
      "velocityCode": "R-MONTH-AMT",
      "periodUnit": "4",
      "startDate": "2026-06-01",
      "endDate": "2026-06-30",
      "currencyCode": "USD",
      "maxAmount": 5000,
      "maxCount": null,
      "usedAmount": 1280.50,
      "usedCount": null,
      "remainingAmount": 3719.50,
      "remainingCount": null
    },
    {
      "transactionType": "C",
      "velocityCode": "C-DAY-CNT",
      "periodUnit": "2",
      "startDate": "2026-06-16",
      "endDate": "2026-06-16",
      "currencyCode": "USD",
      "maxAmount": null,
      "maxCount": 3,
      "usedAmount": null,
      "usedCount": 1,
      "remainingAmount": null,
      "remainingCount": 2
    }
  ]
}

The standard envelope is { code, message, messageDetail, data }, and on success code is SYS_SUCCESS.

How to use these fields

Showing available headroom to the cardholder: read remainingAmount for amount-based rules and remainingCount for count-based rules.
Telling which kind of rule you are looking at: a populated maxAmount means an amount cap, a populated maxCount means a count cap. Within one rule only one of the two is normally set, and the other is null.
Reading the accumulation window: startDate and endDate delimit the current window (UTC); usage resets according to the period rule once the window closes.

Next steps

Where the rules are defined and how to change them: see Card profile.
Basic card information and status: see Virtual card and Card management.
The standard response envelope and return codes: see Authentication and security.

​📄 Guide

​Mental model: one velocity limit rule = three dimensions

​Transaction type (transactionType)

​Time period (periodUnit)

​Query the velocity limits of a card

​Request parameters

​Request example

​Response

​Response example

​How to use these fields

​Next steps

📄 Guide

Mental model: one velocity limit rule = three dimensions

Transaction type (transactionType)

Time period (periodUnit)

Query the velocity limits of a card

Request parameters

Request example

Response

Response example

How to use these fields

Next steps