列卡头

返回当前账号可申请的虚拟卡卡头列表。卡头（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 时是否要补传相关字段