查询卡账户额度
GET/openapi/v2/cards/account-limits| 项 | 内容 |
|---|---|
| 请求方法 | GET |
| 请求路径 | /openapi/v2/cards/account-limits |
| 请求类型 | query |
查询当前租户内某张卡所属卡账户的额度。它与 查询卡余额 的资金余额含义不同,不能相加或互相替代。
沿用 V2 加签说明 和 公共响应。是否支持额度查询取决于卡产品能力;不支持时本接口返回错误,不使用资金余额代替额度。
请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
cardId | string | 是 | 当前租户内的平台注册卡 ID,最大 128 个字符;不是完整卡号。 |
仅需传入卡 ID,不传入用户、租户或服务方账户标识。
http
GET /openapi/v2/cards/account-limits?cardId=DEMO-CARD-001响应 data
| 字段 | 类型 | 说明 |
|---|---|---|
cardId | string | 请求的卡 ID。 |
fpCardAccountId | string | 该卡所属的平台卡账户标识;同一账户的不同卡可能返回同一份额度。 |
currency | string | 额度币种。 |
accountType | string | asset-link、fixed-limit、program-limit 或 prepaid。 |
totalLimit | string/null | 账户总额度;prepaid 模式可能为 null。 |
usedLimit | string/null | 当前净占用,非历史累计消费;prepaid 模式可能为 null。 |
availableLimit | string | 返回的账户可用金额,不由调用方按总额度减占用额推算。 |
金额均为非科学计数法十进制字符串,不是 JSON 数字,且不保证保留末尾零。允许真实零金额 "0";null 表示对应值不可提供,不能按零展示或计算。
accountType
| 值 | 含义 |
|---|---|
asset-link | 资产关联型额度。 |
fixed-limit | 固定额度。 |
program-limit | 计划额度模式,还可能受计划级额度等额外限制。 |
prepaid | 预付模式,总额度及当前净占用可能为空。 |
同一用户的不同卡可能属于不同卡账户,应按 fpCardAccountId 识别额度归属,不能将用户全部卡视为共用额度。退款、还款等可能改变 usedLimit,因此它不能当作累计消费额。
availableLimit 不保证后续支付一定成功,交易仍受卡状态和产品限制等条件影响。
响应示例
以下数据均为模拟。
json
{
"code": 200,
"msg": "操作成功",
"data": {
"cardId": "DEMO-CARD-001",
"fpCardAccountId": "DEMO-CA-001",
"currency": "USD",
"accountType": "asset-link",
"totalLimit": "100",
"usedLimit": "20",
"availableLimit": "80"
}
}prepaid 模式下,totalLimit 和 usedLimit 可明确返回 null,availableLimit 仍以实际查询值返回。
失败处理
- 卡不存在或不属于当前租户、产品不支持查询、查询失败、账户归属或数据无法确认时,沿用公共错误响应;不返回伪造额度。
- 本接口只查询额度,不修改卡状态、账户归属或资金。
- 本接口整体失败时不会返回成功的
data额度对象。若需要在单项失败时仍取得卡列表,使用 查询用户持卡概览;其cardAccounts[]会分别标记FAILED或UNSUPPORTED。
