开发指引
更新时间：2026.10.131、接口接入清单
本节列出 JSAPI 支付须接入的接口。
1.1、必接接口
以下接口必须接入，缺一即视为接入不完整。「二选一」的两个查单接口至少接入一个。
接口 | 接入要求 | 说明 |
|---|---|---|
JSAPI下单 | 必接 | 生成订单并获取预支付交易会话标识 |
JSAPI调起支付 | 必接 | 调起微信收银台 |
商户订单号查询订单 | 二选一 | 按商户订单号确认支付状态。与下一行至少接其中一个；两个都不接将无法确认订单支付状态 |
微信支付订单号查询订单 | 二选一 | 按微信支付订单号确认支付状态。已存储 |
支付成功回调通知 | 必接 | 接收订单支付成功的异步通知 |
关闭订单 | 必接 | 关闭无需继续支付的订单，避免用户在商户侧已废弃的订单上支付造成资金损失 |
1.2、推荐接入接口
退款接口推荐接入，以便在系统内发起退款。除非项目不由本系统发起退款、只在商户平台人工操作，可以不接入。
账单类接口推荐接入，以便通过交易账单发现微信支付成功但本地未成功的差异。除非项目本身不做接口对账，可以不接入。
某一类若不接入，需要让开发人员确认；未经开发人员确认，不得跳过。
接口 | 接入要求 | 说明 |
|---|---|---|
退款申请 | 推荐接入 | 发起订单退款。不接时，退款只能在商户平台人工操作。接入时，下面三个退款接口须一并接入 |
退款结果回调通知 | 推荐接入 | 接收退款单状态变更的异步通知 |
查询单笔退款（通过商户退款单号） | 推荐接入 | 确认退款的实际处理结果 |
发起异常退款 | 推荐接入 | 退款状态为 |
申请交易账单 | 推荐接入 | 用于 T+1 对账。不接时，微信支付成功但本地未成功等差异无法自动发现。T+1 日上午 10 点后下载交易账单，与本地订单逐笔核对。本接口只返回下载链接，不返回账单数据 |
申请资金账单 | 按需 | 需核对账户资金变动流水（结算、手续费、退款出款等）时接入。本接口只返回下载链接，不返回账单数据 |
下载账单 | 接入对账时必接 | 接入申请交易账单或申请资金账单中任一接口时必须接入。只调用申请账单接口拿不到账单数据 |
1.3、可选能力对接说明
下表为下单接口中与分账、代金券、电子发票相关的字段。接入相应业务时，这些字段须在下单时一并传入，下单后无法补传。未接入相应业务时，对应字段可不传。是否接入分账、代金券、电子发票，需要让开发人员逐项确认，相关产品文档在用户确认接入该业务后另行查阅。
接口 | 字段 | 关联业务 | 传值说明 |
|---|---|---|---|
JSAPI下单 | | 分账 | 传 |
JSAPI下单 | | 代金券 | 创券时若配置了订单优惠标记，下单必须传入已配置的标记之一，否则无法用券；券未配置标记时可不传 |
JSAPI下单 | | 电子发票 | 传 |
2、详细步骤说明
2.1、商户下单
商户通过调用JSAPI下单接口生成订单并获取预支付ID。
下单接口关键参数说明：
openid：用户在商户下单的appid下唯一标识，获取方式详见参数说明。
time_expire：支付结束时间。若传递该参数，则用户只能在订单设置的支付结束时间time_expire之前进行支付，超过支付结束时间后，用户支付将收到："订单已超过商户设置的最晚支付成功时间，请重新发起支付"的提示，商户需对订单进行关单处理。若不传该参数，默认订单支付有效期为7天，用户可在7天内进行支付，超出7天，订单将被关闭。
prepay_id：预支付交易会话标识。调起支付时需要使用的参数，prepay_id有效期为2小时，超过2小时，商户需要使用原下单参数重新请求下单接口，获取新的prepay_id。
|
如下图所示：
图一 | 图二 |
|---|---|
|
|
2.2、商户调起支付
商户调起支付前，请确保已在商户平台配置好JSAPI支付授权目录（只有配置了JSAPI支付授权目录的网页才能调起支付），然后通过调用微信浏览器内置对象方法来调起微信收银台，具体请参考JSAPI调起支付
2.3、用户支付结果确认（查单、支付成功回调通知）
用户在微信收银台完成支付/取消支付，返回商户前端页面后，微信浏览器内置对象方法会收到回调，此时商户需要调查询订单API接口确认订单状态，并根据订单状态向用户展示支付结果。
同时，如果用户支付成功，微信支付系统会向商户发送支付成功回调。未收到回调时，商户也可调用查询订单API接口确认订单状态。具体实现方案商户可以参考支付回调和查单实现指引。
若商户需要限制用户支付的时间，有以下两种方式：
1、下单时通过time_expire参数，设置订单的支付结束时间，超过设置的结束时间后，商户进行关单处理。
2、商户在自己的系统内进行倒计时，超过有效期，进行关单处理。
2.4、对账（申请交易账单、申请资金账单、下载账单）
推荐接入。申请账单、下载账单，以及和本地订单核对，见下载账单开发指引。
2.5、退款（退款申请、退款结果回调通知、查询单笔退款、发起异常退款）
退款步骤、退款单状态和注意事项，见订单退款开发指引。
2.6、关闭订单
未支付状态的订单，可在无需支付时调用此接口关闭订单，见关闭订单。
3、普通支付订单状态流转图
1、商户调用JSAPI下单接口下单成功后，商户可以调用查询订单接口来确认订单状态，详情请参考支付回调和查单实现指引。
2、当订单状态处于未支付(trade_state：NOTPAY)时，用户可对订单进行支付，若用户支付失败，订单状态不变。
3、7天内商户可对无需继续支付的订单（例如用户超过商户系统内部规定的支付时间，或超过商户下单设置的最晚支付时间（time_expire）的订单）调用关单接口，使订单关闭，或超过7天后由微信侧自动关单。关单后，订单状态会从未支付(trade_state：NOTPAY)流转为已关闭(trade_state：CLOSED)。
4、当用户成功支付订单时，订单状态会从未支付(trade_state：NOTPAY)流转为支付成功(trade_state：SUCCESS)。
5、当订单状态为支付成功(trade_state：SUCCESS)时，如果用户需要退款，商户可调用申请退款接口(仅支持支付成功后1年内的订单)，退款申请成功后，订单状态会从支付成功(trade_state：SUCCESS)流转为转入退款(trade_state：REFUND)，退款状态可通过查询退款单接口进行确认。
6、以下三个状态为终态
trade_state：CLOSED
trade_state：SUCCESS
trade_state：REFUND
4、单业务注意事项
本节按环节列出接入 JSAPI 支付时须遵守的约束。
下单
事项 | 说明 |
|---|---|
下单必须传 | 未传 |
| 授权链接里的 |
| 回调页拿到 |
下单必须传入公网可访问的 | |
前端下单按钮须防抖，服务端须防止同一笔业务重复下单 | 前端对同一笔业务重复提交时，服务端应识别为同一次下单，而不是再受理一笔新单。 |
| |
| 返回「商户号该产品权限未开通，请前往商户平台>产品中心检查后重试」或「产品权限预开通中」时，开通 JSAPI 支付，并把下单使用的 AppID 绑定至该商户号。见 常见问题 |
下单必须传入 |
|
调起支付
事项 | 说明 |
|---|---|
须从微信内置浏览器调起 | 必须在微信内置浏览器中调起。从外部浏览器打开再调起时，提示「该商户暂不支持通过外部拉起微信完成支付」。见 常见问题 |
调起参数 | |
支付授权目录须为支付页面所在目录 | 授权目录为支付页面 URL 去掉文件名后的目录，且以 |
网页授权域名与支付授权目录分别配置 | 网页授权域名在公众平台配置，用于获取 |
| |
支付回调、查单
支付回调、查单注意事项，见 支付回调和查单实现指引 。
退款
退款注意事项，见 开发指引 。
对账
对账注意事项，见 开发指引 。
