HOME
SDK 文档
回到顶部

云收银开发文档

文档说明

阅读对象

本文阅读对象:接入云收银支付功能涉及到的技术架构师,研发工程师,测试工程师,系统运维工程师。

版本说明

修订日期 文档版本 版本说明
2016.07.28 1.0 补充场景说明和交易流程说明
2016.09.19 1.2 增加H5支付接口
2016.09.19 2.0 新增版本号、签名方式、编码格式、商品列表、商家内部订单号字段,新版本去除goodsInfo字段上送
2016.11.07 2.1 支付及查询接口新增请求参数订单名称,新增返回参数

场景介绍

如您已对扫码支付场景非常熟悉,可直接跳转至[业务流程]章节。

商户主扫场景介绍

步骤1:用户选择使用扫码支付,打开相应客户端的付款条码。微信:打开app->进入“我”->“钱包”->“刷卡”条码界面;支付宝:打开app->打开顶部“付款码”;
步骤2:收银员在商户系统操作生成支付订单,用户确认支付金额;
步骤3:商户收银员用扫码设备扫描用户的条码/二维码,商户收银系统提交支付;
步骤4:云收银后台系统收到支付请求,根据验证密码规则判断是否验证用户的支付密码,不需要验证密码的交易直接发起扣款,需要验证密码的交易会弹出密码输入框。支付成功后微信端/支付宝端会弹出成功页面,支付失败会弹出错误提示。 交易流程视频:范例视频

下面以微信为例,列出图片。

我的钱包
我的钱包

刷卡界面
image

输入密码,确认支付
image

支付成功页面提示
image

商户被扫场景介绍

用户扫描商户展示在各种场景的二维码进行支付。
步骤1:商户为不同订单生成不同的二维码(如图6.1),展示在各种场景,用于用户扫描购买。
步骤2:用户使用微信“扫一扫”(如图6.2)扫描二维码后,获取商品支付信息,引导用户完成支付(如图6.3)。
步骤3:用户确认支付,输入支付密码(如图6.4)。
步骤4:支付完成后会提示用户支付成功(如图6.5),商户后台得到支付成功的通知,然后进行发货处理。
图6.1 支付二维码(此码仅作演示)
image

图6.2 打开微信扫一扫二维码
image

图6.3 确认支付页面
image

图6.4 用户确认支付,输入密码
image

图6.5 支付成功提示
image

验证密码规则

微信:1,支付金额>500元的交易需要验证用户支付密码。
2,用户账号每天最多有5笔交易可以免密,超过后需要验证密码。
3,微信支付后台判断用户支付行为有异常情况,符合免密规则的交易也会要求验证密码

支付宝:一般小于2000元不需要输入密码,输入密码的额度因支付宝风控政策会根据个人动态调整

业务流程

条码支付

商户侧接入流程

关于接入模式的选择:如果您希望自己管理所有的收款设备,并且有自建的中心系统,建议您采取系统对接的模式;如果您想以较轻量级的方式完成支付对接,可以让您的终端直联我们系统,我们也会提供相应的后台供您使用。 1、接入模式-系统接入
该模式适合具备自有系统的商户。门店收银台与商户后台通信,商户系统负责与后台系统发送交易请求和接收返回结果。 image

2、接入模式-终端接入
该模式适合门店收银台通过公网直接与后台系统通信的商户。门店收银台直接发起交易请求和处理返回结果。商户可以根据实际需要,处理门店和商户系统之间的其它业务流程。
image

完整交易流程

在扫码交易过程中,为了保证交易的便捷性,通常是小额交易不用输入密码,扫码后直接扣款完成交易(即免密支付),同时,也存在需要验证密码的情况。
1.免密支付流程
请参看以下时序图:
image
流程详细说明:
(1)收银员在商户收银台生成支付订单,向用户展示支付金额;
(2)用户打开支付客户端,选择“付款”,进入条码界面;
(3)使用扫码设备读取用户手机屏幕上的条码;
(4)扫码设备将读取的信息上传给门店收银台;
(5)门店收银台得到支付信息后,向商户收银后台发起支付请求。
(6)商户后台对门店收银台的支付请求进行处理,生成签名后调用【下单支付API】向后台系统发起支付请求。
(7)后台系统得到商户侧的支付请求之后会对请求进行验证,验证通过之后会对请求数据进行处理,最后将处理后的支付结果返回给商户收银后台。如果支付成功,后台系统会将支付结果返回给商户。
(8)商户收银后台对得到的支付结果进行签名验证和处理,再将支付结果返回给门店收银台。
(9)收银员看到门店收银台的支付结果后给用户发货。

2.验密支付流程
场景交互与免密模式相同,不同的是在商户调用【下单支付API】发起支付请求之后,支付后台提示用户输入密码确认支付,接口同步返回处理中状态,商户系统再轮询调用查询订单接口来确认当前用户是否已经支付成功。 以下时序图说明验密支付流程:
image
由于在商户收银后台向后台系统发起支付请求之前的流程是完全一样的,所以这里只介绍商户发起支付请求之后的逻辑。
(1)商户门店生成订单后,收银台向后台系统发起支付请求。
(2)后台调用后台系统【下单支付API】生成支付交易。
(3)后台系统对商户请求进行验证,验证通过后判断当前用户需要输入密码。
(4)后台系统返回处理中状态,商户后台系统将应答结果返回给商户门店收银台。
(5)后台系统通知用户支付客户端输入密码。
(6)用户得到输入密码提示后,确认支付并输入密码。
(7)完成密码输入,提交支付。
(8)支付客户端在用户完成支付后提示微信支付后台系统返回的支付结果。
(9)商户收银台得到处理中状态后,经过商户后台系统调用【查询订单API】(详见公共API)查询实际支付结果。
(10)如果支付结果仍为处理中状态,则每隔5秒循环调用【查询订单API】判断实际支付结果,如果用户主动放弃支付或累计60秒用户都未支付,商户收银台退出查询流程后继续调用【取消订单API】关闭支付交易,该笔订单按失败处理。

