开发文档 | 恒付通

API文档简介

1.引言

1.1.概述

本文档是针对支付行业提供的解决方案,供内部相关开发和技术支持人员与商户平台服务方技术人员使用。

1.2.名词解释

名词术语 解释说明
付款码支付 又称为“刷卡支付(微信),当面付(支付宝)”。付款人展示条形码/二维码之后,商户用扫码枪进行扫描,
商户也可以手工输入条形码/二维码对应的数字。该扫码方式属于“被扫”。
收款码支付 又称为“收款二维码,商户二维码,固定二维码”。该二维码是固定的,可以贴在商户柜台上给付款人扫码
支付。付款人扫码之后需要输入金额。该扫码方式属于“主扫”。
订单二维码 每一笔订单生成一个二维码。付款人扫码之后进行支付。该扫码方式属于“主扫”。
商户证书 又称为“商户密钥”。商户提交订单时,加密订单数据时会用到该证书。
订单签名 又称为“签名”。商户提交订单时,使用“商户证书”加密订单数据后会生产该签名。服务器端比较该签名和订单
数据是否一致,就可以知道在传输过程中,订单数据是否被篡改过。

1.3.商户接入流程

商户交易接入的流程如下:

1) 商户提交资料给销售:商户签约后,把资料提交给本公司销售人员。

2) 本公司创建商户:本公司的操作人员把商户录入系统,创建正式商户。

3) 商户自行注册:商户访问本公司的网站之后,自行注册商户信息,并提交审核

4) 本公司开通商户:本公司的人员审核商户资料无误后,即可开通商户。系统会自动发送开户信到商户的指定邮箱。其中包含:商户后台网址,商户号,用户名,登录密码,交易密码 等信息。

5) 商户登录后台,并设置交易帐号:商户根据开户信中的内容,登录商户后台,并设置自己的交易帐号信息。比如:银行商户号,银行商户证书,费率参数等等。

6) 本公司核对交易帐号:本公司核对商户的交易帐号无误后,即可开通该交易帐号。后续即可接入交易。

7) 商户开发接口:商户登录商户后台后,进入“系统管理-接口下载”菜单,即可下载接口开发的文档和demo。商户参考该文档和demo进行接口开发。

8) 商户提交订单到收单接口:商户开发完接口后,即可把交易提交到本公司的收单接口。测试通过后,即正式交易。

1.4.接口开发步骤

测试参数:

交易帐号 说明 密钥
90000010 可测试“网银、快捷”的支付流程 参考Demo例子中列出的密钥
90000011 可测试“微信、支付宝”的支付流程 参考Demo例子中列出的密钥

正式环境接口地址:

接口种类 接口地址
网关收单接口 https://mypay.hengfupay.com/gateway/Order.aspx
API收单接口 https://mypay.hengfupay.com/interface/OrderApply.aspx
收款二维码接口 https://mypay.hengfupay.com/interface/OrderQRCode.aspx
订单查询接口 https://mypay.hengfupay.com/interface/OrderQuery.aspx

接口开发步骤:

1. 首先,登录商户后台,进入“商户管理-接口下载”菜单下载接口文档和Demo。我们提供了asp.net、asp、jsp、php四种版本的Demo,用户可根据需求下载对应版本。

  1)商户提款接口(文档和Demo):商户可以在自己的系统中调用该接口提交提款申请。

  2)统一支付接口(文档和Demo):该接口支持“网银/快捷/支付宝/微信”等多种支付方式。

该文档对应的即“统一支付接口”。

2. 在开发前,请搭建一个有“公网ip或者域名”的测试网站,并把Demo例子安装到该测试网站下。域名可以用修改hosts文件的方式模拟。 备注:如果该测试网站没有“公网ip或者域名”,则无法从本公司网关返回交易结果到该测试网站。当然,提交交易的功能是正常的。

3. 直接用Demo中的例子提交交易,并查看是否正确。 备注:Demo程序中设置了测试商户的“交易帐号(固定为90000010,90000011),商户证书”。确认支付网关收单地址为实际的生产环境的地址。

