微信小程序支付

一、支付产品介绍

1.1 产品概述

微信小程序支付是基于微信小程序生态打造的支付产品，是微信支付面向轻量、高频线上消费场景的核心支付方式，用户在微信小程序内即可完成下单与支付，无需跳转至外部页面或扫码，实现小程序内一键支付的轻量化体验，适配小程序生态下各类商户的交易需求，是通联支付为微信小程序商户提供的一体化支付解决方案。

1.2 适用场景

微信小程序支付仅适用于微信小程序内线上交易场景，依托已认证的微信小程序实现，是电商、本地生活、服务类小程序商户的主流支付方式，适配快速下单、即时消费、线下核销等各类轻量交易需求。（本产品为微信小程序原生支付，与微信 JSAPI 支付、H5 支付分属不同产品，适配场景相互独立）

业务场景	场景特点	典型应用案例
电商类小程序支付	用户在小程序内浏览商品、加入购物车，提交订单后直接调起支付	零售小程序：美妆、服饰、家居用品小程序下单支付；生鲜小程序：果蔬、海鲜同城配送小程序一键付款
本地生活服务小程序支付	小程序内完成服务预约 / 购买，支持到店核销或线上履约，支付环节闭环	餐饮小程序：到店核销的团购券、外卖点餐支付；生活服务：洗车、美甲、家政服务的小程序预约付款
文旅/出行类小程序支付	景区、场馆、出行类小程序完成票务购买 / 行程预订，即时支付即时生效	景区小程序：门票、游乐项目线上购买；出行小程序：网约车、共享单车、城际大巴的小程序订票支付
服务充值类小程序支付	小程序内完成会员充值、虚拟币购买、课程缴费等，资金实时到账	教育小程序：网课、线下课程的报名缴费；会员类小程序：商超、影院的会员充值、积分兑换支付

1.3 商户入网

商户需联系通联支付分公司人员签署合作协议，提交上述入网材料，经通联支付审核通过后，完成微信支付商户号与通联收银宝商户号的绑定，方可正式开通微信小程序支付产品。

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

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

设置商户公私钥、加密key

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

下载通联公钥

第三步：对接规范

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

三、开发指引

3.1 核心开发内容

开发模块	核心功能	关联接口
小程序用户授权	获取用户 openid（小程序支付必传参数），完成用户身份校验	微信小程序原生授权接口（https://developers.weixin.qq.com/miniprogram/dev/api/open-api/login/wx.login.html）
订单生成	生成小程序预支付订单，传入 openid、订单金额等核心参数，获取预支付标识	【2085-消费申请】
支付调起	将预支付参数转换为小程序原生支付脚本，在小程序内调起微信支付收银台	微信小程序支付调起接口（https://developers.weixin.qq.com/miniprogram/dev/api/payment/wx.requestPayment.html）
支付结果回调处理	验证通联及微信双重签名，更新商户系统订单状态，回复「success」防止重复回调	【订单结果通知】
订单查询	未收到支付回调时，主动查询订单实时状态；支持按商户订单号 / 通联订单号查询	【3001-订单状态查询】、【3002-订单结果查询】
退款（可选）	处理用户退款请求，支持全额 / 部分退款，资金原路退回用户微信支付账户	【2294-退款申请】
订单对账	下载交易、退款、手续费明细对账文件，完成财务资金核对	【4002-对账单文件下载】

3.2 对接规范

测试地址：https://ibstest.allinpay.com/yst/yst-service-api/tx/handle

生产地址：https://ibsapi.allinpay.com/yst-service-api/tx/handle

核心扣款接口：【2085 - 消费申请】、【2089 - 担保消费申请】，支付产品固定上送“WECHATPAY_MINIPROGRAM-微信小程序支付”，不可修改。

调用规则：所有通联微信小程序支付相关接口，统一使用POST方式提交，请求数据格式为JSON，接口编码为UTF-8。

开发参考：通联官方 SDK 示例、签名方法、接口详情可参考通联支付开发者文档：https://prodoc.allinpay.com/doc/1360/

3.3 消费流程

1.用户在微信内打开商户小程序，浏览商品/服务后提交订单，确认订单金额、收货 / 核销信息。

