文档用途

本文档旨在对现在股份的H5智能收款服务端接口服务提供一份详细的规范定义说明。以方便H5智能收款商户开发者能更方便地接入现在股份的H5智能收款服务。

阅读对象

具有服务端接口接入开发能力的H5智能收款平台商户。

名称术语

H5智能收款:现在股份提供给客户的快速接入银联H5、支付宝H5、微信H5等支付渠道的服务;

H5智能收款服务端接口:H5智能收款的接入方式包括前端接入和服务器端接入。像商户支付结果服务器端通知、商户支付订单查询、网银支付等都是要走服务器端接口;

无插件H5智能收款接口:是指针对基于手机、平板WAP网页上的商户应用的支付接口服务。手机或者平板插件接入式APP是不需要的;

H5智能收款商户:与现在股份合作,计划接入现在股份H5智能收款接口服务的商家;

支付结果通知:当消费者在商户的手机网站中支付完成后会收到实时的反馈结果,比如成功或者失败。但是真正的资金流的结果是在后台进行通知的,现在股份服务后台通过Https协议通知到商户后台。

使用场景

用户通过 手机网页浏览器 购买商品、创建订单,并将订单提交到支付渠道选择页面,选择支付渠道,发起支付。

(1)银联支付

在手机网页选择银联支付,传银行卡号模式跳转页面如下:
在手机网页选择银联支付,输卡号模式页面跳转如下:

(2)支付宝支付:在手机网页选择支付宝支付,跳入支付宝的支付网页,进行支付后,返回支付的结果。

(3)微信支付:用户在手机网页选择微信支付,跳转到微信app内进行支付,支付完成后,打开原网页,收到支付成功的通知。

如用户未安装微信,页面如下:

使用场景

在聚合平台创建设备为手机网页的应用

获取appid、appkey:

开通支付白名单,配置费率与限额后,即可使用应用编号及应用秘钥接入系统;

服务端支付结果异步通知

商户支付订单结果通知包括两部分的通知,即前台客户端实时同步交易结果应答和后台服务器端异步通知。前台实时同步应答即是当消费者支付完成后实时得到的UI层面的提示,后台服务器端异步通知是现在股份在实际资金流处理完成后给商户的服务器通过HTTPS协议异步发起的支付最终结果通知。考虑到实际完成支付流程的支付交易失败率比较低,且考虑到避免造成商户服务器端的压力,现只对支付成功的交易通知给智能收款平台商户,使智能收款平台商户能及时得到成功交易的交易状态。其它未通知的交易,智能收款平台商户可以通过交易查询接口主动发起查询或者通过智能收款平台商户管理后台去查看自己相关的交易订单的实时状态信息。

商户支付订单的通知流程如下:

需要注意的一些问题:

1.在商户推送订单给现在股份后,商户APP端实时收到的应答为支付订单受理结果,并非最终支付完成结果,最终结果以服务器端异步通知为准。

2.服务器端异步通知采用HTTPS协议进行通讯。现在股份通知商户的URL以商户支付订单推送时所填写的商户通知URL为准。

3.现规定,现在股份只对支付最终成功的订单进行通知商户,对支付失败或者其它状态的支付订单不进行异步通知。商户收到成功订单通知后进行自己的业务处理,然后实时同步应答字符串“success=Y”给现在股份。

4.如果商户在接收到现在股份异步通知后没有同步应答字符串“success=Y”给现在股份服务端,那么现在股份服务端就认为此次通知商户失败,那么现在股份将重复发起对商户的通知。

5.重复通知机制:现在股份服务端在第一次通知失败后,将在2分钟后发起第二次通知,如果还是失败将再隔10分钟发起第三次通知,以后如果还是不成功,将再间隔30分钟、60分钟、2个小时、6个小时、10个小时、15个小时后重复通知。最终在25小时内完成8次重复通知后,将不再继续重复通知。当然,在每一次通知后,如果收到“success=Y”的应答就停止重复通知。重复通知时间间隔如下: 2分钟、10分钟、30分钟、1小时、2小时、6小时、10小时、15小时。

无插件H5智能收款

现在股份智能收款服务为智能收款平台商户提供了两大类支付接入服务。一个是针对手机APP和平板APP等终端应用APP的支付服务,此类支付服务只要接入现在股份的SDK前端插件就可以直接使用现在股份的智能收款服务了。另一个则是针对电脑浏览器网页或者手机WAP网页的页面应用支付方式,此类支付服务需要智能收款平台商户将浏览器端支付服务直接提交到现在股份的后端HTTPS智能收款服务器上,由现在股份智能收款服务器去重定向渠道页面来完成支付业务,但此类支付对接方式不需要商户自己开发对接插件,所以称为无插件智能收款。

