开发指引
更新时间：2023.11.08# 1. 接口规则
为了在保证支付安全的前提下，带给商户简单、一致且易用的开发体验，我们推出了全新的微信支付APIv3接口。该版本API的具体规则请参考APIv3接口规则。
# 2. 开发准备
# 2.1. 搭建和配置开发环境
为了帮助开发者调用开放接口，我们提供了JAVA、PHP、GO三种语言版本的开发库，封装了签名生成、签名验证、敏感信息加/解密、媒体文件上传 等基础功能（更多语言版本的开发库将在近期陆续提供）。
测试步骤：
1、根据自身开发语言，选择对应的开发库并构建项目，具体配置请参考下面链接的详细说明：
- wechatpay-java (opens new window)（推荐）、wechatpay-apache-httpclient (opens new window)，适用于Java开发者。
- 注：当前开发指引接口JAVA示例代码采用wechatpay-apache-httpclient版本。
- wechatpay-php (opens new window)（推荐）、wechatpay-guzzle-middleware (opens new window)，适用于PHP开发者。
- 注：当前开发指引接口PHP示例代码采用wechatpay-guzzle-middleware版本。
- wechatpay-go (opens new window)，适用于Go开发者。
更多资源可前往微信支付开发者社区 (opens new window)搜索查看。
2、创建加载商户私钥、加载平台证书、初始化httpClient的通用方法。
3、基于接口的示例代码，替换请求参数后可发起测试。
说明：
- 上面的开发库为微信支付官方开发库，其它没有审核或者控制下的第三方工具和库，微信支付不保证它们的安全性和可靠性。通过包管理工具引入SDK后，可根据下面每个接口的示例代码替换相关参数后进行快速测试。
- 开发者如果想详细了解签名生成、签名验证、敏感信息加/解密、媒体文件上传等常用方法的具体代码实现，可阅读下面的详细说明：
- 如想更详细的了解我们的接口规则，可查看我们的接口规则指引文档。
# 3. 快速接入
# 3.1. 业务流程图
# 业务流程时序图
# 申请单状态变化如下
重点步骤说明：
步骤3 商户入驻，服务商收集商户资料后，调用提交申请单接口，提交创建入驻申请单。
步骤5 创建申请单后，可通过查询申请单状态接口，获取特约商户签约链接，让商户扫码确认联系信息，后续申请单进度可通过公众号自动通知超级管理员（简称超管）。
步骤10 进件成功后，若特约商户需修改结算账号时，服务商可调用修改结算账号接口来帮助特约商户修改结算信息，修改后通过状态码判断是否修改成功。也可通过调用查询结算账号接口来查询核查结算账号信息。
# 3.2. API接入（含示例代码）
文档展示了如何使用微信支付服务端 SDK 快速接入支付有礼，完成与微信支付对接的部分。
注意
- 文档中的代码示例是用来阐述 API 基本使用方法，代码中的示例参数需替换成商户自己账号及请求参数才能跑通。
- 以下接入步骤仅提供参考，请商户结合自身业务需求进行评估、修改。
# 3.2.1. 【服务端】提交申请单
步骤说明：服务商收集商户资料后，调用提交申请单接口，提交创建入驻申请单。
重要入参说明：
- business_code 业务申请编号。
- 服务商自定义的唯一编号。
- 每个编号对应一个申请单，每个申请单审核通过后会生成一个微信支付商户号。
- 若申请单被驳回，可填写相同的“业务申请编号”，即可覆盖修改原申请单信息
- mobile_phone： 联系手机。
- 11位数字。
- 用于接收微信支付的重要管理信息及日常操作验证码。
- 该字段需进行加密处理，加密方法详见敏感信息加密说明。(提醒：必须在HTTP头中上送Wechatpay-Serial)
- bank_account_type： 账户类型。
- 若主体为企业/党政、机关及事业单位/其他组织，可填写：对公银行账户。
- 若主体为个体户，可选择填写：对公银行账户或经营者个人银行卡。
枚举值：
- BANK_ACCOUNT_TYPE_CORPORATE：对公银行账户
- BANK_ACCOUNT_TYPE_PERSONAL：经营者个人银行卡
- account_name： 开户名称。
- 选择“经营者个人银行卡”时，开户名称必须与“经营者证件姓名”一致。
- 选择“对公银行账户”时，开户名称必须与营业执照/登记证书的“商户名称”一致。
- 该字段需进行加密处理，加密方法详见敏感信息加密说明。(提醒：必须在HTTP头中上送Wechatpay-Serial)
更多参数、响应详情及错误码请参见提交申请单接口文档。
# 3.2.2.【服务端】查询申请单状态
步骤说明：创建申请单后，可通过查询申请单状态接口，获取特约商户签约链接，让商户扫码确认联系信息，后续申请单进度可通过公众号自动通知超级管理员（简称超管）。
重要入参说明：
- business_code: 业务申请编号。
- 只能由数字、字母或下划线组成，建议前缀为服务商商户号。
- 服务商自定义的唯一编号。
- 每个编号对应一个申请单，每个申请单审核通过后生成一个微信支付商户号。
- 若申请单被驳回，可填写相同的“业务申请编号”，即可覆盖修改原申请单信息。
- applyment_id: 申请单号， 微信支付分配的申请单号。
更多参数、响应详情及错误码请参见查询申请单状态接口文档
# 3.2.3. 【服务端】修改结算账号
步骤说明： 进件成功后，若特约商户需修改结算账号时，服务商可调用修改结算账号接口来帮助特约商户修改结算信息。
重要入参说明：
- sub_mchid: 投诉单对应的投诉单号，在投诉通知回调中会返回这个参数
- account_bank：开户银行，请填写开户银行名称，详细参见开户银行对照表。
- account_number：银行账号。
- 数字，长度遵循系统支持的开户银行对照表中对公/对私卡号长度要求。
- 该字段需进行加密处理，加密方法详见敏感信息加密说明。(提醒：必须在HTTP头中上送Wechatpay-Serial)
更多参数、响应详情及错误码请参见修改结算账号接口文档。
# 3.2.4. 【服务端】查询结算账户
步骤说明： 服务商调用修改结算账号接口来帮助特约商户修改结算信息，修改后通过状态码判断是否修改成功。也可通过调用查询结算账号接口来查询核查结算账号信息。
重要入参说明：
- sub_mchid: 特约商户号、请输入本服务商进件、已签约的特约商户号。
更多参数、响应详情及错误码请参见查询结算账户接口文档。
# 4. 常见问题
# Q1：调用特约商户进件“提交申请单接口”返回“暂无权限”？
A1：请按照以下几点检查
- 服务商商户号被处罚，被限制权限，请登录服务商商户平台查看站内信，按照收到的站内信提示申诉解决
- 请求头中的参数mchid填写错误，该参数只能填写为普通服务商的商户号，不能填写为其他类型的商户号
- 特约商户进件接口不允许进件小微商户
# Q2：调用特约商户进件“提交申请单接口”返回“身份证号码，与营业执照不匹配，请核对修改”？
A2：请按照以下几点检查
- 身份证号码字段（id_card_number）取值错误，请填写个体户经营者/法定代表人对应身份证的号码
- 身份证号码字段（id_card_number）取值错误，身份证号码的规则是15位数字或17位数字+1位数字|X，该字段需进行加密处理
- 请使用办理营业执照的身份证号码
# Q3：调用特约商户进件“提交申请单接口”返回："参数“组织机构代码证照片”是必填项
A3：请仔细检查上传的参数是否有问题，如果传入组织机构代码证的结构（organization_info），将进行真实校验，请去掉组织机构代码证的结构（organization_info）
# Q4：调用特约商户进件“提交申请单接口”返回“系统繁忙，请稍后重试”
A4：请按照以下几点检查
- 系统繁忙，可以稍后重试
- 请求头中的参数mchid填写错误，该参数只能填写为普通服务商的商户号
- 在请求参数中，不需要的参数不要上传，不能传空值，空的字段也不能上传
# Q5：查询结算账户API不返回verify_result字段，是什么原因？
A5：入驻后若没有修改过银行卡，除非是汇款失败，否则不返回verify_result字段
