首信易支付v43接口说明.doc

《首信易支付v43接口说明.doc》由会员分享，可在线阅读，更多相关《首信易支付v43接口说明.doc（12页珍藏版）》请在三一文库上搜索。

1、首信易支付（v4.3）接口说明（首信易支付商户后台管理系统 ）首信易支付流程及功能简要介绍 首信易支付网上支付主要流程大致分为商户交易订单提交过程和银行订单确认这两个部分。首先，当消费者在商户处完成购物过程，在商户端服务器形成最终订单（订单参数格式见文档第一部分“”说明）且消费者选择首信易支付方式时，该接口程序将消费者订单中有关支付的信息引导到首信易支付平台，消费者在该平台选择银行进行网上支付交易。当交易完成后，首信易支付平台可以通过两种方式通知商户银行对该笔订单的确认消息，商户根据实际业务需要选择这两种方式（其中任一种或者全部）编写相应的程序来接收银行返回的相关支付确认参数，通过对参数的判断

2、来进行后续的业务操作。1 前台页面链接方式：这种方式接收的参数格式见文档第二部分“”说明，是将此次支付订单的交易结果（参数）以页面连接的形式发送给商户。这里的前台指这个参数传递过程对持卡消费者是可见的。这种方式的特点是：返回参数的实时性好。但有个别几种支付方式不支持这种方式，有诸如网络中断或者持卡消费者不按要求操作等情况出现时，这种方式会有漏单（银行支付确认消息商户收不到）的现象。一旦出现漏单的情况，商户只能通过后台接口程序方式接收银行订单支付确认消息，或者登录到首信易支付商户后台管理系统查询确认。注意：这种方式接收程序的地址由商户在提交订单时参数v_url的值来指定，无需事先通知首信易支付平

3、台，如有变更只需要在提交订单参数时修改v_url的值即可。2 后台接口程序方式：这种方式接收的参数格式见文档第三部分“”说明，是由首信易支付平台转发银行支付确认信息。这种方式是首信易支付平台服务器与商户服务器之间进行通信的，对于持卡消费者是不可见的。这种方式的特点是：支持平台上所有的支付方式，而且在与商户的通信过程中如有网络故障，此方式支持自动重发功能（在首次发送的24小时内）。注意：这种方式接收程序的地址需要由商户来确定，在商户号开通时所填写的初始单中，填写在“订单支付确认返回地址”一栏，并由首信易支付平台管理员按照初始单内容进行开通。开通后如有修改，需要事先通知管理员确认修改。最后，首信易

4、支付将根据交易金额通知银行转帐。通常情况下，首信易支付结算中心会在周一、周四进行转帐工作，但需要满足本地商户本次转帐金额达到两百元人民币、外埠商户本次转帐金额达到六百元人民币的条件。如果不满足上述金额则累计到下次转帐时一起完成。在一旦转帐成功，将立即通知商户转帐结果，通知接口的参数格式为文档第四部分“”说明。此接口地址由商户确认，填写在初始单中“转帐确认通知接口”一栏中。商户开通后，如果需要更改也要事先通知管理员确认后修改。注意：通知商户转帐过程与网上支付交易是两个相对独立的过程，转帐工作是由首信易支付结算中心工作人员线下完成的，在通知银行进行转帐工作后，会通过“”将本次转帐的所有订单号发给商

5、户。由于这个接口发送的信息只是起到通知作用，不会影响商户的实际转帐工作。因此商户可以根据自己的实际需要选择是否使用这个接口。（本接口可选）各接口的具体格式如下：一、商户提交待付款订单接口（商户首信易支付）用途：用来接收商户发来的订单信息1、 CGI程序接口form method=post action=2、 FORM表单参数说明1 商户编号(v_mid) 说明：不可为空值，以初始单上所填商户编号为准。2 订单编号(v_oid) 说明：不可为空值，首信易支付订单编号格式统一为：订单生成日期(yyyymmdd)-商户编号-商户流水号 例如：19990720-888-12345。商户流水号为数字，每

