draft

docs/design/001-heepay-customer-enter-enterprise-apply.md

@@ -0,0 +1,330 @@
+# 001 - 汇元企业入网申请 API
+
+**接口名称：** `customer.enter.enterprise.apply`
+**更新时间：** 2025-11-28
+**状态：** 已实现
+
+---
+
+## 调用地址
+
+| 环境 | 地址 |
+|------|------|
+| 生产 | `https://openapi.heepay.com/v1/customer/gateway` |
+| 沙箱 | `http://openapi.heepaydev.com/v1/customer/gateway` |
+
+> 注意：进件网关地址与支付网关不同，对应 `config.yaml` 中的 `channels.heepay.merchant_url`。
+
+---
+
+## 接口说明
+
+企业商户入网申请。所有 `*_img` 字段均需先调用**文件上传接口**（接口 002）获取 `file_id` 后传入。
+
+---
+
+## 请求业务参数（biz_content）
+
+### 顶层字段
+
+| 字段 | 名称 | 必填 | 类型 | 说明 |
+|------|------|------|------|------|
+| `base_info` | 基础信息 | 是 | Object | 见下方 |
+| `settlement_info` | 结算信息 | 是 | Object | 见下方 |
+| `addition_info` | 补充信息 | 否 | Object | 见下方 |
+| `subject_info` | 主体信息 | 是 | Object | 见下方 |
+| `identity_info` | 法人信息 | 是 | Object | 见下方 |
+| `contact_info` | 业务联系人信息 | 是 | Object | 见下方 |
+| `ubo_infos` | 受益所有人信息 | 条件必填 | Object[] | 受益人非法人时必传 |
+| `business_info` | 业务信息 | 是 | Object | 见下方 |
+
+---
+
+### base_info 基础信息
+
+| 字段 | 名称 | 必填 | 类型 | 说明 |
+|------|------|------|------|------|
+| `request_no` | 商户入网申请流水号 | 是 | String(64) | 商户自定义，全局唯一 |
+| `alias_name` | 商户简称 | 是 | String(20) | 支付宝/微信支付页显示该名称 |
+| `mcc` | 经营类目编码 | 是 | String(4) | 参照【经营类目编码】列表 |
+| `service_phone` | 客服电话 | 是 | String | 客服电话 |
+| `email` | 商户邮箱 | 是 | String(128) | 首次入网默认作为登录账号和联系人邮箱 |
+| `notify_url` | 通知地址 | 否 | String(256) | 汇元主动通知的 http/https 回调地址 |
+
+---
+
+### settlement_info 结算信息
+
+| 字段 | 名称 | 必填 | 类型 | 说明 |
+|------|------|------|------|------|
+| `settle_type` | 结算类型 | 是 | String | `ACCOUNT`=结算到汇付宝账户，`BANK_CARD`=结算到银行卡 |
+| `account_type` | 账户类型 | 是 | String | `PUBLIC`=对公，`PRIVATE`=对私；公司只支持对公，小微只支持对私 |
+| `account_no` | 银行卡号 | 是 | String(35) | 银行卡号 |
+| `account_name` | 开户名称 | 是 | String(32) | 开户名称 |
+| `account_branch_no` | 开户支行联行号 | 是 | String(64) | 开户支行联行号 |
+| `open_account_img` | 银行开户许可照 | 条件必填 | String(64) | 对公账号必传，传 `file_id` |
+| `bank_name` | 银行名称 | 是 | String | 参照【银行列表】 |
+| `region_code` | 银行卡省市区县编码 | 是 | String(6) | 参照省市编码列表 |
+
+---
+
+### addition_info 补充信息（选填）
+
+| 字段 | 名称 | 必填 | 类型 | 说明 |
+|------|------|------|------|------|
+| `open_merch_video` | 开户意愿视频 | 否 | String | 传 `file_id` |
+| `sharing_protocol_img` | 分账协议 | 否 | String | 传 `file_id` |
+| `business_developer` | 业务开发者（拓展商户的业务员） | 否 | String(20) | 业务员姓名 |
+
+---
+
+### subject_info 主体信息
+
+| 字段 | 名称 | 必填 | 类型 | 说明 |
+|------|------|------|------|------|
+| `name` | 商户名称 | 是 | String(50) | 须与营业执照名称一致 |
+| `cert_no` | 营业执照号 | 是 | String(32) | 营业执照号 |
+| `region_code` | 营业执照区划编码 | 是 | String(32) | 传区县编码（通过行政区划查询接口获取） |
+| `address` | 营业执照注册地址 | 是 | String(250) | 营业执照注册地址 |
+| `cert_img` | 营业执照图片 | 是 | String | 传 `file_id` |
+| `cert_expire` | 营业执照有效期 | 是 | String | 格式：`yyyy-MM-dd/yyyy-MM-dd`，长期有效传 `yyyy-MM-dd/forever` |
+
+---
+
+### identity_info 法人信息
+
+| 字段 | 名称 | 必填 | 类型 | 说明 |
+|------|------|------|------|------|
+| `name` | 姓名 | 是 | String(18) | 法人姓名 |
+| `mobile` | 手机号 | 是 | String(11) | 法人手机号 |
+| `cert_type` | 证件类型 | 是 | String | `ID_CARD`=大陆身份证，`HK_CARD`=港通行证，`MC_CARD`=澳通行证，`TW_CARD`=台通行证，`PASSPORT`=外籍护照 |
+| `cert_no` | 证件号 | 是 | String(32) | 证件号码 |
+| `nation` | 国籍类型 | 是 | Int | 参照【国家编码】列表 |
+| `cert_front_img` | 证件正面照（人像面） | 是 | String | 传 `file_id` |
+| `cert_back_img` | 证件反面照（非人像面） | 是 | String | 传 `file_id` |
+| `cert_expire` | 证件有效期 | 是 | String | 格式：`yyyy-MM-dd/yyyy-MM-dd`，长期有效传 `yyyy-MM-dd/forever` |
+| `belong_ubo` | 受益人是否是法人 | 是 | Bool | `true`=是，`false`=否；为 false 时 `ubo_infos` 必传 |
+
+---
+
+### contact_info 业务联系人信息
+
+| 字段 | 名称 | 必填 | 类型 | 说明 |
+|------|------|------|------|------|
+| `name` | 姓名 | 是 | String(32) | 业务联系人姓名 |
+| `mobile` | 手机号 | 是 | String(11) | 业务联系人手机号 |
+| `cert_type` | 证件类型 | 是 | String | 同 `identity_info.cert_type` 枚举值 |
+| `cert_no` | 证件号 | 是 | String(18) | 证件号码 |
+| `nation` | 国籍类型 | 是 | Int | 参照【国家编码】列表 |
+| `cert_expire` | 证件有效期 | 是 | String | 格式：`yyyy-MM-dd/yyyy-MM-dd`，长期有效传 `yyyy-MM-dd/forever` |
+| `cert_front_img` | 证件正面照（人像面） | 是 | String(255) | 传 `file_id` |
+| `cert_back_img` | 证件反面照（非人像面） | 是 | String(255) | 传 `file_id` |
+
+---
+
+### ubo_infos 受益所有人信息（受益人非法人时必传，数组）
+
+| 字段 | 名称 | 必填 | 类型 | 说明 |
+|------|------|------|------|------|
+| `name` | 证件姓名 | 是 | String(64) | 受益所有人证件姓名 |
+| `cert_type` | 证件类型 | 是 | String | 同 `identity_info.cert_type` 枚举值 |
+| `cert_no` | 证件号码 | 是 | String(32) | 证件号码 |
+| `nation` | 国籍类型 | 是 | Int | 参照【国家编码】列表 |
+| `cert_expire` | 证件有效期 | 是 | String | 格式：`yyyy-MM-dd/yyyy-MM-dd`，长期有效传 `yyyy-MM-dd/forever` |
+| `cert_address` | 证件地址 | 是 | String(255) | 受益所有人证件地址 |
+| `rate` | 持股比例 | 是 | String | 以 % 为单位，传 1-100 的数字，如 `10` 表示占股 10% |
+
+---
+
+### business_info 业务信息
+
+| 字段 | 名称 | 必填 | 类型 | 说明 |
+|------|------|------|------|------|
+| `business_open_info` | 业务开通详情 | 是 | Object | 见下方 |
+
+#### business_open_info
+
+| 字段 | 名称 | 必填 | 类型 | 说明 |
+|------|------|------|------|------|
+| `business_platform` | 业务平台 | 是 | String | `HEEPAY`=汇付宝，`HEELIFE`=汇生活 |
+| `heepay_info` | 汇付宝信息 | 条件必填 | Object | `business_platform=HEEPAY` 时传入 |
+| `heelife_info` | 汇生活信息 | 条件必填 | Object | `business_platform=HEELIFE` 时传入 |
+
+#### heepay_info 汇付宝信息
+
+| 字段 | 名称 | 必填 | 类型 | 说明 |
+|------|------|------|------|------|
+| `operate_type` | 操作类型 | 是 | String | `OPEN_ORDINARY_MERCH`=开通普通户收单账户，`OPEN_BALANCE`=开通子户余额账户，`OPEN_MERCH`=开通子户收单账户，`APPEND_OPEN_PRODUCT`=补充开通产品；小微商户不支持 `OPEN_ORDINARY_MERCH` |
+| `scene_info` | 场景信息 | 条件必填 | Object | 收单账户必传 |
+| `heepay_ordinary` | 普通商户必须信息 | 条件必填 | Object | `operate_type=OPEN_ORDINARY_MERCH` 时必传 |
+| `product_info` | 产品费率信息 | 条件必填 | Object | `operate_type=OPEN_MERCH` 或 `APPEND_OPEN_PRODUCT` 时必传 |
+| `wechat_config` | 微信配置 | 否 | Object | 见下方 |
+| `wechat_enter` | 微信进件参数 | 否 | Object | 需要指定微信进件参数时传入 |
+| `alipay_enter` | 支付宝进件参数 | 否 | Object | 需要指定支付宝进件参数时传入 |
+
+#### scene_info 场景信息（收单账户必传）
+
+| 字段 | 名称 | 必填 | 类型 | 说明 |
+|------|------|------|------|------|
+| `shop_brand_img` | 商户品牌标识图片 | 是 | String | 企业传公司大楼照，个体/小微传门头照，传 `file_id` |
+| `customer_service_img` | 客户服务照 | 是 | String | 企业传公司前台照，个体/小微传收银台照，传 `file_id` |
+| `work_env_img` | 商户经营照 | 是 | String | 企业传内部办公场所照，个体/小微传店铺经营照，传 `file_id` |
+
+#### heepay_ordinary 普通商户必须信息（operate_type=OPEN_ORDINARY_MERCH 时必传）
+
+| 字段 | 名称 | 必填 | 类型 | 说明 |
+|------|------|------|------|------|
+| `app_type` | 应用类型 | 是 | String | `PC`，`APP`，`WAP`，`WECHAT_MINI`=微信小程序，`ALIPAY_MINI`=支付宝小程序，`WECHAT_PUBLIC_PLATFORM`=微信公众号，`QUICK_PASS`=云闪付，`OTHER`=其他线上场景 |
+| `app_name` | 应用名称 | 是 | String | 应用名称 |
+| `app_url` | 应用网址 | 条件必填 | String | `app_type` 为 PC/APP/WAP/WECHAT_MINI 时必填 |
+| `app_download_url` | 应用下载地址 | 条件必填 | String | `app_type` 为 PC/APP/WAP/WECHAT_MINI 时必填 |
+| `mini_app_id` | 小程序 APPID | 条件必填 | String | `app_type` 为 WECHAT_MINI/ALIPAY_MINI 时必填 |
+| `app_status` | 应用状态 | 是 | String | `OFFLINE`=未上线，`ONLINE`=已上线公开，`ONLINE_SPECIAL`=已上线特定IP/用户开放 |
+| `icp_url` | ICP 备案网址 | 条件必填 | String | `app_type` 为 PC/WAP 时必填 |
+| `business_types` | 业务种类 | 是 | Object[] | 支持多个，见下方 `business_types` 结构 |
+| `business_note` | 业务场景说明 | 是 | String | 业务场景说明 |
+
+`business_types` 单条结构：
+
+| 字段 | 名称 | 必填 | 类型 | 说明 |
+|------|------|------|------|------|
+| `business_type` | 业务种类 | 是 | String | 见下方枚举值 |
+
+`business_type` 枚举值：
+
+| 枚举值 | 说明 |
+|--------|------|
+| `PURCHASE_VIRTUAL_GOODS` | 虚拟商品购买 |
+| `PREPAID_ACCOUNT_CHARGE` | 预付费类账户充值 |
+| `MATERIAL_CONSUMPTION` | 实物消费 |
+| `AVIATION_BUSINESS_TRAVEL_EXPENSES` | 航空商旅消费 |
+| `L_C_CONSUMPTION` | 生活及商业消费服务 |
+| `OTHER_MERCH_CONSUMPTION` | 其他商户消费 |
+| `PAYMENT_PUBLIC_UTILITIES` | 公共事业缴费 |
+| `E_MEDICAL_PAYMENT` | 教育医疗缴费 |
+| `GOVERNMENT_PAYMENT` | 政府服务缴费 |
+| `PUBLIC_WELFARE_DONATION` | 公益捐款 |
+| `OTHER_PUBLIC_SERVICES` | 其他公共服务 |
+| `OTHER_FINANCIAL_PAYMENTS` | 其他金融付款 |
+| `FUND_PURCHASE` | 基金购买 |
+| `INSURANCE_PURCHASE` | 保险选购 |
+| `WEALTH_MANAGE` | 投资理财 |
+| `CREDIT_REPAYMENT` | 信贷偿还 |
+| `CREDIT_CARD_REPAYMENTS` | 信用卡还款转出 |
+| `RECHARGE_PAYMENT_ACCOUNT` | 支付账户充值 |
+| `BANK_ACCOUNT_TRANSFER_OUT` | 银行账户转账转出 |
+| `OTHER_ACCOUNT_CHARGE` | 其他账户充值 |
+| `SERVICE_TYPE` | 服务类 |
+| `SYSTEM_TYPE` | 系统类 |
+| `MANAGE_TYPE` | 管理类 |
+| `BID_BOND_PAYMENT` | 招投标保证金支付 |
+| `OVERSEAS_SHOPPING` | 境外商品购买 |
+| `business_img` | 经营服务图片 | 条件必填 | String | `app_type` 为 APP/WECHAT_MINI 时必填，传 `file_id` |
+| `ext_a_img` ~ `ext_e_img` | 附件 1-5 | 否 | String | 传 `file_id` |
+
+#### product_info 产品费率信息（operate_type=OPEN_MERCH 或 APPEND_OPEN_PRODUCT 时必传）
+
+| 字段 | 名称 | 必填 | 类型 | 说明 |
+|------|------|------|------|------|
+| `reference_merch_id` | 标杆商户编码 | 条件必填 | Long | 与 `rate_infos` 二选一 |
+| `rate_infos` | 费率列表 | 条件必填 | Object[] | 与 `reference_merch_id` 二选一 |
+
+`rate_infos` 单条结构：
+
+| 字段 | 名称 | 必填 | 类型 | 说明 |
+|------|------|------|------|------|
+| `rate_code` | 支付场景编码 | 是 | String | 参照【支付场景】列表 |
+| `rate_type` | 费率类型 | 是 | String(32) | `SINGLE_PERCENT`=单笔百分比，`SINGLE_FIXED`=单笔固定值 |
+| `rate` | 费率值 | 是 | String(5) | 费率值 |
+
+#### wechat_config 微信配置（选填）
+
+| 字段 | 名称 | 必填 | 类型 | 说明 |
+|------|------|------|------|------|
+| `app_ids` | appId 列表 | 否 | Object[] | appId 列表 |
+| `pay_urls` | 支付授权目录列表 | 否 | Object[] | 支付授权目录列表 |
+
+#### wechat_enter 微信进件参数（选填）
+
+| 字段 | 名称 | 必填 | 类型 | 说明 |
+|------|------|------|------|------|
+| `channel_code` | 进件渠道号 | 是 | String | 进件渠道号 |
+
+#### alipay_enter 支付宝进件参数（选填）
+
+| 字段 | 名称 | 必填 | 类型 | 说明 |
+|------|------|------|------|------|
+| `channel_code` | 进件渠道号 | 是 | String | 进件渠道号 |
+
+#### heelife_info 汇生活信息（business_platform=HEELIFE 时传入）
+
+| 字段 | 名称 | 必填 | 类型 | 说明 |
+|------|------|------|------|------|
+| `operate_type` | 操作类型 | 是 | String | 指明业务类型（具体枚举值待补充） |
+
+---
+
+## 响应业务参数
+
+| 字段 | 名称 | 必填 | 类型 | 说明 |
+|------|------|------|------|------|
+| `request_no` | 商户申请流水号 | 是 | String | 后续查询（接口 003）和修改（接口 004）时使用 |
+
+---
+
+## 业务错误码
+
+| 错误码 | 说明 | 处理建议 |
+|--------|------|---------|
+| `invalid_parameter_email_existed` | 汇元已存在此邮箱 | 更换邮箱 |
+| `invalid_parameter_email_except` | 邮箱校验异常 | 检查参数 |
+| `invalid_parameter_enterprise_type_ex` | 企业用户只支持对公账户 | 检查 `account_type` |
+| `invalid_parameter_micro_type_ex` | 小微用户只支持对私账户 | 检查 `account_type` |
+| `invalid_parameter_ubo_must_not_empty` | 受益人不能为空 | 传入 `ubo_infos` |
+| `invalid_parameter_rate_must_not_empty` | 开通收单账户费率信息不能为空 | 检查 `product_info` |
+| `invalid_parameter_common_must_not_empty` | 开通普通户必须信息不能为空 | 检查 `heepay_ordinary` |
+| `invalid_parameter_mark_merch_not_existed` | 标杆商户未配置 | 联系汇元配置 |
+| `business_fail_customer_has_passed` | 商户已入驻完毕 | 确认 `request_no` 是否已用过 |
+| `business_fail_customer_waiting` | 入驻申请处理中 | 等待审核结果 |
+| `business_fail_save_his_work_record_fail` | 迁移创建历史入驻工单失败 | 重试 |
+| `business_fail_delete_his_work_record_fail` | 迁移删除历史入驻工单失败 | 重试 |
+| `business_fail_save_work_record_fail` | 保存入驻记录失败 | 重试 |
+| `unknown_exception` | 系统未知问题 | 参考返回描述 |
+| `unknown_error_gateway` | 网关系统不可用 | 稍后重试 |
+| `invalid_auth` | 授权权限不足 | 检查签名/权限 |
+| `missing_parameter` | 缺少参数 | 补充必填参数 |
+| `invalid_parameter` | 无效参数 | 检查参数格式 |
+| `invalid_request` | 无效请求 | 参考返回详细信息 |
+| `biz_failure` | 业务错误 | 参照具体错误提示 |
+| `service_not_exists` | 服务不存在 | 确认服务是否开通 |
+| `service_time_out` | 系统繁忙 | 稍后重试 |
+| `channel_error` | 通道系统异常 | 用相同参数重新调用 |
+
+---
+
+## 实现要点
+
+1. **网关地址**：使用 `channels.heepay.merchant_url`（进件网关），而非支付网关
+2. **图片先传后用**：所有 `*_img` 字段均为 `file_id`，依赖接口 002（文件上传）
+3. **受益人条件必填**：`identity_info.belong_ubo=false` 时，`ubo_infos` 数组必传
+4. **operate_type 决定必填子结构**：
+   - `OPEN_MERCH` / `APPEND_OPEN_PRODUCT` → `product_info` 必传
+   - `OPEN_ORDINARY_MERCH` → `heepay_ordinary` 必传
+   - 收单账户 → `scene_info` 必传
+5. **费率二选一**：`product_info` 中 `reference_merch_id` 和 `rate_infos` 二选一
+6. **返回 request_no**：作为查询（接口 003）和修改（接口 004）的入参，需持久化存储
+
+---
+
+## 待补充
+
+- [ ] `heelife_info.operate_type` 枚举值（暂不支持汇生活，低优先级）
+- [ ] `wechat_config.app_ids` 和 `pay_urls` 单条结构字段
+- [ ] 省市区县编码（建议用行政区划查询接口在线获取，无需维护静态列表）
+
+## 附录文档
+
+- MCC 经营类目编码 → `appendix-mcc-codes.md`
+- 银行列表 → `appendix-bank-codes.md`
+- 国家编码 → `appendix-nation-codes.md`
+- 支付场景编码 → `appendix-payment-scene-codes.md`