4. 确认已经拿到您的相关信息:

  a) 确认已经拿到了您的商户后台的“商户号,用户名,登录密码,交易密码”这些信息。如果已经拿到,即可登录商户后台获取“商户证书”。

  b) 确认已经拿到了您的“交易帐号,支付网关地址,商户证书”这些参数。其中,“商户证书”可登录商户后台获取;“支付网关地址”可向技术支持索取实际的支付网关地址。

  c) 确认您的“商户号,交易帐号”已开通。如果未开通,则提交的交易会失败。

5. 把Demo例子中的“交易帐号,商户证书”更新为您实际的“交易帐号,商户证书”,确认能正常提交交易。参考该例子继续开发您的支付接口。

1.5.技术支持

技术支持 QQ:2869909653(优先),2961126909

2.网关收单的应用场景

2.1.场景一:网银/快捷 支付

备注:该场景对应“4.1网关收单接口”,需要把“渠道编码(channel_code)”设置为“网银支付(wyzf)”或“银联快捷(ylkj)”。

下图表述了商户的客户(即持卡人)的完整购物流程。

持卡人支付流程:

1.付款人下单:该步骤是持卡人在购物网站进行购物消费。持卡人在确认订单之后,即可点“提交”。商户网站接口将订单提交到本公司的网关。

2.网关收单(无界面):本公司的网关接收到订单信息之后,即可验证订单数据并保存订单。如果是未指定卡种的网银支付,系统会先显示“选卡种页面”给付款人选择;否则系统会直接跳转到银行网关进行支付。

3.收单失败(有界面):如果本公司的网关在验证数据和保存订单时出错,则会显示收单失败的页面信息。

4.网银支付扣款/快捷支付扣款:系统自动跳转到对应的银行网关页面后,付款人输入信息并提交扣款。

5.回传订单(无界面):从银行网关页面返回到本公司的支付网关后,本公司先保存订单信息,然后通过POST方式把订单信息回传到商户接口。该回传方式属于“前台通知”,对应url_back参数。

6.显示订单结果:本公司的支付网关将交易结果回传到商户网站,商户网站即可显示订单的支付结果。

2.2.场景二:扫码支付

备注:该场景对应“4.1网关收单接口”,需要把“渠道编码(channel_code)”设置为“微信扫码支付(wxPubQR)”或“京东扫码支付(jdQR)”或“支付宝扫码支付(alipayQR)”。

下图表述了商户的客户(即付款人)的完整购物流程。

持卡人支付流程:

1.付款人下单:该步骤是持卡人在购物网站进行购物消费。持卡人在确认订单之后,即可点“提交”。商户网站接口将订单提交到本公司的网关。

2.网关收单(无界面):本公司的网关接收到订单信息之后,即可验证订单数据并保存订单。如果是未指定卡种的网银支付,系统会先显示“选卡种页面”给付款人选择;否则系统会直接跳转到银行网关进行支付。

3.收单失败(有界面):如果本公司的网关在验证数据和保存订单时出错,则会显示收单失败的页面信息。

4.显示二维码(有界面):本公司的网关显示出对应的二维码。付款人即可用手机直接扫码或截图后打开图片扫码。备注:如果商户订单未指定扫码种类,系统可能先显示页面,让用户选择“微信扫码”还是“支付宝扫码”。

5.扫码支付:付款人用手机中的微信或支付宝扫描二维码之后,即可进入支付页面,进行支付。

6.回传订单(无界面):付款人支付成功(或失败)后,会自动跳转到本公司网关接收回传信息。然后本公司系统会跳转商户网站。该回传方式属于“前台通知”,对应url_back参数。

7.显示订单结果:本公司的支付网关将交易结果回传到商户网站,商户网站即可显示订单的支付结果。

8.接收扫码结果(无界面):付款人在手机上扫码付款后,系统会自动检测到付款成功/失败结果。在接收订单结果之后,即可跳转商户网站。该回传方式属于“前台通知”,对应url_back参数。

9.显示订单结果:本公司的支付网关将交易结果回传到商户网站,商户网站即可显示订单的支付结果。

3 API收单的应用场景

3.1.场景一:APP支付