无插件H5智能收款服务在使用方式上又可以分为两种形式,一种是由现在股份智能收款提供通用的支付网关页面,智能收款平台商户只需要将支付订单提交给现在股份就可以完成支付了。另一种是由智能收款平台商户自行开发支付网关页面来供消费者选择支付渠道,最后由智能收款平台商户将支付订单信息和支付渠道网关编号一起推送给现在股份智能收款服务器来完成支付业务。

无插件H5智能收款--智能收款平台商户自定义网关页面模式下的业务流程:

报文通讯模式

采用https协议进行交互。数据交互方式包含:后台调用方式。SDK与智能收款平台服务后台系统之间进行交互时,需要通过post方式提交报文信息,请求参数为标准表单参数串形式。

报文定义

报文的统一格式如下:

最终请求和响应报文内容采用表单字符串样式,扁平式,无二级结构。且每个字段的值都经过URLEncodeer编码过,编码字符集根据请求报文中指定的字符集为准。

样例如下:

discount=0.00&payment_type=1&subject=%E9%99%B6%E6%A0%91%E5%BC%BA&trade_no=2014082033116251&buyer_email=finalphase1219%40gmail.com&gmt_create=2014-08-20+15%3A02%3A19¬ify_type=trade_status_sync&quantity=1&out_trade_no=2000104104802311&seller_id=2088701895944944¬ify_time=2014-08-20+15%3A02%3A20&body=%E5%85%B3%E4%BA%8E%E8%AE%A2%E5%8D%95%E9%AA%8C%E8%AF%81%E6%8E%A5%E5%8F%A3%E7%9A%84%E6%B5%8B%E8%AF%95&trade_status=TRADE_FINISHED&is_total_fee_adjust=N&total_fee=0.01&gmt_payment=2014-08-20+15%3A02%3A20&seller_email=jiasheng%40ipaynow.cn&gmt_close=2014-08-20+15%3A02%3A20&price=0.01&buyer_user_id=2088002274619511¬ify_id=4e47de6eabf15c476dc0014c894720014u&use_coupon=N&sign_type=RSA&sign=hq0pvqbbUMwY5TcIbC908eCD0ZkXTNEylQuV7SMDc3rDvLLuh2n4q6FBgfPoViiVdq8paT7jfoHHQHAVORLjCu2dEcxviK%2FT%2B2CcwGd1977lI9jZmfPMuwOwAi1gPjNgtw%2BsHY2esukpp23lNq%2F%2BjXN9hhHhRLrvqvVSuvBTrRg%3D

报文数据类型定义

String(m,n):代表可变长度型字符串类型。长度从m到n可变。

String(m):代表固定长度型字符串类型。m为整型数值。

Number(m,n):代表带精度数值类型。m代表数值位数长度为1~m,n代表小数点后位数。

Number(m):代表整型数值类型。m代表数值位数长度为1~m。

PS:m、n都为整型数值

WP001-被扫智能收款

接口接入URL:https://pay.ipaynow.cn 请求类型:POST

请求由商户页面发起:

字段名称 字段Key 格式 必填 备注
功能码 funcode String(5) Y 定值:WP001
接口版本号 version String(5) Y 定值:1.0.0
商户应用唯一标识 appId String(1,40) Y
商户订单号 mhtOrderNo String(1,40) Y
商户交易类型 mhtOrderType String(1,40) Y 01 普通消费
商户订单币种类型 mhtCurrencyType String(3) Y 156 人民币
商户订单交易金额 mhtOrderAmt Number(22) Y 单位(人民币):分 整数,无小数点
商户订单详情 mhtOrderDetail String(0,200) Y
商户订单超时时间 mhtOrderTimeOut Number(4) N 60~3600秒,默认3600
商户订单开始时间 mhtOrderStartTime String(14) Y yyyyMMddHHmmss
商户后台通知URL notifyUrl String(1,200) N 需要后台通知的必填 如填写,则在验密等异步情况下会发起后台通知
商户字符编码 mhtCharset String(1,16) Y UTF-8
设备类型 deviceType String(4) Y 定值:0601(手机网页)
用户所选渠道类型 payChannelType String(2) Y 银联:11 支付宝:12 微信:13
商户保留域 mhtReserved String(100) N 给商户使用的字段,商户可以
对交易进行标记,必须严格遵
循以下格式:mchBankId=123&商户自定义参数
输出格式 outputType String(2) N outputType=0
outputType=1
商户appId mhtLimitPay String(2) N 0:禁用信用卡
1:允许使用信用卡
支付账号 payAccNo String(40) N outputType=0payChannelType=11时,卡号必传
商品标记 mhtGoodsTag String(0,32) N 用于营销活动
用户支付ip consumerCreateIp String(20) Y payChannelType=13时必填
商户签名方法 mhtSignType String(3) Y 定值: MD5
商户数据签名 mhtSignature String(32) Y 除mhtSignature字段外,所有参数都参与MD5签名,签名逻辑