docs/design/002-heepay-customer-file-upload.md

@@ -0,0 +1,135 @@
+# 002 - 汇元商户文件上传 API
+
+**接口名称：** `customer.file.upload`
+**更新时间：** 2025-11-28
+**状态：** 已实现
+
+---
+
+## 调用地址
+
+| 环境 | 地址 |
+|------|------|
+| 生产 | `https://openapi.heepay.com/v1/customer/gateway` |
+| 沙箱 | `http://openapi.heepaydev.com/v1/customer/gateway` |
+
+与入网接口共用同一进件网关（`channels.heepay.merchant_url`）。
+
+---
+
+## 接口说明
+
+上传图片/视频/文件，返回 `file_id`，供入网接口（001）中所有 `*_img` 字段使用。**必须先上传文件获取 `file_id`，再调用入网接口。**
+
+---
+
+## 请求业务参数（biz_content）
+
+| 字段 | 名称 | 必填 | 类型 | 说明 |
+|------|------|------|------|------|
+| `file_content` | 文件内容 | 是 | ByteData | 文件二进制内容（Base64 编码后传入） |
+| `file_sign` | 文件内容签名 | 是 | String | 文件内容的 MD5 值，用于校验文件完整性 |
+| `file_media_type` | 文件类型 | 是 | String | 参照【文件类型编码】列表（待补充） |
+
+---
+
+## 响应业务参数
+
+| 字段 | 名称 | 必填 | 类型 | 说明 |
+|------|------|------|------|------|
+| `file_id` | 文件 ID | 否 | String | 上传成功后返回，传入入网接口的 `*_img` 字段 |
+
+---
+
+## 支持的文件格式
+
+| 类型 | 格式 |
+|------|------|
+| 图片 | `png` / `bmp` / `gif` / `jpg` / `jpeg` |
+| 视频 | `mp4` / `flv` / `avi` / `rm` / `rmvb` / `wav` |
+| 文件 | `zip` / `rar` / `pdf` |
+
+---
+
+## 业务错误码
+
+| 错误码 | 说明 | 处理建议 |
+|--------|------|---------|
+| `invalid_parameter_file_type_not_correct` | 文件类型不正确 | 检查格式是否在支持列表内 |
+| `invalid_parameter_file_size_too_big` | 文件过大 | 压缩后重新上传 |
+| `invalid_parameter_file_sign_can_not_null` | 文件签名不能为空 | 传入 `file_sign`（MD5） |
+| `invalid_parameter_file_sign_err` | 文件签名异常 | 确认文件是否损坏，重新计算 MD5 |
+| `invalid_parameter_file_has_err` | file 有误，疑似被修改 | 检查文件完整性 |
+| `invalid_parameter_file_need_ext` | 文件名需带扩展名 | 上传时文件名需包含扩展名 |
+| `unknown_exception` | 系统未知问题 | 参考返回描述 |
+| `unknown_error_gateway` | 网关系统不可用 | 稍后重试 |
+| `invalid_auth` | 授权权限不足 | 检查签名/权限 |
+| `missing_parameter` | 缺少参数 | 补充必填参数 |
+| `invalid_parameter` | 无效参数 | 检查参数格式 |
+| `invalid_request` | 无效请求 | 参考返回详细信息 |
+| `biz_failure` | 业务错误 | 参照具体错误提示 |
+| `service_not_exists` | 服务不存在 | 确认服务是否开通 |
+| `service_time_out` | 系统繁忙 | 稍后重试 |
+| `channel_error` | 通道系统异常 | 用相同参数重新调用 |
+
+---
+
+## 实现要点
+
+1. **`file_content` 编码方式**：ByteData 类型，实现时需将文件二进制内容 Base64 编码后放入 `biz_content` JSON 字符串中
+2. **`file_sign` 计算**：对原始文件二进制内容计算 MD5，得到 32 位小写十六进制字符串
+3. **文件名带扩展名**：请求中需要携带文件名（含扩展名），具体字段名待联调确认
+4. **调用顺序**：文件上传 → 获取 `file_id` → 入网申请（001），`file_id` 需持久化存储备用
+5. **复用性**：同一文件可上传一次，`file_id` 在多个字段中复用（如法人正反面同一人时）
+
+---
+
+## 文件类型编码（file_media_type）
+
+| 文件名称 | 类型值 |
+|---------|--------|
+| 营业执照 | `01` |
+| 开户许可证/开户证明照 | `02` |
+| 门头照 | `03` |
+| 店内场景照 | `04` |
+| 收银台照 | `05` |
+| 法人身份证正面照 | `06` |
+| 法人身份证反面照 | `07` |
+| 联系人身份证正面照 | `08` |
+| 联系人身份证反面照 | `09` |
+| 公司大楼照 | `10` |
+| 公司前台照 | `11` |
+| 结算银行卡正面照 | `12` |
+| 结算银行卡反面照 | `13` |
+| 结算人手持银行卡正面照 | `14` |
+| 经营者身份证正面照 | `15` |
+| 经营者身份证反面照 | `16` |
+| 经营者手持身份证正面照 | `17` |
+| 经营者手持银行卡正面照 | `18` |
+| 其它图片1 | `19` |
+| 其它图片2 | `20` |
+| 开户意愿视频 | `50` |
+| 分账协议 | `52` |
+
+> 对照入网接口（001）字段与文件类型的映射关系：
+>
+> | 入网字段 | file_media_type |
+> |---------|----------------|
+> | `subject_info.cert_img`（营业执照） | `01` |
+> | `settlement_info.open_account_img`（开户许可证） | `02` |
+> | `scene_info.shop_brand_img`（门头照/公司大楼照） | `03` 或 `10` |
+> | `scene_info.customer_service_img`（收银台照/公司前台照） | `05` 或 `11` |
+> | `scene_info.work_env_img`（店内场景照） | `04` |
+> | `identity_info.cert_front_img`（法人证件正面） | `06` |
+> | `identity_info.cert_back_img`（法人证件反面） | `07` |
+> | `contact_info.cert_front_img`（联系人证件正面） | `08` |
+> | `contact_info.cert_back_img`（联系人证件反面） | `09` |
+> | `addition_info.open_merch_video`（开户意愿视频） | `50` |
+> | `addition_info.sharing_protocol_img`（分账协议） | `52` |
+
+---
+
+## 待补充
+
+- [ ] 文件大小限制（图片/视频各自上限）
+- [ ] 文件名字段名称确认（`file_name`？）

