开发指引
更新时间：2024.12.30# 1. 接口规则
扫码支付，使用了微信支付 APIv3接口规则。
# 2.开发环境搭建
# 2.1. 集成SDK
为了帮助开发者更好的调用接口，我们提供 微信支付APIv3官方SDK (opens new window)，请根据自身开发语言，选择对应的SDK库集成到项目，并在商户平台配置平台证书。
目前微信支付提供JAVA、PHP、GO三种语言版本的SDK，封装了签名生成、签名验证、敏感信息加/解密、媒体文件上传等基础接口功能。
各编程语言的SDK对“扫码支付”的业务接口支持不一样，如若未支持相关业务接口，你可以使用SDK中的HTTP类实现发送HTTP请求，它会自动生成签名和验证签名。
| SDK | 说明 |
|---|---|
| wechatpay-java (opens new window) | Java 服务端 SDK |
| wechatpay-php (opens new window) | PHP 服务端 SDK |
| wechatpay-go (opens new window) | GO 服务端 SDK |
如下通用基础功能接口，已经在SDK中完成封装，可替换相关参数后快速测试。
若使用的编程语言无对应的SDK，则需要按照接口规则与接口详细信息自行开发。
# 2.2. 接口体验
如果开发者使用过PostmanAPI的调试，建议在正式开发之前，使用 Postman签名脚本 (opens new window)进行接口体验。
# 3. 扫码支付业务接入说明
# 3.1. 业务流程图
# 3.1.1. 关键步骤说明
步骤1.2：客户端调用并呈现金额控件
商户可在微信内网页或小程序中通过金额控件SDK，在页面上呈现“金额控件”。（详见网页展示金额控件、小程序展示金额控件） 在页面上呈现微信支付金额控件，商家通过“展示金额控件”接口，在页面上呈现“金额控件”，通过用户对金额控件的操作，或商家调起金额控件时的设置，由SDK按逻辑自动判断是否出现。（详见下方3.2.1）
步骤1.6：客户端通知商家下单金额
用户输入金额后，轻触“付款”按钮，金额控件SDK向商家传递付款指令（内包含付款金额），并等待商家返回拉起收银台的必要信息。
商家在此过程中获取用户输入金额，并在后台向微信支付下单。
步骤1.8：服务端调用API下单
商户可通过扫码支付下单创建支付订单。（详见下方3.2.2）
步骤 1.12：客户端调起收银台
商户服务端收到下单成功，生成调起支付签名，返回给商户前端，由商户前端调用金额控件SDK，传递签名数据，拉起支付收银台。
步骤2.8：客户端前端回调
用户支付成功后会通过两种渠道为商家发送通知：
# 步骤2.9：客户端核实订单状态
商户在没有接收到微信支付结果通知的情况下需要主动调用查询订单API查询支付结果。（详见下方3.2.4）
注意
- 建议为确保收款成功避免资金损失，无论是否收到支付成功通知都请主动查单。
# 3.2.API接入（含示例代码）
文档展示了如何使用微信支付服务端 SDK 快速接入扫码支付产品，完成与微信支付对接的部分。
注意
- 文档中的代码示例是用来阐述 API 基本使用方法，代码中的示例参数需替换成商户自己账号及请求参数才能跑通。
- 以下接入步骤仅提供参考，请商户结合自身业务需求进行评估、修改。
# 3.2.1.【客户端】扫码支付调起金额控件
步骤说明：
商户在微信页面或微信小程序通过接口调用来展示微信支付金额控件。
注意
- 微信支付金额控件分为微信页面和微信小程序两个场景。
- 对于不支持金额控件的老微信客户端，需要做好兼容，使用原JSAPI/小程序支付方式完成支付。
- 详情请参见 扫码支付 - 使用自定义的金额控件。
# 3.2.2. 【服务端】扫码支付下单
步骤说明：
用户输入金额后，轻触“付款”按钮，金额控件SDK向商家传递付款指令（内包含付款金额），并等待商家返回拉起收银台的必要信息。
示例代码：
重要入参说明：
- out_trade_no：商户系统内部订单号，只能是数字、大小写字母_-*且在同一个商户号下唯一
- description：商品描述
- notify_url：支付回调通知URL，该地址必须为直接可访问的URL，不允许携带查询串
- total：订单总金额，单位为分
- OpenID：OpenID是微信用户在AppID下的唯一用户标识（AppID不同，则获取到的OpenID就不同），可用于永久标记一个用户。OpenID获取方式请参考以下文档小程序获取OpenID (opens new window)、公众号获取OpenID (opens new window)、App获取OpenID (opens new window)
更多参数、响应详情及错误码请参见扫码支付下单接口文档。
# 3.2.3.【服务端】接收支付结果通知
步骤说明：
当用户完成支付，微信会把相关支付结果将通过异步回调的方式通知商户，商户需要接收处理，并按文档规范返回应答。
注意
- 支付结果通知是以POST 方法访问商户设置的通知URL，通知的数据以JSON 格式通过请求主体（BODY）传输。通知的数据包括了加密的支付结果详情。
- 加密不能保证通知请求来自微信。微信会对发送给商户的通知进行签名，并将签名值放在通知的HTTP头Wechatpay-Signature。商户应当验证签名，以确认请求来自微信，而不是其他的第三方。签名验证的算法请参考 《微信支付API v3签名验证》。
- 支付通知HTTP应答码为200或204才会当作正常接收，当回调处理异常时，应答的HTTP状态码应为500，或者4xx。
- 商户成功接收到回调通知后应返回成功的HTTP应答码为200或204。
- 同样的通知可能会多次发送给商户系统。商户系统必须能够正确处理重复的通知。 推荐的做法是，当商户系统收到通知进行处理时，先检查对应业务数据的状态，并判断该通知是否已经处理。如果未处理，则再进行处理；如果已处理，则直接返回结果成功。在对业务数据进行状态检查和处理之前，要采用数据锁进行并发控制，以避免函数重入造成的数据混乱。
- 对后台通知交互时，如果微信收到商户的应答不符合规范或超时，微信认为通知失败，微信会通过一定的策略定期重新发起通知，尽可能提高通知的成功率，但微信不保证通知最终能成功。（通知频率为15s/15s/30s/3m/10m/20m/30m/30m/30m/60m/3h/3h/3h/6h/6h - 总计 24h4m）。
更多参数、响应详情及错误码请参见 扫码支付支付通知接口文档。
# 3.2.4. 【服务端】查询订单
步骤说明：
当商户后台、网络、服务器等出现异常，商户系统最终未接收到支付通知时，商户可通过查询订单接口核实订单支付状态。
示例代码(通过微信订单号查询)：
更多参数、响应详情及错误码请参见 扫码支付查询订单API接口文档。
# 3.2.5. 【服务端】关闭订单
步骤说明：
当商户订单支付失败需要生成新单号重新发起支付，要对原订单号调用关单，避免重复支付；系统下单后，用户支付超时，系统退出不再受理，避免用户继续，请调用关单接口
示例代码：
注意
- 订单生成后不能马上调用关单接口，最短调用时间间隔为5分钟。
- 已支付成功的订单不能关闭。
更多参数、响应详情及错误码请参见 扫码支付关闭订单接口文档。
