限额查询 - DCS Technical Documentation

📄 正文

无论您的用户是日常消费、跨境支付还是大额提现，您都可以随时查询每张卡当前的限额规则与已使用情况，据此向持卡人展示可用额度、做好风险监控。DCS 作为持牌、自有 BIN 的发卡机构，在发卡时即把限额规则写入卡片，并实时累计用量供您查询。限额（Velocity Limit）是一种风险控制机制，用于限制单张卡在特定时间段内的交易次数或交易金额。合理的限额规则可以防止欺诈、控制消费风险，并帮助接入机构管理资金流动。

核心概念：一条限额规则包含三个维度

每张卡可以同时挂多条限额规则，每条规则由三个维度组合而成：

交易类型（如 R 普通消费） × 时间周期（如 4 自然月） × 限制类型（金额 maxAmount / 次数 maxCount）

举例：「普通消费交易 × 自然月 × 最大金额 5000 USD」就是一条规则；DCS 实时累计 usedAmount（已用）并算出 remainingAmount（剩余），授权时据此放行或拒绝。

谁做：限额规则在卡配置（Card Profile）中定义，由 DCS 在卡片发行时自动应用——接入机构无需逐卡设置。本接口为只读查询，不提供改额能力。如需调整限额规则，请联系 DCS 团队调整卡配置（见卡配置）。

交易类型（transactionType）

代码	交易类型
R	普通消费交易
C	取现交易
I	普通分期
L	专项分期
S	现金分期
Q	查询交易
P	还款交易
A	代授权交易

时间周期（periodUnit）

代码	周期单位
1	单笔交易限额
2	自然日限额
3	自然周限额
4	自然月限额
5	自然年限额
6	账单周期限额
7	滚动周期限额（月）

注：周期单位 7 为滚动月周期，较少使用。

查询卡限额列表

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

本接口所有日期字段均为 UTC 时间。

请求参数

字段	位置	类型	必填	说明
`cardId`	query	string	必填	卡 ID（开卡完成后获得）。最大长度 50

请求示例

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

响应

统一响应结构为 { code, message, messageDetail, data }：

code / message：系统级返回码与文案。
messageDetail：面向终端用户的可展示提示（title / message / type / action / linkUrl 等），用于前端引导。
data：限额规则数组，每个元素为一条规则。

data[] 字段：

字段	类型	说明
`transactionType`	string	交易类型代码（见上表 R/C/I/L/S/Q/P/A）
`velocityCode`	string	限额规则码（标识具体限额规则）
`periodUnit`	string	周期单位代码（见上表 1–7）
`startDate`	string	统计起始日期，`yyyy-MM-dd`，UTC
`endDate`	string	统计结束日期，`yyyy-MM-dd`，UTC
`currencyCode`	string	币种代码
`maxAmount`	number	最大限额（金额维度规则使用）
`maxCount`	integer	最大限次（次数维度规则使用）
`usedAmount`	number	已使用金额
`usedCount`	integer	已使用次数
`remainingAmount`	number	剩余可用金额
`remainingCount`	integer	剩余可用次数

响应示例

{
  "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
    }
  ]
}

响应统一结构为 { code, message, messageDetail, data }，成功时 code 为 SYS_SUCCESS。

怎么用这些字段

向持卡人展示可用额度：金额维度看 remainingAmount，次数维度看 remainingCount。
判断某条规则的类型：maxAmount 有值即为金额限额，maxCount 有值即为次数限额（同一条规则二者通常只填其一，另一为 null）。
理解统计窗口：startDate / endDate 是当前周期的统计窗口（UTC），用量在窗口结束后按周期规则重置。

下一步

限额规则在哪里定义、如何调整：见卡配置。
查看卡片基础信息与状态：见虚拟卡与卡管理。
统一响应结构与返回码：见鉴权指南。

​📄 正文

​核心概念：一条限额规则包含三个维度

​交易类型（transactionType）

​时间周期（periodUnit）

​查询卡限额列表

​请求参数

​请求示例

​响应

​响应示例

​怎么用这些字段

​下一步