docs/design/appendix-bank-codes.md

@@ -0,0 +1,270 @@
+# 附录 - 银行列表
+
+使用场景：商户入网接口（001）`settlement_info.bank_name` 字段传入。
+
+> **注意**：请按以下银行名称严格匹配传入。若找不到具体支行名称，按大行名称传入即可。
+> 例如：「中国建设银行股份有限公司宿迁宿豫支行」→ 传入「建设银行」
+
+---
+
+## 结算银行列表（入网使用）
+
+| 编码 | 银行名称 |
+|------|---------|
+| 1 | 工商银行 |
+| 2 | 建设银行 |
+| 3 | 农业银行 |
+| 4 | 邮政储蓄银行 |
+| 5 | 中国银行 |
+| 6 | 交通银行 |
+| 7 | 招商银行 |
+| 8 | 光大银行 |
+| 9 | 浦发银行 |
+| 10 | 华夏银行 |
+| 11 | 广东发展银行 |
+| 12 | 中信银行 |
+| 13 | 兴业银行 |
+| 14 | 民生银行 |
+| 15 | 杭州银行 |
+| 16 | 上海银行 |
+| 17 | 宁波银行 |
+| 18 | 平安银行 |
+| 19 | 东亚银行 |
+| 20 | 上海农村商业银行 |
+| 21 | 南京银行 |
+| 22 | 广州银行 |
+| 23 | 渤海银行 |
+| 24 | 大连银行 |
+| 25 | 徽商银行 |
+| 26 | 江苏银行 |
+| 27 | 齐鲁银行 |
+| 28 | 渣打银行 |
+| 29 | 深圳农村商业银行 |
+| 30 | 温州银行 |
+| 31 | 厦门银行 |
+| 32 | 浙商银行 |
+| 33 | 北京银行 |
+| 34 | 哈尔滨银行 |
+| 35 | 湖北银行 |
+| 36 | 潍坊银行 |
+| 37 | 贵阳银行 |
+| 38 | 浙江泰隆商业银行 |
+| 39 | 济宁银行 |
+| 40 | 台州银行 |
+| 41 | 汉口银行 |
+| 42 | 安徽省农村信用社联合社 |
+| 43 | 郑州银行 |
+| 44 | 中原银行 |
+| 45 | 宜宾商业银行 |
+| 46 | 莱商银行 |
+| 47 | 日照银行 |
+| 48 | 常熟农商银行 |
+| 49 | 北京农商银行 |
+| 50 | 福建省农村信用社联合社 |
+| 51 | 齐商银行 |
+| 52 | 云南省农村信用社联合社 |
+| 53 | 山东省农村信用社联合社 |
+| 54 | 广东华兴银行 |
+| 55 | 江西银行 |
+| 56 | 东营银行 |
+| 57 | 浙江稠州商业银行 |
+| 58 | 重庆农村商业银行 |
+| 59 | 晋城银行 |
+| 60 | 秦农银行 |
+| 61 | 长安银行 |
+| 62 | 成都银行 |
+| 63 | 恒丰银行 |
+| 64 | 承德银行 |
+| 65 | 绍兴银行 |
+| 66 | 广东南粤银行 |
+| 67 | 青岛银行 |
+| 68 | 江苏长江商行 |
+| 69 | 包商银行 |
+| 70 | 富滇银行 |
+| 71 | 自贡市商业银行 |
+| 72 | 湖北农信 |
+| 73 | 浙江农信 |
+| 74 | 葫芦岛银行 |
+| 75 | 昆仑银行 |
+| 76 | 苏州银行 |
+| 77 | 湖州银行 |
+| 78 | 泉州银行 |
+| 79 | 广州农村商业银行 |
+| 81 | 太仓农村商业银行 |
+| 82 | 烟台银行 |
+| 83 | 上饶银行 |
+| 84 | 绵阳市商业银行 |
+| 85 | 德州银行 |
+| 86 | 广西农村信用社 |
+| 87 | 柳州银行 |
+| 88 | 新韩银行中国 |
+| 89 | 长沙银行 |
+| 90 | 黄河农村商业银行 |
+| 91 | 鞍山银行 |
+| 92 | 龙江银行 |
+| 93 | 河北银行 |
+| 94 | 内蒙古银行 |
+| 95 | 吉林农村信用社 |
+| 96 | 浙江三门银座村镇银行 |
+| 97 | 东莞银行 |
+| 98 | 泰安银行 |
+| 99 | 桂林银行股份有限公司 |
+| 100 | 昆山农村商业银行 |
+| 101 | 攀枝花市商业银行 |
+| 102 | 西安银行 |
+| 103 | 营口银行 |
+| 104 | 江苏省农村信用社联合社 |
+| 105 | 顺德农村商业银行 |
+| 106 | 张家港农村商业银行 |
+| 107 | 重庆黔江银座村镇银行 |
+| 108 | 临商银行 |
+| 109 | 洛阳银行 |
+| 110 | 邢台银行 |
+| 111 | 韩亚银行 |
+| 112 | 广西北部湾银行 |
+| 113 | 张家口市商业银行 |
+| 114 | 珠海华润银行 |
+| 115 | 天津银行 |
+| 116 | 阜新银行 |
+| 117 | 吴江农村商业银行 |
+| 118 | 友利银行 |
+| 119 | 北京顺义银座村镇银行 |
+| 120 | 晋商银行 |
+| 121 | 赣州银行 |
+| 122 | 鄞州银行 |
+| 123 | 兰州银行 |
+| 124 | 锦州银行 |
+| 125 | 邯郸市商业银行 |
+| 126 | 深圳福田银座村镇银行 |
+| 127 | 东莞农村商业银行 |
+| 128 | 乌鲁木齐市商业银行 |
+| 129 | 浙江景宁银座村镇银行 |
+| 130 | 威海市商业银行 |
+| 131 | 海南农村商业银行股份有限公司 |
+| 132 | 商丘银行 |
+| 133 | 鄂尔多斯银行 |
+| 134 | 江西赣州银座村镇银行 |
+| 135 | 天津农商银行 |
+| 136 | 重庆银行 |
+| 137 | 宁夏银行 |
+| 138 | 浙江民泰商业银行 |
+| 140 | 长城华西银行 |
+| 141 | 廊坊银行 |
+| 142 | 沧州银行 |
+| 143 | 福建海峡银行 |
+| 144 | 嘉兴银行 |
+| 145 | 吉林银行 |
+| 146 | 青海银行 |
+| 147 | 重庆渝北银座村镇银行 |
+| 148 | 枣庄银行 |
+| 149 | 武汉农村商业银行 |
+| 150 | 重庆三峡银行 |
+| 151 | 南洋商业银行 |
+| 152 | 恒生银行 |
+| 153 | 集友银行 |
+| 154 | 大众银行 |
+| 155 | 永亨银行 |
+| 156 | 上海商业银行 |
+| 157 | 永隆银行 |
+| 158 | 中信嘉华银行 |
+| 159 | 华南商业银行 |
+| 161 | 保定银行 |
+| 162 | 上海华瑞银行 |
+| 163 | 九江银行 |
+| 164 | 江西省农村信用社 |
+| 165 | 广东省农村信用社联合社 |
+| 166 | 河南省农村信用社 |
+| 167 | 辽宁省农村信用社 |
+| 168 | 黑龙江省农村信用社 |
+| 169 | 湖南省农村信用社 |
+| 170 | 河北省农村信用社 |
+| 171 | 甘肃省农村信用社 |
+| 172 | 山西省农村信用社 |
+| 173 | 陕西省农村信用社 |
+| 174 | 贵州省农村信用社 |
+| 175 | 内蒙古自治区农村信用社 |
+| 176 | 新疆自治区农村信用社 |
+| 177 | 四川省农村信用社 |
+| 178 | 成都农商银行 |
+| 179 | 长沙农商银行 |
+| 180 | 三亚农商银行 |
+| 221 | 国家开发银行 |
+| 224 | 汇丰银行 |
+| 239 | 网商银行 |
+| 246 | 武汉众邦银行 |
+| 310 | 中国农业发展银行 |
+| 432 | 深圳前海微众银行股份有限公司 |
+| 473 | 北京中关村银行股份有限公司 |
+| 480 | 吉林亿联银行股份有限公司 |
+| 483 | 四川新网银行股份有限公司 |
+| 492 | 重庆富民银行股份有限公司 |
+| 546 | 四川银行股份有限公司 |
+| 584 | 江苏苏商银行股份有限公司 |
+| 695 | 山西银行股份有限公司 |
+| 720 | 花旗银行（中国）有限公司 |
+| 777 | 摩根大通银行(中国)有限公司 |
+| 948 | 宁波东海银行股份有限公司 |
+
+> 完整列表共 800+ 条，上方仅列出主要银行。如需完整列表请查阅汇元客户中心银行列表 Excel（对接群 @客服督导获取），该列表更新更及时。
+
+---
+
+## 网银支持银行列表
+
+用于网银支付场景的银行编码（与结算银行编码体系不同）。
+
+| 编码 | 银行名称 |
+|------|---------|
+| 001 | 中国工商银行 |
+| 003 | 中国建设银行 |
+| 005 | 中国农业银行 |
+| 006 | 交通银行 |
+| 008 | 广东发展银行 |
+| 009 | 中信银行 |
+| 010 | 中国光大银行 |
+| 011 | 兴业银行 |
+| 012 | 平安银行 |
+| 013 | 中国民生银行 |
+| 014 | 华夏银行 |
+| 020 | 中国邮政储蓄银行 |
+| 022 | 上海银行 |
+| 024 | 宁波银行 |
+| 029 | 北京农商银行 |
+| 035 | 渤海银行 |
+| 044 | 浙商银行 |
+| 045 | 北京银行 |
+
+### 企业网银
+
+| 编码 | 银行名称 |
+|------|---------|
+| 030 | 农业银行（企业银行） |
+| 046 | 中信银行（企业银行） |
+| 047 | 招商银行（企业银行） |
+| 048 | 中国建设银行（企业银行） |
+| 049 | 上海浦东发展银行（企业银行） |
+| 050 | 中国银行（企业银行） |
+| 051 | 广发银行（企业银行） |
+| 052 | 北京银行（企业银行） |
+| 053 | 中国邮政储蓄银行（企业银行） |
+| 054 | 中国工商银行（企业银行） |
+| 055 | 中国民生银行（企业银行） |
+| 056 | 中国光大银行（企业银行） |
+| 057 | 上海银行（企业银行） |
+| 058 | 平安银行（企业银行） |
+| 059 | 宁波银行（企业银行） |
+| 060 | 华夏（企业银行） |
+| 061 | 浙商银行（企业银行） |
+| 062 | 交通银行（企业银行） |
+| 063 | 柳州银行（企业银行） |
+| 066 | 桂林银行（企业银行） |
+| 068 | 杭州银行（企业银行） |
+| 071 | 齐鲁银行（企业银行） |
+
+---
+
+## 注意事项
+
+1. **两套编码体系相互独立**：结算银行列表（数字编码 1-950+）用于入网 `bank_name` 字段；网银支持列表（3位字符编码 001-071）用于网银支付场景，勿混用
+2. **结算银行传名称**：`settlement_info.bank_name` 传银行名称字符串，不传编码
+3. **编码存在跳号**：如结算列表中无 80、139、160 等编号，属正常现象