商户在自己的移动端app中集成支付功能。商户app调用支付后台统一下单接口获取签名后的支付数据,拿到支付数据后商户app调起微信支付的控件发起支付,此时商户app会跳转到相应的支付渠道中,用户确认金额输入密码支付完成后跳回到商户APP内,最后展示支付结果。

3.2.场景二:付款码支付

1.商户收银员在商户系统操作生成支付订单,用户确认支付金额;

2.用户选择刷卡支付付款并打开相应的支付渠道,进入“我”->“钱包”->“付款”条码界面;

3.商户收银员用扫码设备扫描用户的条码/二维码,商户收银系统提交支付请求到支付后台;

4.用户输入密码,完成支付。

3.3.场景三:扫码支付(收款二维码)

1.商户根据相应的规则生成商户的二维码;

2.用户打开支付渠道“扫一扫”扫描二维码;

3.用户输入订单金额,进行支付。

3.4.场景四:扫码支付(订单二维码)

1.商户后台系统根据用户选购的商品生成订单;

2.用户确认支付后调用支付后台订单接口生成交易会话的二维码;

3.用户打开支付渠道“扫一扫”扫描二维码;

4.用户输入密码,完成支付。

3.5.场景五:微信公众号支付(wxPub)

商户在自己H5商城中集成微信支付功能。场景流程同app支付流程。

4.接口定义

4.1.网关收单接口

该接口是将商户网站的订单信息发送到本公司的“支付网关”,该接口基于 HTML 的 Form 表单形式,通过持卡人的浏览器,将支付报文以POST方式提交至“支付网关”。参数顺序没有要求。

该接口的提交的数据包含“基本信息,购物信息,订单签名”这样几部分。其中:“购物信息”可以传多个产品的信息。“订单签名”是为了防止交易数据被篡改而生成的校验信息,当传递的信息中途被修改的话可以通过算法来进行校验,从而防止不法交易的产生。

具体参数及格式可参考下表:

类别 字段名 必填 类型 备注信息
基本信息 merch_id int(8) 交易账户号 (由本公司分配)
备注:交易账户号是8位数字。前6位和商户号相同。
submer_id int(9) 子商户号 (由商户分配)
备注:子商户号是9位数字。前6位和商户号相同
channel_code string(50) 渠道编码 (由本公司定义,参考“6.1渠道编码”)
wyzf :网银支付
ylkj :银联快捷
wxPubQR:微信扫码支付
jdQR :京东扫码支付
alipayQR:支付宝扫码支付
supply_code string(50) 网银支付的卡种编码 (参考附录的卡种编码表)
备注:如果“支付类别”和“卡种编码”的参数值都不为空,则直接跳转到银行支付页面,否则会先显示选择卡种的页面。
language string(50) 浏览器语言。可选值为:
en-us:英语
zh-cn:中文
若此字段传空或者数据不能识别,则默认为中文。支付网关会根据该字段显示不同的界面。
mer_order_id string(50) 商户订单号 (例如:141017114556-3694 , ...)
由商户网站生成,用来唯一标识该订单,不应当重复。
mer_order_date string(14) 商户订单时间
格式:YYYYMMDDHHMMSS。例如:20141031235959
order_amount numeric 订单金额
格式:保留两位小数的金额。例如:263.50
product_desc string(100) 产品描述
备注:该字段不填也不会报错,但可能影响某些支付方式。
url_sync string(200) 订单同步地址 (用于后台通知)
例如:http://www.abc.com/callback.php
备注:该字段不填也不会报错,但会导致商户网站无法接收到订单回传信息。商户只能进后台查看订单情况。
url_back string(200) 订单返回地址 (用于前台通知)
order_remark string(200) 订单备注备注:
在订单状态回传或同步时,该字段会原样返回。
订单 signature string(32) 订单签名=md5(order_hash+merch_id+submer_id+
签名 channel_code +mer_order_id +order_amount)
order_hash:商户的交易证书,可从“商户后台”获取
注意:不同字符集中生成的证书可能不同,应使用utf-8

支付接口实例代码,可在商户网站后台下载,接口支持asp.net、php、asp、jsp四种版本,商户可根据需要下载对应的版本,如有疑问,可联系我司技术支持

4.2.API收单接口

请求参数:

