列卡頭

返回當前賬號可申請的虛擬卡卡頭列表。卡頭（card header）由 BIN + 卡組織 + 地區 + 業務場景共同定義。

端點

項	值
Method	POST
Path	/api/v1/openapi/card_headers/list
鑑權	HMAC（4 個簽名頭）
冪等鍵	不需要
限流	600 / min

請求欄位

欄位	型別	必填	說明
page	int	否	預設 1
page_size	int	否	預設 20，最大 100
card_brand	string	否	卡組織程式碼，如 VISA / MASTER
card_area	string	否	髮卡地區程式碼，如 US
currency	string	否	幣種過濾，如 USD

不需要傳 card_type

本介面僅返回虛擬卡卡頭，無需傳 card_type。

列出即可開（客戶經理管控卡頭按賬號過濾）

部分卡頭交給客戶經理管控、由經理按客戶逐個放開。這類卡頭只有在您的賬號已繫結有效客戶經理、且該經理已對您放開時才會出現在本列表（對單個賬號的設定優先於經理統一設定）；否則服務端直接過濾、不計入 total。拿一個您不可開的卡頭去調 /card_configs/list、/card/first_deposit/preview 或 /card/apply 會返回 400 account_manager_bind_required / account_manager_unavailable / account_manager_open_disabled。不要把別處看到的卡頭 ID 拿來用，一律以本介面返回為準。

請求示例

{
  "page": 1,
  "page_size": 20,
  "card_brand": "VISA"
}

響應欄位

data.list[] 中每項：

欄位	型別	說明
header_id	string	hdr_<id> 格式（apply 時回傳）
card_bin	string	6 位 BIN
card_type	string	全小寫：virtual_l / virtual_p / virtual_v / virtual_r / virtual_g / virtual_a（僅資訊展示，apply 不需要回傳）
card_brand	string	卡組織中文（如 VISA）
card_area	string	地區中文（如 美國）
business_scene	string	業務場景中文
description	object	i18n: {"zh-CN": "...", "en-US": "..."}
features	string[]	特性標籤（如 ["3DS", "EMV"]）
require_phone	bool	apply 是否需要傳 phone/phone_code（生效值，與 apply 校驗同口徑，見整合提示）
require_email	bool	apply 是否需要傳 email（生效值口徑同上；virtual_a 恆為 true）
kyc_requirement	object	開卡平台實名（KYC）要求預覽（卡類型 + 卡頭合併），結構見下方 kyc_requirement。最終口徑以套餐列表行內 kyc_requirement（完整三級合併）為準

data 包含分頁欄位（total / page / page_size / total_pages / has_next / has_prev）。

kyc_requirement

欄位	類型	說明
require_kyc	bool	是否要求終端帳號完成平台實名認證；為 true 且帳號未達標時 /card/apply 返回 400 kyc_required
kyc_type	string	要求的實名類型：personal（個人）/ corporate（企業）
kyc_level	string	要求的實名等級：l1 / l2 / l3

require_kyc=false 時 kyc_type / kyc_level 僅為參考預設值，不要據此向用戶展示任何認證要求。

響應示例

{
  "code": 200,
  "message": "成功",
  "data": {
    "list": [
      {
        "header_id": "hdr_5",
        "card_bin": "424242",
        "card_type": "virtual_v",
        "card_brand": "VISA",
        "card_area": "美國",
        "business_scene": "境外消費",
        "description": {
          "zh-CN": "適合電商訂閱",
          "en-US": "For e-commerce subscriptions"
        },
        "features": ["3DS", "EMV"],
        "require_phone": false,
        "require_email": true,
        "kyc_requirement": {
          "require_kyc": false,
          "kyc_type": "personal",
          "kyc_level": "l1"
        }
      }
    ],
    "total": 12,
    "page": 1,
    "page_size": 20,
    "total_pages": 1,
    "has_next": false,
    "has_prev": false
  }
}

典型錯誤

HTTP	message_key	說明
401	openapi_invalid_credentials	鑑權失敗
500	openapi_list_card_headers_failed	服務端異常

整合提示

• 客戶端不要硬編碼 header_id，每次接入新賬號都應先調本介面
• 只有本介面返回的卡頭才能申請。 客戶經理管控卡頭在經理對您放開後出現、許可權被收回後消失，請在開卡前重新整理列表而不是長期快取 ID；若預期的卡頭沒有出現，請聯絡您的客戶經理為您的賬號放開
• description 的 i18n 字典直接渲染給使用者，不需要客戶端 i18n
• require_phone / require_email 決定 apply 時是否要補傳相關欄位