PDF《百度钱包》

百度在线网络技术(北京)有限公司 文档名称:百度钱包_付码接入文档 百度钱包 条码付(即时到帐)接入文档 版本号:1.

0.6 百度在线网络技术(北京)有限公司 (版权所有,翻版必究) 百度在线网络技术(北京)有限公司 -

1 - 文档名称:百度钱包_付码接入文档 -

1 - 修改记录 No 版本号 修改内容简介 修改日期 修改人

1 1.0.0 全文 2014-11-18 王宁

2 1.0.1 新增按订单号查询支付结果接口. 2014-01-09 王宁

3 1.0.2 按订单号查询支付结果接口增加百度钱包交易单号 [bfb_order_no]、营销优惠信息[mkt_amount]. 2014-01-26 王宁

4 1.0.3 支付增加多级子商户,支付接口输入参数增加分润类型 [profit_type]、分润方案[profit_solution]. 2015-02-27 王宁

5 1.0.4 支持百度源泉平台权益核销 2015-10-20 王宁

6 1.0.5 增加返现 2015-11-11 王宁

7 1.0.6 增加 5.3 支付结果通知接口 2016-07-18 吕卓林 目录百度钱包付码接入文档

1 1 引言

1 1.1 文档概述

1 1.2 阅读对象

1 2 名词解释

1 3 功能概述

2 百度在线网络技术(北京)有限公司 -

2 - 文档名称:百度钱包_付码接入文档 3.1 即时到账支付

2 3.2 支付结果查询

2 3.3 签名机制

2 4 交互流程

4 4.1 即时到账支付流程

5 4.2 查询支付结果流程

6 5 接口规范

7 5.1 支付接口

8 5.1.1 功能说明

8 5.1.2 接口定义

8 5.1.3 输入参数

8 5.1.4 输出参数

13 5.2 按订单号查询支付结果接口

14 5.2.1 功能说明

14 5.2.2 接口定义

14 5.2.3 输入参数

14 5.2.4 输出参数

15 5.3 支付结果通知接口

15 5.3.1 功能说明

15 5.3.2 接口定义

15 5.3.3 通知参数

16 百度在线网络技术(北京)有限公司 -

3 - 文档名称:百度钱包_付码接入文档

6 注意事项

17 6.1 重复的通知

17 6.2 查单接口

18 6.3 签名字符串和中文编码

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

19 7 附录

19 7.1 响应数据格式列表

19 7.2 字符编码列表

19 7.3 摘要算法列表

19 7.4 币种列表

20 7.5 支付结果列表

20 7.6 参数取值范围

20 7.7 返回编码列表

20 百度在线网络技术(北京)有限公司 第1页共22 页 文档名称:百度钱包_付码接入文档

1 引言 1.1 文档概述 百度钱包企业版提供了对外接口,供第三方商户系统与百度钱包系统进行对接.本文档拟对交互 流程和接口规范进行描述,以指导商户系统开发人员顺利对接. 1.2 阅读对象 1. 接入百度钱包系统的商户系统开发人员 2. 百度钱包的对外接口相关技术人员,包括 SDK 开发和技术支持 请商户系统开发人员注意,本文中 红色黑体 部分是额外需要注意的.如果忽略它们,可能会引 发资金风险.

2 名词解释 名词 解释 对外接口 对外接口是商户系统和百度钱包系统交互的途径和契约,分为两类:服 务接口和通知接口. 服务接口由商户调用,百度钱包负责处理;

通知接口由百度钱包调用, 商户负责处理. 接口的规范包括 URL 和请求参数两部分,详见 接口规范 章节. 百度钱包商户号 百度钱包为接入百度钱包系统的每家商户分配一个独一无二的 ID,作为 商户身份的唯一标识,我们把这个 ID 称为百度钱包商户号. 百度钱包商户号在商户与百度钱包签约时分配. 百度钱包合作密钥 为了保证商户系统和百度钱包系统之间通信的真实性,百度钱包与商户 签 百度在线网络技术(北京)有限公司 第2页共22 页 文档名称:百度钱包_付码接入文档 约时,为每个商户分配一个保密的、独一无二的 key,我们把这个 key 称 为百度钱包合作密钥. 百度钱包合作密钥将用于对通信数据的签名,必须确保只有商户和百度 钱包知道,否则通信数据可能被篡改或伪造.

3 功能概述 3.1 即时到账支付 即时到账支付是这样一个过程:买家在商户提交订单后,来到百度钱包进行付款;

百度钱包在买 家付款成功后立刻将款额打到商户的百度钱包账户. 买家支付成功后,百度钱包会通知商户支付结果.这样,商户就可以及时修改订单的支付状 态. 3.2 支付结果查询 除了百度钱包通知这种方式,商户也可以主动向百度钱包查询订单的支付结果. 3.3 签名机制 由于商户和百度钱包之间的通信涉及到订单信息和支付信息,必须保证通信数据不被篡改和伪 造.否则,将给商户和百度钱包造成资金损失. 百度在线网络技术(北京)有限公司 第3页共22 页 文档名称:百度钱包_付码接入文档 百度钱包采用签名机制来保证通信安全.本文中的每个接口规范都包括两个参数: sign_method 和sign.sign_method 是签名算法,sign 是签名结果.商户或百度钱包向对方发送数据时,必须指 定sign_method 并生成相应的 sign;