字段名 变量名 必填 类型 说明
交易账户号 merch_id String(8) 交易账户号 (由本公司分配)
备注:交易账户号是8位数字。前6位和商户号相同。
子商户号 submer_id String(9) 子商户号 (由商户分配)
备注:子商户号是9位数字。前6位和商户号相同
渠道编码 channel_code String(10) 支付使用的第三方支付渠道,见附录“渠道编码”
商户订单号 mer_order_id String(50) 商户系统内部的订单号,32个字符内、可包含字母, 确保在商户系统唯一
订单支付时间 mer_order_date String(14) 格式为yyyyMMddHHmmss,
如2009年12月25日9点10分10秒表示为20091225091010
订单金额 order_amount Number 格式:保留两位小数的金额。例如:263.50
产品描述 product_desc String(100) 备注:该字段不填也不会报错,但可能影响某些支付方式。
订单后台同步 url_sync String(200) 订单同步地址 (用于后台通知)例如:http://www.abc.com/callback.php 备注:该字段不填也不会报错,但会导致商户网站无法接收到订单回传信息。商户只能进后台查看订单情况。
订单备注 order_remark String(200) 在查询API和支付通知中原样返回,该字段主要用于商户携带订单的自定义数据
签名 signature String(32) md5(hash_key+merch_id+submer_id+channel_code+mer_order_id+
order_amount)hash_key:商户的交易证书,可从“商户后台”获取。注意:不同字符集中生成的证书可能不同,应使用utf-8
扩张字段 特定渠道发起交易时需要的额外参数以及部分渠道支付成功返回的额外参数。参见“扩展字段说明”

扩展字段说明:

channel_code 扩展字段 必填 说明
wyzf supply_code 卡种编码
url_back 支付成功跳转路径;参数参考交易详细查询;
ylkj url_back 支付成功跳转路径;参数参考交易详细查询;
wxPub order_expire 订单失效时间,格式yyyyMMddHHmmss。不传默认30分钟
limit_pay 为指定支付方式,指定不能使用信用卡支付可设置为no_credit
url_back 支付成功跳转路径;form表单形式提交商户后台;参数参考交易详细查询;
wxPubQR order_expire 订单失效时间,格式yyyyMMddHHmmss。不传默认30分钟
limit_pay 为指定支付方式,指定不能使用信用卡支付可设置为no_credit
wxApp order_expire 订单失效时间,格式yyyyMMddHHmmss。不传默认30分钟
limit_pay 为指定支付方式,指定不能使用信用卡支付可设置为no_credit
mobile_appid 微信开放平台上创建应用所生成的AppID
wxMicro order_expire 订单失效时间,格式yyyyMMddHHmmss。不传默认30分钟
limit_pay 为指定支付方式,指定不能使用信用卡支付可设置为no_credit
auth_code 授权码
alipayQR order_expire 订单失效时间,格式yyyyMMddHHmmss。不传默认30分钟
alipayApp order_expire 订单失效时间,格式yyyyMMddHHmmss。不传默认30分钟
alipayApp order_expire 订单失效时间,格式yyyyMMddHHmmss。不传默认30分钟
auth_code 支付授权码
jdPay order_expire 订单失效时间,格式yyyyMMddHHmmss。不传默认30分钟
url_back 支付成功跳转路径;form表单形式提交商户后台;参数参考交易详细查询;
access_type 接入类型;默认为PC; 1:PC 2:移动支付
jdQpay order_expire 订单失效时间,格式yyyyMMddHHmmss。不传默认30分钟
url_back 支付成功跳转路径;form表单形式提交商户后台;参数参考交易详细查询;
jdPayGate order_expire 订单失效时间,格式yyyyMMddHHmmss。不传默认30分钟
url_back 支付成功跳转路径
jdMicro order_expire 订单失效时间,格式yyyyMMddHHmmss。不传默认30分钟
jdQR order_expire 订单失效时间,格式yyyyMMddHHmmss。不传默认30分钟
baiduPay order_expire 订单失效时间,格式yyyyMMddHHmmss。不传默认30分钟
url_back 支付成功跳转路径; form表单形式提交商户后台;参数参考交易详细查询;
access_type 接入类型;默认为PC; 1:PC 2:移动支付

