开发指引
更新时间：2023.08.22# 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. 业务流程图
# 业务流程时序图
申请单状态变化如下：
重点步骤说明：
步骤1： 获取微信支付商户号：渠道商使用银行或者支付机构提供的API或者后台系统录入商家门店信息，获取商家每个门店在微信支付侧的商户号（上送给微信支付的“商户名称”字段必须与营业执照上商户名称一致，具体规则 点击查看 (opens new window) ）。
步骤2： 查询微信支付商户号授权状态：渠道商使用《获取商户号开户意愿确认状态接口》查询微信支付商户号是否完成开户意愿确认。
步骤5： 提交商家资料给微信支付：渠道商根据商家类型（企业、个体户、小微、事业单位、其他组织等）准备好相关的商家资料，使用微信支付接口《提交开户意愿确认申请单》获取微信支付申请单编号。
步骤8： 查询申请单审核结果：渠道商提交商家资料后，建议每隔五分钟调用《查询申请单审核结果接口》查询申请单审核结果。
# 申请单正常情况下的状态转换如下
- 提交后申请单状态为“审核中”，微信支付后台会进行审核，审核通过后申请单状态变成“待联系人确认”，同时接口会提供“申请单小程序码” （小程序码的图片）。
- 联系人扫“申请单小程序码”后确认资料无误后，申请单状态变成“待账户验证”。
- 联系人将“法人确认二维码”在微信上发给法人确认后（或打款验证），申请单状态变成“审核通过”。
- 当审核结果为“审核驳回”时，请根据驳回原因重新提交商家资料，重新提交前请使用《撤销原申请单》，再次提交新的商家资料。
- 当审核结果为“待联系人确认”或“待账户验证”或“审核通过”时，接口会同时给出“申请单小程序码”。
# 3.2. API接入（含示例代码）
文档展示了如何使用微信支付服务端 SDK 快速接入支付有礼，完成与微信支付对接的部分。
注意
- 文档中的代码示例是用来阐述 API 基本使用方法，代码中的示例参数需替换成商户自己账号及请求参数才能跑通。
- 以下接入步骤仅提供参考，请商户结合自身业务需求进行评估、修改。
# 3.2.1. 【服务端】提交申请单
步骤说明： 服务商收集商户资料后，调用提交申请单接口，提交创建入驻申请单。
重要入参说明：
out_trade_no： 业务申请编号，服务商自定义的唯一编号，每个编号对应一个申请单。
subject_type： 主体类型。枚举值：
- SUBJECT_TYPE_ENTERPRISE：企业
- SUBJECT_TYPE_INSTITUTIONS_CLONED：事业单位
- SUBJECT_TYPE_INDIVIDUAL：个体工商户
- SUBJECT_TYPE_OTHERS：其他组织
- SUBJECT_TYPE_MICRO：小微商户
licence_number： 营业执照注册号。校验规则：
- 请填写营业执照上的注册号。
- 若主体类型为个体工商户或企业，注册号格式须为15位数字或18位数字|大写字母。
merchant_name： 商户名称。
- 个体工商户，不能以“公司”结尾。
- 个体工商户，若营业执照上商户名称为空或为“无”，请填写"个体户+经营者姓名"，如“个体户张三”。
legal_person： 法人姓名。
- 只能由中文字符、英文字符、可见符号组成。
- 请填写营业执照的经营者/法定代表人姓名。
更多参数、响应详情及错误码请参见提交申请单接口文档。
# 3.2.2.【服务端】撤销申请单
步骤说明： 服务商提交申请单后需要修改信息时，或者申请单审核结果为“已驳回”时服务商要修改申请材料时，均需要先调用撤销申请单接口。
重要入参说明：
- applyment_id： 申请单编号，微信支付分配的申请单号，申请单编号和业务申请编号至少传一个。
- business_code： 业务申请编号。
更多参数、响应详情及错误码请参见撤销申请单接口文档。
# 3.2.3. 【服务端】查询申请单审核结果
步骤说明： 查询申请单审核结果。
重要入参说明：
- applyment_id： 申请单编号，微信支付分配的申请单号，申请单编号和业务申请编号至少传一个。
- business_code： 业务申请编号。
- 服务商自定义的唯一编号。
- 每个编号对应一个申请单。
更多参数、响应详情及错误码请参见撤销申请单接口文档。 origin/master
# 3.2.4. 【服务端】获取商户开户意愿确认状态
步骤说明： 当服务商需要确认微信支付子商户号是否完成确认时，如果调用此接口提到“已授权”状态，则说明该商户号已完成开户意愿确认。
重要入参说明：
- sub_mchid： 特约商户号，微信支付分配的特约商户的唯一标识。
更多参数、响应详情及错误码请参见获取商户开户意愿确认状态接口文档。
# 4. 常见问题
# Q1：商户开户意愿调用“提交申请单”返回：暂未查询到该营业执照注册号，请检查营业执照注册号是否填写正确
A1：请求参数“营业执照注册号（licence_number）”填写错误，请填写营业执照上的注册号，若主体类型为个体工商户或企业，注册号格式须为15位数字或18位数字|大写字母。
# Q2：商户开户意愿调用“提交申请单”返回：系统繁忙，请稍后重试
A2：请按照以下几点检查：
- 系统异常，请使用相同参数稍后重新调用；
- 请求参数错误，请确认参数的大小写、参数名、格式是否与接口文档一致；
- 请求头里面的参数mchid错误，也会报这个错误，请检查确认。
# Q3：商户开户意愿调用“撤消申请单”返回：查询申请单不存在，请检查申请单号是否正确
A3：请求参数申请单编号（applyment_id）填写错误或没有填写，请填写微信支付分配的申请单号，申请单编号和业务申请编号至少传一个。
# Q4：商户开户意愿调用“获取特约商户授权状态”返回：Authorization不合法
A4：请按照以下几点检查：
Authorization头认证类型或签名信息错误,请严格按照文档要求填写参数。
- Authorization头认证类型目前为WECHATPAY2-SHA256-RSA2048。
- Authorization头签名信息包括发起请求的商户（渠道商）的商户号mchid。
- 商户API证书序列号serial_no，用于声明所使用的证书
- 请求随机串nonce_str
- 时间戳timestamp
- 签名值signature
Authorization头参数存在换行，实际数据应在一行。
# Q5：商户开户意愿调用“提交申请单”返回：商户未申请过证书，请到商户平台上申请证书授权机构颁发的证书
A5：请按照错误提示，到商户平台上申请下载API证书并正确使用，请参考以下几点：
# Q6：商户开户意愿调用“撤销申请单”返回：无法将传入参数“申请单编号”转换为uint64类型
A6：请求参数类型填写错误，正确的参数类型是uint64。
