庚悠付api扫码接口开发指南

商户接口规范

www.gengyoufu.cn

只为更安全的支付！

版本(2.1.0)

目录

第一章 文档描述 3

1、 文档说明 3

2、 阅读对象 3

第二章 系统原理 3

1、 术语定义 3

2、 消费流程 4

3、 查询流程 4

4、 查询流程 4

第三章 扫码接口定义 4

1、 同步过程接口定义（商户系统发起请求） 4

2、 下行异步通知过程接口定义（庚悠付api接口发起请求） 6

3、 下行同步通知过程接口定义（庚悠付api接口发起请求） 8

附录 1：庚悠付api支付网关银行类型说明 8

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

第一章 文档描述

1、 文档说明

本说明文档用于指导庚悠付api商户实现与庚悠付api扫码接口的顺利对接。请相关技术人员详细阅读本文档。

2、 阅读对象

商户开发人员。

第二章 系统原理

1、 术语定义

商户：指已独立拥有在线销售系统，并成为庚悠付api扫码接口系统会员，且已使用或者将使用庚悠付api扫码接口实现收付费或其他相关功能需求的企业或者个人。

外部接入接口：指庚悠付api通过统一的方式接受外部请求的接口。

商户系统：指使用庚悠付api外部接入接口的计算机系统，一般指商户所拥有的在线销售系统。

用户：指在商户系统内进行消费的企业或者个人。

商户id： 指庚悠付api为使用外部接入接口的商户统一分配的唯一标识。

商户密钥：指商户在和庚悠付api确定合作意向时庚悠付api为商户提供的16 位字符串。该信息作为商户系统和庚悠付api交互时身份确认的依据，需商户妥善保管。

2、 消费流程

通常，一次支付Zui少包括2 个交互过程。第一个过程是商户系统将在线支付等信息提交庚悠付api支付网关说明文档到庚悠付api接口的过程，称之为上行过程。第二个过程是在支付完成后，庚悠付api接口通过server to server 方式将支付结果告知商户系统的过程，称之为下行异步通知过程。

如果用户在跳转到庚悠付api接口完成支付操作后，需要庚悠付api接口将处理结果立即返回给商户系统的下一步页面，让用户继续完成整个操作流程，此时支付还应包括第三个流程，下行同步通知过程。该过程需要在上行过程中提交参数hrefbackurl。

3、 查询流程

在商户系统将订单成功提交给庚悠付api接口后的任意时间，商户系统可发起请求查询订单的处理结果。该流程由商户系统发起，由接口返回相应结果。

4、 查询流程

庚悠付api采用md5 加密方式对传输数据进行签名验证，具体请参考相关接口定义。对md5 加密后的签名值，请注意结果的大小写务必正确。

为了确保签名值不是因为md5 加密算法而导致结果不正确，请各商户在调用接口前对字符串1234567890abcdefghijklmnopqrstuvwxyz 使用md5 加密算法进行加密，若加密结果为928f7bcdcd08869cc44c1bf24e7abec6 则表示md5 加密正常。

第三章 扫码接口定义

1、 同步过程接口定义（商户系统发起请求）

1、 接入url：
微信扫码:http://你的域名/pay/payweixin_system.aspx
接入方式：get 方式

2、 请求协议参数：

表1 同步过程请求协议参数说明

参数名	参数	可空	加入签名	说明
商户id	partner	n	y	商户id,由庚悠付api分配
通道类型	banktype	n	y	通道类型，具体参考附录1
金额	paymoney	n	y	单位元（人民币）
商户订单号	ordernumber	n	y	商户系统订单号，该订单号将作为庚悠付api接口的返回数据。该值需在商户系统内唯一，庚悠付api系统暂时不检查该值是否唯一
下行异步通知地址	callbackurl	n	y	下行异步通知的地址，需要以http://开头且没有任何参数
下行同步通知地址	hrefbackurl	y	n	下行同步通知过程的返回地址(在支付完成后庚悠付api接口将会跳转到的商户系统连接地址)。 注：若提交值无该参数，或者该参数值为空，则在支付完成后，庚悠付api接口将不会跳转到商户系统，用户将停留在庚悠付api接口系统提示支付成功的页面。
备注信息	attach	y	n	备注信息，下行中会原样返回。若该值包含中文，请注意编码
md5签名	sign	n	n	32位小写md5签名值，gb2312编码

3、 md5签名说明：

待签名数据为表1 中加入签名列值为y 的参数以及商户密钥，签名顺序为表1 中partner到callbackurl 的顺序加商户密钥。具体md5 签名源串及格式如下：

partner={}&banktype={}&paymoney={}&ordernumber={}&callbackurl={}key

其中，key为商户签名。

4、 接入实例：（假设商户 id 为 10000，商户密钥为 4272fafab8869dbd292d959b7542530c） 请求提交方法：

