《布优API点卡接口说明文档.doc》由会员分享，可在线阅读，更多相关《布优API点卡接口说明文档.doc（11页珍藏版）》请在taowenge.com淘文阁网|工程机械CAD图纸|机械工程制图|CAD装配图下载|SolidWorks_CaTia_CAD_UG_PROE_设计图分享下载上搜索。
1、布优API点卡接口开发指南商户接口规范版本(2.0.0)目录第一章文档描述31、文档说明32、阅读对象3第二章系统原理31、术语定义32、消费流程43、查询流程54、系统加密6第三章点卡接口定义61、同步过程接口定义（商户系统发起请求）62、下行异步通知过程接口定义（布优接口发起请求）8附录 1：布优支付接口卡类型说明9第一章 文档描述1、 文档说明本说明文档用于指导布优API商户实现与布优API点卡接口的顺利对接。请相关技术人员详细阅读本文档。2、 阅读对象商户开发人员。四川布优网络科技限公司布优API点卡接口相关技术人员。第二章 系统原理1、 术语定义商户：指已独立拥有在线销售系统，并成为
2、布优API点卡接口系统会员，且已使用或者将使用布优API点卡接口实现收付费或其他相关功能需求的企业或者个人。外部接入接口：指布优API通过统一的方式接受外部请求的接口。商户系统：指使用布优API外部接入接口的计算机系统，一般指商户所拥有的在线销售系统。用户：指在商户系统内进行消费的企业或者个人。商户ID： 指布优API为使用外部接入接口的商户统一分配的唯一标识。商户密钥：指商户在和布优API确定合作意向时布优API为商户提供的16 位字符串。该信息作为商户系统和布优API交互时身份确认的依据，需商户妥善保管。2、 消费流程一般地，在商户系统进行消费时，用户需要向商户支付一定的相关费用。在集成了
3、布优销卡接口后，布优销卡将为商户提供方便的收付费服务。用户在商户系统发起消费请求后，商户系统和布优销卡卡类接口系统（简写为布优接口）的交互流程如下图：图1 商户系统和布优接口交互流程具体地，用户的一次消费中，商户系统和布优接口之间会发生2 次直接交互过程。1、同步过程用户在商户系统选择产品或服务，填写订单（如用户选择卡面值、输入卡号、密码等）后，商户系统将用户填写的信息（如卡号、密码、类型、商户系统订单号等）以及相应的参数（如订单金额、商户ID 和密钥、异步通知地址等信息）组织为订单信息，通过http get/post方式提交到布优接口，该过程如图1箭头1所示。当商户系统提交订单到布优接口时，
4、布优接口将同步返回数据给商户系统。商户系统根据该同步返回结果判断订单是否成功提交到布优接口。若订单提交成功，商户系统需等待布优接口的异步通知结果。注意，在收到异步结果之前，商户系统不能对系统内的订单进行成功或者失败处理。若订单提交失败，商户系统需将系统内订单做失败处理。该过程如图1箭头2所示。2、异步过程布优接口将订单处理完成后会异步通知商户系统订单处理结果（通过http get 方式），商户系统需要先验证返回结果的合法性，并根据合法的异步通知的结果，对商户系统的订单进行操作。若异步通知返回充值成功，则商户系统可对订单进行成功操作。注意，实际的订单金额可能和用户提交的订单金额不一致，商户系统必
5、须以布优接口异步通知返回的订单实际金额为准。若异步通知返回充值失败，则商户系统可对订单进行失败操作。该过程如图1箭头4 所示。商户系统在成功接收布优接口异步通知的订单结果后，需同步返回1个结果“ok”（页面内不能有其他的任何代码）给布优接口（不论订单结果成功与否），当布优接口收到该结果“ok”后便不再通知商户系统，否则布优接口将根据同商户的约定重复通知商户系统。该过程如图1箭头5所示。如果商户系统将订单成功提交到布优接口后，未收到布优接口的异步通知结果，商户可登陆布优接口商户系统手动重发订单结果通知。需特别注意，当未收到布优接口异步通知结果时，商户系统不能对订单状态进行任何操作，否则造成的损失
6、商户自己承担。3、 查询流程在商户系统将订单成功提交给布优接口后的任意时间，商户系统可发起请求查询订单的处理结果。该流程由商户系统发起，由接口返回相应结果。4、 系统加密布优API采用MD5 加密方式对传输数据进行签名验证，具体请参考相关接口定义。对MD5 加密后的签名值，请注意结果的大小写务必正确。为了确保签名值不是因为MD5 加密算法而导致结果不正确，请各商户在调用接口前对字符串abcdefghijklmnopqrstuvwxyz 使用MD5 加密算法进行加密，若加密结果为928f7bcdcd08869cc44c1bf24e7abec6 则表示MD5 加密正常。第三章 点卡接口定义1、 同
7、步过程接口定义（商户系统发起请求）接入URL： 1、 (最新地址)2、 接入方式：GET 方式3、 请求协议参数：表1 同步过程请求协议参数说明参数名参数可空加入签名说明商户IDpartnerNY商户id,由布优API分配卡类型cardtypeNY卡类型，具体参考附录1卡号cardnoNY卡号密码cardpwdNY密码金额paymoneyNY单位元（人民币），无小数商户订单号ordernumberNY商户系统订单号，该订单号将作为布优接口的返回数据。该值需在商户系统内唯一，布优系统暂时不检查该值是否唯一下行异步通知地址callbackurlNY下行异步通知的地址，需要以http:/开头且没有任
8、何参数备注信息attachYN备注信息，下行中会原样返回。若该值包含中文，请注意编码MD5签名signNN32位小写MD5签名值，GB2312编码4、 返回协议参数参数名参数说明操作结果状态状态结果中文说明，详情参见附录25、 MD5签名说明：待签名数据为表1 中加入签名列值为Y 的参数以及商户密钥，签名顺序为表1 中partner到callbackurl 的顺序加商户密钥。具体MD5 签名源串及格式如下：partner=&cardtype=&cardno=&cardpwd=&paymoney=&ordernumber=&callbackurl=key其中，key为商户签名。6、 接入实例：（
9、假设商户 Id 为 10000，商户密钥为 4272fafab8869dbd292d959bc） 请求提交方法：实际进行 MD5 加密的串是partner=10000&cardtype=JUNNET&cardno=&cardpwd=&paymoney=100.00&orderid=&callbackurl=该串 MD5 加密结果为 a628a914bb149d6e0fc47e5977c476037、 注意事项：1）商户系统在提交订单时，需在程序内部模拟发起订单的http 请求，并且获取同步返回结果。用户在商户平台上进行消费均在商户系统上实现，页面无需跳转到布优接口。2）若商户系统订单提交不成功
10、，请联系布优商务检查在布优接口内，商户是否开通了相应权限。3）订单提交成功，并不是订单充值已经成功，是指布优接口已经成功接收到商户系统的订单(卡号密码面值等信息)，商户系统需要等待订单异步通知结果，即下行过程。4）根据HTTP 协议要求，提交参数的值中若存在特殊字符（如：空格、等）时，为使布优接口能接收到正确的参数，这些特殊字符需要做URL Encoding。需特别注意的是，此时待签名数据应该是原生值而不是encoding 之后的值。2、 下行异步通知过程接口定义（布优接口发起请求）1、 接入URL：过程1 中请求参数 callbackurl 值2、 接入方式：GET 方式3、 请求协议参数：
11、表 2 下行过程请求协议参数说明参数名参数加入签名说明商户IDpartnerY商户id,由布优API分配商户订单号ordernumbery上行过程中商户系统传入的ordernumber订单结果orderstatusY状态结果中文说明，详情参见附录3订单金额paymoneyY单位元（人民币）布优订单号sysnumberN此次交易中布优接口系统内的订单ID备注信息attachN备注信息，上行中attach原样返回订单结果中文说明msgN状态结果中文说明，详情参见附录2MD5签名signN32位小写MD5签名值，GB2312编码4、 MD5签名说明：待签名数据为表2中加入签名列值为Y的参数以及商户密
12、钥，签名顺序为表2中partner到paymoney的顺序加商户密钥。具体 MD5 签名源串及格式如下：partner=&ordernumber=&orderstatus=&paymoney=key其中,key为商户签名5、 特别说明： 下行异步通知过程在整个支付流程中一定存在。商户系统在收到下行通知过程后， 需向布优接口返回“ok”。布优接口根据该返回值判断商户系统是否已经收到结果。若返回结果不是“ok”，布优接口会根据商家和布优接口的约定，再次反复向 callbackurl 发送结果，直到商户返回“ok”或者达到和商户约定的重复发送次数。 当布优接口在下行异步通知过程中返回在线支付结果时，
13、商户系统在收到数据后， 应该通过sign值判断是否是有效的返回数据，防止数据在网络传输过程中被恶意篡改。6、 注意事项 在收到布优接口订单下行异步通知结果时，商户系统需首先验证订单通知的合法性， 如果不合法，则不要更新商户系统上的订单状态。 商户系统内订单状态和订单实际金额务必以此次布优接口订单异步通知的结果为准。 商户系统在成功提交订单后，在未没有收到布优接口异步通知结果时，请不要更新商户系统上的订单状态 在下行异步通知过程中商户系统返回结果值“ok”回布优接口时，“ok”并不是将布优接口在下行异步通知的结果原样返回。商户系统返回值“ok”时表示商户系统已经成功接收到了结果（不论结果是什么，
14、总之是收到了），而其他值表示因为某些原因商户系统并不认为布优接口的返回是有效的。布优接口在收到商户系统的返回后，如果返回的值为“ok”布优接口将不再次发送结果，否则布优接口会根据布优接口同商户的约定 再次发送结果。附录 1：布优支付接口卡类型说明银行编码银行名称JUNNET骏网一卡通SNDA盛大卡SZX神州行ZHENGTU征途卡QQCARDQQ卡UNICOM联通卡JIUYOU久游卡NETEASE网易卡WANMEI完美卡SOHU搜狐卡TELECOM电信卡ZONGYOU纵游一卡通TIANXIA天下一卡通TIANHONG天宏一卡通SFTCARD盛付通卡SECARD32卡附录 2：布优支付点卡接口返回
15、状态说明状态码状态码说明1提交成功，下行为1时则为销卡成功1000参数不完整1001商户没通过审核1002订单号重复1003MD5签名不正确1004商户支付帐户没有通过审核1005上级商户支付帐户没有通过审核1006系统关闭了该类卡支付1007卡片或面值类型不正确1008商户没有开通该支付接口1009卡号和密码不符合规范1010系统繁忙稍后重试1011卡号过期1012卡余额不足1013卡号被冻结1014卡未激活2000卡片信息不完整2001请正确请填写卡号密码2002不支持的卡片类型编码2003卡片类型和面值类型不符2004您提交的卡号或密码有误2005您的卡号密码已使用2006其他(卡片或面值类型不正确)2007系统正在维护中2008此卡系统已受理，正在处理中，请勿重复提交2009您的卡号密码重复使用2010该卡已超过系统规定的失败次数2011系统检测到您操作过于频繁，请核对后重试2012你的参数提交非法，请勿越权使用！3000系统不能受理的卡3001系统检测到您的访问IP非法！3002系统检测不到您的访问IP！3005订单号不存在