退款新世界商城与百度合作百度钱包退款接口接入指南2015年

文档名称百度钱包退款接口接入指南

百度钱包退款接口接入指南

文档名称百度钱包退款接口接入指南

文档名称百度钱包退款接口接入指南

文档名称百度钱包退款接口接入指南

目录

百度钱包退款接口接入指南. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1

1引言. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1

1.1文档概述. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1

1.2阅读对象. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1

2名词解释. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1

3功能概述. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1

3.1申请退款. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1

3.2支付结果查询. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1

3.3签名机制. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2

4交互流程. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3

4.1申请退款流程. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3

4.2查询支付结果流程. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3

5接口规范. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4

5.1退款接口. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4

5.2按订单号查询退款结果接口. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6

5.3退款结果通知接口. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9

6注意事项. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10

6.1重复的通知. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10

6.2查单接口. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10

6.3签名字符串和中文编码. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10

6.4百度钱包合作密钥的管理. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11

7附录. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11

7.1 ServiceCode列表. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11

7.2币种列表. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11

7.3摘要算法列表. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11

7.4响应数据格式列表. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11

7.5字符编码列表. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11

7.6退款申请返回码列表. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12

7.7退款查询返回码列表. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12

7.8退款通知返回码列表. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .错误未定义书签。

7.9银行编号列表. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13

文档名称百度钱包退款接口接入指南

1引言

1.1文档概述

百度钱包提供了对外接口供第三方商户系统与百度钱包系统进行对接。本文档拟对交互流程和接口规范进行描述 以指导商户系统开发人员顺利对接。

1.2阅读对象

1. 接入百度钱包系统的商户系统开发人员

2. 百度钱包的对外接口相关技术人员包括SDK开发和技术支持

请商户系统开发人员注意本文中“红色黑体”部分是额外需要注意的。如果忽略它们可能会引发资金风险。

2名词解释

3功能概述

3.1 申请退款

退款是这样一个过程在商户网站提交退款请求后 由百度钱包进行验签验签通过后执行退款

退款成功后百度钱包会通知商户支付结果。这样商户就可以及时修改订单的退款状态。

3.2支付结果查询

除了百度钱包通知这种方式商户也可以主动向百度钱包查询订单的退款结果。

文档名称百度钱包退款接口接入指南

3.3签名机制

由于商户和百度钱包之间的通信涉及到订单信息和支付信息必须保证通信数据不被篡改和伪造。否则将给商户和百度钱包造成资金损失。

百度钱包采用签名机制来保证通信安全。本文中的每个接口规范都包括两个参数 s ign_method和s ign。 s ign_method是摘要算法 s ign是签名结果。商户或百度钱包向对方发送数据时必须指定sign_method并生成相应的s ign对方接收到数据后必须使用相同的签名算法对sign的值进行验证。如果验证不通过则说明通信数据已经被篡改或伪造。

百度钱包没有使用RS A、 D S A等给予非对称密钥的签名算法而是使用了MD 5、 S HA-1等摘要算法。这些摘要算法本身并不能用作签名但是结合百度钱包合作密钥也可以起到签名的作用进而达到防篡改和伪造的目的。

商户与百度钱包签约时百度钱包会分配一个百度钱包合作密钥。每个商户的密钥是唯一的一定不能让第三方知道。如果密钥泄漏必须及时通知百度钱包更换密钥。

签名机制包括拼接待签名数据和对待签名数据进行摘要两个步骤

1. 待签名数据由除sign之外的所有请求参数和百度钱包合作密钥按以下规则拼接而成a) 请求参数都按照名称字符升序排列参数名称不允许相同b) 某些请求参数的值是允许包含中文的为了避免中文的编码问题我们规定所有参数

的值必须按照input_c hars et进行编码input_c hars et的含义请参见即时到帐接口规范c) 对于可选参数接口规范中的非“必须”参数如果没有使用则无需参与拼接。这

样可以增强接口参数的可扩展性。d) 将百度钱包合作密钥作为最后一个参数参数名为k ey参数值就是百度钱包合作密

钥本身e) 将请求参数按上述顺序用&拼接起来

需要注意的是在签名时如果参数的值包括&、@等特殊字符或中文这些字符需要保

持原样不要做URL编码。发送HTTP请求时是需要进行URL编码的。

2. 用指定的摘要算法对待签名数据进行摘要生成签名数据不区分大小写作为附加的请

求参数s ign的值。

下面是一个使用MD 5算法进行签名的示例

下面解释一下为什么签名之前需要对中文进行特定的编码。

相同的字符串(包括中文)如果内部编码格式不同那么对应的字节流可能也不相同。MD 5等摘要算法是对字节流进行操作的。因此相同字符串的摘要结果未必相同取决于内部编码。

商户和百度钱包必须协商好中文的编码才能成功验签。如果商户的请求参数中可能包含中文那么必须指定input_c hars et参数并按照input_c hars et进行编码后才能签名。百度钱包收到请求

文档名称百度钱包退款接口接入指南

4交互流程

在百度钱包对商户提供的服务中参与交互的角色包括商户系统和百度钱包系统。本章的交互流程描述了每种服务中各个角色的职责以及与其他角色的协作关系。

4.1 申请退款流程

商户网站可以提交退款请求到百度钱包百度钱包收到退款请求后首先验证请求参数的合法性然后根据请求参数为指定的交易进行退款操作。退款操作可能不能马上拿到结果 因为某些退银行卡的操作是一个异步的过程需要人为参与。

成功发起退款申请后商户可根据返回结果展示相应的页面退款结果以后台通知或者查询接口查到的结果为准。百度钱包系统会向商户请求r eturn_url退款结果包含在参数中从而将退款结果通知给商户。如果通知失败了百度钱包系统会重试若干次 以避免掉单现象。

需要额外注意的是对于同一笔订单商户网站系统必须能够识别重复的通知并对重复的通知进行除重处理否则就可能因通知多次而引发资金问题。

4.2查询支付结果流程

文档名称百度钱包退款接口接入指南

如果由于种种原因网络问题、商户网站临时维护等百度钱包的通知不能达到商户那么商户就不能及时得到订单的退款状态。这在一定程度上会影响商户网站的用户体验。例如用户申请退款后去商户网站查看订单的支付状态却发现该订单“退款中”。

在这种情况下商户可以主动向百度钱包查询订单的退款结果。 目前百度钱包支持“按退款流水号”的查询条件。

5接口规范

商户网站系统和百度钱包网站系统之间通过http s协议来进行通信接口以UR L的形式提供接口规范就描述了URL及其参数。

本文的接口包括两种服务接口和通知接口。服务接口由百度钱包提供供商户调用通知接口由商户提供供百度钱包调用。虽然通知接口由商户提供但是仍由百度钱包制定接口规范。服务接口包括退款接口、退款结果查询接口通知接口目前仅包括退款结果通知接口。

5.1退款接口

UR L http s://w ww.b aifub ao.c om/ap i/0/refund

请求方式 GET

请求参数

文档名称百度钱包退款接口接入指南

响应数据

示例

商户的请求参数(忽略部分可选参数)

参数名 参数值 参数值的说明s ervic表示退款inp usigsig

version 2 版本号是2