跳转到内容

查询用户持卡概览 ​

GET /openapi/v2/cards/overview

一次返回当前租户内某一用户的全部已持卡记录。共享卡按“资金账户 → 卡账户额度 → 产品 → 卡片”嵌套;独立余额卡平铺自身资料、余额与关联账户额度。不分页、不按卡状态筛选,锁定、注销等已有卡记录仍计入数量,仅返回已持卡产品。

沿用 V2 加签说明 和 公共响应。租户由当前凭证确定,不接受调用方传入租户或渠道账户。原卡列表、卡余额及独立账户额度接口保持原有契约。

请求参数 ​

字段类型必填说明
memberIdstring条件必填平台成员 ID,最大 64 个字符;与 email 必须且只能填写一个。
emailstring条件必填当前租户用户邮箱,最大 128 个字符;与 memberId 必须且只能填写一个。

不提供分页或状态筛选参数。

http
GET /openapi/v2/cards/overview?memberId=DEMO-MB-101
GET /openapi/v2/cards/overview?email=user@example.com

响应 data ​

字段类型说明
memberIdstring平台成员 ID。
totalCardCountinteger共享卡和独立余额卡的全量数量,每张卡只计一次。
sharedAccountsarray共享资金账户,包含余额及关联卡账户、产品和卡片。
individualCardsarray独立余额卡,各自直接携带 balanceQuery 和 limitsQuery。

用户存在但没有卡时,totalCardCount=0,两个数组均为 [];用户不存在时返回业务错误。

sharedAccounts:共享资金账户 ​

字段类型说明
sharedAccountIdstring稳定的平台共享资金账户标识,不是渠道账户 ID;作为不透明字符串使用。
balanceQueryobject共享资金余额查询结果。
cardAccountsarray该资金账户关联的卡账户,各自包含额度和产品。

同一共享资金余额只出现一次。不同租户、用户和服务方的资金分别关联;同一份资金可能关联多个卡账户和产品。

cardAccounts:关联卡账户 ​

位于 sharedAccounts[].cardAccounts[],不是顶层集合。

字段类型说明
fpCardAccountIdstring/null平台卡账户标识,尚未识别时明确为 null。
limitsQueryobject该卡账户的额度查询结果。
productsarray属于该卡账户的已持卡产品及卡片。

未知账户按卡分别保留,不因为标识均为空而合并。额度属于卡账户,概览不返回本次用于查询额度的取证 cardId。共享资金账户标识与卡账户标识不可互换。

products:卡账户内的产品 ​

位于 sharedAccounts[].cardAccounts[].products[]。

字段类型说明
cardTypeIdstring平台卡产品 ID。
displayNamestring/null产品展示名称。
cardImageUrlstring/null产品卡面图片地址。
cardCountinteger该卡账户、该产品下的卡数量,与 cards.length 一致。
cardsarray该账户、该产品下的全部卡片。

同一产品的卡可能属于不同卡账户,因此同一产品可以在不同账户下出现;卡片不会重复出现在多个分组。

卡片资料 ​

共享卡位于 sharedAccounts[].cardAccounts[].products[].cards[]。

字段类型说明
cardIdstring平台卡 ID,继续用于原有详情、锁卡等接口。
cardTypeIdstring平台卡产品 ID。
cardNamestring卡展示名称。
cardImageUrlstring/null卡面图片地址。
statusstring/null平台卡状态,语义见查询卡详情。
networkstring/null卡组织,例如 VISA。
cardTypestring/null卡类型,例如 VIRTUAL。
last4string/null卡号后四位,不包含完整卡号。

共享卡资料不重复返回所属账户标识、余额或额度,直接读取上层账户。

individualCards:独立余额卡 ​

包含以上所有卡片资料字段,并增加:

字段类型说明
balanceModestring固定为 INDIVIDUAL。
fpCardAccountIdstring/null关联的平台卡账户标识,尚未识别时为 null。
balanceQueryobject本卡余额查询结果。
limitsQueryobject关联卡账户额度查询结果;不支持时明确标注。

balanceQuery:资金余额查询结果 ​

字段类型说明
statusstringSUCCESS 或 FAILED。
balanceobject/null成功时为单币种余额;失败时明确为 null。
balance.currencystring按卡产品币种选取的余额币种,不执行换汇。
balance.availablestring可用余额。
balance.ledgerstring账面余额。
errorCodestring/null成功为 null;失败为下文所列错误码。
queriedAtstring查询完成或失败时间,ISO 8601 格式。

limitsQuery:账户额度查询结果 ​

共享卡账户和独立余额卡使用相同结构。

字段类型说明
statusstringSUCCESS、FAILED 或 UNSUPPORTED。
accountLimitsobject/null成功时为下表额度对象;失败或不支持时为 null。
errorCodestring/null成功为 null;其他情况为下文所列错误码。
queriedAtstring/null查询完成或失败时间;UNSUPPORTED 时为 null。
accountLimits 字段类型说明
currencystring额度币种。
accountTypestringasset-link、fixed-limit、program-limit 或 prepaid。
totalLimitstring/null账户总额度,prepaid 可能为 null。
usedLimitstring/null当前净占用,不是累计消费或冻结金额;prepaid 可能为 null。
availableLimitstring渠道返回的账户可用额度,不自行用总额度减占用计算。

以上金额含义与查询卡账户额度一致,但概览额度对象不重复返回该独立接口中的 cardId、fpCardAccountId。

所有金额为非科学计数法十进制字符串,允许真实零 "0",不保证保留末尾零。未知金额不得当作零。资金余额与卡账户额度不相加、不互相替代;不根据余额差推算冻结。不同查询有各自时间,响应不是同一时刻的原子快照。

部分失败与错误码 ​

单项余额或额度查询失败时,账户、产品和卡片仍保留,不使用零金额替代失败结果。

errorCode所在结果说明
BALANCE_QUERY_FAILEDbalanceQuery余额查询失败,或币种、数据、归属无法确认。
BALANCE_ACCOUNT_MISSINGbalanceQuery共享资金账户归属缺失,无法查询对应余额。
SHARED_ACCOUNT_CURRENCY_CONFLICTbalanceQuery同一共享账户关联产品币种不一致,无法返回单币种余额。
ACCOUNT_LIMITS_QUERY_FAILEDlimitsQuery额度查询失败或账户归属无法确认。
CARD_ACCOUNT_MISSINGlimitsQuery支持额度查询,但平台卡账户尚未识别。
ACCOUNT_LIMITS_UNSUPPORTEDlimitsQuery不支持卡账户额度查询,状态为 UNSUPPORTED。

无效用户标识或用户不存在等整体错误,沿用公共错误响应。

响应示例 ​

以下数据均为模拟:同一资金账户关联两个卡账户,同一产品在这两个卡账户下分别持卡;另有一张余额查询失败的独立余额卡。

json
{
  "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 的额度不能按卡数重复累计。
  • 查询失败显示失败状态;不支持显示未支持,不显示为零。
  • 不同币种金额不直接求和,本接口不修改卡状态或资金。