一、支付产品介绍
1.1产品概述
“好码齐”是中国电信打造的聚合支付收款产品，集合了微信支付、支付宝、翼支付、银联云闪付等主流支付方式。通联支付云商通2.0已完成与“好码齐”的接口对接，商户通过云商通2.0接入“好码齐”支付模式后，可在线下实体场景生成二维码，由用户使用微信、支付宝、翼支付或银联云闪付客户端扫码完成支付。
1.2适用场景
好码齐支付模式主要面向线下实体商户的收款场景，用户通过手机客户端扫描商户展示的二维码完成支付。
|
场景类别 |
场景特点 |
典型应用案例 |
|
线上场景 |
商户在网页、公众号、小程序等线上渠道生成收款二维码，用户通过微信、支付宝、翼支付等客户端扫码完成支付。交易不受地理位置限制，支持远程支付。 |
• 公众号/H5商城：用户在微信内访问商户商城，下单后生成支付码，扫码支付。 |
|
线下场景 |
商户在实体经营场所展示收款二维码（码牌、电子屏幕、POS机等），用户现场使用手机客户端扫码支付。交易面对面完成，支持快速结账。 |
• 商超零售：超市、便利店收银台张贴码牌，顾客扫码结账。 |
1.3商户入网
商户可联系通联分公司人员签署协议提交入网材料，审核通过入网成功后，即可进行支付产品开通。
二、技术开发
2.1开发环境准备
第一步：密钥获取（云梯）
设置商户公私钥、加密key
第二步：公共参数获取（云梯）
下载通联公钥
第三步：对接规范
调用通联接口，统一使用POST形式提交，数据格式统一为JOSN，相关SDK及签名方法如下：SDK示例：https://prodoc.allinpay.com/doc/1360/
- 接口说明
3.1 API列表
|
功能 |
接口 |
描述 |
|
订单生成 |
【2085-消费申请】 |
支付产品上送“HMQ-好码齐”，生成预支付订单，获取二维码URL（qrcode_url） |
|
担保交易 |
【担保消费申请】 |
支持担保消费场景，上送“HMQ-好码齐”支付模式 |
|
二维码生成 |
第三方二维码生成库 |
将qrcode_url转换为二维码图片展示给用户 |
|
支付结果回调处理 |
【订单结果通知】 |
接收好码齐支付回调，验证签名、更新订单状态，返回success（防止重复回调） |
|
订单查询 |
【3001-订单状态查询】 |
查询订单状态（未收到回调时使用） |
|
订单详情查询 |
【3002-订单详情查询】 |
查询订单完整详细信息 |
|
退款 |
【2294-退款申请】 |
处理用户退款请求，支持部分退款和多次退款 |
|
同步订单 |
【同步订单】 |
主动同步好码齐侧订单状态 |
|
订单对账 |
【订单对账】 |
D+1日进行好码齐交易对账 |
|
对账文件下载 |
【应用集合对账文件下载】 |
下载好码齐交易账单 |
说明：好码齐暂不支持订单关闭功能，订单过期后由好码齐侧自动关闭。
3.2消费流程
商户调用消费申请接口
商户系统调用云商通【消费申请】或【担保消费申请】接口，支付模式上送“HMQ-好码齐”，系统校验以下条件：
校验应用是否已配置好码齐支付产品
根据支付模式上送的appid，检查【好码齐收款商户管理】中该应用下是否配置了对应appid
如未配置，则报错
云商通请求好码齐
校验通过后，云商通请求好码齐【扫二维码支付】接口，好码齐生成支付二维码URL并返回。
生成二维码并展示
商户将好码齐返回的qrcode_url通过第三方二维码生成库转换为二维码图片，展示给用户。
用户扫码支付
用户使用微信、支付宝、翼支付或银联云闪付客户端扫描二维码，确认支付金额后完成支付。好码齐默认订单有效期为5分钟，超时未支付则自动关闭。
好码齐支付回调
支付成功后，好码齐向云商通推送支付回调。好码齐每隔5分钟推送一次，共推送6次，云商通收到支付结果后返回“success”通知好码齐停止推送。
订单状态更新
云商通接收到支付回调后，更新订单状态
同时落地以下渠道信息：
|
好码齐返回信息 |
云商通落地字段 |
|
trade_id（好码齐系统订单号） |
渠道流水号 |
|
pay_time（支付成功时间） |
渠道完成时间 |
|
pay_type（支付方式：0微信/1支付宝/3翼支付/5银联二维码） |
交易类型 |
|
attach（附加数据） |
附加数据 |
轮询兜底机制
若商户未收到好码齐异步通知，云商通轮询机制会主动请求好码齐【同步订单】接口获取支付状态，更新订单状态及渠道支付信息。
超时处理规则：
订单过期时间必须上送大于5分钟
半小时内未拿到好码齐返回的订单状态，系统不做状态处理
超过半小时仍无好码齐订单状态返回，则置为交易失败
调用【消费申请】/【担保消费申请】接口时，支付模式上送“HMQ-好码齐”，需注意以下字段：
|
字段 |
字段类型 |
是否必填 |
字段说明 |
|
payType |
String |
是 |
支付形态，枚举值：scan_hmq |
|
appid |
String |
是 |
好码齐分配商户appid |
|
discountableAmount |
String |
否 |
优惠金额，单位：分 |
|
discountCoupon |
String |
否 |
微信支付优惠券 |
|
attach |
String |
否 |
附加数据，在查询API和支付回调中原样返回 |
|
openid |
String |
否 |
好码齐系统中用户的openid |
|
deviceNum |
String |
否 |
接口调用设备号，设备唯一标识 |
|
orderValidTime |
String |
否 |
订单过期时间，格式：yyyy-MM-ddHH:mm:ss，须大于5分钟 |
返回参数关注以下字段：
|
字段 |
字段类型 |
字段说明 |
|
respTraceNum |
String |
通联订单号，可用于后续查询订单状态 |
|
result |
String |
订单状态 |
|
chnlFrontParamInfo |
JSON |
渠道参数信息，包含好码齐返回的qrcode_url（二维码URL） |
|
respCode |
String |
业务返回码，00000代表成功 |
|
respMsg |
String |
业务返回说明，失败时返回失败原因 |
若长时间未返回订单状态，可调用【订单状态查询】及【订单详情查询】接口查询交易状态。记账逻辑与收银宝侧保持一致。
3.3退款流程
若用户需要退款则可调用退款接口，将接口调用成功后支付金额将原路退还给客户。退款需上传参数如下：
|
字段 |
字段类型 |
是否必填 |
字段名称 |
|
orgRespTraceNum |
String |
否 |
原通联订单号 |
|
orgReqTraceNum |
String |
否 |
商户订单号，唯一不可重复 |
|
orgTransDate |
String |
否 |
订单时间，yyyy-MM-dd |
|
orderAmount |
Long |
是 |
退款总金额（单位：分） |
|
respUrl |
String |
否 |
后台通知地址 |
- 上传参数时“orgRespTraceNum”和“orgReqTraceNum+orgTransDate”二选一即可成功调用退款接口
- 退款支持部分退款和全额退款，同时支持多次退款。退款金额不能大于支付金额。
3.4订单管理
好码齐支付模式的订单状态映射关系如下：
|
订单类型 |
云商通订单状态 |
场景说明 |
|
消费 |
0：进行中 |
订单已创建，等待用户扫码支付；或用户已扫码正在处理中 |
|
1：交易成功 |
用户已完成支付，资金已到账 |
|
|
2：交易失败 |
支付失败（用户取消、余额不足、风控拦截等）；或订单超时未支付已关闭 |
|
|
退款 |
0：进行中 |
退款申请已提交，好码齐/银行正在处理 |
|
1：交易成功 |
退款成功，资金已原路退回用户账户 |
|
|
2：交易失败 |
退款失败（超过退款有效期、账户异常等原因） |
商户可通过以下方式查询订单状态：
【订单查询】菜单：在【订单查询】菜单中新增“好码齐”支付模式筛选条件，支持消费、担保消费、退款订单的查询及日志落地
【订单状态查询】接口：调用【3001-订单状态查询】接口查询订单状态
【订单详情查询】接口：调用【3002-订单详情查询】接口获取订单完整信息
【同步订单】接口：主动请求好码齐同步订单状态
3.5订单对账
为满足财务对账需求，通联支持商户下载对账文件。具体方式如下：
门户下载对账文件：可在商户门户【对账单下载】菜单下载对账文件
调用API接口获取对账文件
商户可调用【下载商户对账文件】接口下载对账文件，支持日度、月度对账文件获取，文件格式支持CSV/Excel，包含订单号、交易金额、退款金额、手续费、交易时间、支付方式等核心字段。