异常处理
用户遇到支付异常,请按如下说明处理
(1)建议接入方设置超时时间50s,当【下单支付API】接受应答超时时,必须调用【取消订单API】,关闭此交易,系统按失败处理该交易; (2)当【查询订单API】接收应答超时或返回98时,请继续发起【查询订单API】,如在发起支付后累计60s内依然没有收到成功应答,建议调用【取消订单API】关闭支付交易,该笔订单按失败处理;
(3)当【取消订单API】接收应答超时时,请继续调用【取消订单API】交易超时或支付交易失败,商户收银系统必须继续调用【取消订单API】,关闭此交易,建议至多重试6次,知道收到应答,应答为失败或成功均可停止取消。

扫码支付

商户系统先调用后台系统的【预下单API】,后台系统返回链接参数qrcode,商户终端将qrcode值生成二维码图片,用户使用客户端扫码后发起支付。注意:qrcode有效期默认为2小时,过期后扫码不能再发起支付。
业务流程时序图:
image
业务流程说明:
(1)商户系统根据用户选购的商品生成订单。
(2)用户确认支付后调用后台系统【预下单API】生成预支付交易;
(3)后台系统收到请求后生成预支付交易单,并返回交易会话的二维码链接qrcode。
(4)商户系统根据返回的qrcode生成二维码。
(5)用户打开支付客户端“扫一扫”扫描二维码,支付客户端将扫码内容发送到后台系统。
(6)后台系统收到客户端请求,验证链接有效性后发起用户支付,要求用户授权。
(7)用户在支付客户端输入密码,确认支付后,支付客户端提交授权。
(8)后台系统根据用户授权完成支付交易。
(9)后台系统完成支付交易后给客户端返回交易结果,支付客户端展示支付交易结果页面。
(10)后台系统通过发送异步消息通知商户后台系统支付结果。商户系统需回复接收情况,通知后台系统不再发送该单的支付通知。
(11)未收到支付通知的情况,商户后台系统调用【查询订单API】。
(12)商户确认订单已支付后给用户发货。

接入流程(必读)

1.阅读本文的所有内容,根据实际需要接入的接口进行选择或者本文档的【API列表】部分

2.开发集成云收银接口,若开发过程中有任何技术问题,联系后台系统技术对接人员。

3.软件通过接入方内部自测。内部自测通过标准:所有对接接口功能正常使用。

4.填写《云收银认证测试案例》,发送给后台系统技术对接人员,等待反馈。

5.后台系统人员审核《云收银认证测试案例》通过后,会出具认证测试报告给客户,测试报告中将包含投产相关参数。

6.后台系统协助客户进行投产验证测试。

7.投产完成,测试结束。后续生产事宜走运营流程。

接口规则

报文格式

系统提供两种通讯协议的接口,一种采用https协议通讯,一种采用tcp协议socket通信。对比如下:

接口协议|功能区别|报文区别|其他说明| ----| https|预下单接口带异步通知消息|Json格式,报文头不加长度位|预下单交易成功发送异步通知,,详情参考下文异步通知接口| tcp/socket|没有异步通知消息|Json格式,报文头需加4位报文长度位|需发起3.3查询订单请求确定支付状态,若轮询,频率不得超过5s每次|

报文请求特别说明:

调用http协议接口时,除H5支付接口为get方式提交外,其他接口均以post方式提交,提交是时,http请求的Header应该设置为content:application/json,以json方式提交请求,body也应该是一整个json字符串,不需要加上长度位。

报文示例:

//http报文示例,下单支付:
{"sign":"d6048cea0a24b417e8872c8982f6337159e892e1","txndir":"Q","scanCodeId":"28149154864202839","mchntid":"100000000000009","orderNum":"0017900500010580","chcd":"ALP","busicd":"PURC","inscd":"10134001","txamt":"000000000001"}

//tcp/socket报文示例,下单支付:
0226{"sign":"d6048cea0a24b417e8872c8982f6337159e892e1","txndir":"Q","scanCodeId":"28149154864202839","mchntid":"100000000000009","orderNum":"0017900500010580","chcd":"ALP","busicd":"PURC","inscd":"10134001","txamt":"000000000001"}

//http报文,下单支付返回(返回09:交易处理中):

{"mchntid":"100000000000009","inscd":"10134001","orderNum":"0017900500010580","txamt":"000000000001","channelOrderNum":"2015031621001004560096797452","consumerAccount":"","consumerId":"","respcd":"09","errorDetail":"ORDER_SUCCESS_PAY_INPROCESS","txndir":"A","busicd":"PURC","chcdDiscount":"0.00","merDiscount":"0.00","sign":""}

//http报文,下单支付(返回00:交易成功):

{"mchntid":"100000000000010","inscd":"10134001","orderNum":"000212012133616","txamt":"000000000010","channelOrderNum":"2015081221001004250093902009","consumerAccount":"mys***@126.com","consumerId":"2088202600821258","respcd":"00","errorDetail":"ORDER_SUCCESS_PAY_SUCCESS","txndir":"A","busicd":"PURC","chcdDiscount":"0.00","merDiscount":"0.00","chcd":"ALP","sign":"e9365d5cce0e3b7d9d8087c9bbe49373efcafdd3"}

签名机制

采用 SHA256 签名方式:

a.对待上送 JSON 报文中的所有传入参数(除 sign 参数外)按照字段名的 ASCII 码从小到大排序后(字典序),使用 URL 键值对的格式(即 key1=value1&key2=value2…)拼接成字符串 string1。

b.在 string1 最后直接拼接(不需要用“&”连接)双方约定的签名密钥 K1(接入时后台系统侧分配),得到stringSignTemp 字符串,并对 stringSignTemp 进行 SHA256 运算,得到 sign 的值。

验签:

a.对收到JSON响应报文的每个参数(除sign参数外)按照字段名的 ASCII 码从小到大排序后(字典序),使用URL键值对的格式(即 key1=value1&key2=value2…)拼接成字符串 string1。

b.在 string1 最后直接拼接双方约定的签名密钥K1(接入时后台系统侧分配),得到 stringSignTemp 字符串,并对 stringSignTemp 进行 SHA256 运算,得到验签字段 sign1

c.对比响应报文中 sign 参数的值和上面得到的 sign1,如果相等则验证通过,若不等,则验签不通过。

Sign 计算示例

