> ## Documentation Index
> Fetch the complete documentation index at: https://docs-payment-merchant.keysecure.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 开卡申请

开卡申请。授信模式传 `package_no`，授权模式传 `card_bin_no`（二选一）。

## 请求头

<ParamField header="Api-Key" type="string" required placeholder="your_api_key">
  apiKey（商户凭证，与 IP 白名单绑定）
</ParamField>

<ParamField header="Timestamp" type="string" required>
  Unix 时间戳（毫秒），与服务端偏差须在 60 秒内，且不接受未来时间戳
</ParamField>

<ParamField header="Access-Token" type="string" required placeholder="your_access_token">
  登录标识（除获取 Token 外必填）
</ParamField>

<ParamField header="Content-Type" type="string" default="application/json">
  固定为 `application/json`
</ParamField>

## 请求体

<ParamField body="card_bin_no" type="string">
  卡 BIN 单号（授权模式必填）
</ParamField>

<ParamField body="cardholder_no" type="string" required>
  持卡人单号
</ParamField>

<ParamField body="card_unique_no" type="string" required>
  商户侧卡唯一单号（最长 64 字符）
</ParamField>

<ParamField body="package_no" type="string">
  卡套餐单号（授信模式必填）
</ParamField>

<ParamField body="card_type" type="string" required>
  卡类型，见 【附录常量表】卡类型
</ParamField>

<ParamField body="address_info" type="object">
  地址信息（实体卡、部分虚拟卡必填）

  <Expandable title="address_info">
    <ParamField body="first_name" type="string">
      名（英文，实体卡必填）
    </ParamField>

    <ParamField body="last_name" type="string">
      姓（英文，实体卡必填）
    </ParamField>

    <ParamField body="phone_code" type="string">
      手机号国别码（**纯数字，不含 `+` 号**，如 `86` 表示中国大陆；须为平台支持的有效国别码，实体卡必填）
    </ParamField>

    <ParamField body="phone" type="string">
      手机号（不含国别码，与 `phone_code` 组合校验，实体卡必填）
    </ParamField>

    <ParamField body="postal_code" type="string" required>
      邮编（须与 `country` / `state` / `city` 匹配）
    </ParamField>

    <ParamField body="country" type="string" required>
      国家 ISO 3166-1 alpha-2（如 `US`）
    </ParamField>

    <ParamField body="state" type="string" required>
      省/州（英文）
    </ParamField>

    <ParamField body="city" type="string" required>
      城市（英文）
    </ParamField>

    <ParamField body="address_line1" type="string" required>
      地址1（英文字母、数字、空格或常用地址符号）
    </ParamField>

    <ParamField body="address_line2" type="string">
      地址2（同上，可空）
    </ParamField>
  </Expandable>
</ParamField>

<Note>
  **重要说明：**

  * `card_bin_no` 与 `package_no` 至少传一个；两者均为空时返回错误码 **1004**
  * **实体卡**（`card_type = Physical`）时 `address_info` 整体不能为空，且 `first_name`、`last_name`、`phone_code`、`phone` 及所有地址字段均必填
  * **虚拟卡**可按业务需要省略 `address_info`，若传入则必须包含 `postal_code`、`country`、`state`、`city`、`address_line1` 并参与校验
  * `phone_code` 为纯数字，不得含 `+` 号
  * 地址字段须使用英文填写，并符合所在国家的地址格式
</Note>

## 返回参数

<ResponseField name="code" type="number">
  响应状态码，`0` 表示成功
</ResponseField>

<ResponseField name="msg" type="string">
  响应消息
</ResponseField>

<ResponseField name="data" type="object">
  返回数据

  <Expandable title="data">
    <ResponseField name="card_no" type="string">卡单号</ResponseField>
    <ResponseField name="card_unique_no" type="string">商户侧卡唯一单号</ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash Request theme={null}
  curl --request POST \
    --url https://sandbox-openplatform.keysecure.io/open-api/v1/card/apply \
    --header 'Content-Type: application/json' \
    --header 'Api-Key: your_api_key' \
    --header 'Timestamp: 1716307200000' \
    --header 'Access-Token: your_access_token' \
    --data '{
      "card_bin_no": "",
      "cardholder_no": "",
      "package_no": "",
      "card_type": "Virtual",
      "card_unique_no": "",
      "address_info": {
        "first_name": "",
        "last_name": "",
        "phone_code": "86",
        "phone": "",
        "postal_code": "",
        "country": "CN",
        "state": "",
        "city": "",
        "address_line1": "",
        "address_line2": ""
      }
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "code": 0,
    "msg": "Success",
    "data": {
      "card_no": "",
      "card_unique_no": ""
    }
  }
  ```
</ResponseExample>