欢迎光临合肥新店商信息技术咨询有限公司官方网站!
  咨询电话:400-0551-517

新闻相关

新店收开发文档

文档说明

阅读对象

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

版本说明

修订日期文档版本版本说明
2016.07.281.0补充场景说明和交易流程说明
2016.09.191.2增加H5支付接口
2016.09.192.0新增版本号、签名方式、编码格式、商品列表、商家内部订单号字段,新版本去除goodsInfo字段上送
2016.11.072.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

报文:

                上一条:口碑巢湖耳街五一活动
                下一条:Windows SDK 概述
            

新闻中心

联系我们

公 司:合肥新店商信息技术咨询有限公司

联系人:管照红

电话:400-0551-517

手机:13965106133

E-mail:hfxds2018@sina.com

地 址:合肥市蜀山区望江西路69号西湖国际D座1504