> ## Documentation Index
> Fetch the complete documentation index at: https://developer.speedpay.hk/llms.txt
> Use this file to discover all available pages before exploring further.

# 申请签约

> 提交 JCB 卡申请资料并生成申请流水号。

## 接口信息

| 项目            | 说明                                                  |
| ------------- | --------------------------------------------------- |
| 方法            | `POST`                                              |
| 路径            | `/mc-platformapi/v1/open/jcb/card/apply`            |
| Content-Type  | `application/json`                                  |
| Authorization | 完整 JSON 请求体经 `SHA256withRSA` 签名后再 `BASE64` 编码得到的签名值 |

## 请求参数

| 字段                    | 类型              | 必填 | 说明                                                      |
| --------------------- | --------------- | -- | ------------------------------------------------------- |
| `app_id`              | `string`        | 是  | 应用 ID，在商户平台生成                                           |
| `timestamp`           | `integer`       | 是  | Unix 秒级时间戳，参与请求验签                                       |
| `card_no`             | `string`        | 否  | 指定卡号；不传时由后续流程分配                                         |
| `pay_pwd`             | `string`        | 是  | 支付密码                                                    |
| `mob_no_of`           | `string`        | 是  | 手机号码国家或地区区号，例如 `+852`                                   |
| `mob_no`              | `string`        | 是  | 手机号码                                                    |
| `first_name`          | `string`        | 条件 | 名；`first_name` 与 `last_name` 至少按业务要求提供姓名信息              |
| `last_name`           | `string`        | 条件 | 姓；`first_name` 与 `last_name` 至少按业务要求提供姓名信息              |
| `en_name`             | `string`        | 否  | 英文姓名                                                    |
| `email`               | `string`        | 是  | 电子邮箱                                                    |
| `cert_type`           | `string`        | 是  | 证件类型，取值见下方 `cert_type` 枚举                               |
| `cert_id`             | `string`        | 是  | 证件号码                                                    |
| `id_card_img`         | `string`        | 条件 | 身份证正面图片 URL。证件类型为身份证时必填                                 |
| `id_card_back_img`    | `string`        | 条件 | 身份证背面图片 URL；大陆身份证必填                                     |
| `passport_img`        | `string`        | 条件 | 护照图片 URL。证件类型为护照时必填                                     |
| `driver_license_img`  | `string`        | 条件 | 驾驶证图片 URL。证件类型为驾驶证时必填                                   |
| `cert_start_date`     | `string`        | 条件 | 证件有效期开始日期，格式 `YYYY-MM-DD`；香港地区身份证可不传，其他情况按业务要求传入        |
| `cert_end_date`       | `string`        | 条件 | 证件有效期结束日期，格式 `YYYY-MM-DD`；香港地区身份证可不传，长期有效传 `9999-12-31` |
| `address`             | `string`        | 是  | 居住地址                                                    |
| `birthday`            | `string`        | 是  | 出生日期，格式 `YYYY-MM-DD`                                    |
| `country`             | `string`        | 是  | 国家或地区代码，取值见支持国家接口                                       |
| `profession`          | `string`        | 否  | 职业代码                                                    |
| `position`            | `string`        | 否  | 职位代码                                                    |
| `pay_voucher`         | `string`        | 否  | 支付凭证图片 URL                                              |
| `yearly_income`       | `string`        | 否  | 年收入                                                     |
| `consignee`           | `string`        | 是  | 收货人姓名                                                   |
| `consignee_mob_no_of` | `string`        | 是  | 收货人手机国家或地区区号                                            |
| `consignee_mob_no`    | `string`        | 是  | 收货人手机号码                                                 |
| `consignee_address`   | `string`        | 是  | 收货地址                                                    |
| `consignee_note`      | `string`        | 否  | 收货备注                                                    |
| `other_field`         | `array<object>` | 否  | 扩展字段数组                                                  |
| `other_field[].name`  | `string`        | 否  | 扩展字段名称                                                  |
| `other_field[].value` | `string`        | 否  | 扩展字段值                                                   |
| `other_field[].field` | `string`        | 否  | 扩展字段标识                                                  |

## 枚举值

### `cert_type`

| 值                | 说明  | 图片要求                                          |
| ---------------- | --- | --------------------------------------------- |
| `ID_CARD`        | 身份证 | `id_card_img` 必填；大陆身份证还需填写 `id_card_back_img` |
| `PASSPORT`       | 护照  | `passport_img` 必填                             |
| `DRIVER_LICENSE` | 驾驶证 | `driver_license_img` 必填                       |

## 字段规则

* 图片 URL 需在申请时可访问；平台会下载并保存，支持 JPEG、JPG、PNG。
* `country` 必须是平台支持国家或地区代码。
* `cert_start_date` 与 `cert_end_date` 按实际证件有效期填写；证件长期有效时，`cert_end_date` 传 `9999-12-31`。
* 同一证件号或手机号已有申请中/已成功的申请时，不能重复提交。
* 商户卡与钱包配置未初始化时会返回错误。

## 请求示例

```json theme={null}
{
  "app_id": "app_123456",
  "timestamp": 1784880000,
  "pay_pwd": "123456",
  "mob_no_of": "+852",
  "mob_no": "61234567",
  "first_name": "San",
  "last_name": "Zhang",
  "en_name": "San Zhang",
  "email": "user@example.com",
  "cert_type": "ID_CARD",
  "cert_id": "A1234567",
  "id_card_img": "https://example.com/id-card-front.jpg",
  "id_card_back_img": "https://example.com/id-card-back.jpg",
  "cert_start_date": "2018-09-10",
  "cert_end_date": "9999-12-31",
  "address": "香港中环金融街 1 号",
  "birthday": "1990-01-01",
  "country": "HKG",
  "profession": "009",
  "position": "1",
  "yearly_income": "500000",
  "consignee": "San Zhang",
  "consignee_mob_no_of": "+852",
  "consignee_mob_no": "61234567",
  "consignee_address": "香港中环金融街 1 号"
}
```

## 返回字段

| 字段         | 类型       | 说明        |
| ---------- | -------- | --------- |
| `water_no` | `string` | JCB 申请流水号 |

## 返回示例

```json theme={null}
{
  "code": 0,
  "msg": "success",
  "data": {
    "water_no": "IpTy6F48AwLLxXf5hpRhYSCBiSDEzJ8T"
  }
}
```

申请提交成功不代表最终开卡成功，最终结果以 JCB 回调或查询结果为准。