微信小程序支付
| 日期 | 版本 | 作者 | 说明 |
|---|---|---|---|
| 2023-06-20 | V-1.0 | 孔留锋 | 文档新建。 |
微信小程序支付
简介
商户已有微信小程序，用户通过好友分享或扫描二维码在微信内打开小程序时，可以调用微信支付完成下单购买的流程。
**注意：**小程序不能通过拉起H5页面做jsapi支付，小程序内只能使用小程序支付
业务流程
- 如图1，用户通过分享或扫描二维码进入商户小程序，用户选择购买，完成选购流程。
- 如图3，调起微信支付控件，用户开始输入支付密码。
- 如图4，密码验证通过，支付成功。商户后台得到支付成功的通知。
- 如图5，返回商户小程序，显示购买成功。
- 如图6，微信支付公众号下发支付凭证。
接入准备
选择接入模式
商户/服务商在接入前首先要判断自己公司注册区域适用的接入模式，微信支付目前提供两种接入方式：直连模式和服务商模式。
直连模式
信息、资金流：微信支付—>直连商户
直连模式，商户自行申请入驻微信支付，无需服务商协助。（商户平台申请）成为直连商户
服务商模式
服务商模式，商户申请成为微信支付服务商，服务商自身无法作为一个直连商户直接发起交易，其发起交易必须传入相关特约商户商户号的参数信息。
总结：结合应用部署场景，直连模式适用。
直连模式参数申请
商户自行申请入驻微信支付，无服务商协助。（商户平台申请）成为直连商户。
申请APPID
由于微信支付的产品体系全部搭载于微信的社交体系之上，所以直连商户或服务商接入微信支付之前，都需要有一个微信社交载体，该载体对应的ID即为APPID。
小程序，请前往 小程序平台 申请。
申请mchid
申请mchid和APPID的操作互不影响，可以并行操作，申请地址如下： 商户号申请平台 。 申请成功后，会向服务商填写的联系邮箱下发通知邮件，内容包含申请成功的mchid及其登录账号密码，请妥善保存。
注：一个mchid只能对应一个结算币种，若需要使用多个币种收款，需要申请对应数量的mchid。
绑定APPID及mchid
APPID和mchid全部申请完毕后，需要建立两者之间的绑定关系。直连模式下，APPID与mchid之间的关系为多对多，即一个APPID下可以绑定多个mchid，而一个mchid也可以绑定多个APPID。
配置API key
API v3密钥主要用于平台证书解密、回调信息解密，具体使用方式可参见接口规则文档中证书和回调报文解密章节。
请根据以下步骤配置API key：
登录微信商户平台，进入【账户中心 > API安全 】目录，设置APIV3密钥。
下载并配置商户证书
商户API证书具体使用说明可参见接口规则文档中私钥和证书章节。
商户可登录微信商户平台，在【账户中心】->【API安全】目录下载证书。
以下为具体下载步骤：
生成证书串
- 在【商户平台】-“复制证书串”环节，点击“复制证书串”按钮后；
- 在【证书工具】-“复制请求串”环节，点击“下一步”按钮进入“粘贴证书串”环节；
- 在【证书工具】-“粘贴证书串”环节，点击“粘贴”按钮后；
- 击“下一步”按钮，进入【证书工具】-“生成证书”环节
配置应用
小程序开通微信支付，即申请或复用微信支付商户号，申请完小程序后，登录小程序后台。点击左侧导航栏的微信支付，在页面中进行开通。
点击开通按钮后，有2种方式可以获取微信支付能力，新申请微信支付商户号或绑定一个已有的微信支付商户号，请根据你的业务需要和具体情况选择，只能二选一。
开发流程
流程图
重要步骤说明
- 步骤4：用户下单发起支付，商户可通过JSAPI下单创建支付订单。
- 步骤9：商户小程序内使用小程序调起支付API（wx.requestPayment）发起微信支付，详见小程序API文档
- 步骤16：用户支付成功后，商户可接收到微信支付支付结果通知支付通知API。
- 步骤21：商户在没有接收到微信支付结果通知的情况下需要主动调用查询订单API查询支付结果。
小程序支付相关接口
商户平台小程序支付 官方文档
- JSAPI下单 ：通过本接口提交微信支付小程序支付订单。
- 查询订单：通过此接口查询订单状态。
- 关闭订单：通过此接口关闭待支付订单。
- 小程序调起支付：通过小程序下单接口获取到发起支付的必要参数prepay_id，可以按照接口定义中的规则，调起小程序支付。
- 支付通知：微信支付通过支付通知接口将用户支付成功消息通知给商户。
- 申请退款：商户可以通过该接口将支付金额退还给买家。
- 查询单笔退款：提交退款申请后，通过调用该接口查询退款状态 。
- 退款结果通知：微信支付通过退款通知接口将用户退款成功消息通知给商户。
- 申请交易账单：商户可以通过该接口获取交易账单文件的下载地址。
- 申请资金账单：商户可以通过该接口获取资金账单文件的下载地址。
- 下载账单：通过申请交易/资金账单获取到download_url在该接口获取到对应的账单。
JSAPI下单API
商户系统先调用该接口在微信支付服务后台生成预支付交易单，返回正确的预支付交易会话标识后再按Native、JSAPI、APP等不同场景生成交易串调起支付。
地址：JSAPI下单
注意：
- 应用ID（微信生成的应用ID，全局唯一）
- 直连商户号（直连商户的商户号，由微信支付生成并下发） 参考 接入准备中
- 商户订单号（商户系统内部订单号，只能是数字、大小写字母_-*且在同一个商户号下唯一），需要结合系统自己定义
- 通知地址（异步接收微信支付结果通知的回调地址，通知url必须为外网可访问的url，不能携带参数。 公网域名必须为https，如果是走专线接入，使用专线NAT IP或者私有回调域名可使用http）
查询订单API
商户可以通过查询订单接口主动查询订单状态，完成下一步的业务逻辑。查询订单状态可通过微信支付订单号或商户订单号两种方式查询，两种查询方式返回结果相同。
需要调用查询接口的情况：
- 当商户后台、网络、服务器等出现异常，商户系统最终未接收到支付通知。
- 调用支付接口后，返回系统错误或未知交易状态情况。
- 调用付款码支付API，返回USERPAYING的状态。
- 调用关单或撤销接口API之前，需确认支付状态。
地址：查询订单
注意：
- 直连商户号 参考 接入准备中
关闭订单API
以下情况需要调用关单接口：
商户订单支付失败需要生成新单号重新发起支付，要对原订单号调用关单，避免重复支付；
系统下单后，用户支付超时，系统退出不再受理，避免用户继续，请调用关单接口。
地址：关闭订单
注意：
- 关单没有时间限制，建议在订单生成后**间隔几分钟（最短5分钟）**再调用关单接口，避免出现订单状态同步不及时导致关单失败。
小程序调起支付API
通过JSAPI下单接口获取到发起支付的必要参数prepay_id，然后使用微信支付提供的小程序方法调起小程序支付。
地址：小程序调起支付
注意：
- 小程序调起支付的参数需要按照签名规则进行签名计算
支付通知API
微信支付通过支付通知接口将用户支付成功消息通知给商户。
注意：
- 同样的通知可能会多次发送给商户系统。商户系统必须能够正确处理重复的通知。 推荐的做法是，当商户系统收到通知进行处理时，先检查对应业务数据的状态，并判断该通知是否已经处理。如果未处理，则再进行处理；如果已处理，则直接返回结果成功。在对业务数据进行状态检查和处理之前，要采用数据锁进行并发控制，以避免函数重入造成的数据混乱。
- 如果在所有通知频率后没有收到微信侧回调，商户应调用查询订单接口确认订单状态。
特别提醒：商户系统对于开启结果通知的内容一定要做签名验证，并校验通知的信息是否与商户侧的信息一致，防止数据泄露导致出现“假通知”，造成资金损失。
申请退款API
当交易发生之后一年内，由于买家或者卖家的原因需要退款时，卖家可以通过退款接口将支付金额退还给买家，微信支付将在收到退款请求并且验证成功之后，将支付款按原路退还至买家账号上。
地址：申请退款
注意：
交易时间超过一年的订单无法提交退款
微信支付退款支持单笔交易分多次退款（不超50次），多次退款需要提交原支付订单的商户订单号和设置不同的退款单号。申请退款总金额不能超过订单金额。 一笔退款失败后重新提交，请不要更换退款单号，请使用原商户退款单号
错误或无效请求频率限制：6qps，即每秒钟异常或错误的退款申请请求不超过6次
每个支付订单的部分退款次数不能超过50次
如果同一个用户有多笔退款，建议分不同批次进行退款，避免并发退款导致退款失败
申请退款接口的返回仅代表业务的受理情况，具体退款是否成功，需要通过退款查询接口获取结果
一个月之前的订单申请退款频率限制为：5000/min
同一笔订单多次退款的请求需相隔1分钟
查询单笔退款API
提交退款申请后，通过调用该接口查询退款状态。退款有一定延时，建议在提交退款申请后1分钟发起查询退款状态，一般来说零钱支付的退款5分钟内到账，银行卡支付的退款1-3个工作日到账。
地址：查询单笔退款
退款结果通知API
退款状态改变后，微信会把相关退款结果发送给商户。
地址：退款结果通知
注意：
- 对后台通知交互时，如果微信收到应答不是成功或超时，微信认为通知失败，微信会通过一定的策略定期重新发起通知，尽可能提高通知的成功率，但微信不保证通知最终能成功
- 同样的通知可能会多次发送给商户系统。商户系统必须能够正确处理重复的通知。 推荐的做法是，当商户系统收到通知进行处理时，先检查对应业务数据的状态，并判断该通知是否已经处理。如果未处理，则再进行处理；如果已处理，则直接返回结果成功。在对业务数据进行状态检查和处理之前，要采用数据锁进行并发控制，以避免函数重入造成的数据混乱。
- 如果在所有通知频率后没有收到微信侧回调。商户应调用查询订单接口确认订单状态。
申请交易账单API
微信支付按天提供交易账单文件，商户可以通过该接口获取账单文件的下载地址。文件内包含交易相关的金额、时间、营销等信息，供商户核对订单、退款、银行到账等情况。
地址：申请交易账单
注意：
微信侧未成功下单的交易不会出现在对账单中。支付成功后撤销的交易会出现在对账单中，跟原支付单订单号一致；
对账单中涉及金额的字段单位为“元”；
对账单接口只能下载三个月以内的账单。
申请资金账单API
微信支付按天提供微信支付账户的资金流水账单文件，商户可以通过该接口获取账单文件的下载地址。文件内包含该账户资金操作相关的业务单号、收支金额、记账时间等信息，供商户进行核对。
地址：申请资金账单
注意：
- 资金账单中的数据反映的是商户微信支付账户资金变动情况；
- 对账单中涉及金额的字段单位为“元”。
下载账单API
下载账单API为通用接口，交易/资金账单都可以通过该接口获取到对应的账单。
地址：下载账单
注意：
- 账单文件的下载地址的有效时间为30s。
- 强烈建议商户将实际账单文件的哈希值和之前从接口获取到的哈希值进行比对，以确认数据的完整性。
- 该接口响应的信息请求头中不包含微信接口响应的签名值，因此需要跳过验签的流程。
- 微信在次日9点启动生成前一天的对账单，建议商户10点后再获取。
