微信JS

一、支付产品介绍

1.1产品概述

微信 JS 支付也叫微信 JSAPI 支付，是基于微信公众号生态，在微信内网页中直接调起微信支付完成付款的模式，属于微信支付面向线上场景的核心产品，无需用户跳转扫码，实现微信内一键支付的便捷体验。

1.2适用场景

微信 JS 支付仅适用于微信内场景，依托微信公众号/服务号、扫一扫等实现，是微信生态内电商、服务类商户的主流支付方式，适配各类轻量下单、快速支付的业务需求。（本产品为微信 JSAPI 支付，微信官方独立的 H5 支付产品适用于微信外浏览器场景，与本产品无关）

业务场景	场景特点	典型应用案例
微信公众号内支付	用户关注商户公众号，在公众号菜单栏/图文内打开下单页面，直接调起支付	公众号商城：美妆、服饰、生鲜类公众号内下单，一键付款；公众号服务：会员充值、课程报名、水电煤缴费等服务类支付
微信内 H5 网页支付（公众号授权）	商户在微信内打开自定义 H5 网页，完成公众号授权后调起支付收银台	品牌私域 H5 商城：商户独立开发的微信内 H5 购物页面；线下核销类 H5：餐饮团购、景区门票、健身卡券的线上购买 H5

1.3商户入网

商户可联系通联分公司人员签署协议提交入网材料，审核通过入网成功后，即可进行支付产品开通。

二、技术开发准备（仅针对需对接API商户）

第一步：密钥获取（云梯）

设置商户公私钥、加密key

第二步：公共参数获取（云梯）

下载通联公钥

第三步：对接规范

调用通联接口，统一使用POST形式提交，数据格式统一为JOSN，相关SDK及签名方法如下：SDK示例：https://prodoc.allinpay.com/doc/1360/

三、开发指引

3.1核心开发内容

开发模块	核心功能	关联接口
公众号授权	获取用户 openid（微信 JS 支付必传参数），完成用户身份校验，这是调起微信收银台的前提。	微信网页授权接口（https://developers.weixin.qq.com/doc/service/guide/h5/auth.html）
订单生成	生成预支付订单，传入 openid 等核心参数，获取预支付标识	【2085-消费申请】
支付调起	将预支付参数转换为 JS 脚本，在微信内网页 / 小程序调起支付收银台	微信JSAPI支付调起接口、第三方 JS 桥接库
支付结果回调处理	验证通联及微信双重签名，更新订单状态，回复「success」防止重复回调	【订单结果通知】
订单查询	查询支付状态（未收到回调时），或主动查询订单信息	【3001-订单状态查询】、【3002-订单结果查询】
退款（可选）	处理用户退款请求，支持原路退回微信支付账户	【2294-退款申请】
订单对账	下载商户对账文件	【4002-对账单文件下载】

3.2对接规范

测试环境：https://ibstest.allinpay.com/yst/yst-service-api/tx/handle
生产环境：https://ibsapi.allinpay.com/yst/yst-service-api/tx/handle
扣款接口：【2085-消费申请】、【2089-担保消费申请】，支付产品固定上送“WECHAT_PUBLIC-微信JS”
调用通联微信 JS 支付相关接口，统一使用POST形式提交，数据格式为JSON，接口编码UTF-8；相关SDK 示例及签名方法参考通联官方文档：https://prodoc.allinpay.com/doc/1360/。

3.3消费流程

1.用户在微信内打开商户公众号/ H5 /小程序，进入下单页面并提交订单信息。

2.商户后端调用微信网页授权接口获取用户openid，并将 openid、订单金额、商户订单号等参数传入消费申请接口（指定支付产品为微信 JS）。

3.通联系统接收请求后，调用微信支付服务端生成预支付订单，返回预支付标识（prepay_id）及通联订单信息至商户系统。

4.商户后端将预支付参数转换为微信JS 支付脚本，在前端页面触发调起微信支付收银台。

5.用户在微信内确认支付，输入支付密码/完成指纹/面容验证，微信支付完成扣款。

6.微信支付将支付结果同步至通联系统，通联系统通过订单结果通知接口异步推送支付结果至商户系统，同时支持商户主动调用查询接口获取订单终态。

支付产品=微信JS需注意

