建行网上支付接口开发规范.docx
《建行网上支付接口开发规范.docx》由会员分享，可在线阅读，更多相关《建行网上支付接口开发规范.docx（13页珍藏版）》请在冰豆网上搜索。
建行网上支付接口开发规范
1．网上支付使用条件ﻩ1
1.1客户进行网上支付的条件1
1.２商户在建行网银系统开户ﻩ1
２.网上支付流程ﻩ2
2．1网上支付业务流程图:
2
2．２ﻩ客户使用建行证书ﻩ３
2．3网银系统返回信息3
2.4商户的货款结算与对帐流程3
2.５ﻩ商户向客户退还货款的流程４
２.5．１当日退款ﻩ4
2.5.2ﻩ隔日退款4
3．商户→银行接口参数（个人客户）ﻩ5
4.商户→银行接口参数（企业客户）7
5．银行→商户接口参数９
附录1：
ＭAC算法说明ﻩ11
附录２：
数字签名算法说明1３
1.网上支付使用条件
客户进行网上支付的条件
1）与建行签约的客户
Ø客户已在建设银行签约,申请网上支付服务
Ø客户签约的帐户（信用卡或储蓄卡帐户）可用于网上支付
Ø其购物的商户提供了建行支付功能
Ø网上支付的结算范围不能超过建行网上银行的辖区范围
2）未与建行签约的客户
Ø在建设银行有帐户（信用卡或储蓄卡帐户）
Ø其购物的商户提供了建行支付功能
Ø网上支付的结算范围不能超过建行网上银行的辖区范围
商户在建行网银系统开户
Ø商户与建设银行签定协议
Ø银行为其提供结算帐户与网上预申请密码
Ø在网上填写申请（需输入预申请密码才能见到开户申请表）
Ø网银中心授理并核发CＡ证书,建立商户信息维护表
Ø商户下载证书
Ø如果是需要实时反馈支付信息的商户,登录网银系统，申请密钥
Ø完成开户
2.网上支付流程
网上支付业务流程图:
ﻩﻩﻩﻩ
ﻩﻩﻩ
ﻩ
ﻩ
网上支付业务流程步骤说明：
1）客户登录商户网站，选择商户网站商品。
2）客户将选好的商品放入购物车,并下订单。
商户提供商户代码、订单号、合计金额等信息；
3）客户选择代理付款的银行-建行,确认后,商户代码、订单信息、合计金额通过浏览器ＵRL传到建行网上银行站点；网上银行自动显示支付页面，客户首先选择是否使用建行证书,然后输入龙卡号和密码,选择“确定”。
支付信息经加密后传送到网银中心；
4）网银中心接收客户支付信息，转发到银行后台业务处理系统;
5）银行后台业务系统处理后,返回处理结果给网银；
6）网银通知客户支付（扣帐）是否成功。
如果扣帐成功，提示客户注意接收商户返回的送货信息;对于不需要立即响应的商户,跳过步骤7、8；
7）对于需要立即响应的商户，如果支付成功,网银将成功结果反馈给商户。
若支付失败,不返回给商户信息
8）对于需要立即响应的商户，收到银行扣帐成功的通知后,发给客户送货信息。
如客户收到银行支付（扣帐）成功通知（步骤6），但未收到商户送货信息,则需向商户查询。
日终时，商户与开设结算帐户的建设银行（网银成员行）进行流水核对,对已支付但未得到商户确认的交易进行退款处理。
客户使用建行证书
客户在商户网站选择建行支付后,被链接到建行网上银行网站。
该链接将商户名、柜台号、定单号、金额,验证信息传到网上银行系统（建行提供无密钥的MAC算法）。
客户进入建行网上银行系统时选择是否使用建行证书进行支付。
1）如果是建行签约客户,可以选择有证书支付
Ø选择使用证书支付后，输入用户号及登录密码,进入网上支付页面
Ø支付页面显示商户名、柜台号、定单号、金额等商户传来的信息（不能改动）。
客户选择付款帐户,输入交易密码，选择“确定”或“取消”
2）如果客户没有与建行签约,只能使用无证书支付
Ø选择无证书支付后,进入网上支付页面
Ø支付页面显示商户名、柜台号、定单号、金额等商户传来的信息（不能改动）。
客户输入龙卡卡号和密码，选择“确定”或“取消”。
网银系统返回信息
网银系统返回给商户成功或失败信息（按商户类型，分两种情况进行处理）
1）对于不需要实时反馈支付结果的商户，直接将支付结果通过浏览器显示给客户（业务流程步骤6）。
2）对于需要实时反馈支付结果的商户,将支付结果返回客户（业务流程步骤6）,同时,如果支付成功，将结果和数字签名信息（注：
签名算法和签名内容由建行指定）反馈给商户（业务流程步骤7），签名校验成功后,进行后续处理；如果支付失败,不再通知商户。
商户的货款结算与对帐流程
1）每个商户在建行开设专用结算帐户。
客户在建行网上银行支付功能下付款,货款记入商户的专用结算帐户（含定单号信息）。
2）商户通过浏览器登录建行网上银行,可实时查询网上支付流水；对于需要实时反馈支付结果的商户，由于在交易过程中已获取了支付结果，因此也可在商户本地数据库中查到支付信息。
3）商户也可通过浏览器下载对帐文件（支付流水清单）,该文件上的每笔货款已成功支付。
商户向客户退还货款的流程
退还货款是指银行支付（扣款）成功后，因客户向商户提出退货或商户无法配送商品,商户通过银行向客户退还货款。
银行退款处理流程根据商户提出退款请求的时间而定。
2.1.1当日退款
1）商户登录建行网上银行，选择网上退款功能。
2）商户输入当日的定单号（每个订单只能退款一次）
3）银行查询原始交易返回交易日期和付款金额
4）商户输入退款金额（全部或部份）,交易密码，备注。
5）银行后台系统检验是否能退款，返回成功或失败信息。
2.1.2隔日退款
1）商户与当地建行联系，退款由人工完成。
3.商户→银行接口参数（个人客户）
个人客户在商户网站选择商品后,商户网站生成以下信息，传送到建行网站：
域名
名称
类型
备注
ＭEＲCHANTIＤ
商户代码
ＣHAR（9）
由建行统一分配
POＳID
商户柜台代码
CHAR（９）
由建行统一分配，缺省为000000000
BＲAＮＣHID
分行代码
CHAＲ（9）
由建行统一指定
ＯRＤＥRID
定单号
CHAR（3０）
由商户提供，最长30位,按实际长度给出
PＡYMENＴ
付款金额
NUMBＥR（16,２）
由商户提供,按实际金额给出
CＵＲCOＤE
币种
CHAR
（2）
缺省为01-人民币
REMARK1
备注1
CHＡR（３0）
网银不处理，直接传到城综网
ＲＥMAＲK2
备注2
CHAR（30）
网银不处理，直接传到城综网
TXCODE
交易码
CHAR（6）
由建行统一分配为520100
ＭAＣ
ＭＡC校验域
ＣHAR（32）
采用标准MD5算法,由商户实现
注：
商户要保证定单号的唯一性。
为了加快站点间接口开发,站点间接口的参数传送采用普通的URL方式,商户将以上信息包含在FORM中,在SUBMIT后将生成ＵRＬ，如下所示：
/ccbMaiｎ？
MＥRCHANTＩD=1234５67８9＆POＳID=０0００0０000&BＲＡＮCＨID＝110000000&ＯRDERＩD=19991１01２34&ＰAYＭＥNT=500.00&CURCODＥ=01&TXＣODE=520100&RＥMＡＲK１＝&ＲEMARK2＝＆MAC=qwerｔyｕｉｏｐlkｊhgfdｓａzxcｖbnm9０1234
参与ＭAC运算的字符及其顺序如下:
MERＣHANTIＤ=1234５67８9&POSID=000000000&BRANCHＩD=１１0000０0０&ＯＲDＥRID=19991101２34&ＰAYMＥNT＝5０0．00&CＵRＣＯDＥ＝01&ＴＸCＯDE=520100&REMＡＲK1＝&ＲEＭAＲK2＝
注：
字符串中变量名必须是大写字母。
4.商户→银行接口参数（企业客户）
企业客户在商户网站选择商品后,商户网站生成以下信息，传送到建行网站:
域名
名称
类型
备注
MERCHANTID
商户代码（客户号）
CＨAR（21）
由建行统一分配
POSID
商户柜台代码
CＨAR（９）
由建行统一分配,缺省为000０000０0
BRＡNCHID
分行代码
CHAR（9）
由建行统一指定
ORDEＲIＤ
定单号
CHＡR（３0）
由商户提供,最长30位，按实际长度给出
PＡYＭENＴ
付款金额
NUMＢER（16,2）
由商户提供，按实际金额给出
CURCODＥ
币种
CHAR
（2）
缺省为0１-人民币
RＥMＡＲK1
备注1
ＣHＡR（30）
网银不处理,直接传到城综网
ＲEＭARK2
备注2
CHAＲ（30）
网银不处理，直接传到城综网
ＴXCODE
交易码
CHＡR（6）
由建行统一分配为69０４０1
MＡC
MＡＣ校验域
CHＡＲ（32）
采用标准MD5算法，由商户实现
注：
商户要保证定单号的唯一性。
站点间接口的参数传送采用表单的post方式提交，商户将以上信息包含在ＦORＭ中。
例如,
？
MEＲCHAＮTIＤ=1２3456789&ＰOSIＤ＝00０0０0０00&BRAＮCHID＝1１０00０000&ORDERID=１99９１101２34&PＡYMENＴ=50０．00&CURＣODＥ＝01&ＴXＣODE=690４01&RＥMARK1=&REMARK２＝&ＭAC=ｓｄs6dd８gdｄdｄwdｓdddfuj
（测试为 ）
参与MAC运算的字符及其顺序如下:
ＭERCＨAＮTID=1234567８９&ＰOSID=00０000000&BRANCＨIＤ=１1０00000０&ＯＲDERIＤ=1９99110123４&PＡYＭENＴ＝500.0０&CURCＯＤE=01&TXCODE＝6９04０1&REMＡRＫ1=＆REＭARK2=
注:
字符串中变量名必须是大写字母。
5.银行→商户接口参数
建行网站生成以下信息，传送到商户网站：
域名
名称
类型
备注
ＰOＳID
商户柜台代码
CＨＡR（９）
从商户传送的信息中获得
BRＡNCHID
分行代码
CHＡR（９）
从商户传送的信息中获得
ORDEＲID
定单号
CHAR（３0）
从商户传送的信息中获得
PAYMENT
付款金额
ＮUMBER（16,2）
从商户传送的信息中获得
CURCODE
币种
CHＡR
（2）
从商户传送的信息中获得
REＭARK１
备注一
ＣHAR（30）
从商户传送的信息中获得
RＥMAＲK2
备注二
CHＡR（３0）
从商户传送的信息中获得
SUCCESS
成功标志
CHAR
（1）
成功时返回Y
ＳIGN
数字签名
CHAＲ（２5６）
站点间接口的参数传送仍然采用普通的URＬ方式,信息包含在CＧI参数，具体如下所示：
=1９991１０1&ＲEＭARK2＝ｍerｃｈanｔname&ＳUCCＥSS＝Ｙ&ＳＩGN=4ｂ3ef０２9516193b7d969aｃ1840083６35a３e090１b８ｃｄ5２6caａ44c１a072f4９６d７f０d4bｃa394２c０ｄ９０30ｂeｄe37c780９ｂ8３５ceｃ７87eb３９e1８ｂ75９6ａ72４ｆｂａ9８0５b２47１4ｄfbb0f４a3ｆb４３0ｂ3２e075254a114d4c3８ａ0ac５2ef46a0ad3３dｅc3ｆbfｃ15４17402a1399ｅ６5ｅ4６996c0ｃf4９fｃ7ffca9222f8ｃd693ｃ８3７6b6f928８2８96７ｂec42
注:
?
前的ＵRL由商户在签约时提供
参与签名运算的字符及其顺序如下
POSID=０000０00０0&BRAＮCHＩD=１1000０000&ORDERIＤ=19991101234&PＡYMENT=500．0０＆CUＲＣOＤE=01&RＥMARK1=199９１10１&REMARK2=ｍｅｒchantnａｍe&SＵCＣＥSS=Y
注：
字符串中变量名必须是大写字母。
如果商户的程序将ＭＥＲCHANTＩＤ,POSIＤ，ＢRＡNCＨＩD，ORDERID, ＰＡYMENT，CＵRＣＯＤＥ,TXCODE和MAC作为隐藏域（hiｄｄeｎ），然后使用SUＢMIT按纽，注意在FORM的METHOD中使用“ＧET”的方式。
附录１:
ＭAC算法说明
建设银行网上银行项目组决定对商户向网上银行系统提交的交易内容进行MAC校验,校验算法采用标准MD5算法,不带密钥。
该算法的详细说明请参见RFC132１文档。
我们假设商户实行标准的MD5算法对向网上银行系统提交的交易内容进行MAＣ校验,产生１28位（biｔ）的MAC结果。
输入为字符串，输出为16进制字符表示的字符串。
下面是对MAC结果的显示方式的描述：
1、对128位的交易结果按4位为一个单位进行划分，共获得32段
2、将每段看成一个16进制数，如00１1为0Ｘ3,1１０1为0Xd。
3、将这个数映射到ＡSCIＩ码表，形成相应的字符,如０X2为“2”,0Ｘd为“ｄ”。
4、将这些字符连成一个字符串，长度为32。
下面是使用JAVA语言对表现方法的描述：
public static Strｉｎgｂｉntoascｉi（bｙｔe[］ｂｙSourceByte）
ﻩﻩ｛
ﻩintlen，i;
ﻩｂytetb;
ﻩﻩchaｒhｉｇh,tｍp,lｏw;
ﻩﻩﻩStriｎgreｓulｔ＝nｅwString（）;
ｌen=bySourｃeByte．lenｇth;
ﻩﻩﻩfor（i=0;i＜len；i＋+）
ﻩﻩﻩ｛
ﻩﻩﻩｔb＝bｙSｏurcｅＢyte[i］;
ﻩﻩﻩ
ﻩﻩtmp=（char）（（tｂ>>>４）&０x000ｆ）；
ﻩﻩﻩﻩｉｆ（tｍｐ>＝10）
high=（ｃhar）（＇ａ'+ｔmｐ-10）；
ﻩﻩﻩﻩelｓｅ
ﻩﻩﻩhiｇh＝（ｃhar）（'0'+ｔmｐ）；
ﻩﻩﻩrｅsult＋＝hｉgh;
ﻩﻩtmp＝（cｈａr）（tb&0ｘ０0０ｆ）;
ﻩﻩiｆ（tｍp＞＝10）
ﻩlow=（char）（'a'+tｍp-１0）;
ﻩﻩeｌｓe
ﻩﻩﻩloｗ=（chａr）（'0'+tmｐ）;
ﻩﻩﻩﻩ
ﻩresuｌt＋=loｗ;
ﻩﻩ}
ﻩﻩretｕrnresult;
ﻩﻩ｝
下面是一些字符串进行MAＣ并按上述方法进行转换后获得的结果:
ØMＤ５（""）= d41ｄ8cd9８f00b204e９８00998eｃｆ8427ｅ
ØMＤ5（"a"） ＝0cｃ1７5b9c０f１b6a831ｃ399ｅ269772６6１
ØMD5 （"abc＂）=９00１5０983cｄ24fｂ０d696３f7d2８e1７f72
ØMＤ５（"mｅｓsaｇedｉgest"）=ﻩf９6b697ｄ７cb7９38d525ａ2ｆ３1ａaf161d0
ØMD5（"ａｂcｄｅfghiｊklmnopｑｒstｕvwxyz"）=ﻩｃ３ｆｃd3ｄ7６192ｅ4007dfb496cca67e13b
ØMD5（＂ＡBＣDEＦGHIJＫＬＭＮOＰＱRSTUVＷXＹＺabｃdefｇｈijklｍnoｐqrstuvwxｙz０12345６789＂）= ｄ174ab98d2７7d９f５ａ5611ｃ2c9f419d9f
ØMD５（"１２３4５６7８912345678９１23４5678９12345６789"）=ﻩ5７eｄｆ4a22bｅ3c955ac49da2ｅ2１07b6７a
在实施时若遇到具体问题,可由双方协商解决。
附录2：
数字签名算法说明
银行将客户支付信息实时通知给商户时，使用的数字签名算法是ＭD5wiｔhRSA算法。
商户验证签名的公钥在商户在网银系统开户，获取数字证书后，登录到网银系统中，通过下载公钥交易获取。
商户获取的公钥用X.509格式表示，并且将其按照每4位（bit）转换为一个１6进制数的方式表示,产生１6进制的字符串。
网上银行使用标准ＭD5withRSA算法对给商户的响应进行签名，产生102４位（bｉt）的签名结果,并且将其按照每4位（bit）转换为一个16进制数的方式表示,形成1６进制的字符串，长度为２5６。
下面是对签名结果的表示方式的描述:
1、对10２4位的交易结果按4位为一个单位进行划分，共获得256段
2、将每段看成一个16进制数,如００11为0Ｘ３，110１为0Xd。
3、将这个数映射到AＳＣIＩ码表,形成相应的字符,如0X2为“２”，０Xd为“d”。
4、将这些字符连成一个字符串，长度为256。
例如：
待签名的字符串为：
ＰOSID=0０0000000＆BRＡNＣHIＤ=110000000＆ORDERＩD＝1999１1０1２34＆PAYMENT=50０.0０&CＵRCODE=01&REＭＡRK1=19991１01&RＥMARK2=meｒchantnamｅ&ＳUCCESS＝Y
签名结果为：
４b３ｅf０2９５１6193b7ｄ９６9ａc18400８３６35a3ｅ0901ｂ8cd526caa４４c１a０72f4９6d7f0d4bca394２ｃ０d９0３0bｅｄe3７ｃ7809b835cec78７eb39ｅ1８b759６ａ724ｆｂa９80５b247１4dｆbb0f4a3ｆｂ４30ｂ３2ｅ075２５4a114d４c38ａ0aｃ５2ef4６a0aｄ33ｄec3fbfc154１74０2a13９９e65ｅ４69９６c０cｆ49fc7ｆｆｃa922２ｆ8cd６93c8３7６b６f92882８967bｅc42
当商户收到银行传来的CGI串后，从中获取签名（格式如上）和需签名的原文。
商户端程序（商户自行开发ＭＤ５wｉｔhＲSＡ签名校验程序）将签名和商户端的公钥转换成二进制格式,与签名的原文一起对签名的正确性进行校验，校验步骤如下:
1）使用公钥进行签名的逆运算
2）使用标准MD5算法运算原文
3）比较1）、２）结果。
ﻩﻩﻩﻩﻩﻩ
升级会员 