省号百平台支付接口技术规范-V10

【WEB网上号百技术接口规范】V1.02011年6月湖北公众目录1.文档说明 31.1文档目标 31.2阅读对象 31.3相关约定 31.4业务及技术支持 32.业务描述及接口开发 32.1功能说明及流程 32.2商户接入前提 42.3参数说明 52.3.1 HTTP订单支付请求接口 52.3.2退款接口 52.4开发提示 52.4.1商户对支付结果的处理 53.参考资料 53.1出参类型说明 51.文档说明1.1文档目标本文档的目的是为WEB网上支付定义一个标准接口规范，以帮助各省号百及合作商户技术人员接入号百网上支付，并快速掌握号百网上支付相关功能，为业务开展提供支付服务。1.2阅读对象对号百网上支付存在需求的公司、机构及合作商户的网上应用开发人员、维护人员和业务管理人员。1.3相关约定商户：指已注册成为号百用户、并使用号百产品实现其收付费功能需求、为其用户提供各类产品或者相关服务的个人。用户：指在商户网站等系统购物的个人。购物：指用户在商户网站购买相关产品或服务。1.4业务及技术支持如果您有任何业务及技术上的疑问，可联系省号百技术人员。2.业务描述及接口开发2.1功能说明及流程WEB网上支付方式是指利用网银账户，通过互联网Web网页操作完成支付过程的方式。此种方式下，客户利用PC终端，通过登陆号百或合作方网站，进行商品或服务选购，生成并确认订单信息，根据本人使用借记卡或贷记卡付款的要求，选择相应银行通过银行网银界面实现支付的功能。用户向交易网站购物时，需要通过一定方式向商户支付相关费用。商户网站系统如果集成号百网上支付功能，则可以让用户安全、方便、快捷地向商户支付选购商品及服务款项，并且商户也可以很容易了解到款项的到帐情况及用户购买的产品或服务。整体流程如下：用户在商户交易网站选择产品或服务，在下订单支付完成后，商户网站会将该订单号及对应订单金额等相关信息提交到号百，然后跳转到号百页面进行支付。当支付完成后，号百将支付结果返回商户，并且根据商户指定的地址跳转到商户指定页面。商户系统后台接收到支付结果之后，对数据库进行相应更新，然后在显示给用户的页面中作出相应提示。2.2商户接入前提商户接入号百平台网上支付，须准备好指定网站供客户上网浏览，并为用户提供商品查询、选购，直至下单的功能及页面展示。以下页面须由商户预先实现方能进行号百网上支付接入，参考图示如下：2.3参数说明2.3.1 HTTP订单支付请求接口http订单支付请求地址：/serviceInterface/do.aspx接口描述接口名称重定向跳转订单支付请求接口接口描述通过调用支付接口向号百平台发出支付请求,平台通过支付Portal与用户进行交互，完成支付处理后，重定向回应用系统（SP）接口提供者号百平台接口使用者应用系统（SP）接口定义应用系统的请求参数定义：字段名称长度是否必填说明BSTMERCHANTIDSP身份标识CHAR(30)是由号百平台统一分配ORDERSEQ订单号CHAR(30)是由SP提供，在sp处不能重复，用于标识一个唯一的订单，订单号可以在没有支付成功的情况下，再次进行交易，但每次交易时的订单请求交易流水号不能重复数字或字母组成ORDERREQTRANSEQ订单请求交易流水号CHAR(30)是订单支付请求的交易流水号每次订单支付时，不要重复以日期时间yyyyMMddHHmmssff+号百平台商户代码（由号百平台提供），如：200610121324253500012006101213242535为日期时间0001为号百给定的商户代码数字或字母组成ORDERDATE订单日期CHAR(8)是由SP提供，长度8yyyy-MM-dd格式ORDERAMOUNT订单总金额NUMBER(10)是单位：分订单总金额=产品金额+附加金额PRODUCTAMOUNT产品金额NUMBER(10)是单位：分ATTACHAMOUNT附加金额NUMBER(10)是单位：分VIEWURL前台返回地址CHAR(256)是SP提供的用于接收交易返回的前台url，不做业务处理，仅仅用于前台页面显示结果DEALURL后台返回地址CHAR(256)是SP提供的用于接收交易返回的后台url，用于实际的业务处理USERIDSP用户IDCHAR(40)是SP平台用户ID，为SP平台用户体系的唯一标识。REMARK备注CHAR(256)是SP平台提供对本次订单的描述如：“充值”或“购买了一张电影票”ATTACH附加信息CHAR(50)否SP附加信息MACMAC校验域CHAR(256)是采用标准的MD5算法，由SP实现说明：1）商户要保证订单号的唯一性。2）在商户提交订单的页面上，提交按钮应该是点击一次后，马上不可用，防止用户多次提交。3）接口方式采用表单方式，商户将以上信息包含在表单中，直接SUBMIT到号百平台url上4）MAC校验，保证了交易信息到支付平台的完整性，参与MAC运算的字符及其顺序如下：BSTMERCHANTID=123456789&ORDERSEQ=20060314000001&ORDERDATE=20060314&ORDERAMOUNT=10000将上述固定顺序组织的字符串，参数名均为大写，使用标准md5算法进行摘要，然后将摘要果转成16进制字符串，就是校验域MAC的值，并在提交订单时，将MAC值和订单信息一起提交到号百平台号百平台的响应参数定义：字段名称类型是否必填说明BSTUPTRANSEQ号百平台交易流水号CHAR(50)是由号百平台提供，SP必须保存该信息，作为对帐依据BSTTRANDATE号百平台交易日期CHAR(8)是由号百平台提供，SP必须保存该信息，格式：yyyy-MM-dd,商户对账、清算报表以此日期为准RETNCODE处理结果码CHAR(4)是由号百平台统一定义，SP需保存，作为对帐数据。结果码为“0000”表示支付成功，其他值则表示支付失败RETNINFO处理结果解释码CHAR(10)是由号百平台统一定义，对支付结果的说明码ORDERREQTRANSEQ订单请求交易流水号CHAR(32)是从SP发送的订单的信息中获得，号百平台原值传回ORDERSEQ订单号CHAR(32)是从SP发送的订单的信息中获得，号百平台原值传回ORDERAMOUNT订单总金额NUMBER(10)是从SP发送的订单的信息中获得，号百平台原值传回，单位：分订单总金额=产品金额+附加金额PRODUCTAMOUNT产品金额NUMBER(10)是从SP发送的订单的信息中获得，号百平台原值传回，单位：分ATTACHAMOUNT附加金额NUMBER(10)是从SP发送的订单的信息中获得，号百平台原值传回，单位：分USERIDSP用户IDCHAR(40)是SP平台用户ID，为SP平台用户体系的唯一标识。号百平台原值传回ATTACHSP附加信息CHAR(32)否从SP发送的订单的信息中获得，号百平台原值传回SIGN数字签名CHAR(256)是数字签名算法由号百平台统一提供，作为核查依据说明：商户提供的后台url，号百平台是以post方式将支付结果提交到该url上商户平台在收到后台支付结果后，请直接在应答时写入格式为UPTRANSEQ_XXXXXX的字符串，其中UPTRANSEQ_为固定写死，XXXXXX为号百平台发送过去的号百平台交易流水号号百平台，如果在60秒钟没有收到应答，则会重复发送，重复次数是3次，如果还没有应答会每隔半小时发送一次截止到第二天凌晨。号百平台如果收到应答，则不再发送支付结果。当商户收到号百平台发回来的支付结果信息后，获取支付结果和签名的信息，然后对数字签名进行校验，步骤如下：1）商户将支付结果的明文和密钥组成一个固定顺序的串，如下：BSTUPTRANSEQ=20080101000001&BSTMERCHANTID=0250000001&ORDERSEQ=2006050112564931556&ORDERAMOUNT=10000&RETNCODE=0000&RETNINFO=0000&BSTTRANDATE=20060101&KEY=123456串的顺序不能改变，参数名一定要用大写；KEY的值由号百平台统一提供。2）将1）获得的结果使用标准的MD5算法运算，再将运算结果转成16进制字符串；3）将2）获得值和SIGN值进行比较，如一致则数字签名正确，说明信息没有被篡改。2.3.2退款接口Webservices接口地址：/services方法名：Stringrefund()号百支付平台对调用该接口的服务器地址进行绑定，在联调前，请提供服务器地址。请求入参说明：参数含义类型长度必填备注commCode商户代码xsd:string20是由号百平台统一分配给各接入商户subCommCode商户子代码xsd:string30否商户子代码如没有则填空commPwd商户调用密码xsd:string20是商户执行时需填入相应密码oldOrderId原扣款订单号xsd:string30是原扣款成功的订单号oldOrderPayId原订单请求支付流水号xsd:string30是原订单请求支付流水号orderRefundId退款流水号xsd:string30是该流水在商户处必须是唯一的，而且每次发起支付或退款时，都必须是唯一的transamt订单交易金额xsd:string12是单位为元如2.00reqTime交易请求时间xsd:string14是YYYYMMDDHHMMSSmacMac校验域xsd:string32是md5摘要为什么支付时交易金额单位是分，而在退款时时以元为单位？能否统一？方法返回参数类型长度必填备注xsd:String20是具体见出参类型说明返回成功即表示退款成功说明：1）商户要保证退款流水号的唯一性。2）在商户提交退款时，防止多次提交同一笔退款。3）接口方式采用webservices方式，key由号百支付平台分配给各商户。4）MAC校验，保证了交易信息到支付平台的完整性，参与MAC运算的字符及其顺序如下：COMMCODE=123456789&COMMPWD=123456&ORDERREFUNDID=20080314000001&REQTIME=20080314&TRANSAMT=10000&KEY=DJKF34ER35D58D商户平台将上述固定顺序组织的字符串，参数名均为大写，使用标准md5算法进行摘要，然后将摘要果转成16进制字符串，就是校验域MAC的值，将MAC值和订单信息调用接口时，一起提供给号百支付平台附：MD5算法的.net实现：///<summary>///MD5加¨®密¨¹///</summary>///<paramname="str">加¨®密¨¹字Á?符¤?</param>///<returns></returns>privatestringmd5(stringstr){returnSystem.Web.Security.FormsAuthentication.HashPasswordForStoringInConfigFile(str,"MD5");}上述算法如果在实施时遇到具体问题，可以协商解决。2.4开发提示2.4.1商户对支付结果的处理商户在接收到号百的支付结果之后，基于安全的考虑，请务必要判断同一订单号是否已经针对支付成功的情况进行过处理。特别是对于一些使用号百提供充值功能的商户，必须严格防止对同一订单对用户多次进行充值。如果同一订单号，已经按照支付成功的情况进行过处理，商户再次接收到时则不要重复处理。因网络或银行服务器原因，号百可能第一次发送支付失败的结果给商户，但后来会对同一订单号发送支付成功的信息给商户。商户应在保证对加密验证串等信息严格验证的前提下，对相同订单号按照支付成功的业务逻辑进行处理。即商户收到的支付结果通知有失败也有成功，以成功信息为准进行支付成功相关业务处理。可能会由于网络或者用户刷新页面的原因，商户的页面可能短时间内会多次接收到支付结果信息，而支付人看到的只能是最后的页面。商户最好能在后续的提示中，给出让支付人不易误解的提示信息。3.参考资料3.1出参类型说明0本次调用成功0000本次调用成功1001商户未注册1002商户已注册，但未审批1003商户已注册，已审批，但未开通1004商户已注销1005商户原自助服务用户密码错误1006商户已注册，但未开通此业务1007商户已注册，但未开通此接入方式1101订单正在交易中，不允许再次交易1102订单交易成功，不允许再次交易1103订单交易