银联统一在线收银台
最近更新时间：2023.10.17
1. 产品介绍
1.1 简介
商户开通银联统一收银台后，消费者在向商户付款时选择银联，支持消费者在手机端用已安装的银行APP完成支付。银联会提供旗下多种支付工具，如各银行APP、云闪付APP、银联手机闪付等。
银联线上统一收银台支持银行
1.2 应用场景
- 主要用于线上交易场景，如电商购物、旅游平台等
可以下载斗拱演示APP了解银联统一收银台的效果。
2. 接入前准备
2.1 商务准备
-
选择接入模式
-
直签模式：指商户与汇付直接签约。具体流程：商户完成协议签署后，商户需要准备好入网材料提供给汇付销售人员，汇付收到后会尽快为商户发起入网申请，待审核通过入网成功后，商户联系人将收到短信通知控台账号及密码。
-
服务商模式：指服务商与汇付签约，服务商通过接口或控台方式完成商户入网。具体流程：服务商完成协议签署后，服务商需要准备好入网材料提供给汇付销售人员，汇付收到后会尽快为服务商发起入网申请，待审核通过入网成功后，服务商联系人将收到短信通知控台账号及密码。
-
客户要准备好线上业务场景，快捷支付可以集成到APP的线上场景中。
-
在斗拱完成商户进件入网
- 直签模式：已有汇付销售人员申请开通，商户无须另行操作；
- 服务商模式：
- 控台入网：参考服务商控台进件流程，渠道商接入指引；
- API入网：企业商户调用企业商户基本信息入驻接口 、小微商户调用个人商户基本信息入驻接口 完成开户、绑卡、结算配置。
-
选择接入功能并准备相关材料
- 银联统一在线收银台支付能力：
- 直签模式：联系汇付销售人员申请开通，商户无须另行操作；
- 服务商模式：联系汇付销售人员申请开通服务商银联统一在线收银台支付权限，开通后给予所属商户开通相关权限；
- 银联统一在线收银台支付能力：
2.2 对接准备
第一步：密钥获取
联调之前需要先获取公私钥，参见公私解钥参数获取说明；
第二步：公共参数获取
登录服务商/商户控台后，可在开发设置-开发者信息中，获取sys_id，product_id参数信息;（如控台未展示，请联系对接群内汇付技术助手提供）
3. 开发指引
3.1 对接规范
调用汇付接口，均采取POST形式提交，数据格式统一为JSON格式，相关SDK及签名方法见链接：
SDK示例：Java SDK
加签验签：v2版接口加签验签
3.3 系统调用流程
3.3.1 交易流程
银联APP支付Android开发包下载 | iOS开发包下载
银联统一在线收银台接口
入参需关注以下字段：
| 参数 | 中文名 | 说明 |
|---|---|---|
| pay_card_no | 交易银行卡卡号 | 卡号是密文(公私钥加解密)； |
| card_number_lock | 卡号锁定标识 | 1-表示锁定卡，锁定指只能用pay_card_no卡号做支付。默认为空-不锁定； |
| ebank_en_abbr | 直通模式的银行标识 | 目前支付以下银行： CCB-中国建设银行， CNCB-中信银行， CEB-光大银行， PAB-平安银行； |
| front_url | 前端跳转地址 | 支付成功后跳转页面，格式：http或https开头 |
| notify_url | 异步通知地址 | 交易结果异步通知地址，格式：http或https开头 |
同步返参需关注字段：
| 参数 | 中文名 | 说明 |
|---|---|---|
| union_order_no | 银联受理订单号 | 银联受理订单,银联移动支付系统返回该流水号，调用支付控件时使用 示例值：562616342321571143110 |
异返参需关注字段：
| 参数 | 中文名 | 说明 |
|---|---|---|
| union_order_no | 银联受理订单号 | 银联受理订单,银联移动支付系统返回该流水号，调用支付控件时使用 示例值：562616342321571143110 |
| trans_status | 交易状态 | 绑卡状态，I:初始化,P:处理中,S:成功,F:失败 |
| bank_code | 银行返回码 | N |
| bank_message | 银行返回信息 | 示例值：成功[0000000] |
3.3.2 退款流程
完整的交易流程还要包括退款。由于用户或者商户的原因需要退款时，商户可以通过本接口将支付款退还给用户，退款成功资金将原路返回。
参见线上交易退款接口；
关注以下请参：
| 参数 | 中文名 | 必填 | 说明 |
|---|---|---|---|
| org_req_date | 原交易请求日期 | Y | 用户发起支付的日期 |
| org_req_seq_id | 原交易请求流水号 | C | 商户系统发给斗拱的指令流水号 |
| org_hf_seq_id | 原交易全局流水号 | C | 汇付生成的系统流水号 |
| ord_amt | 申请退款金额 | Y | 退款金额<=原交易金额 |
- 原交易请求流水号、原交易全局流水号、原交易微信支付宝的商户单号三选一即可；
- 退款金额不能大于交易金额；由于接口支持多次部分退款，多次退款场景下退款总额不能高于原交易金额；
- 退款也是以异步返回的成功或失败状态为最终结果；
- 一些特殊场景下退款时效可能比较长，注意接口描述文档中的退款时效说明；
3.3.3 对账流程
为了满足商户财务的对账需求，斗拱提供了对账功能。
方案一：控台下载；
方案二：接口获取；参见交易结算对账单查询接口
- 接口下载的对账文件包括以下四类：
- 日对账单类型：包括日结算对账单、日分账对账单、日出金对账单；
- 日交易数据：主要是各种支付交易记录；
- 月结算对账单：按月汇总的结算对账单；
- 月交易数据：按月汇总支付交易记录；
3.3.4 异步通知
针对交易结果，汇付会通过异步消息的方式通知客户系统。
调用汇付接口时上送的异步通知地址为http/https路径：服务器为POST回调，默认超时时间为5秒，超时后会重试3次;不支持HTTP重定向;服务器对应答不是200~300之间的错误，会默认重试3次;异步通知服务器对HTTPS不认证验签和ALLOW_ALL_HOSTNAME_VERIFIER;如商户自定义通知端口，请使用8000-9005内端口，否则无法通知;URL 上请勿附带参数;异步回调请求编码集为：UTF-8;收到通知后请返回状态码“200”，响应异步通知。
注意事项：
同样的异步消息可能会通知多次，因此接收异步消息的处理需做好幂等，保障多次接收到同样的消息处理后结果不变。
在实现异步消息接收的同时，都建议您在重要的业务环节，通过反查接口确认 非终态 支付订单的状态，以保证在发生异步消息延迟或无法送达情况下的支付结果一致性。
详见异步通知使用说明。
4. API列表
| 类型 | 功能 | 描述 |
|---|---|---|
| 应用程序接口 | 银联统一在线收银台 | 银联统一在线收银台接口 |
| 应用程序接口 | 线上交易查询接口 | 查询单笔线上交易状态及明细 |
| 应用程序接口 | 线上交易退款接口 | 支持线上交易全额或部分退款 营销补贴退款：支持全额退款、银行卡退款，不支持单独退补贴金额 |
| 应用程序接口 | 线上退款查询接口 | 查询单笔线上退款状态及明细 |
