支付宝正扫

一、支付产品介绍

1.1 产品概述

通联支付宝正扫是通联支付基于支付宝生态打造的用户主扫商户收款码支付产品，属于支付宝官方标准扫码支付方式。用户打开支付宝“扫一扫”扫描商户生成的动态/静态二维码即可完成付款，无需跳转、无需输入账号，体验轻量化、交易实时生效。本产品是通联支付为线下门店、自助设备、PC网站、H5场景商户提供的一体化扫码收款解决方案。

1.2适用场景

支付宝正扫适用于用户扫商户二维码的线上及线下交易场景，与支付宝反扫（商户扫用户付款码）、支付宝 JSAPI、支付宝H5支付分属不同产品，适配场景相互独立。

业务场景	场景特点	典型应用案例
线下门店收银	用户到店消费，前台/收银机出示二维码，扫码即付	便利店、商超、餐饮、奶茶店、水果店等门店收款
自助设备支付	设备屏幕展示动态二维码，用户自助扫码付款	自动售货机、充电桩、自助储物柜、自助取票机
线上PC/H5支付	PC官网、H5页面生成订单二维码，用户跨端扫码	企业缴费、教育培训报名、软件充值、团购下单
服务核销类支付	团购券、预约服务生成二维码，扫码完成核销 + 支付	到店美业、家政服务、影院票务、景区核销

1.3商户入网

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

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

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

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

设置商户公私钥、加密key

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

下载通联公钥

第三步：对接规范

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

三、开发指引

3.1核心开发内容

开发模块	核心功能	关联接口
订单生成	生成支付宝正扫订单，获取二维码串	【2085-消费申请】
二维码展示	将二维码串转为图片供用户扫码	可使用Qrcode.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

支付产品固定值：payMode=SCAN_ALIPAY

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

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

3.3消费流程

1.用户在商户网站选购商品，选购完成后在商户网站下单。

2.用户下单后选择使用支付宝支付，商户后端调起通联【2085-消费申请】接口，同时指定支付模式为SCAN_ALIPAY。

3.通联接收商户后端请求信息后，调起支付宝服务。接收支付宝返回参数后，将qrCode、通联订单号传递给商户后端。

4.商户后端接收到这些信息后，将qrCode转换为二维码展示在商户前端。

5.用户扫描二维码，完成密码/指纹/面容验证，微信支付完成实时扣款。

6.支付宝将支付结果推送至通联，通联异步推送订单结果给商户。

7.若商户后端未收到通联推送的订单结果，商户可主动调用【订单结果查询】接口获取订单信息。

支付宝正扫必传字段

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

核心返回参数

字段	字段类型	是否必填	字段说明
respCode	String	是	业务返回码 00000：代表成功66666、66667：处理中，即当前的请求已受理，需要继续调用关联的确认类接口，或通过发起订单查询、等待异步通知，来获取处理状态。其他返回码均代表失败。
respTraceNum	String	是	通联订单号，用于后续订单查询、退款、对账等操作
qrCode	String	是	支付宝正扫二维码字符串，用于生成扫码图片。
result	String	否	订单状态：支付成功/支付失败

同时支付宝正扫产品支持支付宝花呗分期，支付宝信用卡分期。选择分期时需上送字段

字段

字段类型

是否必填

字段说明

fqNum

String

否

3花呗分期3期

6花呗分期6期

12花呗分期12期

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

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

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

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

3.6订单对账

为满足财务对账需求，通联支持商户下载对账文件。具体方式如下：

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

调用API接口获取对账文件

调用接口下载对账文件支持下载日度对账文件和月度对账文件，调用详情见：https://prodoc.allinpay.com/doc/476/。