举例如下:

<form method="post" action="http://pay.hengfupay.com/api/trans_order.aspx">
<input type=hidden name="merch_id" value="90000011">
<input type=hidden name="submer_id" value="900000001">
<input type=hidden name="channel_code" value="wxPubQR">
<input type=hidden name="mer_order_id" value="20161013005">
<input type=hidden name="mer_order_date" value="20160131235959">
<input type=hidden name="order_amount" value="32.61">
<input type=hidden name="product_desc" value="产品">
<input type=hidden name="url_sync" value="http://xxx.xxx.xxx/aaa.php">
<input type=hidden name="order_remark" value="附加数据">
<input type=hidden name="signature" value="656E72AF744DE642828E58221BDE68BA">
{扩张字段}
</form>

备注:直接根据{扩展字段}的具体字段替换这一行。比如:

<input type=hidden name="mobile_appid" value="">
<input type=hidden name="url_sync" value="...">

正常情况的返回参数:

字段名 变量名 类型 描述
交易账户号 merch_id String(8) 交易账户号 (由本公司分配)
备注:交易账户号是8位数字。前6位和商户号相同。
商户订单号 mer_order_id String(20) 商户系统内部的订单号,32个字符内、可包含字母, 确保在商户系统唯一
订单金额 order_amount Number 订单金额
订单备注 order_remark String(100) 商户提交订单时填写的订单备注
系统订单号 order_id String(32) 支付渠道返回的订单号
银行返回单号 bank_order_no String(50) 银行返回的订单号
订单状态 status String(1) 订单状态
Y-成功 N-失败 T-其他
错误编码 err_code String 如果订单失败,则返回该错误编码
错误描述 err_info String 如果订单失败,则返回该错误描述
签名 signature String(32) 签名=md5(hash_key+merch_id+mer_order_id +order_amount+order_id+status)
hash_key:商户的交易证书,可从“商户后台”获取
注意:不同字符集中生成的证书可能不同,应使用utf-8
支付URL pay_url String(32) 代表扫码的URL或跳转的URL。渠道编码为wxPubQR,alipayQR,wxPub,jdQpay等参数时有返回值。
支付码信息 pay_code String(1000) 其他支付参数。渠道编码为wxApp,alipayApp等参数时有返回值。

异常时的返回结果:

<message>
<run_err>[E999]系统出现未知的运行错误。</run_err>
</message>

正常时的返回结果:

<message>
<merch_id>90000011</merch_id>
<mer_order_id>234987234</mer_order_id>
<order_amount>65.10</order_amount>
<order_remark>备注信息</order_remark>
<order_id>1601312359590001</order_id>
<bank_order_no>2395672193847</bank_order_no>
<status>N</status>
<err_code>E888</err_code><err_info>商户被禁用</err_info>
<signature>656E72AF744DE642828E58221BDE68BA</signature>
<pay_url>weixin://wxpay/bizpayurl?pr=GDaO3tU</pay_url>
<pay_code>3987</pay_code>
</message>

4.3.收款二维码接口 (仅用于指定商户)

备注:该二维码同时支持“微信,支付宝,京东”扫码。

请求的POST参数

字段名 变量名 必填 类型 描述
交易账户号 merch_id String(8) 由本公司分配的交易账户号,例如:90000011
备注:交易账户号是8位数字。前6位和商户号相同。
子商户号 submer_id String(9) 子商户号 (由商户分配)
备注:子商户号是9位数字。前6位和商户号相同
是否可用信用卡 limit_pay String(10) 为指定支付方式,指定不能使用信用卡支付可设置为no_credit
签名 signature String(32) 签名=md5(hash_key+merch_id+submer_id)
hash_key:商户的交易证书,可从“商户后台”获取
注意:不同字符集中生成的证书可能不同,应使用utf-8

举例如下:

<form method="post" action="http://pay.hengfupay.com/api/trans_qrcode.aspx">
<input type=hidden name="merch_id" value="90000011">
<input type=hidden name="submer_id" value="900000001">
<input type=hidden name="limit_pay" value="no_credit">
<input type=hidden name="signature" value="807367912301425E1010D108AF31AB0F">
</form>