docs/design/appendix-mcc-codes.md

@@ -0,0 +1,179 @@
+# 附录 - MCC 经营类目编码
+
+使用场景：商户入网接口（001）`base_info.mcc` 字段传入。
+
+> 小微商户：使用企业或个体户对应行业的编码即可。
+
+## 企业 - 线上业务
+
+适用于游戏、网络虚拟、电商团购、财经资讯、众筹、电信运营商、机票、共享服务、网购平台、O2O 平台、信用还款等。
+
+| 行业细分 | 编码 |
+|---------|------|
+| 线上商超 | 1000 |
+| 在线教育培训机构 | 1001 |
+| 人才中介机构/招聘/猎头 | 1002 |
+| 职业社交/婚介/交友 | 1003 |
+| 机票/机票代理 | 1004 |
+| 在线图书/视频/音乐 | 1005 |
+| 门户/资讯/论坛 | 1006 |
+| 网络直播 | 1008 |
+| 软件/建站/技术开发 | 1009 |
+| 网络推广/网络广告 | 1010 |
+| 综合生活服务平台 | 1011 |
+| 电信运营商 | 1012 |
+| 宽带收费 | 1013 |
+| 信用还款 | 1014 |
+| 其他 | 1015 |
+
+## 企业 - 保险
+
+适用于保险公司、保险代理公司。
+
+| 行业细分 | 编码 |
+|---------|------|
+| 保险业务 | 1016 |
+
+## 企业 - 线下实体
+
+适用于餐饮、零售批发、交通出行、生活娱乐服务、民营医疗机构、缴费、加油、物流快递等。
+
+| 行业细分 | 编码 |
+|---------|------|
+| 餐饮 | 1017 |
+| 超市 | 1018 |
+| 便利店 | 1019 |
+| 百货 | 1020 |
+| 食品生鲜 | 1021 |
+| 数码电器/电脑办公 | 1022 |
+| 家具建材/家居厨具 | 1023 |
+| 服饰箱包 | 1024 |
+| 运动户外 | 1025 |
+| 美妆个护 | 1026 |
+| 母婴用品/儿童玩具 | 1027 |
+| 图书音像/文具乐器 | 1028 |
+| 黄金珠宝 | 1029 |
+| 钟表眼镜 | 1030 |
+| 宠物/宠物用品 | 1031 |
+| 礼品鲜花/农资绿植 | 1032 |
+| 物流/快递 | 1033 |
+| 咨询/法律咨询/金融咨询等 | 1034 |
+| 婚庆/摄影 | 1035 |
+| 装饰/设计 | 1036 |
+| 家政/维修服务 | 1037 |
+| 广告/会展/活动策划 | 1038 |
+| 房地产 | 1039 |
+| 丧仪殡葬服务 | 1040 |
+| 宠物医院 | 1041 |
+| 娱乐票务 | 1042 |
+| 运动健身场馆 | 1043 |
+| 俱乐部/休闲会所 | 1044 |
+| 院线影城 | 1045 |
+| 演出赛事 | 1046 |
+| 美发/美容/美甲店 | 1047 |
+| 酒吧 | 1048 |
+| 租车 | 1049 |
+| 加油 | 1050 |
+| 船舶/海运服务 | 1051 |
+| 铁路客运 | 1052 |
+| 旅行社 | 1053 |
+| 汽车用品 | 1054 |
+| 汽车美容/维修保养 | 1055 |
+| 停车缴费 | 1056 |
+| 旅馆/酒店/度假区 | 1057 |
+| 景区 | 1058 |
+| 宗教 | 1059 |
+| 教育/培训/考试缴费/学费 | 1060 |
+| 诊所/卫生站/卫生服务中心 | 1061 |
+| 私立/民营医院/诊所 | 1062 |
+| 有线电视缴费 | 1063 |
+| 话费通讯 | 1064 |
+| 拍卖/典当 | 1065 |
+| 其他 | 1066 |
+
+## 企业 - 民办教育
+
+| 行业细分 | 编码 |
+|---------|------|
+| 民办大学及学院 | 1067 |
+| 民办中小幼 | 1068 |
+
+## 企业 - 民生缴费 / 交通
+
+适用于水电煤暖气民生缴费、交通罚款、公交/高速。
+
+| 行业细分 | 编码 |
+|---------|------|
+| 高速收费 | 1069 |
+| 城市公共交通 | 1070 |
+| 公共事业（水、电、燃气、供暖） | 1071 |
+| 游戏 | 1073 |
+
+## 个体户 - 线上业务
+
+适用于电商团购、电信运营商/宽带收费、机票/机票代理。
+
+| 行业细分 | 编码 |
+|---------|------|
+| 机票/机票代理 | 1074 |
+| 线上商超 | 1075 |
+| 综合生活服务平台 | 1076 |
+
+## 个体户 - 线下实体
+
+适用于餐饮、零售批发、交通出行、生活娱乐服务、民营医疗机构、缴费等。
+
+| 行业细分 | 编码 |
+|---------|------|
+| 餐饮 | 1077 |
+| 超市 | 1078 |
+| 便利店 | 1079 |
+| 百货 | 1080 |
+| 食品生鲜 | 1081 |
+| 数码电器/电脑办公 | 1082 |
+| 家具建材/家居厨具 | 1083 |
+| 服饰箱包 | 1084 |
+| 运动户外 | 1085 |
+| 美妆个护 | 1086 |
+| 母婴用品/儿童玩具 | 1087 |
+| 图书音像/文具乐器 | 1088 |
+| 黄金珠宝 | 1089 |
+| 钟表 | 1090 |
+| 宠物/宠物用品 | 1091 |
+| 礼品鲜花/农资绿植 | 1092 |
+| 眼镜 | 1093 |
+| 物流/快递 | 1094 |
+| 咨询/法律咨询/金融咨询等 | 1095 |
+| 婚庆/摄影 | 1096 |
+| 装饰/设计 | 1097 |
+| 家政/维修服务 | 1098 |
+| 广告/会展/活动策划 | 1099 |
+| 丧仪殡葬服务 | 1100 |
+| 宠物医院 | 1101 |
+| 娱乐票务 | 1102 |
+| 运动健身场馆 | 1103 |
+| 俱乐部/休闲会所 | 1104 |
+| 院线影城 | 1105 |
+| 演出赛事 | 1106 |
+| 美发/美容/美甲店 | 1107 |
+| 酒吧 | 1108 |
+| 租车 | 1109 |
+| 加油 | 1110 |
+| 船舶/海运服务 | 1111 |
+| 汽车用品 | 1112 |
+| 汽车美容/维修保养 | 1113 |
+| 停车缴费 | 1114 |
+| 旅馆/酒店/度假区 | 1115 |
+| 景区 | 1116 |
+| 教育/培训/考试缴费/学费 | 1117 |
+| 保健器械/医疗器械/非处方药品 | 1118 |
+| 诊所/卫生站/卫生服务中心 | 1119 |
+| 私立/民营医院/诊所 | 1120 |
+| 有线电视缴费 | 1121 |
+| 话费通讯 | 1122 |
+| 拍卖/典当 | 1123 |
+| 其他 | 1124 |
+
+## 小微商户
+
+使用企业或个体户对应行业编码（1000-1124）均可。