字段	字段类型	是否必填	字段名称
payMode	JSONObject	是	支付产品为微信 JS 时，payMode=WECHAT_PUBLIC(固定传值，不可修改)
acct	String	是	用户openid由微信分配
orderValidTime	String	否	格式：yyyy-MM-dd HH:mm:ss，默认过期时间 1 小时，最长支持 2 小时
extendParams	String	否	渠道拓展参数，最长 1000 字符，可传入公众号标识、业务类型等自定义信息

核心返回参数关注

字段	字段类型	是否必填	字段名称
respTraceNum	String	是	通联订单号，用于后续订单查询、退款等操作
result	String	否	订单实时状态
prepay_id	String	是	微信预支付标识，调起 JS 支付收银台的核心参数
respCode	String	是	业务返回码00000：请求成功；66666/66667：处理中，需等待异步通知或主动查询；其他编码：请求失败
respMsg	String	是	业务返回说明，失败时返回具体失败原因（如 openid 无效、授权目录错误等）

订单创建成功必传金额字段

字段	字段类型	是否必填	字段名称
payAmount	Long	是	实际支付金额（单位：分），与用户实际扣款金额一致
orderAmount	Long	是	订单总金额（单位：分），需与 payAmount 保持一致（无优惠时）

若商户系统长时间未收到支付结果异步通知，可调用订单状态查询接口或订单结果查询接口，传入通联订单号/ 商户订单号获取最终交易状态。

3.4退款流程

微信 JS 支付的退款流程与微信正扫通用，支持全额退款、部分退款及多次退款，退款金额累计不超过实际支付金额，资金将原路退回用户微信支付绑定的银行卡/零钱/零钱通。

退款接口必填参数

字段	字段类型	是否必填	字段名称
orgRespTraceNum	String	否	原通联订单号
orgReqTraceNum	String	否	原商户订单号，唯一不可重复
orgTransDate	String	否	原订单交易时间，格式：yyyy-MM-dd
orderAmount	Long	是	本次退款金额（单位：分），单次退款金额需大于 0
respUrl	String	否	退款结果后台通知地址，需为 HTTPS 域名

1.调用退款接口时，orgRespTraceNum或orgReqTraceNum+orgTransDate两组参数二选一即可，无需重复传入；

2.多次退款时，需保证每次退款的商户退款单号唯一，避免重复退款。同时退款金额不得超过原订单实际支付金额，超出将直接被系统拒绝。

3.退款申请提交后，通联系统实时受理，微信支付/银行处理时效为 1-3 个工作日，退款结果将通过 respUrl 异步推送。

3.5订单管理

微信 JS 支付订单在商户系统内必须遵循统一状态流转规则，禁止自定义订单状态，确保交易全链路可追溯、可对账、可排查，具体流转如下：

订单类型	订单状态	场景
消费	0：进行中	待支付：商户成功调用通联消费申请接口，获取 prepay_id 并调起支付收银台，等待用户确认支付。支付中：用户已打开支付收银台，正在输入密码 / 验证身份，微信支付通道处于交易处理中。
	1：交易成功	支付成功：微信已完成扣款。
	2：交易失败	支付失败：用户主动取消支付、密码错误、余额不足、银行卡异常、风控拦截、openid 无效、授权目录错误等，支付流程终止。已关闭：订单超过orderValidTime未支付，系统自动关闭；或商户主动关闭未支付订单。
退款	0：进行中	退款中：商户已调用退款接口，通联受理退款请求，微信 / 银行正在处理退款。
	1：交易成功	退款成功：资金已原路退回用户账户，退款流程完结。
	2：交易失败	退款失败：超过退款有效期、通道拒绝、账户异常等原因导致退款无法完成。

3.6订单对账

为满足商户财务对账、资金核对需求，通联为微信JS支付提供多渠道对账文件下载方式，对账文件包含所有微信 JS 支付的交易、退款、手续费等明细，可与商户其他支付方式的对账文件合并展示，支持按日/按月查询。

门户下载对账文件:门户下载对账文件：可在商户门户【对账单下载】菜单下载对账文件

调用 API 接口获取对账文件

商户可调用接口自动下载对账文件，支持日度、月度对账文件获取，接口详情参考通联官方文档：https://prodoc.allinpay.com/doc/476/；接口调用支持批量下载、定时拉取，适配商户财务系统自动化对账需求，文件格式为 CSV/Excel，包含订单号、交易金额、退款金额、手续费、交易时间、支付方式（微信 JS）等核心字段。