List Card Headers

Returns the virtual card headers your account can apply for. A "card header" is defined by BIN + brand + region + business scene.

Endpoint

Item	Value
Method	POST
Path	/api/v1/openapi/card_headers/list
Auth	HMAC (4 signing headers)
Idempotency	Not required
Rate limit	600 / min

Request Fields

Field	Type	Required	Description
page	int	No	Default 1
page_size	int	No	Default 20, max 100
card_brand	string	No	Brand code, e.g. VISA / MASTER
card_area	string	No	Region code, e.g. US
currency	string	No	Currency filter, e.g. USD

Don't send card_type

This endpoint only returns virtual card headers — card_type is not needed.

Listed = applicable (account-manager-controlled headers are filtered per account)

Some headers are handed over to account managers, who open them per customer. Such a header appears in this list only if your account is bound to an active account manager who has opened it for you (a per-account setting beats the manager-wide one); otherwise it is filtered server-side and not counted in total. Calling /card_configs/list, /card/first_deposit/preview or /card/apply with a header you cannot apply for returns 400 account_manager_bind_required / account_manager_unavailable / account_manager_open_disabled. Do not reuse header IDs seen elsewhere — always take them from this endpoint.

Example Request

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

Response Fields

Each item in data.list[]:

Field	Type	Description
header_id	string	hdr_<id> format (used in apply)
card_bin	string	6-digit BIN
card_type	string	Lowercase: virtual_l / virtual_p / virtual_v / virtual_r / virtual_g / virtual_a (informational only — not sent on apply)
card_brand	string	Brand display name
card_area	string	Region display name
business_scene	string	Business scene
description	object	i18n: {"zh-CN": "...", "en-US": "..."}
features	string[]	Feature tags (e.g. ["3DS", "EMV"])
require_phone	bool	Whether phone / phone_code are required when applying (effective value, same rules the apply validation uses — see Integration tips)
require_email	bool	Whether email is required when applying (effective value, same rules; always true for virtual_a)
kyc_requirement	object	Preview of the platform KYC requirement for opening cards on this header (card type + header merged); see kyc_requirement below. The authoritative value is the per-package kyc_requirement on the package list (full three-level merge)

data also contains pagination fields (total / page / page_size / total_pages / has_next / has_prev).

kyc_requirement

Field	Type	Description
require_kyc	bool	Whether the end account must complete platform identity verification; when true and the account does not meet the requirement, /card/apply returns 400 kyc_required
kyc_type	string	Required verification type: personal / corporate
kyc_level	string	Required verification level: l1 / l2 / l3

When require_kyc=false, kyc_type / kyc_level are reference defaults only — do not surface any verification requirement to users based on them.

Example Response

{
  "code": 200,
  "message": "OK",
  "data": {
    "list": [
      {
        "header_id": "hdr_5",
        "card_bin": "424242",
        "card_type": "virtual_v",
        "card_brand": "VISA",
        "card_area": "United States",
        "business_scene": "Cross-border spending",
        "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
  }
}

Common Errors

HTTP	message_key	Description
401	openapi_invalid_credentials	Auth failure
500	openapi_list_card_headers_failed	Server error

Integration Tips

• Don't hardcode header_id. Always call this endpoint when integrating a new account.
• Only headers returned here can be applied for. Account-manager-controlled headers appear once your account manager opens them for you and disappear if the permission is revoked, so refresh this list before applying rather than caching IDs long-term. If a header you expect is missing, ask your account manager to open it for your account.
• The description i18n dict is server-rendered — no client-side translation needed.
• require_phone / require_email determine whether you must include those fields when applying.