正常情况的返回参数:

字段名 变量名 必填 类型 描述
交易账户号 merch_id String(8) 交易账户号 (由本公司分配)
查询状态 status String(1) 执行结果 Y-执行成功 N-执行失败
备注:这不是订单状态,而是操作是否执行成功
错误编码 err_code String 如果订单失败,则返回该错误编码
错误描述 err_info String 如果订单失败,则返回该错误描述
二维码串 qrcode_url String 例如https://xxxx/xxx/xx/xx
签名 signature String(32) 签名=md5(hash_key+merch_id+status)
hash_key:商户的交易证书,可从“商户后台”获取
注意:不同字符集中生成的证书可能不同,应使用utf-8

异常时的返回结果:

<message>
<run_err>[E999]系统出现未知的运行错误。</run_err>
</message>

正常时的返回结果:

<message>
<merch_id>90000011</merch_id>
<status>Y</status>
<err_code></err_code>
<err_info></err_info>
<qrcode_url>https://xxxx.xxx.xx/aaa.php</qrcode_url>
<signature>807367912301425E1010D108AF31AB0F</signature>
</message>

4.4.订单查询接口

请求参数:

字段名 变量名 必填 类型 描述
交易账号 merch_id String(8) 交易账户号 (由本公司分配)
商户订单号 mer_order_id String(32) 商户订单号
系统订单号 order_id String(16) 例如:1410302359590000
本公司的系统生成的唯一标识该订单的订单号
签名 signature String(32) 签名=md5(hash_key+merch_id+mer_order_id+order_id)
hash_key:商户的交易证书,可从“商户后台”获取
注意:不同字符集中生成的证书可能不同,应使用utf-8

备注:mer_order_id和order_id只需要有一项必填。

举例如下

<form method="post" action="http://pay.hengfupay.com/api/trans_order.aspx">
<input type=hidden name="merch_id" value="90000011">
<input type=hidden name="mer_order_id" value="20160131312">
<input type=hidden name="order_id" v alue="1410302359590000">
<input type=hidden name="signature" value="8BC54648F98169DCBD2F661B1729B45A">
</form>

正常情况的返回参数:

字段名 变量名 必填 类型 描述
系统订单号 order_id String(50)
订单状态 status String(1) 状态Y-成功 N-失败 T-其他(比如处理中)
收单时间 receive_time String(50) 格式yyyy-mm-dd hh:mm:ss
交易账号 merch_id String(8) 交易账户号 (由本公司分配)
备注:交易账户号是8位数字。前6位和商户号相同。
子商户号 submer_id String(50) 子商户号 (由商户分配)
备注:子商户号是9位数字。前6位和商户号相同
支付渠道 channel_code String(50) 渠道编码
卡种编码 supply_code String(50) 卡种编码
商户订单号 mer_order_id String(50) 商户订单号
商户订单时间 mer_order_date String(50) 商户订单时间
订单金额 order_amount Number 订单金额
商品描述 product_desc String(100) 商品或支付单简要描述
订单备注 order_remark String(100) 商户提交订单时填写的订单备注
提交银行时间 post_time String(50) 格式yyyy-mm-dd hh:mm:ss
返回银行时间 back_time String(50) 格式yyyy-mm-dd hh:mm:ss
银行订单号 bank_order_no String(32) 银行返回的订单号
签名 signature String(32) 签名=md5(hash_key+merch_id+mer_order_id+status)
hash_key:商户的交易证书,可从“商户后台”获取
注意:不同字符集中生成的证书可能不同,应使用utf-8

异常时的返回结果:

<message>
<run_err>[E999]系统出现未知的运行错误。</run_err>
</message>

正常时的返回结果

<message>
<order_id>1720161011512</order_id>
<status>Y</status>
<receive_time>2017-03-31 12:59:59</receive_time>
<merch_id>90000011</merch_id>
<submer_id>900000001</submer_id>
<channel_code>wy</channel_code>
<supply_code>icbc</supply_code>
<mer_order_id>20161011312</mer_order_id>
<mer_order_date>20170131235959</mer_order_date>
<order_amount>12.01</order_amount>
<product_desc>订单产品</product_desc>
<order_remark>备注</order_remark>
<post_time>2017-01-01 10:00:00</post_time>
<back_time>2017-01-01 10:00:00</back_time>
<bank_order_no>298374</bank_order_no>
<signature>3B61007C11C5BABEC3F5020F2775D619</signature>
</message>