支付交易同步返回:

字段名称 字段Key 格式 必填 备注
功能码 funcode String(5) Y 定值:WP001
接口版本号 version String(5) Y 同输入
商户应用唯一标识 appId String(1,40) Y
响应码 responseCode String(4) Y
响应时间 responseTime String(14) Y yyyyMMddHHmmss
响应信息 responseMsg String(64) Y
商户订单号 mhtOrderNo String(1,40) Y
现在股份流水号 nowPayOrderNo String(1,40) N 下单成功时返回
支付交易状态 transStatus String(4) N
支付调起凭证 tn String(1,1000) N
商户子商户号 mhtSubMchId String(64) N 现在股份子商户号,机构商模式使用
签名方式 signType String(3) Y 定值:MD5
签名串 signature String(32) Y signature字段外,所有参数都参与MD5签名。签名逻辑

MQ002-商户支付订单查询

接口接入URL:https://pay.ipaynow.cn 请求类型:POST

由商户发起:

字段名称 字段Key 格式 必填 备注
功能码 funcode String(5) Y 定值:MQ002
接口版本号 version String(5) Y 定值:1.0.0
设备类型 deviceType String(4) Y 定值:0601(手机网页)
商户应用唯一标识 appId String(1,40) Y
商户订单号 mhtOrderNo String(1,40) Y
商户字符集 mhtCharset String(1,6) Y UTF-8
签名方法 mhtSignType String(3) Y 定值:MD5
数据签名 mhtSignature String(32) Y mhtSignature字段外,其它字段都参与MD5签名。签名逻辑

同步返回:

字段名称 字段Key 格式 必填 备注
功能码 funcode String(5) Y 定值:MQ002
接口版本号 version String(5) Y 定值:1.0.0
商户应用唯一标识 appId String(1,40) Y
商户订单号 mhtOrderNo String(1,40) Y
商户商品名称 mhtOrderName String(1,40) Y
商户子商户号 mhtSubMchId String(64) N 现在股份子商户号,机构商模式使用
订单交易类型 mhtOrderType String(2) Y 01 普通消费
05 代理消费
订单币种类型 mhtCurrencyType String(3) Y 156 人民币
订单交易金额 mhtOrderAmt Number(22) Y 单位(人民币):分
整数,无小数点
订单超时时间 mhtOrderTimeOut Number(4) N 60~3600秒,默认3600
订单开始时间 mhtOrderStartTime String(14) Y yyyyMMddHHmmss
交易字符编码 mhtCharset String(1,6) Y UTF-8
设备类型 deviceType String(4) Y 0601 手机网页
用户所选渠道类型 payChannelType String(2) Y 11 银联手机
12 支付宝支付
13 微信
现在股份订单号 nowPayOrderNo String(32) N 查询成功时返回
渠道订单号 channelOrderNo String(0,64) N
付款人账号 payConsumerId String(0,60) N 微信返回sub_openid
支付宝返回buyer_user_id
支付成功时间 payTime String(14) N yyyyMMddHHmmss
交易状态 transStatus String(4) Y
商户保留域 mhtReserved String(100) N
响应时间 responseTime String(14) Y yyyyMMddHHmmss
响应码 responseCode String(4) Y
响应信息 responseMsg String(1,100) N
签名方法 signType String(3) Y 定值:MD5
数据签名 signature String(32) Y signature字段外,其它字段都参与MD5签名。签名逻辑

N001-商户服务器端支付结果通知

现在股份的智能收款服务端异步发起:通讯方式:HTTPS POST

请求由商户页面发起:

字段名称 字段Key 格式 必填 备注
功能码 funcode String(4) Y 定值:N001
接口版本号 version String(5) Y 定值:1.0.0
商户应用唯一标识 appId String(1,40) Y
商户子商户号 mhtSubMchId String(64) N 现在股份子商户号,机构商模式使用
商户订单号 mhtOrderNo String(1,40) Y
商户商品名称 mhtOrderName String(1,40) Y
商户交易类型 mhtOrderType String(2) Y 01 普通消费
05 代理消费
商户订单币种类型 mhtCurrencyType String(3) Y 156 人民币
商户订单交易金额 mhtOrderAmt Number(22) Y 单位(人民币):分
商户订单超时时间 mhtOrderTimeOut Number(4) N 60~3600秒,默认3600
商户订单开始时间 mhtOrderStartTime String(14) Y yyyyMMddHHmmss
支付成功时间 payTime String(14) Y yyyyMMddHHmmss
商户字符编码 mhtCharset String(1,6) Y 定值:UTF-8
现在股份流水号 nowPayOrderNo String(0,64) Y
渠道订单号 channelOrderNo String(0,64) Y
设备类型 deviceType String(4) Y 0601 手机网页
用户所选渠道类型 payChannelType String(2) N 11银联手机
12支付宝支付
13微信支付
交易支付状态 transStatus String(4) Y
付款人账号 payConsumerId String(0,60) N 微信:openId
支付宝:buyer_id
商户保留域 mhtReserved String(0,100) N 给商户使用的字段,商户可以对交易进行标记,现在股份将原样返回
签名方法 signType String(3) Y 定值:MD5
数据签名 signature String(32) Y 除signature字段外,所有参数都参与MD5签名。

商户同步返回:

字段名称 字段Key 格式 必填 备注
是否成功 success Char(1) Y Y通知成功
N通知失败(现在股份未收到success=Y,后端将按规则默认重发通知)

N002-商户前端支付结果通知

现在股份的智能收款前端发起(Form表单数据如下):通讯方式:HTTPS GET

字段名称 字段Key 格式 必填 备注
功能码 funcode String(5) Y 定值:N002
接口版本号 version String(5) Y 定值:1.0.0
商户应用唯一标识 appId String(1,40) Y
商户订单号 mhtOrderNo String(1,40) Y
现在股份订单号 nowPayOrderNo String(0,64) N 成功时返回
商户字符编码 mhtCharset String(1,6) Y 定值:UTF-8
交易支付状态 transStatus String(4) Y A001支付成功
商户保留域 mhtReserved String(100) N 给商户使用的字段,商户可以对交易进行标记, 现在股份将原样返回
商户签名方法 signType String(3) Y 定值: MD5
商户数据签名 signature String(32) Y signature字段外,所有参数都参与MD5签名。
签名逻辑

交易的MD5签名逻辑

说明:除签名串(signature/mhtSignature)本身以外所有参数都参与签名

签名规则:

第一步:对参与MD5签名的字段按字典升序排序后,分别取值后并排除值为空的字段键值对,最后组成key1=value1&key2=value2....keyn=valuen"表单字符串"

第二步:对MD5密钥进行加密得到"密钥MD5值"。

第三步:最后对第一步中得到的表单字符串&第二步得到的密钥MD5值MD5签名

PS:MD5密钥是用户在注册应用的时候生成的,每个应用一个MD5密钥。

交易响应码表(不代表交易状态)

响应码 含义
A001 成功
A002 失败
A003 未知

交易响应码表

响应码 含义
A001 订单支付成功
A002 订单支付失败
A003 支付结果未知
A004 订单受理成功
A005 订单受理失败

设备类型表

类型码 含义
0601 手机网页

设备类型表

类型码 含义
11 银联
12 支付宝
13 微信
25 手Q

交易类型表

类型码 含义
01 普通消费
05 代理消费

支付调起凭证tn值样式

tn=weixin%3A%2F%2Fwap%2Fpay%3Fprepayid%253Dwx201611251324275019a969840267138070%26package% 3D2110169749%26noncestr%3D1480051467%26sign%3D11d5e57045fbdf79a1a86bc9399110ea(需要URLDecode)

商户保留域说明

平台类商户在使用微信支付时,需要上送mchBankId字段,值为在现在股份备案的子商户编号;格式:mchBankId=123&商户保留域参数

outputType取值说明

0 payChannelType=11表示银联有卡模式,必须传卡号; payChannelType=12、13时表示跳转现在股份页面

1 payChannelType=13表示返回https://pay.ipaynow.cn连接

3 且payChannelType=11表示银联无卡模式,不需要传卡号