收银宝POS支付

一、支付产品介绍

1.1 产品概述

收银宝POS支付是通联支付面向线下实体商户推出的全场景线下收单产品，整合传统银行卡收单与新兴移动支付能力，支持磁条卡、芯片卡、非接闪付等全形态银行卡支付，同时兼容微信、支付宝、云闪付、数字人民币等主流扫码支付，覆盖传统POS、智能POS、扫码POS等多终端形态通联支付商户服务平台。

1.2 适用场景

收银宝POS支付适配各类线下实体经营场景，典型应用如下：

业务场景	场景特点	典型应用案例
线下零售门店	实体门店日常收银，交易笔数多、金额灵活，需支持多种支付方式快速收款，配套小票打印与对账能力	便利店、社区超市、烟酒专卖店、服饰鞋帽门店、数码产品零售店
餐饮堂食与外卖	堂食点餐结账、外卖到店核销，高峰时段交易并发高，需对接点餐/收银系统，支持免密快速支付	连锁中餐厅、快餐品牌、咖啡茶饮门店、烘焙店、外卖自提点
连锁品牌门店	多门店统一经营，总部需集中管控终端、统一对账与资金归集，支持门店级交易数据统计与权限分级	连锁便利店、品牌餐饮连锁、母婴用品连锁、健身美体门店
医疗教育线下缴费	公立机构窗口缴费，需支持对公/对私银行卡支付，交易全程可追溯，满足财务合规与审计要求	医院门诊/住院缴费、私立学校学费缴纳、职业培训机构线下报名缴费

1.3 商户入网

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

2.完成通联收银宝商户号注册与实名认证，无不良经营记录与风控黑名单记录

3.商户经营内容与备案类目一致，不得超范围开展支付业务，不得转借支付接口与终端设备

4.申领通联认证的POS终端设备，完成终端入库、绑定与激活，确保终端网络环境稳定

二、技术开发准备

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

点击密钥管理获取商户公钥、私钥及加密密钥。

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

点击通联公钥下载通联公钥

第三步：对接规范

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

三、开发指引

3.1 核心开发内容

开发模块	核心功能	关联接口
订单生成	支付模式固定传值payMode=POS_ORDER_VSP，传入订单信息与指定终端号，订单自动推送至对应 POS 终端待支付	【2085-消费申请】
支付结果回调	用户在终端完成支付后，通联主动推送支付终态结果至商户回调地址，商户验签通过后必须返回字符串success	【订单结果异步通知】
订单查询	未收到异步通知时，主动查询订单最终状态	【3001-订单状态查询】、【3002-订单结果查询】
退款（可选）	支持订单全额/部分退款，资金原路退回用户付款账户	【2294-退款申请】
订单对账	下载交易、退款、手续费明细对账文件，完成财务对账	【4002-对账单文件下载】
终端管理（可选）	查询商户名下终端列表、在线状态与绑定信息，适配连锁门店多终端统一管理需求	【4001-终端信息查询】

3.2对接规范

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

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

支付产品固定值：payMode=SCAN_UNIONPAY

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

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

3.3 消费流程

1.用户在商户线下门店选购商品，收银员在收银系统创建订单，选择POS支付

2.商户收银系统调用通联【2085 -消费申请】接口，传入订单信息、指定终端号，支付模式设为ORDER_VSPPAY

3.通联系统校验订单合法性与终端状态，将订单推送至指定POS终端，同步返回受理成功结果

4.POS终端展示待支付订单，收银员确认订单后，用户完成支付操作（刷卡/插卡/挥卡/扫码/刷脸）

5.POS 终端实时展示支付结果并打印交易小票，同时通联系统生成交易终态

6.通联系统将支付成功/失败结果异步推送至商户预设回调地址

7.商户系统收到通知并验签通过后，更新收银系统订单状态，完成收银流程

8.未收到异步通知时，商户可主动调用【3001-订单状态查询】接口获取订单终态

POS 支付必填字段

字段	字段类型	是否必填	字段说明
payMode	String	是	支付模式固定传值ORDER_VSPPAY
reqTraceNum	String	是	商户订单号，全局唯一，不可重复
orderAmount	Long	是	订单总金额（单位：分）
payAmount	Long	是	实际支付金额（单位：分），需与orderAmount 一致
terminalNo	String	是	指定收款的POS终端号，需为商户名下已激活终端
orderSubject	String	否	订单主题，展示在POS终端订单列表中，便于收银员识别
limitPay	String	否	支付限制：no_credit-禁止信用卡支付，默认空则借、贷记卡均支持

核心返回参数

字段	字段类型	是否必填	字段说明
respCode	String	是	业务返回码00000：代表接口调用成功66666、66667：交易处理中，需等待异步通知或调用订单查询接口获取终态其他返回码均代表接口调用失败
respTraceNum	String	是	通联系统生成的唯一订单号，用于后续订单查询、退款、对账等操作
result	String	否	订单状态：支付成功/支付失败

3.4退款流程

银联正扫退款支持全额退款、部分退款、多次退款，累计退款金额不得超过原订单实付金额，退款资金将原路退回，退款时效取决于银联和发卡行清算规则。

退款必填参数

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

退款操作规则

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

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

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

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

3.5 订单管理

收银宝POS支付订单需遵循统一状态流转规则，禁止自定义订单状态，确保交易全链路可追溯、可对账、可排查：

订单类型	订单状态	场景说明
消费	0：进行中	待支付：订单已推送至POS终端，等待用户完成支付支付中：用户已发起支付操作，银行渠道正在处理
	1：交易成功	支付成功：用户已完成付款，交易已清算确认
	2：交易失败	支付失败：用户取消、余额不足、风控拦截等原因导致支付终止已关闭：订单超时未支付自动关闭，或商户主动撤销未支付订单
退款	0：进行中	退款中：商户已提交退款申请，通联已受理，银行正在处理退款流程
	1：交易成功	退款成功：退款资金已原路退回用户支付账户，退款流程完结
	2：交易失败	退款失败：商户账户余额不足、超过退款有效期、支付通道拒绝等原因导致退款失败

3.6订单对账

为满足商户财务对账、资金核对与多门店管理需求，通联提供两种对账文件获取方式，对账文件包含所有 POS 终端的交易、撤销、退款、手续费明细，支持按门店、终端号维度筛选：

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

调用API接口获取对账文件

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