反扫码支付

1、修订记录

修订记录 日期 说明
1.0 2023.11.01 初版

2、业务说明

（1）接口说明

场景说明：
商家需使用扫码枪等条码识别设备，扫描用户钱包上的 条码/二维码 完成收款，用户仅需出示付款码，所有收款操作由商家端完成。适用于各类商家系统，如大型商超、餐饮，连锁品牌等商家。

注意事项：
1、整合银联云闪付、微信、支付宝反扫接口，调用该接口进行反扫支付
2、收银员使用扫码设备读取用户 APP 展示的二维码后，商家系统识别付款APP， 通过系统调用该接口发起支付
3、当收单机构返回支付中或交易状态不明时， 需要调用交易查询接口查询订单实际支付状态。
4、notifyUrl 通知字段，支持成功时异步通知。

请求主体类型：application/json

请求方式：POST

3、请求地址

环境 HTTPS请求地址
测试环境 https://appdev.ysepay.com/openapi/unify/scan/barcodepay
正式环境 https://ysgate.ysepay.com/openapi/unify/scan/barcodepay

4、请求参数说明

4.1、公共请求参数

参数 类型(长度） 必填 参数说明
timeStamp String Y 发送请求的时间，格式"yyyy-MM-dd HH:mm:ss"
method String(128) Y 接口名称，固定值：unify.scan.barcodepay
charset String(10) Y 请求使用的编码格式，如utf-8,gbk,gb2312等,固定为utf-8
sign String Y 商户请求参数的签名串（签名算法默认为国密）,详见demo,注意:请用商户私钥进行签名
check String Y 银盛公钥加密随机生成的字符串（key）得到的加密值，详见demo
bizContent String Y 业务参数的集合，最大长度不限，除公共参数外所有请求参数都必须放在这个参数中传递。注意：需要通过AES以及随机生成的字符串（key）加密业务参数集合，得到bizContent
reqId String Y 请求唯一流水号,商户系统唯一，要求32个字符内（最少14个字符），只能是数字、大小写字母_-且在同一个商户号下唯一。最后12位要求格式为"yyMMddHHmmss" 示例值：xy1415220315145602
certId String Y 发起方商户号，服务商在银盛给自己开设的商户号，即可当作发起方商户号，由银盛生成并下发。 注意：不同于子商户号，服务商发展的商户即为子商户号
version String Y 调用的接口版本，固定为：1.0

4.2、业务请求参数

（bizContent加密前的json数据明文字符串）

参数 类型(长度） 必填 参数说明
orderId String(32) Y 商户订单号,商户系统生成的订单号，要求如下：
1、须保证在商户端不重复。
2、只能由大小写英文字母、数字、下划线及横杠组成。
建议前8位为交易日期，如20220525，范围跨度支持包含当天在内的前后一天，示例值：202205256843192280647118。
shopDate String(8) Y 交易日期
note String(250) Y 订单备注
amount String(10) Y 订单总金额,该笔订单的资金总额，必须为正整数，单位为：分。
currency String(3) N 交易币种,默认CNY（人民币）。
payeeMercId String(20) Y 收款商户号,收款商户号（银盛支付生成并下发）。
payeeMercName String N 收款方商户名称,收款商户号对应商户名称。
timeOutExpress String(5) Y 交易超时时间,订单失效时间, 单位分钟，最小1分钟，最长不超过21600分钟.。
extendParams String(500) N 业务扩展参数,业务扩展参数，一个json字符串,orderMode订单模式，暂时可选的值为:00 代表购物车模式;sellerList参与分账的收款方信息数组，每个元素包含sellerId收款方银盛支付用户号。实时分账业务，orderMode和sellerList均不能为空，orderMode的值必须为00。样列：{ "cartType": "00", "orderMode": "00", "sellerList": [{ "sellerId": "123" }, { "sellerId": "456" }] }。示例值：样例8.8
extraCommonParam String(2000) N 公用回传参数, 商户自定义数据域，原样返回。
busiCode String(10) Y 业务代码,请联系银盛客户经理获取。注意：业务代码非固定值，不同到账方式需要传不同的业务代码。
bankType String(9) N 二维码行别,微信：1902000；支付宝：1903000；中国银联：9001002；招商银行：3085840。
scene String(32) N 支付场景,条码支付取值：bar_code 声波支付取值：wave_code 刷脸支付：security_code。注：当bankType域为支付宝：1903000时，此域为必填字段。
authCode String(1000) Y 扫码支付授权码,扫码支付授权码(APP中的付款码)，设备读取用户展示的条码或者二维码信息。
deviceInfo String(32) N 终端设备号,当bank_type域为中国银联：9001002时，此域为必填字段。银联反扫必传8位整数 ，支付宝上送终端号共用此字段。
subMerchantInfo Object N 二级商户信息
consigneeInfo Object N 收货人信息
appId String(32) N 微信公众号账号ID,微信分配的子商户公众号账号ID 示例值：wx8888888888888888。
limitCreditPay String(2) N 是否限制信用卡,类型如下：
0：不限制（默认值）；
1：禁用信用卡；
2：禁用花呗；
3：禁用花呗分期；
4：禁用所有信用支付类型
hbFqNum String(2) N 花呗分期期数,仅支付宝支付的时候生效,目前期数支持6,12 示例值：6。
allowRepeatPay String(1) N 是否允许多次支付,Y：允许；N：不允许；
当参数为空或者Y时，如果该笔订单交易状态非成功状态时，支持选择其他支付方式继续付款；
当参数为N时表示当该笔订单交易状态为失败状态时，不支持选择其他支付方式继续付款；
failNotifyUrl String(190) N 失败通知地址,交易状态为失败时，银盛支付服务器主动通知商户网站里指定的页面http路径，支持多个url进行异步通知，多个url用分隔符“,”分开，格式如：url1,url2,url3
注：只有不允许多次支付的交易才会通知。
notifyUrl String(500) Y 通知地址,交易成功异步通知到商户的后台地址，支持多个url进行异步通知，多个url用分隔符“,”分开，格式如：url1,url2,url3。
detail Object N 微信商品详情
aliGoodsDetails Array N 支付宝营销信息
srcIP String(16) Y 发起方IP
submerIp String(16) N 子商户ip
storeId String(32) N 商户门店编号
alipayStoreId String(32) N 支付宝的店铺编号
operatorId String(28) N 商户操作员编号
unionQrcodeParams Object N 银联259号文条码改造字段
terminalParams String N 设备终端信息,支付宝刷脸支付时，商户传入设备终端字段,json格式。
businessParams String N 支付宝刷脸支付参数,支付宝刷脸支付时，商户传入的业务参数，应用于安全，营销参数等直接传入场景，json格式。
extendParamsChannel String N 支付宝业务拓展参数,支付宝业务拓展参数json格式,示例： { "food_order_type": "qr_order" }。
fqType String(2) N 分期类型,值为00表示花呗分期,值01表示信用卡分期。不填默认为花呗分期

4.2.1 subMerchantInfo具体参数

参数 类型(长度） 必填 参数说明
merName String(50) N 二级商户名称
merShortName String(50) N 二级商户简称
merAddr String(200) N 二级商户地址
telephone String(13) N 客户手机号
merNo String(32) N 二级商户编号
category String(20) N 类目编号
mrchntCertId String(18) N 身份证号,只支持身份证格式。

4.2.2 consigneeInfo具体参数

参数 类型(长度） 必填 参数说明
consigneeName String(150) N 收货人姓名
consigneeAddr String(200) N 收货地址
transportationInfo String(200) N 物流配送信息,物流名称+订单号。
commodityName String(150) N 商品名称
commodityNumber String(10) N 商品数量

4.2.3 detail具体参数

参数 类型(长度） 必填 参数说明
costPrice String(10) N 订单原价,单位分。
receiptId String(32) N 商品小票ID,长度不能超过32位。
goodsDetails Array N 商品列表

4.2.3.1 goodsDetails具体参数

参数 类型(长度） 必填 参数说明
goodsId String(32) Y 商户商品编码,由半角的大小写字母，数字，下划线，中划线中的一种或者几种组成，长度不能超过32位 示例：Shouji_abcef_001-001。
wxpayGoodsId String(32) N 微信商品编号
goodsName String(256) N 商品实际名称,长度不能超过256。
quantity String(10) Y 数量,只能是正整数。
price String Y 商品单价,单位分。

4.2.4 aliGoodsDetails具体参数

参数 类型(长度） 必填 参数说明
goodsId String(32) Y 商品编号
alipayGoodsId String(32) N 支付宝商品编号,支付宝定义的统一商品编号。
goodsName String(256) Y 营销单品名称
quantity String(10) Y 营销单品数量,不超过10位的正整数。
price String(12) Y 营销单品单价,单位分。
goodsCategory String(24) N 营销单品类目
categoriesTree String(128) N 营销单品类目树
body String(1000) N 营销单品描述
showUrl String(400) N 营销单品展示地址

4.2.5 unionQrcodeParams具体参数

参数 类型(长度） 必填 参数说明
terminalNo String(8) N 终端号
terminalType String(2) N 终端类型,线下交易场景必填，类型如下：
01-自动柜员机（含 ATM 和 CDM）和多媒体自助终端
02-传统 POS
03-mPOS
04-智能 POS
05-II 型固定电话
06-云闪付终端
07-保留使用
08-手机 POS
09-刷脸付终端
10-条码支付受理终端
11-辅助受理终端
12-行业终端（公交、地铁用于指定行业的终端）
13-MIS 终端
serialNum String(50) N 终端序列号
networkLicense String(5) N 入网认证编号,银行卡受理终端产品入网认证编号。
appVersion String(5) N 终端应用版本号,终端应用程序的版本号。
terminalGps String(32) N 交易设备位置信息,格式:纬度/经度,东经为正数，西经为负数;北纬为正数，南纬为负数,线下交易场景、terminal_ip和terminal_gps 二者选其一 必填。
terminalIp String(8) N 终端设备IP,如经、维度信息未上送，该字段必送。
encrypRandNum String(10) N 加密随机因子
secretText String(16) N 密文数据

5、响应参数说明

请注意：银盛后期会对返回参数保留扩展的权力，扩展方式为新增参数但不会删除参数，请商户在解析银盛返回参数时要支持银盛可能扩展参数这种情况。

5.1、公共响应参数

参数 类型(长度） 必填 参数说明
code String(5) Y 网关响应码，示例值：00000 ，详见网关公共响应码
msg String(50) Y 网关响应码描述
subCode String Y 业务响应码，参见具体的API接口文档
subMsg String Y 业务响应描述
timeStamp String Y 响应时间，格式"yyyy-MM-dd HH:mm:ss"
norce String(128) Y 随机参数
sign String Y 响应参数的签名串，详见demo,
注意:请用银盛公钥进行验签
businessData String Y 业务响应参数集合，
注意：银盛网关通过AES加密业务响应参数集合，得到businessData，商户需要对其进行解密，详情请见demo

5.2、业务响应参数

响应业务参数businessData(json数据)

参数 类型(长度） 必填 参数说明
reqMsgId String Y 请求流水号,同⼊参请求流水号
systemCode String N 系统编码
businessData Object Y 响应结果对象

5.2.1 businessData具体参数

参数 类型(长度） 必填 参数说明
orderId String Y 商户订单号,同请求订单号。
tradeSn String N 交易流水号
tradeStatus String Y 交易状态,如下：
00-交易成功
01-支付成功
02-支付成功,人工入账
10-待支付
11-处理中，已向渠道发起
13-全部已支付(担保交易使用)等待发货
14-未确认收货（等待付款方确认）
50-业务超时
80-部分退款
81-全部退款
93-订单撤销
96-交易失败
97-客户主动关闭
98-支付失败
99-到时关闭'
tradeStatusExt String N 交易扩展状态,如下：
11-用户支付中，需要输入密码，可对该交易做查询，避免重复支付。
amount String Y 订单总金额,该笔订单的资金总额,单位分。
accountDate String(19) N 入账日期,银盛入账日期，格式"yyyy-MM-dd" ，示例值：2017-05-01。
openId String N 用户唯一标识,子商户appid下用户唯一标识。
couponInfo String N 银联优惠信息,couponInfo优惠信息活动对象为多个时，couponInfo中就有多方优惠信息spnsrId出资方，值为1时银联出资，值为2时付款方出资，值为3时商户出资,offstAmt优惠金额(单位分) 。
settlementAmount String(10) N 结算金额,单位分，示例值：100。
isDiscount String N 是否参与优惠,Y：是，N：否。
totalDiscountFee String(10) N 总优惠手续费,单位：分。
totalDiscount String(10) N 总优惠金额,单位：分。
extraCommonParam String(2000) N 商户自定义数据域
paySuccessTime String(19) N 支付完成时间,格式"yyyy-MM-dd HH:mm:ss"， 示例值：2014-07-24 03:07:50。
buyerUserId String(128) N 支付宝用户Uid
cardType String(5) N 支付卡类型,类型如下:
credit-信用卡
debit-借记卡
示例值：credit。
riskInfo String N 风险信息json串
preferentialAmount String(10) N 惠金额,单位：分。
preferentialFee String(10) N 优惠手续费,单位：分。
marketingRuleJson String N 营销规则,JSON字符串。

6、业务响应码 网关公共响应码

响应码 响应码描述 解决方案
0000 交易成功 请求成功后，根据参数businessData里面的业务信息进行业务处理。
9999 失败 具体原因查看描述。
5000 交易超时 订单超时后，调用查询接口进行查询订单状态。
A029998 网关非法参数 检查请求参数，修改后重新发起请求。
B020100 前置无提供者 检查请求参数，修改后重新发起请求。
B021100 前置系统参数验证错误 检查请求参数，修改后重新发起请求。
B022011 发起方商户号和商户号的归属关系校验失败 检查发起方商户号和商户号的归属关系。
B023006 订单重复支付 检查订单号是否重复，重新生成订单号。
B029901 业务失败 根据实际返回消息分析具体原因。
B049900 获取支付网关编号失败 检查行别。
B044012 查询第三方商户号出错 输入正确的商户号。
B044335 获取支付网关编号失败 注意金额、行别需要填正确
B059999 失败 具体原因查看描述。
B049999 失败 具体原因查看描述。
A029994 前置无提供者异常 检查请求参数，修改后重新发起请求。

results matching ""

    No results matching ""