如发生签名错误,请使用下面的报文做验证,看是否能得到相同结果sign。

报文准备:

{"txndir":"Q","busicd":"PURC","inscd":"10130001","charset":"utf-8","mchntid":"100000000000203","signType":"SHA256","terminalid":"00000001","txamt":"000000000001","orderNum":"1481006881300","scanCodeId":"130704380939251367","version":"2.1","sign":""}

拼接 string1:

string1等于busicd=PURC&charset=utf-8&inscd=10130001&mchntid=100000000000203&orderNum=1481006881300&scanCodeId=130704380939251367&signType=SHA256&terminalid=00000001&txamt=000000000001&txndir=Q&version=2.1

拼接 stringSignTemp:

stringSignTemp等于busicd=PURC&charset=utf-8&inscd=10130001&mchntid=100000000000203&orderNum=1481006881300&scanCodeId=130704380939251367&signType=SHA256&terminalid=00000001&txamt=000000000001&txndir=Q&version=2.1zsdfyreuoyamdphhaweyrjbvzkgfdycs

计算sign:

 sign=SHA256(stringSignTemp)=c733cacfbbd3d0f009d07e300a8621885a582ca6633eab1c86f969741163f5b8

API列表

下单支付

下单支付接口适用于获取支付宝客户端的“付款码”或微信“刷卡”的条码号,并通过该接口上送此条码号(scanCodeId字段)进行支付。注意:当接口返回为09时,表明该笔订单需要验证用户密码,收款终端上应该给出相关提示到顾客或收银员,同时建议软件后台发起间隔为5s的查询接口轮询,直到查询到支付成功应答或者超过一定时间,建议轮询总时长设置为60s,超过轮询时间后,调用取消接口关闭订单,同时将订单置为失败状态。

示例(不包含可选域)

拼接 stringSignTemp:

stringSignTemp:
busicd=PURC&charset=utf-8&inscd=10130001&mchntid=100000000000203&orderNum=1481006881300&scanCodeId=130704380939251367&signType=SHA256&terminalid=00000001&txamt=000000000001&txndir=Q&version=2.1zsdfyreuoyamdphhaweyrjbvzkgfdycs

签名:

 sign=SHA256(stringSignTemp)=e79725b5c2731d042de868ab9c90e14cdf9f16390891f7d8f0b54611fb20b8ba

报文:

{"txndir":"Q","busicd":"PURC","inscd":"10130001","charset":"utf-8","mchntid":"100000000000203","signType":"SHA256","terminalid":"00000001","txamt":"000000000001","orderNum":"1481006881300","scanCodeId":"130704380939251367","version":"2.1","sign":"e79725b5c2731d042de868ab9c90e14cdf9f16390891f7d8f0b54611fb20b8ba"}
参数 参数名称 请求 应答 类型及最大长度 备注说明
版本号 version M M String(4) 固定为2.1
签名方式 signType M M String(10) 固定为SHA256
编码格式 charset M M String(10) 固定为utf-8
订单号 orderNum M C String(32) 支付方的订单号,同一个商户下的订单号不可重复(失败交易亦记录订单号),建议加时间戳(精确到毫秒)和随机数(或交易顺序号),保证每笔交易的订单号均不同,例如:20160916123029123000001
交易方向 txndir M M String(1) Q:请求,A:应答
交易类型 busicd M M String(4) 下单交易填写:PURC
交易结果 respcd M String(2) 应答码,00:交易成功,09:处理中(需要用户在手机客户端输入支付密码)此时需要通过查询订单接口进行订单查询,以确定此订单的最终状态,其他参考应答码表
机构号 inscd M M String(8) 机构代码,后台系统分配
渠道 chcd C String(5) 成功应答中必选
商户号 mchntid M M String(15) 商户号,后台系统分配
终端号 terminalid M String(8) 终端号,要求不同终端此号码不一样,会显示在对账单中
订单金额 txamt M M String(12) 12定长字符,单位为分,左补0,例如:1元表示为 000000000100,0.01元表示为000000000001
交易币种 currency C String(3) 符合ISO 4217标准的三位币种代码,不上送默认按人民币:CNY处理
商品列表 goodsList C String(8192) 商品列表,上送格式为:{"goodsList":[{"goodsId":"iphone6s16G","unifiedGoodsId":"1001","goodsName":"iPhone6s 16G","goodsNum":"1","price":"528800","goodsCategory":"123456","body":"苹果手机16G","showUrl":"www.cardinfolink.com"},{"goodsId":"iphone6s32G","unifiedGoodsId":"1002","goodsName":"iPhone6s 32G","quantity":"1","price":"608800","goodsCategory":"123789","body":"苹果手机32G","showUrl":"www.cardinfolink.com"}]},字段解释:goods_name:商品名称,price:单价(单位分),goodsNum:数量,goodsId:商户定义商品编号(一般商品条码),unifiedGoodsId:统一商品编号(可选),goodsCategory:商品类目(可选),body:商品描述信息(可选),showUrl:商品的展示网址(可选)
渠道交易号 channelOrderNum C String(64) 在各钱包渠道系统中的订单号
渠道账号 consumerAccount C String(64) 付款用户相关账号
渠道账号ID consumerId C String(64) 付款用户相关钱包渠道ID
错误信息 errorDetail C String(64) 接口调用发生错误时,此字段会展示错误详情,可根据此字段判断错误原因
扫码号 scanCodeId M String(32) 客户端软件中展示的条码值,扫码设备扫描获取
签名 sign M M String(128)
渠道优惠 chcdDiscount C String(13)
商户优惠 merDiscount C String(13)
外部流水号 outOrderNum C C String(512) 建议商家使用此字段来标示商家内部订单信息,此字段系统会原样返回,并且会在流水文件中体现(请不要填入特殊字符)
银行标识 bankType C String(24) 标识列表见最后“银行标识”附录
交易时间 transTime C String(24)
订单标题 subject C String(128) 订单标题,可在客户端用于电子账单中体现

预下单

预下单接口为一笔指定金额的交易生成一个url(qrcode字段),将此url直接转换成二维码,使用支付宝或微信的扫一扫功能即可在手机端完成支付。可通过查询订单接口确定此交易的交易状态,也提供异步通知服务,附:二维码生成方法参考百度:您使用的语言+生成二维码,例如java:java生成二维码参考示例

