支付宝JS

一、支付产品介绍

1.1 产品概述

通联支付宝 JS 支付（JSAPI）是通联支付基于支付宝开放平台生态打造的、适配支付宝内嵌场景的免扫码支付产品，属于支付宝官方标准 JSAPI 支付方式。用户在支付宝 APP 内打开商户的 H5 页面、生活号、小程序页面，下单后无需扫码，直接通过页面调用支付宝 JSAPI 拉起原生收银台，完成密码/指纹/面容验证即可完成付款。

1.2适用场景

支付宝 JS 支付适用于支付宝 APP 内的全链路交易场景，与支付宝正扫（用户主扫商户码）、支付宝反扫（商户扫用户付款码）分属不同产品，适配场景相互独立，核心适用场景如下：

业务场景	场景特点	典型应用案例
支付宝生活号支付	商户生活号内嵌 H5 商城/小程序，用户在支付宝内完成选品-下单-支付全流程	本地生活服务号、品牌官方生活号、政务缴费生活号
支付宝小程序支付	支付宝小程序内商品/服务下单，直接调起收银台完成支付	电商零售小程序、餐饮外卖小程序、票务预订小程序、便民服务小程序
支付宝内嵌 H5 支付	用户通过支付宝扫码、分享链接打开商户H5页面，在支付宝内置浏览器内完成支付	营销活动页、单品推广页、社群分销 H5、教育培训报名页

1.3商户入网

1.商户主体合规，营业执照在有效期内，不属于支付宝/通联支付禁止准入的行业类目。

2.商户签署合作协议，入网材料经通联支付审核通过后，正式开通支付宝JS支付产品权限。

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

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

设置商户公私钥、加密key

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

下载通联公钥

第三步：对接规范

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

三、开发指引

3.1核心开发内容

开发模块	核心功能	关联接口
用户授权	生成支付宝正扫订单，获取二维码串	alipay.system.oauth.token
订单生成	生成支付宝 JS 支付订单，获取支付调用参数	【2085-消费申请】
支付调起	前端通过通联返回的支付参数，调用支付宝 JSAPI 拉起原生收银台	支付宝官方 JSAPI 接口 https://opendocs.alipay.com/open/common/105591
支付结果回调	验签并更新订单状态，返回 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

支付产品固定值：payMode=ALIPAY_SERVICE

请求方式：POST，数据格式 JSON，编码 UTF-8

开发文档：https://prodoc.allinpay.com/doc/1360/

3.3消费流程

1.用户在支付宝APP内打开商户小程序，选购商品/服务，提交订单。

2.商户前端将订单信息提交至商户后端，商户后端生成全局唯一的商户订单号。

3.商户后端调起通联【2085 - 消费申请】接口，指定支付模式为ALIPAY_SERVICE，同时上送支付宝user_id等必填参数。

4.通联系统接收商户请求后，完成参数校验，调用支付宝服务端预下单接口，发起JSAPI 支付交易请求。

5.支付宝服务端处理交易请求，返回预支付会话标识等核心参数至通联系统。

6.通联系统完成参数签名与封装，将支付调用参数、通联订单号（respTraceNum）返回至商户后端。

7.商户后端将支付调用参数透传给商户前端页面。

8.商户前端通过支付宝JSAPI，使用返回的支付参数直接拉起支付宝原生收银台。

9.用户在收银台确认订单信息，完成支付密码/指纹/面容验证，授权支付宝完成扣款。

10.支付宝服务端完成实时扣款，同步返回支付结果至用户端与通联系统。

11.通联系统接收支付宝支付结果后，通过异步通知接口，将订单终态推送至商户后端预设的回调地址。

12.商户后端接收异步通知后，严格完成验签，校验订单金额、订单号等信息，更新订单状态，按规范返回success 字符串；若未返回 success，通联系统将按规则重发通知。

13.若商户后端未收到异步通知，可主动调用【订单结果查询】接口，获取订单最终状态，严禁以前端返回结果作为订单终态依据。

支付宝JS必填字段

字段	字段类型	是否必填	字段说明
payMode	JSONObject	是	支付模式固定传值：ALIPAY_SERVICE
reqTraceNum	String	是	商户订单号，全局唯一，不可重复
orderAmount	Long	是	订单总金额（单位：分）
payAmount	Long	是	实际支付金额（单位：分）

核心返回参数

字段	字段类型	是否必填	字段说明
respCode	String	是	业务返回码00000：代表接口调用成功66666、66667：交易处理中，需等待异步通知或调用订单查询接口获取终态其他返回码均代表接口调用失败
respTraceNum	String	是	通联系统生成的唯一订单号，用于后续订单查询、退款、对账等操作
payInfo	String	是	支付宝 JSAPI 调起支付的核心参数串，已完成签名封装，可直接用于前端调起支付宝收银台
result	String	否	订单状态：支付成功/支付失败

同时支付宝JS支付宝花呗分期，支付宝信用卡分期。选择分期时需上送字段

字段

字段类型

是否必填

字段说明

fqNum

String

否

3花呗分期3期

6花呗分期6期

12花呗分期12期

3-cc支付宝信用卡分期3期

6-cc 支付宝信用卡分期6期

12-cc支付宝信用卡分期12期

3.4退款流程

支付宝JS退款支持全额退款、部分退款、多次退款，累计退款金额不得超过原订单实付金额，退款资金将原路退回支付宝，退款时效取决于支付宝退款规则。

退款必填参数

字段	字段类型	是否必填	字段说明
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：进行中	待支付：商户成功调用通联消费申请接口，已生成二维码等待支付。支付中：用户扫描二维码，输入密码/验证身份，支付宝通道处于交易处理中。
	1：交易成功	支付成功：支付宝完成扣款，通联推送订单结果至商户系统，订单资金将按结算规则划转至商户账户。
	2：交易失败	支付失败：用户主动取消支付、密码错误、余额不足、银行卡异常、风控拦截等，支付流程终止。已关闭：订单超过orderValidTime未支付，系统自动关闭；或商户主动关闭未支付订单。
退款	0：进行中	退款中：商户已调用退款接口，通联受理请求，支付宝/银行正在处理退款。
	1：交易成功	退款成功：资金已原路退回用户支付宝账户，退款流程完结。
	2：交易失败	退款失败：订单已结算、超过退款有效期、支付通道拒绝、商户账户余额不足等，退款无法完成，通联支付返回具体失败原因。

3.6订单对账

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

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

调用API接口获取对账文件

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