http://你的域名/pay/pay.aspx?partner=10000&banktype=icbc&paymoney=100.00&ordernumber=1234567890&callbackurl=http://www.mydomain.com/backaction&hrefbackurl=http://www.mydomain.com/notifyaction&attach=jrapi&sign=9e4908fe082687db7396f856ff4bbd23

实际进行 md5 加密的串是

partner=10000&banktype=icbc&paymoney=100.00&ordernumber=1234567890&callbackurl=http://www.mydomain.com/backaction4272fafab8869dbd292d959b7542530c

该串 md5 加密结果为 9e4908fe082687db7396f856ff4bbd23

5、 特别说明：

①  在接口使用中，商户系统内发起请求时应使用页面跳转的方式跳转到接口地址。如在jsp中，使用response.sendredirect(接口地址及参数)，在.net中使用 response.redirect(接口地址及参数)。

② 若 hrefbackurl 有效，则在跳转返回通知过程中，庚悠付api接口将使用相同方法跳转回商 户系统，跳转地址是 hrefbackurl。

③ 根据 http 协议要求，提交参数的值中若存在特殊字符（如：空格、@等）时，为 使庚悠付api接口能接收到正确的参数，这些特殊字符需要做 url encoding。需特别注意的是， 此时待签名数据应该是原生值而不是 encoding 之后的值。

2、 下行异步通知过程接口定义（庚悠付api接口发起请求{建议使用异步！}）

1、 接入url：过程1 中请求参数 callbackurl 值

2、 接入方式：get 方式

3、 请求协议参数：

表 2 下行过程请求协议参数说明

参数名	参数	加入签名	说明
商户id	partner	y	商户id,由庚悠付api分配
商户订单号	ordernumber	y	上行过程中商户系统传入的ordernumber
订单结果	orderstatus	y	1:支付成功，非1为支付失败
订单金额	paymoney	y	单位元（人民币）
庚悠付api订单号	sysnumber	n	此次交易中庚悠付api接口系统内的订单id
备注信息	attach	n	备注信息，上行中attach原样返回
md5签名	sign	n	32位小写md5签名值，gb2312编码

4、 md5签名说明：

待签名数据为表2中加入签名列值为y的参数以及商户密钥，签名顺序为表2中partner到paymoney的顺序加商户密钥。具体 md5 签名源串及格式如下：

partner={}&ordernumber={}&orderstatus={}&paymoney={}key

其中,key为商户签名

5、 特别说明：

① 下行异步通知过程在整个支付流程中一定存在。商户系统在收到下行通知过程后， 需向庚悠付api接口返回“ok”。庚悠付api接口根据该返回值判断商户系统是否已经收到结果。若返回结果不是“ok”，庚悠付api接口会根据商家和庚悠付api接口的约定，再次反复向 callbackurl 发送结果，直到商户返回“ok”或者达到和商户约定的重复发送次数。

② 当庚悠付api接口在下行异步通知过程中返回在线支付结果时，商户系统在收到数据后， 应该通过sign值判断是否是有效的返回数据，防止数据在网络传输过程中被恶意篡改。

6、 注意事项

① 在收到庚悠付api接口订单下行异步通知结果时，商户系统需首先验证订单通知的合法性， 如果不合法，则不要更新商户系统上的订单状态。

② 商户系统内订单状态和订单实际金额务必以此次庚悠付api接口订单异步通知的结果为准。

③ 商户系统在成功提交订单后，在未没有收到庚悠付api接口异步通知结果时，请不要更新商户系统上的订单状态

④ 在下行异步通知过程中商户系统返回结果值“ok”回庚悠付api接口时，“ok”并不是将庚悠付api接口在下行异步通知的结果原样返回。商户系统返回值“ok”时表示商户系统已经成功接收到了结果（不论结果是什么，总之是收到了），而其他值表示因为某些原因商户系统并不认为庚悠付api接口的返回是有效的。庚悠付api接口在收到商户系统的返回后，如果返回的值为“ok”庚悠付api接口将不再次发送结果，否则庚悠付api接口会根据庚悠付api接口同商户的约定 再次发送结果。

3、 下行同步通知过程接口定义（庚悠付api接口发起请求）

1、 接入url：过程1 中请求参数 hrefbackurl值

2、 接入方式：get 方式

3、 请求协议参数：

该过程参数同表2所示

4、 特别说明:

如果用户在跳转到庚悠付api数卡接口完成支付操作后，需要庚悠付api数卡接口将处理结果立即返回给商户系统的下一步页面，让用户继续完成整个操作流程，此时支付还应包括下行同步通知过程。该过程需要在上行过程中提交参数hrefbackurl。

当庚悠付api接口在下行同步通知过程中返回在线支付结果时，商户系统在收到数据后，应该 通过sign值判断是否是有效的返回数据，防止数据在网络传输过程中被恶意篡改。

 

 

 

 

 

 

 

 

 

 

 

 

附录 1：庚悠付api网关银行类型说明

alipay	支付宝
weixin	微信
alipaywap	支付宝wap
weixinwap	微信wap