示例(不包含可选域):

拼接 stringSignTemp:

stringSignTemp:
busicd=PAUT&charset=utf-8&chcd=WXP&inscd=10130001&mchntid=100000000000203&orderNum=1481008356321&signType=SHA256&terminalid=00000001&txamt=000000000001&txndir=Q&version=2.1zsdfyreuoyamdphhaweyrjbvzkgfdycs

签名:

 sign=SHA256(stringSignTemp)=5f9f5dc29b98d13b76d8c2cf8111577bc3e5533c135990a8f8beea2d448c62d2

报文:

{"txndir":"Q","busicd":"PAUT","chcd":"WXP","inscd":"10130001","charset":"utf-8","mchntid":"100000000000203","signType":"SHA256","terminalid":"00000001","txamt":"000000000001","orderNum":"1481006881300","version":"2.1","sign":"5f9f5dc29b98d13b76d8c2cf8111577bc3e5533c135990a8f8beea2d448c62d2"}
参数 参数名称 请求 应答 类型及最大长度 备注说明
版本号 version M M String(4) 固定为2.1
签名方式 signType M M String(10) 固定为SHA256
编码格式 charset M M String(10) 固定为utf-8
订单号 orderNum M M String(32) 支付方的订单号,同一个商户下的订单号不可重复(失败交易亦记录订单号),建议加时间戳(精确到毫秒)和随机数(或交易顺序号),保证每笔交易的订单号均不同,例如:20160916123029123000001
交易方向 txndir M M String(1) Q:请求,A:应答
交易类型 busicd M M String(4) 预下单交易填写:PAUT
交易结果 respcd M String(2) 应答码,00:交易成功,09:处理中(需要用户在手机客户端输入支付密码)此时需要通过查询订单接口进行订单查询,以确定此订单的最终状态,其他参考应答码表
机构号 inscd M M String(8) 机构代码,后台系统分配
渠道 chcd M M String(5) 需要请求的渠道代码,例如需要请求支付宝则填写ALP,填写列表:ALP:支付宝,WXP:微信,YZF:翼支付,QQP:qq钱包,京东钱包:JDP,百度钱包:BDP,YDP:移动和包,YLP:银联钱包
商户号 mchntid M M String(15) 商户号,后台系统分配
终端号 terminalid M String(8) 终端号,要求不同终端此号码不一样,会显示在对账单中
订单金额 txamt M M String(12) 12定长字符,单位为分,左补0,例如:1元表示为 000000000100,0.01元表示为000000000001
交易币种 currency C String(3) 符合ISO 4217标准的三位字母币种代码,不上送默认按人民币:CNY处理
商品列表 goodsList C String(8192) 商品列表,上送格式为:{"goodsList":[{"goodsId":"iphone6s16G","unifiedGoodsId":"1001","goodsName":"iPhone6s 16G","goodsNum":"1","price":"528800","goodsCategory":"123456","body":"苹果手机16G","showUrl":"www.cardinfolink.com"},{"goodsId":"iphone6s32G","unifiedGoodsId":"1002","goodsName":"iPhone6s 32G","quantity":"1","price":"608800","goodsCategory":"123789","body":"苹果手机32G","showUrl":"www.cardinfolink.com"}]},字段解释:goods_name:商品名称,price:单价(单位分),goodsNum:数量,goodsId:商户定义商品编号(一般商品条码),unifiedGoodsId:统一商品编号(可选),goodsCategory:商品类目(可选),body:商品描述信息(可选),showUrl:商品的展示网址(可选)
渠道交易号 channelOrderNum C String(64)
错误信息 errorDetail C String(64)
二维码信息 qrcode C String(128) 预下单支付宝返回的二维码url串,需转为二维码图片展示给顾客
异步通知地址 backUrl C C String(1024) 用户完成支付后,系统会向该url发送异步通知消息,详情参考下文异步通知接口
透传参数 attach C C String(127) 附加数据原样返回
签名 sign M M String(128)
渠道优惠 chcdDiscount C String(13)
商户优惠 merDiscount C String(13)
外部流水号 outOrderNum C C String(512) 此字段系统会原样返回,并且会在流水文件中体现(请不要填入特殊字符)
银行标识 bankType C String(24) 标识列表见最后“银行标识”附录
交易时间 transTime C String(24)
订单标题 subject C String(128) 订单标题,可在客户端用于电子账单中体现

H5支付接口

此接口提交方式为get方式,提交后的效果是:在微信或支付宝环境内调起输入密码对话框,密码输入成功后,会向接口提交的frontUrl和backUrl分别发送通知,订单支付结果以给backUrl发送的异步通知为准,异步通知接口见本文最后“http协议异步通知”接口。

报文规范和其他接口略有不同,步骤如下:

拼接 stringSignTemp:

stringSignTemp:
backUrl=http://www.cardinfolink.com/&busicd=WPAY&charset=utf-8&chcd=WXP&frontUrl=http://www.cardinfolink.com/&mchntid=100000000000203&orderNum=2481008356321&signType=SHA256&terminalid=00000001&txamt=000000000001&version=2.1zsdfyreuoyamdphhaweyrjbvzkgfdycs

签名:

 sign=SHA256(stringSignTemp)=8d2580322f587cc0ebec2ccc0f67d57f211028d418982dda43a566f2618bc541

报文:

{"orderNum":"2481008356321","txamt":"000000000001","busicd":"WPAY","version":"2.1","chcd":"WXP","backUrl":"http://www.cardinfolink.com/","frontUrl":"http://www.cardinfolink.com/","mchntid":"100000000000203","charset":"utf-8","signType":"SHA256","terminalid":"00000001","sign":"8d2580322f587cc0ebec2ccc0f67d57f211028d418982dda43a566f2618bc541"}

对报文进行SHA256:

data=BASE64(s)=eyJvcmRlck51bSI6IjI0ODEwMDgzNTYzMjEiLCJ0eGFtdCI6IjAwMDAwMDAwMDAwMSIsImJ1c2ljZCI6IldQQVkiLCJ2ZXJzaW9uIjoiMi4xIiwiY2hjZCI6IldYUCIsImJhY2tVcmwiOiJodHRwOi8vd3d3LmNhcmRpbmZvbGluay5jb20vIiwiZnJvbnRVcmwiOiJodHRwOi8vd3d3LmNhcmRpbmZvbGluay5jb20vIiwibWNobnRpZCI6IjEwMDAwMDAwMDAwMDIwMyIsImNoYXJzZXQiOiJ1dGYtOCIsInNpZ25UeXBlIjoiU0hBMjU2IiwidGVybWluYWxpZCI6IjAwMDAwMDAxIiwic2lnbiI6IjhkMjU4MDMyMmY1ODdjYzBlYmVjMmNjYzBmNjdkNTdmMjExMDI4ZDQxODk4MmRkYTQzYTU2NmYyNjE4YmM1NDEifQ==

get方式提交:

http://test.quick.ipay.so/scanpay/unified?data=eyJvcmRlck51bSI6IjI0ODEwMDgzNTYzMjEiLCJ0eGFtdCI6IjAwMDAwMDAwMDAwMSIsImJ1c2ljZCI6IldQQVkiLCJ2ZXJzaW9uIjoiMi4xIiwiY2hjZCI6IldYUCIsImJhY2tVcmwiOiJodHRwOi8vd3d3LmNhcmRpbmZvbGluay5jb20vIiwiZnJvbnRVcmwiOiJodHRwOi8vd3d3LmNhcmRpbmZvbGluay5jb20vIiwibWNobnRpZCI6IjEwMDAwMDAwMDAwMDIwMyIsImNoYXJzZXQiOiJ1dGYtOCIsInNpZ25UeXBlIjoiU0hBMjU2IiwidGVybWluYWxpZCI6IjAwMDAwMDAxIiwic2lnbiI6IjhkMjU4MDMyMmY1ODdjYzBlYmVjMmNjYzBmNjdkNTdmMjExMDI4ZDQxODk4MmRkYTQzYTU2NmYyNjE4YmM1NDEifQ==

请求参数:

参数 参数名称 请求是否必填 类型及最大长度 示例值 备注说明
版本号 version String(4) 固定为2.1
签名方式 signType String(10) 固定为SHA256
编码格式 charset String(10) 固定为utf-8
透传参数 attach String(127) 扫码消费 附加数据原样返回
交易类型 busicd String(4) WPAY 本交易的交易类型为:WPAY
异步通知接收地址 backUrl String(120) http://www.cardinfolink.com 商户服务器接收云收银服务器后台通知URL
支付渠道代码 chcd String(5) WXP 支付渠道,目前仅支持微信支付和支付宝,WXP:微信支付,ALP:支付宝
支付成功或失败后跳转到的url frontUrl String(120) http://www.cardinfolink.com 前台通知地址,用户支付完成后,需要跳转到的地址URL
商品列表 goodsList String(8192) 商品列表,上送格式为:{"goodsList":[{"goodsId":"iphone6s16G","unifiedGoodsId":"1001","goodsName":"iPhone6s 16G","goodsNum":"1","price":"528800","goodsCategory":"123456","body":"苹果手机16G","showUrl":"www.cardinfolink.com"},{"goodsId":"iphone6s32G","unifiedGoodsId":"1002","goodsName":"iPhone6s 32G","quantity":"1","price":"608800","goodsCategory":"123789","body":"苹果手机32G","showUrl":"www.cardinfolink.com"}]},字段解释:goods_name:商品名称,price:单价(单位分),goodsNum:数量,goodsId:商户定义商品编号(一般商品条码),unifiedGoodsId:统一商品编号(可选),goodsCategory:商品类目(可选),body:商品描述信息(可选),showUrl:商品的展示网址(可选)
商户号 mchntid String(15) 100000000000203 商户ID,由后台系统分配
订单号 orderNum String(32) 20160901182402001231 支付方的订单号,同一个商户下的订单号不可重复(失败交易亦记录订单号),建议加时间戳
订单金额 txamt String(12) 000000000400 金额,12位定长字符串,例如:1元表示为 000000000100,0.01元表示为000000000001
签名 sign String(32) ba6c866b88070c6e851329651ac3007c82961b40 签名规则见文章开头说明
终端号 terminalid String(8) 00000001 上送您系统维护的终端序列号,如没有终端概念,可使用00000001
外部流水号 outOrderNum String(512) 此字段系统会原样返回,并且会在流水文件中体现(请不要填入特殊字符)
订单标题 subject String(128) 测试订单 订单标题,可在客户端用于电子账单中体现

frontUrl通知:前台通知,支付完成后,跳转到frontUrl,并在URL尾部带上如下参数,接入方根据参数进行相应处理,订单结果以后台通知为准,前台通知用于页面展示,接入方需兼容后期增加返回字段的情况。

参数 参数名称 请求是否必填 类型及最大长度 示例值 备注说明
state 支付状态 String(1) 0 返回为数字,各数值含义为:0:支付成功,1:支付失败,-1:用户取消:未支付
orderNum 订单号 String(32) 20160919123345098000001 结果对应支付订单号
txamt 订单金额 String(12) 000000000100 单位为分,如000000000100表示为1元
attach 附加内容,原样返回 String(127) 附加内容 和请求上送时一样
errorDetail 错误信息 String(64) 订单号重复 具体以返回为准

frontUrl通知示例:

https://www.cardinfolink.com/?attach=120300008&txamt=000000000100&orderNum=ZT201602150000001937&state=1&errorDetail=%25E7%25AD%25BE%25E5%2590%258D%25E9%2594%2599%25E8%25AF%25AF&from=844b&vit=fps

查询订单

此接口用于查询下单支付、预下单交易和H5支付交易的交易状态,当下单支付或预下单支付返回09:交易处理中或98:交易超时的应答码或者接入方没有收到应答时(网络原因等),推荐需要调用此接口,以明确订单状态。

示例(不包含可选域):

拼接 stringSignTemp:

stringSignTemp:
busicd=INQY&charset=utf-8&inscd=10130001&mchntid=100000000000203&origOrderNum=1481008356321&signType=SHA256&terminalid=00000001&txndir=Q&version=2.1zsdfyreuoyamdphhaweyrjbvzkgfdycs

