> ## 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.

# 申请签约

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

## 接口信息

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

## 请求参数

| 字段                    | 类型              | 必填 | 说明                                                   |
| --------------------- | --------------- | -- | ---------------------------------------------------- |
| `app_id`              | `string`        | 是  | 应用 ID，在商户平台生成                                        |
| `timestamp`           | `integer`       | 是  | Unix 秒级时间戳，参与请求验签                                    |
| `card_no`             | `string`        | 否  | 指定申请使用的 Visa 卡号。不传时，系统会从该商户未激活卡中随机分配一张；若商户没有可用卡会返回错误 |
| `pay_pwd`             | `string`        | 是  | 支付密码，传 MD5 加密后的值                                     |
| `mob_no_of`           | `string`        | 是  | 手机号码国家或地区区号，例如 `+852`                                |
| `mob_no`              | `string`        | 是  | 手机号码                                                 |
| `name`                | `string`        | 是  | 中文姓名                                                 |
| `name_en`             | `string`        | 是  | 英文姓名；中国大陆用户通常填写大写拼音                                  |
| `email`               | `string`        | 是  | 电子邮箱                                                 |
| `cert_type`           | `string`        | 是  | 证件类型，`00` 为身份证，`02` 为护照                              |
| `cert_id`             | `string`        | 是  | 证件号码                                                 |
| `id_card_img`         | `string`        | 条件 | 身份证正面图片 URL。`cert_type=00` 时必填，请确保接口请求时平台可访问         |
| `id_card_back_img`    | `string`        | 否  | 身份证背面图片 URL。传入时平台会下载并保存，请确保接口请求时平台可访问                |
| `passport_img`        | `string`        | 条件 | 护照图片 URL。`cert_type=02` 时必填，请确保接口请求时平台可访问            |
| `cert_start_date`     | `string`        | 否  | 证件有效期开始日期，格式 `YYYY-MM-DD`；香港身份证可不传                   |
| `cert_end_date`       | `string`        | 否  | 证件有效期结束日期，格式 `YYYY-MM-DD`；香港身份证会按系统规则置空              |
| `address`             | `string`        | 是  | 联系地址。中国大陆地址必须使用 `省-市-区-详细地址` 格式，其他国家或地区可直接填写完整地址     |
| `birthday`            | `string`        | 是  | 出生日期，格式 `YYYY-MM-DD`                                 |
| `sex`                 | `string`        | 是  | 性别，`M` 男性，`F` 女性                                     |
| `country`             | `string`        | 是  | 国家或地区代码，取值见 Visa 支持国家/地区接口                           |
| `profession`          | `string`        | 是  | 职业代码，取值见 Visa 支持行业/职业接口                              |
| `profession_other`    | `string`        | 条件 | `profession` 为其他时必填                                  |
| `position`            | `string`        | 是  | 职位代码，取值见 Visa 支持职位接口                                 |
| `purpose`             | `array<string>` | 是  | 开户目的代码数组，取值见 Visa 支持开户目的接口                           |
| `purpose_other`       | `string`        | 条件 | `purpose` 包含其他时必填                                    |
| `wealth_source`       | `array<string>` | 是  | 资金来源代码数组，取值见 Visa 支持资金来源接口                           |
| `wealth_source_other` | `string`        | 条件 | `wealth_source` 包含其他时必填                              |
| `sign_applicant`      | `string`        | 是  | 申请人签名图片 URL，仅支持 PNG，请确保接口请求时平台可访问                    |
| `company_name`        | `string`        | 是  | 公司名称                                                 |
| `office_address`      | `string`        | 是  | 公司办公地址                                               |
| `office_tel_no_of`    | `string`        | 是  | 公司电话国家或地区区号，例如 `852`                                 |
| `office_tel_no`       | `string`        | 是  | 公司电话号码                                               |
| `yearly_income`       | `string`        | 是  | 年收入                                                  |
| `years_of_service`    | `string`        | 是  | 工作年限，单位：年                                            |
| `consignee`           | `string`        | 是  | 收货人姓名                                                |
| `consignee_mob_no_of` | `string`        | 是  | 收货人手机国家或地区区号                                         |
| `consignee_mob_no`    | `string`        | 是  | 收货人手机号码                                              |
| `consignee_address`   | `string`        | 是  | 收货地址                                                 |
| `consignee_note`      | `string`        | 否  | 收货备注                                                 |
| `pay_voucher`         | `string`        | 否  | 支付凭证图片 URL。传入时平台会下载并保存，支持 JPEG、JPG、PNG               |
| `other_field`         | `array<object>` | 否  | 扩展字段数组                                               |
| `other_field[].name`  | `string`        | 否  | 扩展字段名称                                               |
| `other_field[].value` | `string`        | 否  | 扩展字段值                                                |
| `other_field[].field` | `string`        | 否  | 扩展字段标识                                               |

## 字段规则

* `app_id`、`timestamp` 和 `Authorization` 缺失时会鉴权失败。
* 图片字段需提供可公网访问的 URL；系统会在申请时下载图片并保存。
* 同一证件号在 30 秒内只能提交一次申请。
* 同一证件号如已存在未注销的 Visa 卡，不能再次申请。
* `card_no` 传入时，卡号必须属于当前商户且处于未激活状态，并且没有正在处理中的申请。
* `purpose` 和 `wealth_source` 支持传多个代码；请求体中使用 JSON 数组。

## 请求示例

```json theme={null}
{
  "app_id": "app_123456",
  "timestamp": 1784880000,
  "card_no": "",
  "pay_pwd": "e10adc3949ba59abbe56e057f20f883e",
  "mob_no_of": "+852",
  "mob_no": "61234567",
  "name": "张三",
  "name_en": "ZHANG SAN",
  "email": "user@example.com",
  "cert_type": "00",
  "cert_id": "A1234567",
  "id_card_img": "https://example.com/images/id-card-front.png",
  "id_card_back_img": "https://example.com/images/id-card-back.png",
  "cert_start_date": "2020-01-01",
  "cert_end_date": "2030-01-01",
  "address": "香港九龙示例地址",
  "birthday": "1990-01-01",
  "sex": "M",
  "country": "HKG",
  "profession": "01",
  "position": "01",
  "purpose": ["01"],
  "wealth_source": ["01"],
  "sign_applicant": "https://example.com/images/signature.png",
  "company_name": "Example Limited",
  "office_address": "Hong Kong Example Office",
  "office_tel_no_of": "852",
  "office_tel_no": "21234567",
  "yearly_income": "300000",
  "years_of_service": "3",
  "consignee": "张三",
  "consignee_mob_no_of": "+852",
  "consignee_mob_no": "61234567",
  "consignee_address": "香港九龙示例收货地址",
  "consignee_note": "",
  "pay_voucher": "",
  "other_field": [
    {
      "name": "渠道",
      "value": "partner-a",
      "field": "channel"
    }
  ]
}
```

## 返回示例

```json theme={null}
{
  "code": 0,
  "msg": "SUCCESS",
  "data": {
    "busi_water_no": "tz3kaIdtZkMtFPse"
  }
}
```

| 字段              | 类型       | 说明                  |
| --------------- | -------- | ------------------- |
| `busi_water_no` | `string` | 申请流水号，可用于后续查询该申请单状态 |

申请为异步流程，最终结果以 Visa 回调或后续查询结果为准。