查询用户持卡概览
GET/openapi/v2/cards/overview一次返回当前租户内某一用户的全部已持卡记录。共享卡按“资金账户 → 卡账户额度 → 产品 → 卡片”嵌套;独立余额卡平铺自身资料、余额与关联账户额度。不分页、不按卡状态筛选,锁定、注销等已有卡记录仍计入数量,仅返回已持卡产品。
沿用 V2 加签说明 和 公共响应。租户由当前凭证确定,不接受调用方传入租户或渠道账户。原卡列表、卡余额及独立账户额度接口保持原有契约。
请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
memberId | string | 条件必填 | 平台成员 ID,最大 64 个字符;与 email 必须且只能填写一个。 |
email | string | 条件必填 | 当前租户用户邮箱,最大 128 个字符;与 memberId 必须且只能填写一个。 |
不提供分页或状态筛选参数。
GET /openapi/v2/cards/overview?memberId=DEMO-MB-101
GET /openapi/v2/cards/overview?email=user@example.com响应 data
| 字段 | 类型 | 说明 |
|---|---|---|
memberId | string | 平台成员 ID。 |
totalCardCount | integer | 共享卡和独立余额卡的全量数量,每张卡只计一次。 |
sharedAccounts | array | 共享资金账户,包含余额及关联卡账户、产品和卡片。 |
individualCards | array | 独立余额卡,各自直接携带 balanceQuery 和 limitsQuery。 |
用户存在但没有卡时,totalCardCount=0,两个数组均为 [];用户不存在时返回业务错误。
sharedAccounts:共享资金账户
| 字段 | 类型 | 说明 |
|---|---|---|
sharedAccountId | string | 稳定的平台共享资金账户标识,不是渠道账户 ID;作为不透明字符串使用。 |
balanceQuery | object | 共享资金余额查询结果。 |
cardAccounts | array | 该资金账户关联的卡账户,各自包含额度和产品。 |
同一共享资金余额只出现一次。不同租户、用户和服务方的资金分别关联;同一份资金可能关联多个卡账户和产品。
cardAccounts:关联卡账户
位于 sharedAccounts[].cardAccounts[],不是顶层集合。
| 字段 | 类型 | 说明 |
|---|---|---|
fpCardAccountId | string/null | 平台卡账户标识,尚未识别时明确为 null。 |
limitsQuery | object | 该卡账户的额度查询结果。 |
products | array | 属于该卡账户的已持卡产品及卡片。 |
未知账户按卡分别保留,不因为标识均为空而合并。额度属于卡账户,概览不返回本次用于查询额度的取证 cardId。共享资金账户标识与卡账户标识不可互换。
products:卡账户内的产品
位于 sharedAccounts[].cardAccounts[].products[]。
| 字段 | 类型 | 说明 |
|---|---|---|
cardTypeId | string | 平台卡产品 ID。 |
displayName | string/null | 产品展示名称。 |
cardImageUrl | string/null | 产品卡面图片地址。 |
cardCount | integer | 该卡账户、该产品下的卡数量,与 cards.length 一致。 |
cards | array | 该账户、该产品下的全部卡片。 |
同一产品的卡可能属于不同卡账户,因此同一产品可以在不同账户下出现;卡片不会重复出现在多个分组。
卡片资料
共享卡位于 sharedAccounts[].cardAccounts[].products[].cards[]。
| 字段 | 类型 | 说明 |
|---|---|---|
cardId | string | 平台卡 ID,继续用于原有详情、锁卡等接口。 |
cardTypeId | string | 平台卡产品 ID。 |
cardName | string | 卡展示名称。 |
cardImageUrl | string/null | 卡面图片地址。 |
status | string/null | 平台卡状态,语义见查询卡详情。 |
network | string/null | 卡组织,例如 VISA。 |
cardType | string/null | 卡类型,例如 VIRTUAL。 |
last4 | string/null | 卡号后四位,不包含完整卡号。 |
共享卡资料不重复返回所属账户标识、余额或额度,直接读取上层账户。
individualCards:独立余额卡
包含以上所有卡片资料字段,并增加:
| 字段 | 类型 | 说明 |
|---|---|---|
balanceMode | string | 固定为 INDIVIDUAL。 |
fpCardAccountId | string/null | 关联的平台卡账户标识,尚未识别时为 null。 |
balanceQuery | object | 本卡余额查询结果。 |
limitsQuery | object | 关联卡账户额度查询结果;不支持时明确标注。 |
balanceQuery:资金余额查询结果
| 字段 | 类型 | 说明 |
|---|---|---|
status | string | SUCCESS 或 FAILED。 |
balance | object/null | 成功时为单币种余额;失败时明确为 null。 |
balance.currency | string | 按卡产品币种选取的余额币种,不执行换汇。 |
balance.available | string | 可用余额。 |
balance.ledger | string | 账面余额。 |
errorCode | string/null | 成功为 null;失败为下文所列错误码。 |
queriedAt | string | 查询完成或失败时间,ISO 8601 格式。 |
limitsQuery:账户额度查询结果
共享卡账户和独立余额卡使用相同结构。
| 字段 | 类型 | 说明 |
|---|---|---|
status | string | SUCCESS、FAILED 或 UNSUPPORTED。 |
accountLimits | object/null | 成功时为下表额度对象;失败或不支持时为 null。 |
errorCode | string/null | 成功为 null;其他情况为下文所列错误码。 |
queriedAt | string/null | 查询完成或失败时间;UNSUPPORTED 时为 null。 |
| accountLimits 字段 | 类型 | 说明 |
|---|---|---|
currency | string | 额度币种。 |
accountType | string | asset-link、fixed-limit、program-limit 或 prepaid。 |
totalLimit | string/null | 账户总额度,prepaid 可能为 null。 |
usedLimit | string/null | 当前净占用,不是累计消费或冻结金额;prepaid 可能为 null。 |
availableLimit | string | 渠道返回的账户可用额度,不自行用总额度减占用计算。 |
以上金额含义与查询卡账户额度一致,但概览额度对象不重复返回该独立接口中的 cardId、fpCardAccountId。
所有金额为非科学计数法十进制字符串,允许真实零 "0",不保证保留末尾零。未知金额不得当作零。资金余额与卡账户额度不相加、不互相替代;不根据余额差推算冻结。不同查询有各自时间,响应不是同一时刻的原子快照。
部分失败与错误码
单项余额或额度查询失败时,账户、产品和卡片仍保留,不使用零金额替代失败结果。
| errorCode | 所在结果 | 说明 |
|---|---|---|
BALANCE_QUERY_FAILED | balanceQuery | 余额查询失败,或币种、数据、归属无法确认。 |
BALANCE_ACCOUNT_MISSING | balanceQuery | 共享资金账户归属缺失,无法查询对应余额。 |
SHARED_ACCOUNT_CURRENCY_CONFLICT | balanceQuery | 同一共享账户关联产品币种不一致,无法返回单币种余额。 |
ACCOUNT_LIMITS_QUERY_FAILED | limitsQuery | 额度查询失败或账户归属无法确认。 |
CARD_ACCOUNT_MISSING | limitsQuery | 支持额度查询,但平台卡账户尚未识别。 |
ACCOUNT_LIMITS_UNSUPPORTED | limitsQuery | 不支持卡账户额度查询,状态为 UNSUPPORTED。 |
无效用户标识或用户不存在等整体错误,沿用公共错误响应。
响应示例
以下数据均为模拟:同一资金账户关联两个卡账户,同一产品在这两个卡账户下分别持卡;另有一张余额查询失败的独立余额卡。
{
"code": 200,
"msg": "操作成功",
"data": {
"memberId": "DEMO-MB-101",
"totalCardCount": 3,
"sharedAccounts": [
{
"sharedAccountId": "DEMO-SA-001",
"balanceQuery": {
"status": "SUCCESS",
"balance": {
"currency": "USD",
"available": "100",
"ledger": "120"
},
"errorCode": null,
"queriedAt": "2026-11-13T16:00:00+08:00"
},
"cardAccounts": [
{
"fpCardAccountId": "DEMO-CA-001",
"limitsQuery": {
"status": "SUCCESS",
"accountLimits": {
"currency": "USD",
"accountType": "asset-link",
"totalLimit": "100",
"usedLimit": "20",
"availableLimit": "80"
},
"errorCode": null,
"queriedAt": "2026-11-13T16:00:00+08:00"
},
"products": [
{
"cardTypeId": "DEMO-SHARED-VIRTUAL",
"displayName": "Shared virtual card",
"cardImageUrl": null,
"cardCount": 1,
"cards": [
{
"cardId": "DEMO-CARD-001",
"cardTypeId": "DEMO-SHARED-VIRTUAL",
"cardName": "Shared virtual card",
"cardImageUrl": null,
"status": "active",
"network": "VISA",
"cardType": "VIRTUAL",
"last4": "1001"
}
]
}
]
},
{
"fpCardAccountId": "DEMO-CA-002",
"limitsQuery": {
"status": "SUCCESS",
"accountLimits": {
"currency": "USD",
"accountType": "prepaid",
"totalLimit": null,
"usedLimit": null,
"availableLimit": "50"
},
"errorCode": null,
"queriedAt": "2026-11-13T16:00:00+08:00"
},
"products": [
{
"cardTypeId": "DEMO-SHARED-VIRTUAL",
"displayName": "Shared virtual card",
"cardImageUrl": null,
"cardCount": 1,
"cards": [
{
"cardId": "DEMO-CARD-002",
"cardTypeId": "DEMO-SHARED-VIRTUAL",
"cardName": "Shared virtual card",
"cardImageUrl": null,
"status": "active",
"network": "VISA",
"cardType": "VIRTUAL",
"last4": "1002"
}
]
}
]
}
]
}
],
"individualCards": [
{
"cardId": "DEMO-CARD-003",
"cardTypeId": "DEMO-INDIVIDUAL",
"cardName": "Individual balance card",
"cardImageUrl": null,
"status": "locked",
"network": "MASTERCARD",
"cardType": "VIRTUAL",
"last4": "2001",
"balanceMode": "INDIVIDUAL",
"fpCardAccountId": "DEMO-CA-003",
"balanceQuery": {
"status": "FAILED",
"balance": null,
"errorCode": "BALANCE_QUERY_FAILED",
"queriedAt": "2026-11-13T16:00:00+08:00"
},
"limitsQuery": {
"status": "UNSUPPORTED",
"accountLimits": null,
"errorCode": "ACCOUNT_LIMITS_UNSUPPORTED",
"queriedAt": null
}
}
]
}
}结构调整与展示规则
本版概览用嵌套层级替换原顶层 sharedCardGroups 和 cardAccounts;已使用试用版概览的调用方需要同步调整路径,旧卡列表、卡详情、余额及独立额度接口不变。
- 共享卡按资金账户、卡账户、产品依次展示,无需跨顶层集合关联。
- 共享余额只展示/累计一次,不按产品、卡账户或卡数重复累加。
- 产品卡数在所属卡账户内统计;用户总卡数按全部共享卡加独立余额卡统计。
- 独立卡的额度仍属于关联卡账户,相同
fpCardAccountId的额度不能按卡数重复累计。 - 查询失败显示失败状态;不支持显示未支持,不显示为零。
- 不同币种金额不直接求和,本接口不修改卡状态或资金。
