列出銀行卡

商戶查詢當前 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 編碼方案時減少破壞面。