6、日内不重复即可。 注：订单编号所有字符总和不可超过64位，否则首信易支付平台拒绝接受。3 收货人姓名(v_rcvname) 说明：不可为空值，统一用商户编号的值代替。4 收货人地址(v_rcvaddr) 说明：不可为空值，总长不超过128个字符。5 收货人电话(v_rcvtel) 说明：不可为空值，总长不超过32个字符。6 收货人邮政编码(v_rcvpost) 说明：不可为空值，总长不超过12个字符。7 订单总金额(v_amount) 说明：不可为空值，单位：元，小数点后保留两位，如13.458 订单产生日期(v_ymd) 说明：不可为空值，长度为8位，格式为yyyymmdd9 配货状态(v_

7、orderstatus) 说明：商户配货状态，0为未配齐，1为已配齐10订货人姓名(v_ordername) 说明：总长不超过64个字符11支付币种(v_moneytype) 说明：0为人民币，1为美元12返回商户页面地址(v_url) 说明：为消费者完成购物后返回的商户页面，此地址为页面连接方式的返回地址，在此地址放置接收程序用于接收银行返回的支付确认消息（参数格式参照文档第二部分）。URL参数是以http:/开头的完整URL地址。13订单数字指纹(v_md5info) 详情见md5说明注：以上参数值中不能包含以下特殊字符”&()3、示例（注：此例商户号888应改为您的商户号）form na

8、me=form method=post action= 商户编号 订单编号 收货人姓名 收货人地址 收货人电话 收货人邮编 订单总金额 订单产生日期 配货状态 订货人姓名 币种,0为人民币,1为美元 支付动作完成后返回到该url，支付结果以GET方式发送 订单数字指纹 由于采用HTML表单方式传递参数，就出现了消费者可以任意篡改页面信息的问题，为防止此类现象发生，我们需要对页面部分敏感信息作签名以保证其真实性和完整性。首信易支付平台向入驻商户提供了一个标准的签名程序源码，该程序提供签名功能，主功能函数为char* hmac (char* text, char* key)，该函数有两个入口参数：

9、char* text和char* key。其中text是将表单中部分敏感信息拼串的结果，具体做法如下：当消费者在商户端生成最终订单的时候，将订单中的v_moneytype v_ymd v_amount v_rcvname v_oid v_mid v_url七个参数的value值拼成一个无间隔的字符串(char型，顺序不要改变)。而另一个入口参数key则是首信易支付与商户私下约定的密钥。该密钥由商户生成，建议为16个字符，字母数字的组合。并通知首信易支付相关人员。在更换密钥时，请按照：公司名、商户号、联系人、密钥的顺序发送到zhaoruifan。该密钥初始值为test，以下所用到的密钥均为此密钥

10、例如上例表单的拼串结果应为：01999072013.4588819990720-888-000001234888http:/domain/program该函数返回值即为我们所需的数字指纹，将其写入v_md5info字段即可。注：为了满足不同商户需要，首信易支付还提供以下几种快捷支付通道，相关支付通道CGI接口链接地址及说明：英文支付通道：（四种外卡）可使用如下CGI接口链接（form表单参数与前面相同）：form name=form method=post action= 会员支付快捷通道：form name=form method=post action= 手机支付快捷通道：商户）支付完成

11、后页面转到商户时，从首信易支付返回的消息格式（注意，与后台接口程序文档第三部分定时发送方式使用的消息格式有区别）为：v_url?v_oid=19990720-商户号-000001234&v_pstatus=30&v_pstring=无效卡号&v_pmode=支付方式(字符串)&v_md5info=a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4&v_amount=0.01&v_moneytype=0&v_md5money=56b2c3d345f6a1b2c3d4e766a1b2c323&v_sign=7e85042c517d4e42f77b0ef967e7a6f20f2ede9