docs/design/appendix-nation-codes.md

@@ -0,0 +1,145 @@
+# 附录 - 国家编码
+
+使用场景：商户入网接口（001）以下字段传入：
+- `identity_info.nation`（法人国籍）
+- `contact_info.nation`（业务联系人国籍）
+- `ubo_infos[].nation`（受益所有人国籍）
+
+| 编码 | 国家/地区名称 |
+|------|-------------|
+| 1 | 中国大陆 |
+| 2 | 中国香港 |
+| 3 | 中国澳门 |
+| 4 | 中国台湾地区 |
+| 5 | 马来西亚 |
+| 6 | 新加坡 |
+| 7 | 日本 |
+| 8 | 韩国 |
+| 9 | 美国 |
+| 10 | 加拿大 |
+| 11 | 澳大利亚 |
+| 12 | 新西兰 |
+| 13 | 阿尔巴尼亚 |
+| 14 | 阿根廷 |
+| 15 | 阿联酋 |
+| 16 | 阿曼 |
+| 17 | 阿塞拜疆 |
+| 18 | 爱尔兰 |
+| 19 | 埃及 |
+| 20 | 爱沙尼亚 |
+| 21 | 安哥拉 |
+| 22 | 奥地利 |
+| 23 | 巴布亚新几内亚 |
+| 24 | 巴哈马 |
+| 25 | 巴勒斯坦 |
+| 26 | 巴林 |
+| 27 | 巴拿马 |
+| 28 | 巴西 |
+| 29 | 白俄罗斯 |
+| 30 | 保加利亚 |
+| 31 | 贝宁 |
+| 32 | 比利时 |
+| 33 | 秘鲁 |
+| 34 | 波兰 |
+| 35 | 玻利维亚 |
+| 36 | 伯利兹 |
+| 37 | 布基纳法索 |
+| 38 | 赤道几内亚 |
+| 39 | 丹麦 |
+| 40 | 德国 |
+| 41 | 多哥 |
+| 42 | 俄罗斯 |
+| 43 | 法国 |
+| 44 | 菲律宾 |
+| 45 | 芬兰 |
+| 46 | 佛得角 |
+| 47 | 冈比亚 |
+| 48 | 格林纳达 |
+| 49 | 格鲁吉亚 |
+| 50 | 哥伦比亚 |
+| 51 | 哥斯达黎加 |
+| 52 | 圭亚那 |
+| 53 | 荷兰 |
+| 54 | 洪都拉斯 |
+| 55 | 吉布提 |
+| 56 | 吉尔吉斯斯坦 |
+| 57 | 几内亚 |
+| 58 | 几内亚比绍 |
+| 59 | 加蓬 |
+| 60 | 柬埔寨 |
+| 61 | 津巴布韦 |
+| 62 | 喀麦隆 |
+| 63 | 卡塔尔 |
+| 64 | 开曼群岛 |
+| 65 | 克罗地亚 |
+| 66 | 科摩罗 |
+| 67 | 科威特 |
+| 68 | 肯尼亚 |
+| 69 | 拉脱维亚 |
+| 70 | 莱索托 |
+| 71 | 立陶宛 |
+| 72 | 卢森堡 |
+| 73 | 卢旺达 |
+| 74 | 罗马尼亚 |
+| 75 | 马达加斯加 |
+| 76 | 马尔代夫 |
+| 77 | 马拉维 |
+| 78 | 马里 |
+| 79 | 毛里求斯 |
+| 80 | 毛里塔尼亚 |
+| 81 | 蒙古 |
+| 82 | 摩尔多瓦 |
+| 83 | 摩洛哥 |
+| 84 | 莫桑比克 |
+| 85 | 墨西哥 |
+| 86 | 纳米比亚 |
+| 87 | 南非 |
+| 88 | 尼加拉瓜 |
+| 89 | 尼日尔 |
+| 90 | 尼日利亚 |
+| 91 | 挪威 |
+| 92 | 葡萄牙 |
+| 93 | 瑞典 |
+| 94 | 瑞士 |
+| 95 | 萨尔瓦多 |
+| 96 | 塞尔维亚 |
+| 97 | 塞拉利昂 |
+| 98 | 塞内加尔 |
+| 99 | 塞浦路斯 |
+| 100 | 塞舌尔 |
+| 101 | 沙特阿拉伯 |
+| 102 | 斯里兰卡 |
+| 103 | 斯洛伐克 |
+| 104 | 斯洛文尼亚 |
+| 105 | 斯威士兰 |
+| 106 | 苏里南 |
+| 107 | 塔吉克斯坦 |
+| 108 | 泰国 |
+| 109 | 坦桑尼亚 |
+| 110 | 特立尼达和多巴哥 |
+| 111 | 土耳其 |
+| 112 | 土库曼斯坦 |
+| 113 | 突尼斯 |
+| 114 | 危地马拉 |
+| 115 | 委内瑞拉 |
+| 116 | 文莱 |
+| 117 | 乌干达 |
+| 118 | 乌克兰 |
+| 119 | 乌拉圭 |
+| 120 | 乌兹别克斯坦 |
+| 121 | 西班牙 |
+| 122 | 希腊 |
+| 123 | 匈牙利 |
+| 124 | 牙买加 |
+| 125 | 也门 |
+| 126 | 意大利 |
+| 127 | 以色列 |
+| 128 | 印度 |
+| 129 | 印度尼西亚 |
+| 130 | 英国 |
+| 131 | 英属维尔京群岛 |
+| 132 | 约旦 |
+| 133 | 越南 |
+| 134 | 赞比亚 |
+| 135 | 乍得 |
+| 136 | 智利 |