4.5.订单状态回传

前台通知:对于网页跳转形式的支付方式,在银行完成支付之后跳转到我公司网页之后,我公司系统会以GET或POST到指定的商户接口。该商户接口是商户提交订单时设置的“url_back”参数。

注意:

1)只有部分支付方式才支持“前台通知”,具体需要查看收单接口的参数定义。

2)付款人有可能在支付过程中终止支付行为(比如 关闭浏览器),这类订单就无法进行前台通知。

3)回传的订单状态可能为“成功,失败,其他”。比后台通知多了一种“其他”状态,可能代表 未支付、处理中、或其他含义。

后台通知:在商户提交订单时,可以设置“url_sync”参数,用于后台通知。我公司系统的后台进程,会每隔5分钟检索出可能需要回传状态的订单(仅限3天内订单),并把订单状态以form表单形式POST到指定的商户接口。商户接口接收到数据后需要返回“ISRESPONSION”信息;我公司后台进程收到该“ISRESPONSION”信息之后,即确认商户接口已收到信息。

备注:

1)只有“成功,失败”状态的订单才会通过“后台通知”的形式回传订单信息。“未支付、处理中”等状态的订单不会回传。

2)如果商户接口未返回“ISRESPONSION”信息,则我公司的后台进程会认为商户接口未收到信息。我们会持续回传订单信息,最多回传5次。

回传数据的字段定义如下:

类别 字段名 必填 类型 说明与备注
订单信息 merch_id int(8) 交易账户号 (由本公司分配)
备注:交易账户号是8位数字。前6位和商户号相同。
mer_order_id string(50) 商户订单号
由商户网站生成,用来唯一标识该订单,不应当重复。
order_amount numeric 订单金额
order_remark string(100) 商户提交订单时填写的订单备注
支付信息 order_id int(16) 系统订单号 (16位数字,例如:1410302359590000)
本公司的系统生成的唯一标识该订单的订单号。
bank_order_no string(50) 银行返回的订单号
status string(1) 订单状态
Y-成功 N-失败 T-未支付/处理中/其他
状态“T”只有在前台通知时才可能用到。
err_code string(10) 如果订单失败,则返回该错误编码
err_info string(100) 如果订单失败,则返回该错误描述
签名信息 signature string(32) 签名=md5(order_hash+merch_id+mer_order_id+
order_amount+order_id+status)
order_hash:商户的交易证书
注意:不同字符集中生成的证书可能不同,应使用utf-8
扩展字段 supply_code string(50) 当前订单对应的卡种。可能为空。一般只有网银支付才有这项数据。

成功订单回传信息 举例如下:

<form method="get/post" action="{url_back或url_sync}">
<input type=hidden name="merch_id" value="90000011">
<input type=hidden name="mer_order_id" value="2235">
<input type=hidden name="order_amount" value="12.30">
<input type=hidden name="order_remark" value="网银">
<input type=hidden name="order_id" value="1410302359590000">
<input type=hidden name="bank_order_no" value="19283741873681-2133">
<input type=hidden name="status" value="Y">
<input type=hidden name="err_code" value="">
<input type=hidden name="err_info" value="">
<input type=hidden name="signature" value="0B91096219AB77E148F180307FD07687">
<input type=hidden name="supply_code" value="icbc">
</form>

失败订单回传信息 举例如下:

<form method="get/post" action="{url_back或url_sync}">
<input type=hidden name="merch_id" value="90000011">
<input type=hidden name="mer_order_id" value="2235">
<input type=hidden name="order_amount" value="12.30">
<input type=hidden name="order_remark" value="网银">
<input type=hidden name="order_id" value="1410302359590000">
<input type=hidden name="bank_order_no" value="19283741873681-2133">
<input type=hidden name="status" value="N">
<input type=hidden name="err_code" value="E999">
<input type=hidden name="err_info" value="该交易帐号禁止交易">
<input type=hidden name="signature" value="0B91096219AB77E148F180307FD07687">
<input type=hidden name="supply_code" value="icbc">
</form>