2.商户小程序后端调用微信小程序login 接口获取用户 code，通过 code 换取用户 openid（小程序支付必传），并将 openid、商户订单号、订单金额等参数传入通联【2085 - 消费申请】接口（支付产品指定为 WECHAT_MINI）。

3.通联支付系统接收请求后，调用微信支付服务端生成小程序预支付订单，返回预支付标识（prepay_id）、通联订单号及相关支付参数至商户小程序后端。

4.商户小程序后端将预支付参数转换为微信小程序原生支付脚本，前端调起微信支付收银台。

5.用户在小程序内确认支付，完成密码/指纹/面容验证，微信支付完成实时扣款。

6.微信支付将支付结果同步至通联支付系统，通联系统通过【订单结果通知】接口异步推送支付结果至商户小程序后端；若商户未收到回调，可主动调用订单查询接口获取订单终态。

支付产品=微信小程序支付需注意

字段	字段类型	是否必填	字段说明
payMode	JSONObject	是	支付产品固定传值：WECHATPAY_MINIPROGRAM
acct	String	是	用户openid由微信分配
payAmount	Long	是	实际支付金额（单位：分），与用户实际扣款金额一致
orderAmount	Long	是	订单总金额（单位：分），无优惠时需与 payAmount 完全一致
reqTraceNum	String	是	商户订单号，全局唯一，不可重复

核心返回参数关注

字段	字段类型	是否必填	字段说明
respTraceNum	String	是	通联订单号，用于后续订单查询、退款、对账等操作
prepay_id	String	是	微信小程序预支付标识，调起支付的核心参数，有效期 2 小时
respCode	String	是	业务返回码：00000 = 请求成功；66666/66667 = 处理中（需等待回调/主动查询）；其他编码 = 请求失败
respMsg	String	是	业务返回说明，失败时返回具体原因（如 openid 无效、域名配置错误、金额异常等）
result	String	否	订单实时状态，如交易成功、交易失败

可选扩展字段

字段	字段类型	是否必填	字段说明
orderValidTime	String	否	订单有效期，格式：yyyy-MM-dd HH:mm:ss，默认 1 小时，最长支持 2 小时
extendParams	String	否	渠道拓展参数，最长 1000 字符，可传入小程序页面路径、商品类型等自定义信息

3.4 退款流程

微信小程序支付的退款流程与微信支付原生规则一致，支持全额退款、部分退款及多次退款，累计退款金额不得超过原订单实际支付金额，退款资金将原路退回用户微信支付绑定的银行卡/零钱/零钱通，退款时效由微信支付及银行处理规则决定。

退款申请接口必填参数

字段	字段类型	是否必填	字段说明
orderAmount	Long	是	本次退款金额（单位：分），单次退款金额需大于 0
reqTraceNum	String	是	商户退款单号，全局唯一，不可重复
orgRespTraceNum	String	否	原通联订单号（与原商户订单号二选一）
orgReqTraceNum	String	否	原商户订单号（与原通联订单号二选一）
orgTransDate	String	否	原订单交易日期，格式：yyyy-MM-dd（传原商户订单号时必填）
respUrl	String	否	退款结果异步通知地址，需为 HTTPS 域名，用于接收退款成功 / 失败通知

1.调用退款接口时，orgRespTraceNum（原通联订单号）或orgReqTraceNum+orgTransDate（原商户订单号 + 原交易日期）两组参数二选一即可，无需重复传入。

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

3.退款申请提交后，通联支付系统实时受理，微信支付/ 银行处理时效为1-3 个工作日，退款结果将通过 respUrl 异步推送至商户系统；商户也可调用订单查询接口查询退款状态。

4.订单已完成资金结算、超过微信支付退款有效期的，将无法通过接口发起退款，需通过线下人工方式处理。

3.5 订单管理

微信小程序支付订单在商户系统内需遵循统一状态流转规则，禁止自定义订单状态，确保交易全链路可追溯、可对账、可排查，状态定义与微信支付原生规则一致：

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

3.6 订单对账

3.6订单对账

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

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

调用 API 接口获取对账文件

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