对方接收到数据后,必须使用相同的签名算法对 sign 的值进 行验证.如果验证不通过,则说明通信数据已经被篡改或伪造. 百度钱包没有使用 RSA、DSA 等给予非对称密钥的签名算法,而是使用了 MD

5、SHA-1 等摘要 算法.这些算法本身并不能用作签名,但是结合百度钱包合作密钥,也可以起到签名的作用,进 而达到防篡改和伪造的目的. 商户与百度钱包签约时,百度钱包会分配一个百度钱包合作密钥.每个商户的密钥是唯一的,一 定不能让第三方知道.如果密钥泄漏,必须及时通知百度钱包更换密钥. 签名机制包括拼接待签名数据和对待签名数据进行摘要算法两个步骤: 1. 待签名数据由除 sign 之外的所有请求参数和百度钱包合作密钥按以下规则拼接而成: a) 请求参数都按照名称字符升序排列(参数名称不允许相同 ) b) 某些请求参数的值是允许包含中文的,为了避免中文的编码问题,我们规定所有带中文的参 数的值必须按照 input_charset 进行编码(input_charset 的取值目前固定为 1,表示 GBK 编码,详情请参见即时到帐接口规范) c) 对于可选参数(接口规范中的非 必须 参数) ,如果没有使用,则无需参与拼接.这样可以 增强接口参数的可扩展性. d) 将百度钱包合作密钥作为最后一个参数,参数名为 key,参数值就是百度钱包合作密钥本身 e) 将请求参数按上述顺序用&

拼接起来 需要注意的是:在签名时,如果参数的值包括&

、@等 特殊字符或中文,这些字符需要保持原样,不要做 URL 编码.发送 HTTP 请求时,是需要 进行 URL 编码的. 百度在线网络技术(北京)有限公司 第4页共22 页 文档名称:百度钱包_付码接入文档 2. 用指定的摘要算法对待签名数据进行摘要,生成签名数据(不区分大小写) ,作为附加的请求 参数 sign 的值. 下面是一个使用 MD5 算法进行签名的示例: sign = MD5(currency=1&

expire_time=20080908080808&

goods_desc=这是一笔使用百度钱包支付的订单 &

goods_name=商品的名称&

input_charset=1&

order_create_time=20080808080808 &

return_url=http://www.yoursite.com/return_url&

service_code=1&

sign_method=1 &

sp_no=1234567890&

total_amount=1000&

version=2&

key=XXXXXXXXXXXXXXXX) = 0EBBD22EF456D779B21A97482B9D3504 其中,红字部分是按照 GBK 编码后的字符串. 下面解释一下为什么签名之前,需要对中文进行特定的编码. 相同的字符串(包括中文),如果内部编码格式不同,那么对应的字节流可能也不相同.MD5 等摘 要算法是对字节流进行操作的.因此,相同字符串的摘要结果未必相同,取决于内部编码. 商 户和百度钱包必须协商好中文的编码,才能成功验签.如果商户的请求参数中可能包含中文,那 么必须指定 input_charset 参数,并按照 input_charset 进行编码后,才能签名.百度钱包收到请求 数据后,使用相同的编码进行验签.

4 交互流程 在百度钱包对商户提供的服务中,参与交互的角色包括商户系统和百度钱包系统.本章的交互流 程描述了每种服务中,各个角色的职责以及与其他角色的协作关系. 百度在线网络技术(北京)有限公司 第5页共22 页 文档名称:百度钱包_付码接入文档 4.1 即时到账支付流程 百度在线网络技术(北京)有限公司 第6页共22 页 文档名称:百度钱包_付码接入文档 买家在商户收银台付款时,向收银员出示买家在百度钱包的付款码. 商户收银员下单并使用 扫描枪扫描付款码后,商户系统调用百度钱包支付 API 接口发起支付请求. 百度钱包收到即时到账支付请求后,首先验证请求参数(请求参数主要包括商户信息、订单信 息、付款码)的合法性,然后根据请求参数,进行支付受理,并返回支付受理结果.对于同一笔 订单、同一个付款码,重复调用支付 API 接口不会重复扣款,只会返回订单支付结果. 商户对于支付结果的处理:

1、如返回结果为 [0]OK , 商户可以主动通过查单接口查询该交易的支付结果.

2、如返回结果为 [69556]支付中 ,则需要用户在手机端输入手机支付密码确认支付,商户 POS 需要轮询调用查单接口查询订单支付结果.用户验证手机支付密码确认支付的有效时间为

2 分钟,用户超过

2 分钟未支付,则需用户重新生成付款码后,商户重新扫码发起支付请求.

3、如返回结果为其他返回码,则商户直接展示百度钱包的返回信息描述. 支付成功后,百度钱包系统会向商户请求 return_url,支付结果包含在参数中,从而将支付结 果通知给商户;

如商户不使用后台通知的方式,则需要主动通过查单接口查询该交易的支付结 果. 如果通知商户 return_url 失败了,百度钱包系统会重试若干次,以避免掉单现象.需要额外注 意的是:........