12、ff6558c8309712ec7edddb69dc783a2019a48599cc81ada8397a03b3af0ae42789ac6bc2783a5084419d51b0f54749df0123d51b319cf5f8a3c4a4b886372463dd96f9922a8a1e88a0c663b0065b25f7c9ac29fc98478e665c079d57308c01780d3d8067bbb634c9dd3853c8e该消息格式详细解释如下：v_url是该笔订单提交时（接口文档第一部分）参数v_url 的值，即Capinfo返回到商户的接口地址。 其中， * 为商户发送的v_url

13、 1v_oid = 商户发送的v_oid定单编号；2v_pmode = 支付方式（字符串）； 3v_pstatus = 1（已提交，对使用非实时银行卡进行扣款的订单）； 20（支付成功，对使用实时银行卡进行扣款的订单）； 30（支付失败，对使用实时银行卡进行扣款的订单）； 4v_pstring 支付结果信息= 已提交（当v_pstatus=1时）； 支付完成（当v_pstatus=20时）； 失败原因（当v_pstatus=30时,字符串）；5v_md5info =char* hmac_md5(char* text, char* key) char* text 拼串结果 char* key

14、对称密钥注：v_md5info校验四个参数，拼接字符串的顺序为：v_oid，v_pstatus，v_pstring和v_pmode 6v_amount订单实际支付金额 7v_moneytype 订单实际支付币种 8v_md5money=char* hmac_md5(char* text, char* key)char* text 拼串结果 char* key 对称密钥v_md5money效验两个参数，拼接字符串的顺序为：v_amount，v_moneytype9v_sign：商城数据签名，参与签名的数据（v_oid+v_pstatus+v_amount+v_moneytype）验证商城数据签名

