在线支付网关接口说明.doc

南京网乐天下购支付网关接口说明Version: 1.0Public date: 2008-09-25All copyright 1. 文档描述1.1 文档说明此文档用来指导银行支付网关开发人员与天下购电子商务支付网关系统的顺利对接。请相关技术人员详细阅读本文档。文中黑粗的内容表示要重点注意的内容。1.2 版本接口基于HTTP协议实现，各种平台，只要支持HTTP协议，各种语言均可实现。1.3 阅读对象天下购开发人员银行支付网关相关技术人员1.5 术语约定缩略语含义商户使用银行在线支付平台进行网上收款的各经营商品或者服务卖家，这里主要指南京网乐信息科技有限公司。商户系统商户的营销管理系统，这里主要指南京网乐旗下的天下购交易平台用户商品或者服务的消费者，买家，这里主要指银行信用卡积分执有者。浏览器WEB浏览器，用来浏览WEB站点。如Internet Exploer银行支付网关银行提供的在线支付平台，主要为银行积分支付平台。通讯密钥银行支付网关与商户系统之间的身份验证密钥，用来验证交易报文的有效性。需要妥善保管。并定期更换。HMAC-MD5HMAC-MD5 是一种秘密的密钥验证算法。HMAC提供的数据完整性和源身份验证完全取决于通讯密钥分配的范围。如果只有发起者和接收者知道HMAC通讯密钥，那么这就对两者之间发送的数据提供了源身份验证和完整性保证。2. 业务功能描述2.1 作业流程简述1) 商户根据用户的支付行为生成订单，包括商户号、订单号、金额、等支付要素，并提交付款请求。（订单付款状态为未付款）2) 用户支付成功以后，银行支付网关使用后台调用方式将支付结果实时通知给商户系统。3) 商户接收到银行支付网关的支付通知请求后，输出反馈信息给银行支付网关，并完成相关业务逻辑。（订单付款状态为已付款）4) 银行支付网关接收到商户返回的成功信息并完成相关业务处理后，再将用户引导回商户网站。（订单付款状态为已结束）2.2 作业流程详述1) 用户在商户系统上选择商品，确认提交订单付款。2) 商户系统根据用户选择商品，生成付款订单，包括商户号、订单信息、订单明细及相关签名信息，并提交到银行支付网关。3) 银行支付网关验证签名数据有效后，检查商户订单号，并向导用户完成支付操作此处由各银行支付网关自由实现(登录，付款)。4) 用户完成支付操作后(冻结金额)，银行支付网关使用后台调用方式将用户付款信息通知给商户系统。通知中包含商户号、付款订单信息、付款订单明细及相关签名信息。其中付款订单允许和商户系统中的订单不一致，因为用户积分可能不足以支付此次订单中的所有商品，所以允许用户在银行支付网关中选择部分商品进行支付。注意商品只能从商户订单中进行选择，且价格等商品信息不能变更。5) 商户系统接收到银行支付网关的支付通知请求后，进行签名验证并处理相关业务逻辑(将定单置为已付款)，处理成功后返回8080此为处理成功后，天下购返回给银行支付网关的识别码信息码，其它结果皆为处理失败，包括无响应。a) 若商户系统未成功处理，则银行支付网关要求根据返回的错误码友好提示用户支付失败(释放冻结金额)，并记录日志。b) 若商户系统无响应，应该记录警报日志，并提示用户支付失败(释放冻结金额)。c) 若商户系统处理成功并返回8080信息码，则银行支付网关提交支付扣款，成功后将用户引导回到商户系统中。6) 商户系统收到引导回的信息，将交易置为结束，提示交易成功页。l 导常状态n 若商户收到银行支付网关的支付信息后，将定单置为已付款，此时出现故障，消息未发送到银行支付网关，银行支付网关将此通知视为无响应处理，直接取消支付。n 银行支付网关提交扣款后出现故障，商户系统未收到引导回的信息，既定单状态为已付款状态，则定单醒目提示，要求人工核对银行账单数据。2.2 接口通知流程1) 返回结果在此通知接口模式中，商户需要确保notify_url（通知回调地址）稳定可靠。在notify_url完成接收并成功处理银行支付网关发送的支付结果信息后，银行支付网关将用户传回至商户系统。银行支付网关只将支付成功的订单进行返回传递。在传送的参数中，包含使用双方约定的MD5密钥签名的sign参数，应该先验证该数字签名，确认该通知信息的合法性。然后完成相关业务逻辑。2) 输出反馈返回8080为成功，其它皆为失败，包括无返回3) 用户返回银行支付网关接收到以上反馈信息后，将引导用户返回至return_url。2.3 安全控制1 银行支付网关采用加密和数字签名认证体系2 通讯使用SSL协议（128位），对数据进行加密3 商户和银行支付网关之间数据交互都使用加密，并使用数字签名进行数据验证，确保数据的完整性。3. 支付请求接口协议3.1 接入URLhttps:/www.*/pay /3.2 接入方式POST方式 3.3 协议参数目的URL/pay/字段名必填类型长度说明version是整数4版本号，取定值1service是整数4服务接口代码，取定值：1charset是整数41：UTF-8编码，默认为UTF-8编码。2：GB2312编码。biz_id是字符串65银行提供的商户号biz_orderid是字符串100商家的定单号，商家内部唯一order_goods是字符串-定单商品明细商品ID商品名称商品数量|商品单价; 商品ID商品名称商品数量|商品单价可以传多个商品，不能包含”%特殊字符order_diff是整数10定单增减金额。单位按需求，积分为个，RMB为分(无小数)无增减额时取定值0order_desc是字符串-交易说明，不能包含”%特殊字符notify_url是字符串255回调通知URL,此字段填写有效回调链接,银行将把交易相关信息通知给此URL return_url是字符串255支付后的商户支付结果展示页面。attach是字符串-该参数不做处理。回调时原样返回。为商户可能的个性化应用预留。sign是字符串32Md5签名信息，签名规则如下。3.4 签名规则对所有请求字段，其值为空的不加入MD5验证对所有请求字段，按字段名的ASCII顺序进行连接，连接方式同URL参数连接方式，使用&key=总是附加在签名串的最后，不参与ASCII排序。MD5的结果转化为小写。4. 通知接口协议4.1 通知url商户提供的notify_url ，当用户付款成功，调用notify_url跳转后，浏览器会把链接导向到return_url，参数与notify_url一致4.2 通知方式POST 方式4.3 协议参数目的URL/pay/notify_url字段名必填类型长度说明version是整数1版本号，取定值1service是整数1服务接口代码，取定值：1charset是整数11：UTF-8编码，默认为UTF-8编码。2：GB2312编码。fee_no是字符串20支付流水号，银行内部唯一2009-07-21 20:44:30 000001日期 时间 自增编号fee_total是整数10付款总额biz_orderid是字符串100商家的定单号，各商家内部唯一order_goods是字符串-定单商品明细商品ID商品名称商品数量|商品单价; 商品ID商品名称商品数量|商品单价可以传多个商品，不能包含”%特殊字符attach是字符串-该参数不做处理。回调时原样返回。为商户可能的个性化应用预留。sign是字符串32Md5签名信息，sign_type=1的签名方法如下：1、 对所有请求字段，其值为空的不加入MD5验证2、 对所有请求字段，按字段名的ASCII顺序进行连接，连接方式同URL参数连接方式。3、 key=总是附加在签名串的最后，不参与ASCII排序。4、 MD5的结果转化为小写。Sign_type是整数1签名(加密)方式，取定值15. 其他5.1 接口联系人职责技术支持姓名卢朝帅电话025 - 8441 8909 - 896E-MQQ1715860985.2 版权说明此文档版权归南京网乐信息科技有限公司（以下简称南京网乐）所有。作为本系统的最终用户，可以拥有该份文档的使用权，但未征得南京网乐的书面批准，不得为任何目的、以任何形式或手段（包括但不限于机械的或电子的）复制或传播本文档的任何部分。对于本文档涉及的技术和产