5.网关收单的典型流程截图

5.1.扫码支付的PC界面

本公司的支付网关会自动检测用户使用的是电脑还是手机,并显示出相符的界面。

扫码支付的电脑界面是这样的:

第一步:选法扫码支付的方式“微信/支付宝”

第二步:系统显示出二维码。付款人进行扫码支付。

5.2.扫码支付的手机界面

扫码支付的手机界面是这样的:

第一步:选择“扫码支付”

第二步:选择“微信/支付宝”

第三步:系统显示出二维码。付款人进行扫码支付。

5.3.网银支付的PC界面

网银支付的电脑界面是这样的:选择网银的卡种,点“确认支付”,即跳转到网银的页面。

5.4.网银支付的手机界面

网银支付的手机界面是这样的:

5.5.快捷支付的PC界面

快捷支付的电脑界面是这样的:

5.6.快捷支付的手机界面

快捷支付的手机界面是这样的:

第一步:该页面是模拟下单页面,点“提交”

第二步:快捷支付页面


第三步:显示快捷支付的结果。

第四步:显示本公司的结果页面。

6.附录

6.1.渠道编码(对应channel_code参数)

渠道编码 渠道名称 是否开通
wyzl 网银支付
ylkj 银联快捷
wxPub 微信公众账号支付
wxPubQR 微信公众账号扫码支付
wxApp 微信app支付
wxMicro 微信付款码支付
jdPay 京东支付 未开通
jdPayGate 京东快捷支付
jdQpay 京东网关 未开通
jdMicro 京东付款码支付 未开通
jdQR 京东扫码支付 未开通
baiduPay 百度钱包支付 未开通
alipayQR 支付宝扫码支付
alipayApp 支付宝APP支付 未开通
alipayMicro 支付宝付款码支付

6.2.卡种编码(对应supply_code参数)

对于网银支付(wyzl),涉及的卡种编码如下:

编码(supply_code) 银行名称
ICBC 工商银行
ABC 农业银行
CMB 招商银行
CIB 兴业银行
CNCB 中信银行
CCB 建设银行
BOC 中国银行
COMM 交通银行
SPDB 浦东发展银行
CMSB 民生银行
HXB 华夏银行
CEB 光大银行
BJB 北京银行
CGB 广东发展银行
SHB 上海银行
PSBC 邮政储蓄
PAB 平安银行

6.3.错误码表

错误码 错误描述
E100 只允许以POST方式提交订单。
E101 未读取到订单数据。
E102 交易帐号()为空或或格式不对。
E103 订单金额()必须大于0。
E104 订单签名 不能为空。
E105 订单签名 不匹配。
E106 商户证书 不能为空。
E107 商户状态()不允许收单。
E108 交易账户状态()不允许收单。
E109 普通商户提交的交易不能设置子商户值()。
E110 同一个交易帐号()的商户订单号()不能重复。
E111 该子商户()不存在或者和交易账号()不匹配。
E112 该渠道编码()不存在或者该交易帐号不支持该渠道编码。
E113 该卡种编码()不存在或者该交易帐号不支持该卡种编码。
E114 保存订单过程中出现异常。
E115 该交易帐号()目前只支持两种扫码(wxPubQR,alipayQR)。
E116 商户收单时间()必须为标准的“yyyyMMddHHmmss”格式。
E117 生成二维码时未获取到有效的渠道编码。----程序Bug或使用不当
E118 该支付方式的 渠道编码 不能为空。
E119 该支付方式的 卡种编码 不能为空。
E120 商户订单号 和系统订单号 不能都为空。
E121 银行商户号和银行商户证书 不能为空。
E200 只允许POST提交。
E201 未读取到有效数据。
E202 系统订单号格式不对。
E203 该订单未找到。
E204 该订单已提交支付,不允许刷新页面或再次提交。
E205 该订单已超过3小时,不允许刷新页面或再次提交。
E999 系统运行出现未知错误。