列出银行卡

商户查询当前 AppID 名下所有银行卡，支持状态过滤、日期范围过滤、余额范围过滤和分页。

关键特性：

• 仅虚拟卡：响应已强制过滤为虚拟卡（virtual_l / virtual_p / virtual_v / virtual_r / virtual_g / virtual_a），物理卡不会通过 OpenAPI 暴露。
• 默认行为：未传 statuses 也未传 usable_only 时，默认返回 status ∈ [1, 2]（pending + active），自动隐藏失败/已注销/已冻结的历史卡。
• 列表接口不下发敏感字段：本接口的响应永远不含完整 PAN / CVV / 到期日 / 持卡人姓名，无论凭证权限如何。如需获取这些字段，请改用 /openapi/card/info 并传 with_sensitive=true（按卡选择性获取，通过账户二次验证或免验证特权凭证授权）。

端点

项	值
Method	POST
Path	/api/v1/openapi/cards/list
鉴权	HMAC
幂等键	不需要

请求字段

字段	类型	必填	说明
statuses	int[]	否	状态过滤数组，可选值 1 2 3 4 5 6；与 usable_only 互斥
usable_only	bool	否	简便过滤：true 等价 statuses=[2]；与 statuses 互斥
start_date	string	否	创建日期下界，格式 YYYY-MM-DD
end_date	string	否	创建日期上界，格式 YYYY-MM-DD（含当日）
min_balance	string	否	最小余额（字符串数字，如 "10.5"）
max_balance	string	否	最大余额（字符串数字）
page	int	否	页码，最小 1，默认 1
page_size	int	否	每页数量，1–100，默认 20

卡状态值

status	含义	默认包含？
1	pending（开卡处理中 / KYC 审核中）	✅
2	active（正常）	✅
3	failed（开卡失败）	❌（需显式 statuses=[3]）
4	closing（注销中）	❌
5	closed（已注销）	❌
6	frozen（已冻结）	❌

为何默认隐藏失败/已注销/已冻结

为了防止商户误把废卡当可用卡。如需做对账或审计，请显式传 statuses 参数。

请求示例

1. 默认查询（仅可用卡：pending + active）

curl -X POST "${baseUrl}/api/v1/openapi/cards/list" \
  -H "Content-Type: application/json" \
  -H "X-App-Id: cp_xxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-Timestamp: 1715251200" \
  -H "X-Nonce: 9b5603a21d2d4e1d" \
  -H "X-Signature: <hmac_sha256_hex>" \
  -d '{}'

2. 仅查可立即使用的卡（active）

{ "usable_only": true }

3. 自定义状态（含历史卡）

{
  "statuses": [2, 5, 6],
  "page": 1,
  "page_size": 50
}

4. 余额 + 日期范围筛选

{
  "min_balance": "10",
  "max_balance": "1000",
  "start_date": "2026-01-01",
  "end_date":   "2026-12-31"
}

响应字段

顶层包络

字段	类型	说明
list	CardListItemOut[]	卡数组（见下）
total	int64	总记录数
page	int	当前页码
page_size	int	每页数量
total_pages	int	总页数
has_next	bool	是否有下一页
has_prev	bool	是否有上一页

CardListItemOut

字段	类型	说明
card_id	string	card_<id> 格式，可作为其他接口（/card/info、/card/recharge）的 card_id 参数
card_type	string	全小写：virtual_l / virtual_p / virtual_v / virtual_r / virtual_g / virtual_a
card_brand	string	卡组织：Visa / Mastercard
card_holder_name	string	持卡人姓名（apply 时由商户提供）
currency	string	卡内币种 ISO 4217（如 USD）
status	int	1=pending 2=active 3=failed 4=closing 5=closed 6=frozen
status_desc	string	英文描述：pending / active / failed / closing / closed / frozen
masked_card_no	string	脱敏卡号（前 6 后 4）
last_four	string	卡号末 4 位
balance	string (decimal)	卡内可用余额
frozen_balance	string (decimal)	卡内冻结余额
freeze_type	int	冻结类型：0=未冻结 1=用户冻结 2=系统冻结 3=管理员冻结 4=风控冻结
nickname	string	卡昵称（可选）
activated_at	string nullable	激活时间（RFC3339）
created_at	string	创建时间（RFC3339）

列表响应中不含敏感持卡人数据

本接口的响应永远不包含完整卡号、CVV、卡有效期或持卡人姓名 —— 这些字段在任何情况下都不属于本接口的契约。内部字段（DB 主键、提供方引用、累计统计、内部标签等）同样不会暴露。

如需为单张已激活的卡获取完整 PAN / CVV / 到期日 / 持卡人姓名，请改用 /openapi/card/info 并传 with_sensitive=true，随请求提交账户的二次验证凭据（或使用免验证特权凭证）。

响应示例

{
  "code": 200,
  "message": "成功",
  "data": {
    "list": [
      {
        "card_id": "card_133",
        "card_type": "virtual_r",
        "card_brand": "Visa",
        "card_holder_name": "John Doe",
        "currency": "USD",
        "status": 2,
        "status_desc": "active",
        "masked_card_no": "493724******4245",
        "last_four": "4245",
        "balance": "37.72",
        "frozen_balance": "0.00",
        "freeze_type": 0,
        "nickname": "我的主卡",
        "activated_at": "2026-05-09T01:06:25Z",
        "created_at": "2026-05-08T10:55:12Z"
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 20,
    "total_pages": 1,
    "has_next": false,
    "has_prev": false
  }
}

空列表响应

{
  "code": 200,
  "message": "成功",
  "data": {
    "list": [],
    "total": 0,
    "page": 1,
    "page_size": 20,
    "total_pages": 0,
    "has_next": false,
    "has_prev": false
  }
}

典型错误

HTTP	message_key	说明
400	openapi_conflicting_card_filters	usable_only 与 statuses 不能同时传
400	openapi_invalid_status_value	statuses 只能填 1–6
400	invalid_min_balance	min_balance 必须是合法非负数字字符串
400	invalid_max_balance	max_balance 必须是合法非负数字字符串
400	min_balance_exceeds_max_balance	min_balance 不能大于 max_balance
400	invalid_date_format	日期必须为 YYYY-MM-DD 格式
401	openapi_invalid_credentials	HMAC 签名 / 时间戳 / nonce / 凭证状态任一失败
500	openapi_list_cards_failed	服务端内部错误，建议带退避重试

补充说明

1. 资源归属：仅返回当前 X-App-Id 关联的商户 user_id 名下的卡。即便重置过 secret，凭证按 user_id 隔离，多次 reset 后看到的卡保持一致。
2. 物理卡过滤：本接口强制只返回虚拟卡。商户即便通过用户端 portal 开过物理卡，本接口也不会返回。
3. 历史卡查询：默认隐藏 status ∈ {3, 4, 5, 6} 的卡。需要做对账时显式传 statuses=[5] 等查询。
4. 与其他接口的关联：
   • 拿到 card_id 后，可调 /openapi/card/info 查单卡详情。
   • 可调 /openapi/card/recharge 充值。
   • 重要：发起充值前请确保 status=2，否则会被拒（invalid_card_status）。
5. 不要把 card_id 当固定主键存：建议商户在自己侧也用字符串保存 card_id，未来如果迁移到不同 ID 编码方案时减少破坏面。