签名:

 sign=SHA256(stringSignTemp)=d6a8a183c989bf2e6a8f35564b2ca60dc3948544be464adba6cf0d3eadf9fe5c

报文:

{"txndir":"Q","busicd":"INQY","inscd":"10130001","charset":"utf-8","mchntid":"100000000000203","signType":"SHA256","terminalid":"00000001","origOrderNum":"1481008356321","version":"2.1","sign":"d6a8a183c989bf2e6a8f35564b2ca60dc3948544be464adba6cf0d3eadf9fe5c"}
参数 参数名称 请求 应答 类型及最大长度 备注说明
版本号 version M M String(4) 固定为2.1
签名方式 signType M M String(10) 固定为SHA256
编码格式 charset M M String(10) 固定为utf-8
原订单号 origOrderNum M M String(32) 需要确认交易状态的交易的订单号
交易方向 txndir M M String(1) Q:请求,A:应答
交易类型 busicd M M String(4) 查询交易填写:INQY,应答为所查员交易交易类型
交易结果 respcd M String(2) 应答码,00:交易成功,09:处理中(需要用户在手机客户端输入支付密码)此时需要通过查询订单接口进行订单查询,以确定此订单的最终状态,其他参考应答码表
订单金额 txamt M String(12) 原交易金额,12定长字符,单位为分,左补0,例如:1元表示为 000000000100,0.01元表示为000000000001
机构号 inscd M M String(8) 机构代码,后台系统分配
渠道 chcd C String(5) 成功应答中必选
商户号 mchntid M M String(15) 商户ID,由后台系统系统分配
终端号 terminalid M String(8) 上送您系统维护的终端序列号,如没有终端概念,可使用00000001
渠道交易号 channelOrderNum C String(64)
渠道账号 consumerAccount C String(64)
渠道账号ID consumerId C String(64)
错误信息 errorDetail C String(64)
签名 sign M M String(128)
渠道优惠 chcdDiscount C String(13)
商户优惠 merDiscount C String(13)
外部流水号 outOrderNum C C String(512) 此字段系统会原样返回,并且会在流水文件中体现(请不要填入特殊字符)
银行标识 bankType C String(24) 标识列表见最后“银行标识”附录
交易时间 transTime C String(24)

退款

对成功的下单支付或预下单支付做退款处理,支持部分退款。

示例(不包含可选域):

拼接 stringSignTemp:

stringSignTemp:
busicd=REFD&charset=utf-8&inscd=10130001&mchntid=100000000000203&orderNum=1481009668652&origOrderNum=1481008356321&signType=SHA256&terminalid=00000001&txamt=000000000001&txndir=Q&version=2.1zsdfyreuoyamdphhaweyrjbvzkgfdycs

签名:

 sign=SHA256(stringSignTemp)=01915ba8ce4b530291a296278ce944b838b2e447650a7008c5e68b0b83417ac7

报文:

{"txndir":"Q","busicd":REFD","inscd":"10130001","charset":"utf-8","mchntid":"100000000000203","signType":"SHA256","terminalid":"00000001","orderNum":"1481009668652",origOrderNum":"1481008356321","txamt":"000000000001","version":"2.1","sign":"01915ba8ce4b530291a296278ce944b838b2e447650a7008c5e68b0b83417ac7"}
参数 参数名称 请求 应答 类型及最大长度 备注说明
版本号 version M M String(4) 固定为2.1
签名方式 signType M M String(10) 固定为SHA256
编码格式 charset M M String(10) 固定为utf-8
订单号 orderNum M M String(32) 注意:此字段为退款交易的订单号,与原订单号不同。同一个商户下的订单号不可重复(失败交易亦记录订单号),建议加时间戳(精确到毫秒)和随机数(或交易顺序号),保证每笔交易的订单号均不同,例如:20160916123029123000001
原订单号 origOrderNum M M String(64) 需要进行退款操作的交易的订单号,即某一笔支付交易的订单号
交易方向 txndir M M String(1) Q:请求,A:应答
交易类型 busicd M M String(4) 退款交易填写:REFD
交易结果 respcd M String(2) 应答码
机构号 inscd M M String(8)
渠道 chcd C String(5) 成功应答中必选
商户号 mchntid M M String(15)
终端号 terminalid M String(8)
订单金额 txamt M String(12) 12定长字符,单位为分,左补0,例如:1元表示为 000000000100,0.01元表示为000000000001
渠道交易号 channelOrderNum C String(64)
渠道账号 consumerAccount C String(64)
渠道账号ID consumerId C String(64)
错误信息 errorDetail C String(64)
签名 sign M M String(128)
渠道优惠 chcdDiscount C String(13)
商户优惠 merDiscount C String(13)
外部流水号 outOrderNum C C String(512) 此字段系统会原样返回,并且会在流水文件中体现(请不要填入特殊字符)

取消订单

本接口有两重作用,对于未成功付款的订单进行取消,则关闭交易,使用户后期不能支付成功;对于成功付款的订单进行取消,系统将订单金额返还给用户,相当于对此交易做撤销,接口在交易提交24小时内可调用。

示例(不包含可选域):

拼接 stringSignTemp:

stringSignTemp:
busicd=CANC&charset=utf-8&inscd=10130001&mchntid=100000000000203&orderNum=1481009849946&origOrderNum=1481008356321&signType=SHA256&terminalid=00000001&txndir=Q&version=2.1zsdfyreuoyamdphhaweyrjbvzkgfdycs

签名:

 sign=SHA256(stringSignTemp)=c1195a455345bd2a876ca15f6787d92077e2043fc9a39803561b44404f6ef367

报文:

{"txndir":"Q","busicd":CANC","inscd":"10130001","charset":"utf-8","mchntid":"100000000000203","signType":"SHA256","terminalid":"00000001","orderNum":"1481009849946",origOrderNum":"1481008356321","version":"2.1","sign":"c1195a455345bd2a876ca15f6787d92077e2043fc9a39803561b44404f6ef367"}
参数 参数名称 请求 应答 类型及最大长度 备注说明
版本号 version M M String(4) 固定为2.1
签名方式 signType M M String(10) 固定为SHA256
编码格式 charset M M String(10) 固定为utf-8
订单号 orderNum M M String(32) 注意:此字段为取消交易的订单号,与原订单号不同。同一个商户下的订单号不可重复(失败交易亦记录订单号),建议加时间戳(精确到毫秒)和至少4位随机数,以保证每笔交易的订单号均不同,例如:20160916123029123000001
原订单号 origOrderNum M M String(64) 需要进行取消操作的交易的订单号,即某一笔支付交易的订单号
交易方向 txndir M M String(1) Q:请求,A:应答
交易类型 busicd M M String(4) 取消交易填写:CANC
交易结果 respcd M String(2) 应答码
机构号 inscd M M String(8)
渠道 chcd C String(5) 成功应答中必选
商户号 mchntid M M String(15)
终端号 terminalid M String(8)
渠道交易号 channelOrderNum C String(64)
渠道账号 consumerAccount C String(64)
渠道账号ID consumerId C String(64)
错误信息 errorDetail C String(64)
签名 sign M M String(128)
渠道优惠 chcdDiscount C String(13)
商户优惠 merDiscount C String(13)
外部流水号 outOrderNum C C String(512) 此字段系统会原样返回,并且会在流水文件中体现(请不要填入特殊字符)

http协议异步通知

该接口为get方式提交,请注意!该接口作用为:对成功的预下单、H5支付交易,在用户支付成功后,系统向接入方发送该异步通知消息,前提是需在预下单接口上送backUrl参数。接入方在收到消息后,向系统响应一个应答消息内容为“SUCCESS”的应答字符串即可,我系统没有收到响应消息时,会按通知频率间隔定期重新发起通知,直到对方响应成功应答或者通知次数超限(通知频率为15/15/30/180/1800/1800/1800/1800/3600,单位:秒) 对接入方处理要求:由于存在重新发送通知的情况,因此同样的通知可能会多次发送给接入方。接入方必须能够正确处理重复的通知。推荐的做法是,当收到通知进行处理时,首先检查对应业务数据的状态,判断该通知是否已经处理过,如果没有处理过再进行处理,如果处理过直接返回结果成功。在对业务数据进行状态检查和处理之前,要采用数据锁进行并发控制,以避免函数重入造成的数据混乱。 接口调用方接收到此通知报文后,需回复“SUCCESS”这7个字母(不包含空格)。

参数 参数名称 应答 类型及最大长度 备注说明
版本号 version M String(4) 固定为2.1
签名方式 signType M String(10) 固定为SHA256
编码格式 charset M String(10) 固定为utf-8
订单号 orderNum M String(32) 接入方发起支付用的订单号
交易类型 busicd M String(4) PAUT或WPAY
交易结果 respcd M String(2) 应答码,00:交易成功
机构号 inscd M String(8)
渠道 chcd M String(5)
商户号 mchntid M String(15)
终端号 terminalid M String(8)
订单金额 txamt M String(12)
交易方向 txndir M String(1)
附加信息 attach C String(127)
商品名称 goodsInfo C String(120) 商品详情,上送格式如下:商品名称 1,单价,数量; 商品名称 n,单价,数量;各要素之间逗号分隔,每条之间分号分隔
渠道交易号 channelOrderNum C String(64)
错误信息 errorDetail M String(64)
签名 sign M String(128)
银行标识 bankType C String(24) 标识列表见最后“银行标识”附录
交易时间 transTime M String(24)
消费者账户 consumerAccount C String(64)

应答码列表

附应答码列表,见附件。
下载附件

银行标识