15、Public1024.key为商城公钥） asp验证签名：set com=server.CreateObject(RSACOM.RSAMD5.1)source=v_oid & v_pstatus & v_amount & v_moneytype verifyStatus=com.PublicVerifyMD5(D:Public1024.key ,v_sign ,source ,len(source) (verifyStatus：0 验证成功) jsp验证签名：RSA_MD5 myRSA=new RSA_MD5(); String source=v_oid + v_pstatus + v_a

16、mount + v_moneytype;int verifyStatus = myRSA.PublicVerifyMD5(D:Public1024.key ,v_sign ,source);(verifyStatus：0 验证成功)关于验证参数的说明：首信易支付订单页面返回接口共有9个参数，其中v_oid，v_pstatus，v_pstring，v_pmode，v_amount，v_moneytype 这6个参数是订单支付相关的消息。v_md5info，v_md5money，v_sign 这3个参数是附加的验证消息。其中，v_sign 参数是用于首信易支付平台最新推出的非对称安全验证方式的指纹

17、结果。为了保持首信易支付平台的兼容性，所以保留了原来用于对称验证方式的两个验证值参数：v_md5info和v_md5money，这样原有商户就不必做任何改动，v_md5money中参加验证的参数均不含中文，如果在验证时遇到中文编码问题，可以通过验证这个指纹解决。首信易支付平台建议新入驻商户采用非对称的安全验证方式。这种验证方式也适用于后面的首信易支付订单支付结果后台返回接口，只是注意参加验证的参数有所不同。特在此说明，后面不再赘述。由于非对称安全验证方式使用时需要有安装证书文件等操作，如果是虚拟主机用户鉴于条件所限无法实现，则还可以使用原来md5验证方式。三、首信易支付订单支付结果后台返回接口

18、首信易支付商户） 用途：首信易支付向商户发送订单的支付结果，商户返回接收情况。 注：此接口以及后面的转账结果返回接口，需由商户入驻时提供，填写在初始单的“订单支付返回接口”一栏中，或者以公司名、商户号、联系人、两个接口的URL（请注明哪个接口）的形式发送到zhaoruifan。1、 首信易支付提交的FORM表单参数说明 首信易支付一次将返回一个或多个订单的支付结果，返回为多个订单结果时，我们将以订单组的形式发送，具体说明如下：对每一笔订单，首信易支付都实时地将支付结果发送给商户。如果某一笔订单未发送成功（如出现网络中断或该笔订单md5校验错）但已经成功支付，则此订单将随着下一次发送订单支付结

19、果时发送，如发送还不成功，则在当日重复发送。对于支付失败的订单只发送一次。在每次发送时，我们将以七个参数（v_count、v_oid、v_pmode、v_pstatus、v_pstring、v_amount、v_moneytype）表示订单相关内容，另外附加三个数字指纹字段（v_mac、v_md5money、v_sign）用于以上订单信息的校验。对于单笔订单，以上七个订单参数说明如下： 订单个数（v_count）：本次发送的订单个数；（最少为1，最大为4） 订单编号组（v_oid）：定义同商户提交待付款订单接口中的订单编号定义； 支付方式组（v_pmode）：支付方式中文说明，如“中行长城信用

20、卡”。 支付状态组（v_pstatus）：支付结果，0待处理（支付结果未确定）； 1支付完成； 3支付被拒绝； 支付结果说明（v_pstring）：对支付结果的说明，成功时（v_pstatus=1）为“支付成功”，支付被拒绝时（v_pstatus=3）为失败原因。订单支付金额(v_amount):订单实际支付金额订单支付币种(v_moneytype):订单实际支付币种v_sign：商城数据签名，参与签名的数据（v_oid+v_pstatus+v_amount+v_moneytype+v_count）对于批量订单的发送，以v_oid字段为例，v_oid1表示本次发送的第一笔订单，v_oid2表示

21、本次发送的第二笔订单，依此类推，组成v_oid字段，中间以“|_|”组合分割，举例如下：v_oid=v_oid1|_|v_oid2|_|v_oid3|_|v_oid4|_|。同理，v_pmode字段表示为：v_pmode=v_pmode1|_|v_pmode2|_|v_pmode3|_|v_pmode4|_|，v_pstatus字段表示为：v_pstatus=v_pstatus1|_|v_pstatus2|_|v_pstatus3|_|v_pstatus4|_|，v_pstring字段表示为：v_pstring=v_pstring1|_|v_pstring2|_|v_pstring3|_|,v

22、amount字段表示为：v_amount=v_amount1|_|v_amount2|_|v_amount3|_|,v_moneytype字段表示为：v_moneytype=v_moneytype1|_|v_moneytype2|_|。v_sign：商城数据签名，参与签名的数据（v_oid+v_pstatus+v_amount+v_moneytype+v_count）数字指纹（v_mac）：防篡改信息，v_mac=hmac_md5(text , key)；其中text是表单中各项的value按如下顺序拼串的结果：v_oid+v_pmode+v_pstatus+v_pstring+v_coun

23、t，key为双方约定的密钥。例如一次发送两笔订单：20001124-888-test002|_|20001124-888-test003招商银行一网通|_|招商银行一网通3|_|1支付被拒绝|_|支付完成2数字指纹（v_md5money）：防篡改信息，v_md5money=hmac_md5(text , key)；其中text是表单中各项的value按如下顺序拼串的结果：v_amount +v_moneytype，key为双方约定的密钥。验证商城数据签名（v_sign）：（Public1024.key为商城公钥） asp验证签名：set com=server.CreateObject(RSAC

24、OM.RSAMD5.1)source=v_oid & v_pstatus & v_amount & v_moneytype & v_countverifyStatus=com.PublicVerifyMD5(D:Public1024.key ,v_sign ,source ,len(source) (verifyStatus：0 验证成功) jsp验证签名：RSA_MD5 myRSA=new RSA_MD5(); String source=v_oid + v_pstatus + v_amount + v_moneytype + v_count; int verifyStatus = myRS

25、A.PublicVerifyMD5(D:Public1024.key ,v_sign ,source);(verifyStatus：0 验证成功)2、商户返回消息当商户收到上述消息后，返回消息定义如下：“sent”，表示成功收到支付结果信息。“error”，表示接收消息发生错误，如md5校验错。注：返回信息不要有任何HTML代码或其它符号。3、例如，在ASP中的参考代码% 获取参数 v_count=request(v_count)v_oid=request(v_oid)v_pmode=request(v_pmode)v_pstatus=request(v_pstatus)v_pstring=r

26、equest(v_pstring)v_mac=request(v_mac)v_sign=request(“v_sign”) 解析参数a_oid=split(v_oid,|_|)a_pmode=split(v_pmode,|_|)a_pstatus=split(v_pstatus,|_|)a_pstring=split(v_pstring,|_|) md5校验dim md,fffset md=server.CreateObject (md5_VB.md5class)fff=md.hmac(v_oid&v_pmode&v_pstatus&v_pstring&v_count,test) 按md5校验

27、情况输出结果if fffv_mac thenresponse.write errorelseresponse.write received 或response.write sent，依据商品物流特征决定。 操作数据库 （略）end if% RSA校验过程请参考文档第五部分中关于RSA的使用。四、首信易支付通知商户转帐结果接口（首信易支付商户）用途：首信易支付将订单转帐结果通知商户。（该接口是否使用可选）1、 首信易支付提交的FORM表单参数说明订单编号组（v_oid）：定义同首信易支付订单支付结果返回接口中的订单编号定义； 形式如下：v_oid=v_oid1|_|v_oid2|_|v_oid3

28、v_oid4|_|。转帐结果（v_virement）：1转帐成功；（一批订单无论多少只返回一个1。）订单数目（v_count）：本次发送的订单个数；数字指纹（v_mac）：拼串顺序为v_oid+v_virement+v_count。例如发送九笔订单：20001220-888-135|_|20001220-888-143|_|20001221-888-144|_|20001221-888-145|_|20001221-888-146|_|20001222-888-148|_|20001220-888-141|_|20001222-888-149|_|20001222-888-147192、

29、 商户返回消息“received”，表示成功收到转帐结果。“error”，表示接收消息发生错误，如md5校验错。3、例如，在ASP中的参考代码： % 获取参数 v_oid=request(v_oid)v_virement=request(v_virement)v_count=request(v_count) 解析参数a_oid=split(v_oid,|_|) 验证md5dim md,fffset md=server.CreateObject (md5_VB.md5class)fff=md.hmac(v_oid&v_virement&v_count,test) 按验证结果输出结果if fffv

30、mac thenresponse.write errorelseresponse.write received 操作数据库 （略）end if%RSA校验过程请参考文档第五部分中关于RSA的使用。五、关于安全验证算法的相关说明 MD5算法用于对原始信息进行数学摘要，以用于对数据完整性进行校验。（注：该算法由首信易支付提供asp、标准c、java三个版本）。v_moneytype，v_ymd，v_amount，v_rcvname，v_oid，v_mid，v_url七个参数的value值拼成一个字符串(char型，顺序不要改变)，与我们双方约定的密钥一同作为入口参数，具体调用函数如下带密钥的md

31、5算法库：md5lib.h 其中md5lib.h是外部可调用的函数库。 外部可调用的函数如下（详见readme.txt文件）： char* MDString (char *); /*输入任意一个字符串，经过md5算法处理后，返回结果：一个定长（32个字符）字符串 */char* MDFile (char *); /*输入任意一个文件名，文件内容经过md5算法处理后，返回结果：一个定长（16个字符）字符串 */char* hmac (char* text, char* key); /*输入任意一个字符串text，和一个用做密钥的字符串key，经过hmac算法处理，返回处理结果：一个定长字符串（个

32、字符），您只需要调用hmac函数*/编译时，把md5.c、md5lib.c 和调用函数一起编译；使用时，直接调用md5lib.c中的hmac函数即可。Sample.c 是个带主函数的测试程序，可不用。将算出来的结果加到 即可。RSA算法也是用于对原始信息进行数学摘要，以用于对数据完整性进行校验。（注：该算法由首信易支付提供asp、php for linux/Sun Solaris、jsp等版本）。调用方法：创建对象set rsacom=server.CreateObject(RSACOM.RSAMD5.1)调用方法参数：商城公钥，签名数据，原数据，原数据长度返回值：整型 0：验证成功，其它：验

33、证失败verifyStatus=rsacom.PublicVerifyMD5(D:Public1024.key,v_sign,source,len(source)示例代码：source=abcde12345v_sign=3e5671bc4f91c3d055b18c1e5e22dd9db157380c7ee8facf0b1117082fbf398d7113c2df7e3219fc28dd88dd26cb096cabe607f3e397dfc2dcdb3349351a5f025ea0761da6e39e2d2fd311294a6076e777fe2ab8911f22113c435b89d63ae4

34、f2aff2f333f7ebd40cc89601d58fb37b16596b5c94eb8b64cd52e12b9679248e6aset rsacom=server.CreateObject(RSACOM.RSAMD5.1)verifyStatus=rsacom.PublicVerifyMD5(D:Public1024.key,v_sign,source,len(source)验证签名结果if verifyStatus=0 then response.write 公钥验证成功.else response.write 公钥验证失败.end if六、调试1、 当模拟购物过程能出现首信易支付选择卡

35、种类的页面（ 见下图 ）时，第一部分调试成功。2、 对于第二、第三以及第四部分接口的调试，需到银行成功支付后进行，建议使用招行的账号，实时性比较好。附录： 首信易支付平台：首信易支付会员支付快捷通道：首信易支付手机支付快捷通道：首信易支付英文支付通道：注：1、888为示例商户编号，商户不可用于测试2、商户用于测试的商户编号及密钥请与首信易支付工作人员联系获取3、商户在使用正式商户编号时，请提前与首信易支付工作人员联系约定密钥4、商户测试时，请务必测试md5加密环节接口提交时常见错误列表编号产生错误的原因错误提示01参数v_amount中有“，”例：6，000（）6000（）参数格式错误 Inc

36、orrect information format02参数v_ymd和v_oid中的时间不一致参数格式错误 Incorrect information format03参数v_moneytype值非0或1参数格式错误 Incorrect information format04v_ymd和v_oid中时间没有按照yyyymmdd的格式设置参数格式错误 Incorrect information format05v_mid和v_oid中商户编号不一致参数格式错误 Incorrect information format06订单号（v_oid）不完整，例如：仅将流水号传送等参数格式错误 Incor

37、rect information format07v_md5info值计算结果与首信支付平台不一致订单数字指纹校验错Fingerprint invalid08参数中含有繁体字/生僻字，例如“喆”“張”字等订单数字指纹校验错Fingerprint invalid09商户编号（v_mid）尚未开通该商户信息不完整The service for this merchant is unavailable 10未开通外卡时将参数v_moneytype设置为1提交该商户未开通外卡支付服务Invalid operation 11此订单号曾经提交过，本次提交改变了上一次提交时某些订单参数，例如：第一次提交金额

38、为0.01本次提交为0.02，但是订单号没有变化。订单处理正在进行，但新提交的数据与原定单不一致Order is in process,can not modify order info12同一个订单号，重复使用；例如：订单号：20060808-888-12345，提交后选择工行支付，但没有成功，此订单号再一次被提交时会出现此错误信息；同一张订单号不能重复向银行提交，请重新下单获得新的订单号Order is in process,can not run payment operation注：v_md5info值计算结果与首信支付平台不一致的原因可能为：1拼串顺序错误（正确顺序请参看技术文档第一部分说明）2所使用密钥不一致（请使用和首信支付平台约定的密钥）3可能有些参数中含有空格，取值时并未取出（请确保参与拼串的参数值与表单中所赋的值一致）