微信正扫

一、支付产品介绍

1.1产品概述

微信正扫也叫主扫/用户扫码支付，是用户主动用微信“扫一扫”扫描商家收款码完成支付的模式，属于微信支付的基础核心产品。

1.2适用场景

微信正扫既适用于线上场景，也适用于线下场景。是微信支付覆盖最广、最灵活的支付方式之一。

业务场景	场景特点	典型应用案例
线上场景	商户在网页/小程序生成收款码，用户用微信扫码完成支付。	PC 端网站支付：电商、游戏、教育平台等 PC 网页展示二维码，用户扫码支付。
		公众号/H5商城：用户在微信内打开商户网页，下单后生成支付码，扫码完成支付。
		小程序内扫码支付：小程序内生成订单码，用户扫码确认支付
线下场景	用户现场扫码，确认订单完成支付。	自助机、售货机、共享设备（充电宝、自习室、洗车）生成动态码，用户扫码支付。

1.3商户入网

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

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

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

设置商户公私钥、加密key

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

下载通联公钥

第三步：对接规范

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

三、开发指引

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

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

功能	接口	描述
订单生成	【2085-消费申请】	支付产品上送“SCAN_WEIXIN-微信正扫”，生成预支付订单，获取二维码链接（code_url）
二维码生成	第三方二维码生成库（如 QRCode.js）	将 code_url 转换为二维码图片展示给用户
支付结果回调处理	【订单结果通知】	验证回调签名、更新订单状态、回复「success」（防止重复回调）
订单查询	【3001-订单状态查询】、【3002-订单结果查询】	查询订单状态（未收到回调时），或主动查询订单信息
退款	【2294-退款申请】	处理用户退款请求，将支付金额将原路退还给客户。
订单对账	【4002-对账单文件下载】	下载商户对账文件

3.3消费流程

1.用户在商户系统前端填写商品信息后，商户后端调用通联系统中的消费申请接口，再由云商通调用微信服务端。

2.通联系统接收微信返回的code_url，将code_url传递给商户系统，商户系统将code_url转换为二维码供用户扫码。

3.用户扫码支付后，同步订单终态。若长时间未获取订单终态，则可主动调用订单状态查询接口进行查询。

4.若长时间未返回订单状态，可调用订单状态查询以及订单详情查询接口查询交易状态。

支付产品=微信正扫需注意

字段	字段类型	是否必填	字段名称
payMode	JSONObject	是	支付产品为微信正扫时，payMode=SCAN_WEIXIN
orderValidTime	String	否	格式：yyyy-MM-dd HH:mm:ss，除特殊说明外，默认过期时间为1小时（最长时间为2小时）
extendParams	String	否	渠道拓展参数，最长1000字符

返回参数关注以下字段

字段	字段类型	是否必填	字段名称
respTraceNum	String	是	通联订单号，可用于查询后续订单状态
result	String	否	订单状态
chnlFrontParamInfo	JOSN	否	渠道参数信息，返回微信侧用于生成二维码的code_url
respCode	String	是	业务返回码 00000：代表成功66666、66667：处理中，即当前的请求已受理，需要继续调用关联的确认类接口，或通过发起订单查询、等待异步通知，来获取处理状态。
respMsg	String	是	业务返回说明，失败时返回失败原因

订单创建成功时注意

字段	字段类型	是否必填	字段名称
payAmount	Long	否	支付金额（单位：分）
orderAmount	Long	否	订单金额（单位分）
chnlFrontParamInfo	JOSN	否	渠道参数信息，订单创建成功后返回微信侧用于生成二维码的code_url

3.3退款流程

若用户需要退款则可调用退款接口，将接口调用成功后支付金额将原路退还给客户。退款需上传参数如下：

字段	字段类型	是否必填	字段名称
orgRespTraceNum	String	否	原通联订单号
orgReqTraceNum	String	否	商户订单号，唯一不可重复
orgTransDate	String	否	订单时间，yyyy-MM-dd
orderAmount	Long	是	退款总金额（单位：分）
respUrl	String	否	后台通知地址

1.上传参数时“orgRespTraceNum”和“orgReqTraceNum+orgTransDate”二选一即可成功调用退款接口

2.退款支持部分退款和全额退款，同时支持多次退款。退款金额不能大于支付金额。

3.4订单终态获取

客户支付完成后通联将支付结果推送到客户异步地址【订单结果通知】，

如果长时间未收到异步结果可以调用扫码交易查询接口查询交易状态【3001-订单状态查询】；

各场景订单状态如下：

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

3.5订单对账

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

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

调用API接口获取对账文件

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