字符型银行编码 银行名称
ICBC_DEBIT 工商银行(借记卡)
ICBC_CREDIT 工商银行(信用卡)
ABC_DEBIT 农业银行(借记卡)
ABC_CREDIT 农业银行(信用卡)
PSBC_DEBIT 邮政储蓄银行(借记卡)
PSBC_CREDIT 邮政储蓄银行(信用卡)
CCB_DEBIT 建设银行(借记卡)
CCB_CREDIT 建设银行(信用卡)
CMB_DEBIT 招商银行(借记卡)
CMB_CREDIT 招商银行(信用卡)
BOC_DEBIT 中国银行(借记卡)
BOC_CREDIT 中国银行(信用卡)
COMM_DEBIT 交通银行(借记卡)
SPDB_DEBIT 浦发银行(借记卡)
SPDB_CREDIT 浦发银行(信用卡)
GDB_DEBIT 广发银行(借记卡)
GDB_CREDIT 广发银行(信用卡)
CMBC_DEBIT 民生银行(借记卡)
CMBC_CREDIT 民生银行(信用卡)
PAB_DEBIT 平安银行(借记卡)
PAB_CREDIT 平安银行(信用卡)
CEB_DEBIT 光大银行(借记卡)
CEB_CREDIT 光大银行(信用卡)
CIB_DEBIT 兴业银行(借记卡)
CIB_CREDIT 兴业银行(信用卡)
CITIC_DEBIT 中信银行(借记卡)
CITIC_CREDIT 中信银行(信用卡)
BOSH_DEBIT 上海银行(借记卡)
BOSH_CREDIT 上海银行(信用卡)
CRB_DEBIT 华润银行(借记卡)
HZB_DEBIT 杭州银行(借记卡)
HZB_CREDIT 杭州银行(信用卡)
BSB_DEBIT 包商银行(借记卡)
BSB_CREDIT 包商银行(信用卡)
CQB_DEBIT 重庆银行(借记卡)
SDEB_DEBIT 顺德农商行(借记卡)
SZRCB_DEBIT 深圳农商银行(借记卡)
HRBB_DEBIT 哈尔滨银行(借记卡)
BOCD_DEBIT 成都银行(借记卡)
GDNYB_DEBIT 南粤银行(借记卡)
GDNYB_CREDIT 南粤银行(信用卡)
GZCB_DEBIT 广州银行(借记卡)
GZCB_CREDIT 广州银行(信用卡)
JSB_DEBIT 江苏银行(借记卡)
JSB_CREDIT 江苏银行(信用卡)
NBCB_DEBIT 宁波银行(借记卡)
NBCB_CREDIT 宁波银行(信用卡)
NJCB_DEBIT 南京银行(借记卡)
JZB_DEBIT 晋中银行(借记卡)
KRCB_DEBIT 昆山农商(借记卡)
LJB_DEBIT 龙江银行(借记卡)
LNNX_DEBIT 辽宁农信(借记卡)
LZB_DEBIT 兰州银行(借记卡)
WRCB_DEBIT 无锡农商(借记卡)
ZYB_DEBIT 中原银行(借记卡)
ZJRCUB_DEBIT 浙江农信(借记卡)
WZB_DEBIT 温州银行(借记卡)
XAB_DEBIT 西安银行(借记卡)
JXNXB_DEBIT 江西农信(借记卡)
NCB_DEBIT 宁波通商银行(借记卡)
NYCCB_DEBIT 南阳村镇银行(借记卡)
NMGNX_DEBIT 内蒙古农信(借记卡)
SXXH_DEBIT 陕西信合(借记卡)
SRCB_CREDIT 上海农商银行(信用卡)
SJB_DEBIT 盛京银行(借记卡)
SDRCU_DEBIT 山东农信(借记卡)
SRCB_DEBIT 上海农商银行(借记卡)
SCNX_DEBIT 四川农信(借记卡)
QLB_DEBIT 齐鲁银行(借记卡)
QDCCB_DEBIT 青岛银行(借记卡)
PZHCCB_DEBIT 攀枝花银行(借记卡)
ZJTLCB_DEBIT 浙江泰隆银行(借记卡)
TJBHB_DEBIT 天津滨海农商行(借记卡)
WEB_DEBIT 微众银行(借记卡)
YNRCCB_DEBIT 云南农信(借记卡)
WFB_DEBIT 潍坊银行(借记卡)
WHRC_DEBIT 武汉农商行(借记卡)
ORDOSB_DEBIT 鄂尔多斯银行(借记卡)
XJRCCB_DEBIT 新疆农信银行(借记卡)
ORDOSB_CREDIT 鄂尔多斯银行(信用卡)
CSRCB_DEBIT 常熟农商银行(借记卡)
JSNX_DEBIT 江苏农商行(借记卡)
GRCB_CREDIT 广州农商银行(信用卡)
GLB_DEBIT 桂林银行(借记卡)
GDRCU_DEBIT 广东农信银行(借记卡)
GDHX_DEBIT 广东华兴银行(借记卡)
FJNX_DEBIT 福建农信银行(借记卡)
DYCCB_DEBIT 德阳银行(借记卡)
DRCB_DEBIT 东莞农商行(借记卡)
CZCB_DEBIT 稠州银行(借记卡)
CZB_DEBIT 浙商银行(借记卡)
CZB_CREDIT 浙商银行(信用卡)
GRCB_DEBIT 广州农商银行(借记卡)
CSCB_DEBIT 长沙银行(借记卡)
CQRCB_DEBIT 重庆农商银行(借记卡)
CBHB_DEBIT 渤海银行(借记卡)
BOIMCB_DEBIT 内蒙古银行(借记卡)
BOD_DEBIT 东莞银行(借记卡)
BOD_CREDIT 东莞银行(信用卡)
BOB_DEBIT 北京银行(借记卡)
BNC_DEBIT 江西银行(借记卡)
BJRCB_DEBIT 北京农商行(借记卡)
AE_CREDIT AE(信用卡)
GYCB_CREDIT 贵阳银行(信用卡)
JSHB_DEBIT 晋商银行(借记卡)
JRCB_DEBIT 江阴农商行(借记卡)
JNRCB_DEBIT 江南农商(借记卡)
JLNX_DEBIT 吉林农信(借记卡)
JLB_DEBIT 吉林银行(借记卡)
JJCCB_DEBIT 九江银行(借记卡)
HXB_DEBIT 华夏银行(借记卡)
HXB_CREDIT 华夏银行(信用卡)
HUNNX_DEBIT 湖南农信(借记卡)
HSB_DEBIT 徽商银行(借记卡)
HSBC_DEBIT 恒生银行(借记卡)
HRXJB_DEBIT 华融湘江银行(借记卡)
HNNX_DEBIT 河南农信(借记卡)
HKBEA_DEBIT 东亚银行(借记卡)
HEBNX_DEBIT 河北农信(借记卡)
HBNX_DEBIT 湖北农信(借记卡)
HBNX_CREDIT 湖北农信(信用卡)
GYCB_DEBIT 贵阳银行(借记卡)
GSNX_DEBIT 甘肃农信(借记卡)
JCB_CREDIT JCB(信用卡)
MASTERCARD_CREDIT MASTERCARD(信用卡)
VISA_CREDIT VISA(信用卡)

后续流程

1. 通读上述接口说明后,在进行对接开发
2. 对接开发完成后,进行内部自测
3. 自测通过后,请按后台系统照提供的测试案例,进行认证测试,案例文档见附件
4. 测试过程中,将测试结果填入文档,完成后将修改后的测试案例文档发回给后台系统人员
5. 后台系统人员对文档进行审核,审核通过后将下发生产系统相关参数
6. 后台系统配合进行投产及投产验证工作

常见问题

1. 为什么要做认证测试?
您好,做认证测试的目的是让您对接完成后,在投产后尽可能少的出现问题,认证测试案例中都是一些比较常见的操作,请您耐心花一点时间完成,这会对您上线后的交易质量很有保证。

2. 为什么在发起交易的时候,回复“19”应答?
回复“19”应答的原因是订单号重复造成的,请更换订单号后再发起交易,注意:即使订单号请求后响应支付失败的应答,该订单号也是不能再次提交使用的,为了避免订单号出现问题,建议加时间戳(精确到毫秒)和随机数(或交易顺序号),保证每笔交易的订单号均不同,例如:20160916123029123000001 。

3. 应答报文报30,报文错误,请问什么原因?
原因可能是提交方式有问题,Header设置成 content:application/json,body是一整个json字符串,要用json提交,不能用form提交。

附:ISO 8583接口

ISO 8583接口文档 适用于平台、系统接入云收银系统,除了支持支付宝、微信支付外,还可实现内外卡收单,此接口接入网络最低要求为VPN接入,同时需要接入方有加密机等安全设备,具体接入事宜请详询我司。

下载 ISO 8583 接口说明文档 去看看产品使用场景