docs/design/appendix-payment-scene-codes.md

@@ -0,0 +1,175 @@
+# 附录 - 支付场景编码
+
+使用场景：商户入网接口（001）`business_info.business_open_info.heepay_info.product_info.rate_infos[].rate_code` 字段传入。
+
+---
+
+## 支付场景列表
+
+### 账户类
+
+| 支付场景名称 | 编码 |
+|------------|------|
+| 个人账户余额 | `PERSON_BALANCE_PAY` |
+| 商家余额支付 | `MERCH_BALANCE_PAY` |
+| 商家余额代收 | `MERCH_BALANCE_RECEIVE` |
+| 个人卡包支付 | `PERSON_CARD_PAY` |
+| 商家卡包支付 | `MERCH_CARD_PAY` |
+
+### 银联控件支付
+
+| 支付场景名称 | 编码 |
+|------------|------|
+| 手机 Wap 借记卡 | `UNIPAY_WAP_DEBIT` |
+| 手机 Wap 贷记卡 | `UNIPAY_WAP_CREDIT` |
+
+### 网银支付（B2C）
+
+| 支付场景名称 | 编码 |
+|------------|------|
+| 网银支付 | `BANK_ONLINE_B2C` |
+| 网银借记卡 | `BANK_ONLINE_DEBIT` |
+| 网银贷记卡 | `BANK_ONLINE_CREDIT` |
+| 网银支付（通用） | `BANK_ONLINE` |
+
+### 网银支付（B2B 企业银行）
+
+| 支付场景名称 | 编码 |
+|------------|------|
+| 网银支付 B2B（通用） | `BANK_ONLINE_B2B` |
+| 平安企业银行 | `BANK_ONLINE_SPABANK` |
+| 浦发企业银行 | `BANK_ONLINE_SPDB` |
+| 建设企业银行 | `BANK_ONLINE_CCB` |
+| 农业企业银行 | `BANK_ONLINE_ABC` |
+| 邮储企业银行 | `BANK_ONLINE_PSBC` |
+| 中行企业银行 | `BANK_ONLINE_BOC` |
+| 招商企业银行 | `BANK_ONLINE_CMB` |
+| 广发企业银行 | `BANK_ONLINE_GDB` |
+| 中信企业银行 | `BANK_ONLINE_CITIC` |
+| 民生企业银行 | `BANK_ONLINE_CMBC` |
+| 交通企业银行 | `BANK_ONLINE_COMM` |
+| 杭州企业银行 | `BANK_ONLINE_HZCB` |
+| 宁波企业银行 | `BANK_ONLINE_NBBANK` |
+| 光大企业银行 | `BANK_ONLINE_CEB` |
+| 北京企业银行 | `BANK_ONLINE_BJBANK` |
+| 工商企业银行 | `BANK_ONLINE_ICBC` |
+
+### 支付宝支付
+
+| 支付场景名称 | 编码 |
+|------------|------|
+| 支付宝条码支付 | `ALI_BARCODE` |
+| 支付宝扫码支付 | `ALI_QRCODE` |
+| 支付宝 H5 支付 | `ALI_H5` |
+| 支付宝公众号 | `ALI_JSAPI` |
+| 支付宝小程序 | `ALI_MINI` |
+
+### 微信支付
+
+| 支付场景名称 | 编码 |
+|------------|------|
+| 微信公众号支付 | `WX_JSAPI` |
+| 微信原生扫码支付 | `WX_QRCODE` |
+| 微信 APP 支付 | `WX_APP` |
+| 微信刷卡支付 | `WX_BARCODE` |
+| 微信 H5 支付 | `WX_H5` |
+| 微信小程序支付 | `WX_MINI` |
+
+### 快捷支付
+
+| 支付场景名称 | 编码 |
+|------------|------|
+| 老快捷支付 | `QUICK_PAY_OLD` |
+| 新快捷-借（通用） | `QUICK_PAY_DEBIT` |
+| 新快捷-贷（通用） | `QUICK_PAY_CREDIT` |
+| 新快捷-上海银行-借 | `QUICK_SH_DEBIT` |
+| 新快捷-上海银行-贷 | `QUICK_SH_CREDIT` |
+| 新快捷-华夏银行-借 | `QUICK_HX_DEBIT` |
+| 新快捷-平安银行-借 | `QUICK_PA_DEBIT` |
+| 新快捷-浦发银行-借 | `QUICK_PF_DEBIT` |
+| 新快捷-建设银行-借 | `QUICK_CCB_DEBIT` |
+| 新快捷-建设银行-贷 | `QUICK_CCB_CREDIT` |
+| 新快捷-中信银行-借 | `QUICK_CITIC_DEBIT` |
+| 新快捷-中信银行-贷 | `QUICK_CITIC_CREDIT` |
+| 新快捷-工商银行-借 | `QUICK_ICBC_DEBIT` |
+| 新快捷-工商银行-贷 | `QUICK_ICBC_CREDIT` |
+| 新快捷-光大银行-借 | `QUICK_GD_DEBIT` |
+| 新快捷-光大银行-贷 | `QUICK_GD_CREDIT` |
+| 新快捷-民生银行-借 | `QUICK_MS_DEBIT` |
+| 新快捷-民生银行-贷 | `QUICK_MS_CREDIT` |
+| 新快捷-中国银行-借 | `QUICK_BOC_DEBIT` |
+| 新快捷-中国银行-贷 | `QUICK_BOC_CREDIT` |
+| 新快捷-邮政银行-借 | `QUICK_PSB_DEBIT` |
+| 新快捷-邮政储蓄银行-借 | `QUICK_PS_SB_DEBIT` |
+| 新快捷-农业银行-借 | `QUICK_AB_DEBIT` |
+| 新快捷-交通银行-借 | `QUICK_BC_DEBIT` |
+| 新快捷-交通银行-贷 | `QUICK_BC_CREDIT` |
+| 新快捷-浙商银行-借 | `QUICK_ZSB_DEBIT` |
+| 新快捷-渤海银行-借 | `QUICK_BANK_BH_DEBIT` |
+| 新快捷-恒丰银行-借 | `QUICK_HFBANK_DEBIT` |
+| 新快捷-广东发展银行-借 | `QUICK_GDB_DEBIT` |
+| 新快捷-苏州银行-借 | `QUICK_SUZHOUBANK_DEBIT` |
+| 新快捷-鄞州银行-借 | `QUICK_BEEBANK_DEBIT` |
+| 新快捷-贵州银行-借 | `QUICK_GUIZHOUBANK_DEBIT` |
+| 新快捷-上海农村商业银行-借 | `QUICK_SRCB_DEBIT` |
+| 新快捷-北京农商银行-借 | `QUICK_BJRCBANK_DEBIT` |
+| 新快捷-天津农商银行-借 | `QUICK_TRCBANK_DEBIT` |
+| 新快捷-成都农商银行-借 | `QUICK_CDRCBANK_DEBIT` |
+| 新快捷-深圳农村商业银行-借 | `QUICK_SZNCSYBANK_DEBIT` |
+| 新快捷-重庆农村商业银行-借 | `QUICK_RCB_CQ_DEBIT` |
+| 新快捷-武汉农村商业银行-借 | `QUICK_WHRCBANK_DEBIT` |
+| 新快捷-广东南海农村商业银行-借 | `QUICK_RCB_GD_SOUTH_SEA_DEBIT` |
+| 新快捷-四川省农村信用社-借 | `QUICK_RCC_SC_DEBIT` |
+| 新快捷-河南省农村信用社-借 | `QUICK_RCC_HN_DEBIT` |
+| 新快捷-广西农村信用社-借 | `QUICK_RCC_GX_DEBIT` |
+| 新快捷-甘肃省农村信用社-借 | `QUICK_RCC_GXS_DEBIT` |
+| 新快捷-山西省农村信用社-借 | `QUICK_RCC_SX_DEBIT` |
+| 新快捷-陕西省农村信用社-借 | `QUICK_SXNXSBANK_DEBIT` |
+| 新快捷-河北省农村信用社-借 | `QUICK_HEBNXBANK_DEBIT` |
+| 新快捷-内蒙古自治区农村信用社-借 | `QUICK_NMGNXSBANK_DEBIT` |
+| 新快捷-青海省农村信用社联合社-借 | `QUICK_QINGHAIRCBANK_DEBIT` |
+| 新快捷-黑龙江省农村信用社-借 | `QUICK_HLJRCCBANK_DEBIT` |
+| 新快捷-辽宁省农村信用社-借 | `QUICK_LNRCCBANK_DEBIT` |
+| 新快捷-云南省农村信用社联合社-借 | `QUICK_RCC_YN_DEBIT` |
+| 新快捷-湖南省农村信用社-借 | `QUICK_RCC_HUNS_DEBIT` |
+| 新快捷-海南省农村信用社-借 | `QUICK_RCC_HNS_DEBIT` |
+| 新快捷-安徽省农村信用社联合社-借 | `QUICK_RCC_AH_DEBIT` |
+| 新快捷-吉林农村信用社-借 | `QUICK_RCC_JL_DEBIT` |
+
+### 银联扫码支付
+
+| 支付场景名称 | 编码 |
+|------------|------|
+| 银行卡扫码支付小额-借 | `BANK_QRCODE_SMALL_DEBIT` |
+| 银行卡扫码支付小额-贷 | `BANK_QRCODE_SMALL_CREDIT` |
+| 银行卡扫码支付大额-借 | `BANK_QRCODE_LARGE_DEBIT` |
+| 银行卡扫码支付大额-贷 | `BANK_QRCODE_LARGE_CREDIT` |
+
+### 银联全渠道
+
+| 支付场景名称 | 编码 |
+|------------|------|
+| 银联全渠道 APP-借 | `UNIPAY_APP_DEBIT` |
+| 银联全渠道 APP-贷 | `UNIPAY_APP_CREDIT` |
+| 银联全渠道 H5-借 | `UNIPAY_H5_DEBIT` |
+| 银联全渠道 H5-贷 | `UNIPAY_H5_CREDIT` |
+
+---
+
+## 费率参数示例
+
+`rate_infos` 方式（标准结构）：
+
+```json
+{
+  "product_info": {
+    "rate_infos": [
+      { "rate_code": "WX_JSAPI",  "rate_type": "SINGLE_PERCENT", "rate": "0.006" },
+      { "rate_code": "WX_QRCODE", "rate_type": "SINGLE_PERCENT", "rate": "0.006" },
+      { "rate_code": "WX_MINI",   "rate_type": "SINGLE_PERCENT", "rate": "0.006" }
+    ]
+  }
+}
+```
+
+> 注意：文档中也出现了另一种简写格式 `"rate": {"WX_JSAPI": 0.006, ...}`，以实际联调结果为准，建议优先使用标准 `rate_infos` 数组结构。