> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thedecard.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 限额查询

> 说明卡片限额规则的三个维度（交易类型、时间周期、金额或次数限制），并提供查询接口和字段说明。

## 📄 正文

无论您的用户是日常消费、跨境支付还是大额提现，您都可以随时查询每张卡当前的限额规则与已使用情况，据此向持卡人展示可用额度、做好风险监控。DCS 作为持牌、自有 BIN 的发卡机构，在发卡时即把限额规则写入卡片，并实时累计用量供您查询。

限额（Velocity Limit）是一种风险控制机制，用于限制单张卡在特定时间段内的**交易次数**或**交易金额**。合理的限额规则可以防止欺诈、控制消费风险，并帮助接入机构管理资金流动。

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

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

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

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

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

### 交易类型（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 |

### 请求示例

```http theme={null}
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 | 剩余可用次数                      |

### 响应示例

```json theme={null}
{
  "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），用量在窗口结束后按周期规则重置。

## 下一步

* 限额规则在哪里定义、如何调整：见 [卡配置](./card-profiles)。
* 查看卡片基础信息与状态：见 [虚拟卡](./virtual-card) 与 [卡管理](./card-management)。
* 统一响应结构与返回码：见 [鉴权指南](../../integration-resources/authentication)。