百度钱包v3-api接口文档

byds520

贡献于2017-02-22

字数:15825 关键词:

文档名称:百度钱包企业版商户系统接入指南V2 百度钱包企业版商户系统接入指南V3 模块名称 百度钱包商户系统接入指南V2 所属系统 百度钱包企业版 模块负责人 王金磊 项目负责人 逄胜东 文档提交日期 2013-01-11 百度在线网络技术(北京)有限公司 (版权所有,翻版必究) 百度在线网络技术(北京)有限公司 - - 文档名称:百度钱包企业版商户系统接入指南V2 目 录 百度钱包企业版商户系统接入指南V3 1 1 引言 1 1.1 文档概述 1 1.2 阅读对象 1 2 名词解释 1 3 功能概述 1 3.1 即时到账支付 1 3.2 支付结果查询 2 3.3 签名机制 2 4 交互流程 3 4.1 即时到账支付流程 3 4.2 查询支付结果流程 4 5 接口规范 4 5.1 即时到账支付接口(不要求登录百度钱包) 4 5.2 即时到账支付接口(要求登录百度钱包) 7 5.3 按订单号查询支付结果接口 7 5.4 支付结果通知接口 10 6 注意事项 12 6.1 重复的通知 12 6.2 前台通知 12 6.3 查单接口 12 6.4 签名字符串和中文编码 12 6.5 百度钱包合作密钥的管理 13 7 附录 13 7.1 ServiceCode列表 13 7.2 币种列表 13 7.3 即时到帐接口中支付方式列表 13 7.4 查单接口和通知接口中支付方式列表 14 7.5 摘要算法列表 14 7.6 支付结果列表 14 7.7 响应数据格式列表 14 7.8 字符编码列表 14 7.9 订单查询错误码列表 14 7.10 银行编号列表 14 百度在线网络技术(北京)有限公司 - - 文档名称:百度钱包企业版商户系统接入指南V2 1 引言 1.1 文档概述 百度钱包企业版提供了对外接口,供第三方商户系统与百度钱包系统进行对接。本文档拟对交互流程和接口规范进行描述,以指导商户系统开发人员顺利对接。 1.2 阅读对象 1. 接入百度钱包系统的商户系统开发人员 2. 百度钱包的对外接口相关技术人员,包括SDK开发和技术支持 请商户系统开发人员注意,本文中“红色黑体”部分是额外需要注意的。如果忽略它们,可能会引发资金风险。 2 名词解释 名称 解释 对外接口 对外接口是商户系统和百度钱包系统交互的途径和契约,分为两类:服务接口和通知接口。 服务接口由商户调用,百度钱包负责处理;通知接口由百度钱包调用,商户负责处理。 接口的规范包括URL和请求参数两部分,详见“接口规范”章节。 百度钱包商户号 百度钱包为接入百度钱包系统的每家商户分配一个独一无二的ID,作为商户身份的唯一标识,我们把这个ID称为百度钱包商户号。 百度钱包商户号在商户与百度钱包签约时分配。 百度钱包合作密钥 为了保证商户系统和百度钱包系统之间通信的真实性,百度钱包与商户签约时,为每个商户分配一个保密的、独一无二的key,我们把这个key称为百度钱包合作密钥。 百度钱包合作密钥将用于对通信数据的签名,必须确保只有商户和百度钱包知道,否则通信数据可能被篡改或伪造。 3 功能概述 3.1 即时到账支付 即时到账支付是这样一个过程:买家在商户网站提交订单后,来到百度钱包进行付款;百度钱包在买家付款成功后立刻将款额打到商户的百度钱包账户。 买家支付成功后,百度钱包会通知商户支付结果。这样,商户就可以及时修改订单的支付状态。 百度在线网络技术(北京)有限公司 第 页 共 16 页 文档名称:百度钱包企业版商户系统接入指南V2 3.2 支付结果查询 除了百度钱包通知这种方式,商户也可以主动向百度钱包查询订单的支付结果。 3.3 签名机制 由于商户和百度钱包之间的通信涉及到订单信息和支付信息,必须保证通信数据不被篡改和伪造。否则,将给商户和百度钱包造成资金损失。 百度钱包采用签名机制来保证通信安全。本文中的每个接口规范都包括两个参数:sign_method和sign。sign_method是摘要算法,sign是签名结果。商户或百度钱包向对方发送数据时,必须指定sign_method并生成相应的sign;对方接收到数据后,必须使用相同的签名算法对sign的值进行验证。如果验证不通过,则说明通信数据已经被篡改或伪造。 百度钱包没有使用RSA、DSA等给予非对称密钥的签名算法,而是使用了MD5、SHA-1等摘要算法。这些摘要算法本身并不能用作签名,但是结合百度钱包合作密钥,也可以起到签名的作用,进而达到防篡改和伪造的目的。 商户与百度钱包签约时,百度钱包会分配一个百度钱包合作密钥。每个商户的密钥是唯一的,一定不能让第三方知道。如果密钥泄漏,必须及时通知百度钱包更换密钥。 签名机制包括拼接待签名数据和对待签名数据进行摘要两个步骤: 1. 待签名数据由除sign之外的所有请求参数和百度钱包合作密钥按以下规则拼接而成: a) 请求参数都按照名称字符升序排列(参数名称不允许相同 ) b) 某些请求参数的值是允许包含中文的,为了避免中文的编码问题,我们规定所有参数的值必须按照input_charset进行编码(input_charset的含义请参见即时到帐接口规范) c) 对于可选参数(接口规范中的非“必须”参数),如果没有使用,则无需参与拼接。这样可以增强接口参数的可扩展性。 d) 将百度钱包合作密钥作为最后一个参数,参数名为key,参数值就是百度钱包合作密钥本身 e) 将请求参数按上述顺序用&拼接起来 需要注意的是:在签名时,如果参数的值包括&、@等特殊字符或中文,这些字符需要保持原样,不要做URL编码。发送HTTP请求时,是需要进行URL编码的。 2. 用指定的摘要算法对待签名数据进行摘要,生成签名数据(不区分大小写),作为附加的请求参数sign的值。 下面是一个使用MD5算法进行签名的示例: sign = MD5(currency=1&extra=&goods_desc=使用百度钱包支付的订单&goods_url= &goods_category=1&input_charset=1&order_create_time=20080808080808&order_no=20080808123456123456&pay_type=1&return_url=http://127.0.0.1/return_url&service_code=1&sign_method=1&sp_no=1234567890&total_amount=2500&transport_amount=500&unit_amount=1000&unit_count=2&key=XXXXXXXXXXXXXXXX) 百度在线网络技术(北京)有限公司 第 页 共 16 页 文档名称:百度钱包企业版商户系统接入指南V2 = 39375042FD5F801C2B0A128B145589C3 其中,goods_desc的值(红字部分)应该是按照input_charset编码后的结果。 下面解释一下为什么签名之前,需要对中文进行特定的编码。 相同的字符串(包括中文),如果内部编码格式不同,那么对应的字节流可能也不相同。MD5等摘要算法是对字节流进行操作的。因此,相同字符串的摘要结果未必相同,取决于内部编码。 商户和百度钱包必须协商好中文的编码,才能成功验签。如果商户的请求参数中可能包含中文,那么必须指定input_charset参数,并按照input_charset进行编码后,才能签名。百度钱包收到请求数据后,使用相同的编码进行验签。 4 交互流程 在百度钱包对商户提供的服务中,参与交互的角色包括商户系统和百度钱包系统。本章的交互流程描述了每种服务中,各个角色的职责以及与其他角色的协作关系。 4.1 即时到账支付流程 买家向商户网站提交订单请求后,商户网站生成“去百度钱包支付”的链接或表单。用户点击链接或提交表单后直接来到百度钱包网站进行支付。 百度钱包收到即时到账支付请求后,首先验证请求参数的合法性,然后根据请求参数,展现相应的支付页面。支付页面显示的内容主要包括商户信息、订单信息、支付信息。 买家成功完成支付后,百度钱包网站系统将买家重定向到请求参数中的page_url上(page_url的含义参见“即时到帐支付接口规范”)。同时,百度钱包系统会向商户请求return_url,支付结果包含在参数中,从而将支付结果通知给商户。如果通知失败了,百度钱包系统会重试若干次,以避免掉单现象。 需要额外注意的是:对于同一笔订单,商户网站系统必须能够识别重复的通知,并对重复的通知进行除重处理,否则就可能因通知多次而引发资金问题。 百度在线网络技术(北京)有限公司 第 页 共 16 页 文档名称:百度钱包企业版商户系统接入指南V2 Page_url的值由商户定义,百度钱包会将支付结果作为page_url的参数。因此,page_url也可以起到通知支付结果的作用,我们称之为前台通知。而return_url的作用则是后台通知。前台通知和后台通知可能在同一时间到达商户系统。如果商户系统不能处理这种并发通知,则需要注意,不要将page_url作为接受通知的地址。 4.2 查询支付结果流程 如果由于种种原因(网络问题、商户网站临时维护等)百度钱包的通知不能达到商户,那么商户就不能及时得到订单的支付状态。这在一定程度上会影响商户网站的用户体验。例如,用户支付成功后,去商户网站查看订单的支付状态,却发现该订单“尚未支付”。 在这种情况下,商户可以主动向百度钱包查询订单的支付结果。目前,百度钱包只支持“按订单号”的查询条件。 5 接口规范 商户网站系统和百度钱包网站系统之间通过http协议来进行通信,接口以URL的形式提供,接口规范就描述了URL及其参数。 本文的接口包括两种:服务接口和通知接口。服务接口由百度钱包提供,供商户调用;通知接口由商户提供,供百度钱包调用。虽然通知接口由商户提供,但是仍由百度钱包制定接口规范。服务接口包括即时到账支付接口、按订单号查询支付结果接口;通知接口目前仅包括支付结果通知接口。 5.1 即时到账支付接口(不要求登录百度钱包) URL:https://wallet.baidu.com/api/0/pay/0/direct 请求方式:GET 请求参数: 百度在线网络技术(北京)有限公司 第 页 共 16 页 文档名称:百度钱包企业版商户系统接入指南V2 参数名 参数含义 格式说明 是否必须 service_code 服务编号 整数,目前必须为1 是 sp_no 百度钱包商户号 10位数字组成的字符串 是 order_create_time 创建订单的时间 YYYYMMDDHHMMSS 是 order_no 订单号,商户须保证订单号在商户系统内部唯一。 不超过20个字符 是 goods_category 商品分类号。 与优惠券相关。 在创建优惠券推广计划的时候,可以指定优惠券使用的商品类型。 若订单的类型与优化券的类型一致时,就会出相应的优惠券。 没有指定时,出用户可用的全部优惠券 取值由钱包系统分配 否 goods_name 商品的名称 允许包含中文;不超过128个字符或64个汉字 是 goods_desc 商品的描述信息 允许包含中文;不超过255个字符或127个汉字 否 goods_url 商品在商户网站上的URL。 URL 否 unit_amount 商品单价,以分为单位 非负整数 否 unit_count 商品数量 非负整数 否 transport_amount 运费 非负整数 否 total_amount 总金额,以分为单位 非负整数 是 currency 币种,默认人民币 取值范围参见附录 是 buyer_sp_username 买家在商户网站的用户名 允许包含中文;不超过64字符或32个汉字 否 return_url 百度钱包主动通知商户支付结果的URL 仅支持http(s)的URL。 是 page_url 用户点击该URL可以返回到商户网站;该URL也可以起到通知支付结果的作用 仅支持http(s)的URL。 否 pay_type 默认支付方式 取值范围参见附录 是 bank_no 网银支付或银行网关支付时,默认银行的编码 取值范围参见附录 否;如果pay_type是银行网关支付,则必须有值。 expire_time 交易的超时时间 YYYYMMDDHHMMSS,不得早于交易创建的时间。 否 input_charset 请求参数的字符编码 取值范围参见附录 是 百度在线网络技术(北京)有限公司 第 页 共 16 页 文档名称:百度钱包企业版商户系统接入指南V2 version 接口的版本号 必须为2 是 sign 签名结果 取决于签名方法 是 sign_method 签名方法 取值范围参见附录 是 extra 商户自定义数据 不超过255个字符 否 说明: 1. 商户通过调用该接口来请求对订单的支付。一次调用只能处理一笔订单,但是一笔订单可以包括多个商品。如果只有1个商品,那么goods_desc和goods_url可以使该商品的名称和展现URL;如果包括多个商品,那么goods_desc和goods_url不可能与每个商品一一对应,具体内容由商户定义。 2. 该接口“可能包含中文”的参数包括:goods_name、goods_desc、buyer_sp_username,因此指定了input_charset参数。这三个参数值必须按input_charset编码后,才能参与签名。 3. goods_name和goods_desc同样都是商品的相关信息。区别在于,goods_name是商品名称,比较短;goods_desc是商品的描述,比较长。如果商户觉得goods_name不足以说明商品的信息,则可以使用goods_desc字段。 4. total_amount的值是必须提供的;unit_amount、unit_count和transport_amount的值或者都提供,或者都不提供。如果这4个参数都提供了,那么必须满足下面等式: total_amount = unit_amount*unit_count+transport_amount 否则,百度钱包将拒绝该支付请求。 5. buyer_sp_username是买家在商户网站的用户名。如果商户需要在百度钱包的交易记录中保存该信息,则可以使用这个参数。 6. page_url和return_url分别用于前台通知和后台通知。page_url的内容是用户可见的页面,而return_url的内容包括必要的文本信息即可。这两个URL不应该带有参数。需要注意的是,return_url必须返回200,不能要求登录或重定向。如果page_url必须要求用户登录或有重定向需求,那么return_url必须使用和page_url不同的地址。 7. pay_type是一个辅助性的参数,旨在提高用户体验。商户可以在自己的网站上提供选项,让买家选择支付方式,然后给pay_type赋上相应的值,发送给百度钱包,百度钱包就可以根据pay_type的值向买家展现相应的支付页面。商户也可以对买家的选择进行统计,分析出买家对支付方式的偏好。 8. bank_no是默认银行的编号。该参数是配合pay_type使用的。如果pay_type是余额支付,那么bank_no将被忽略;如果pay_type是网银支付,则百度钱包的支付页面将根据bank_no的取值自动帮用户选中银行,以减少用户点击次数;如果pay_type是银行网关支付,那么百度钱包将直接跳转到bank_no代表的银行。 9. expire_time允许商户指定交易的过期时间。当交易过期后,百度钱包将自动关闭该交易。目前还不支持该行为。 10. extra完全由商户自己使用,对百度钱包是透明的。如果提供了该参数,那么查单接口和通知接口将原样返回该参数。 示例: 商户的请求参数: 参数名 参数值 参数值的说明 service_code 1 表示即时到帐支付 sp_no 1234567890 百度钱包商户号 order_create_time 20080808080808 订单创建时间 order_no 20080808123456123456 订单号 goods_category 1 商品分类号 百度在线网络技术(北京)有限公司 第 页 共 16 页 文档名称:百度钱包企业版商户系统接入指南V2 goods_name 使用百度钱包支付的商品 商品的名称 goods_desc 这是一笔使用百度钱包银行网关支付的订单 订单的描述 unit_amount 1000 商品单价为10元 unit_count 2 订单包含2件相同的商品 transport_amount 500 运费为5元 total_amount 2500 买家需要支付25元 currency 1 支付的币种是人民币 buyer_sp_username jarfield 买家在商户网站的用户名 return_url http://www.yoursite.com/return_url 商户提供的return_url page_url http://www.yoursite.com/page_url 商户提供的page_url pay_type 1 默认支付方式为余额支付 bank_no 201 默认的银行是招行 expire_time 20080908080808 交易在一个月后过期 input_charset 1 参数值的编码为GBK version 2 版本号 sign 0EBBD22EF456D779B21A97482B9D3504 签名结果 sign_method 1 签名算法为MD5 签名: sign = MD5(bank_no=201&buyer_sp_username=jarfield¤cy=1&expire_time=20080908080808&goods_category=1&goods_desc=这是一笔使用百度钱包纯网关支付的订单&goods_name=使用百度钱包支付的商品&input_charset=1&order_create_time=20080808080808&order_no=20080808123456123456 &page_url=http://www.yoursite.com/page_url&pay_type=1&return_url=http://www.yoursite.com/return_url&service_code=1&sign_method=1&sp_no=1234567890&total_amount=2500&transport_amount=500&unit_amount=1000&unit_count=2&version=2&key=XXXXXXXXXXXXXXXX) = 0EBBD22EF456D779B21A97482B9D3504 其中,红字部分是按照GBK编码后的字符串。 5.2 即时到账支付接口(要求登录百度钱包) URL:https://wallet.baidu.com/api/0/pay/0/direct/0 其他方面,与 即时到账支付接口(不要求登录百度钱包) 基本相同。不同点包括:请求参数pay_type不支持3(银行网关支付)。 5.3 按订单号查询支付结果接口 URL:https://wallet.baidu.com/api/0/query/0/pay_result_by_order_no 请求方式:GET 请求参数: 参数名 参数含义 格式说明 是否必须 百度在线网络技术(北京)有限公司 第 页 共 16 页 文档名称:百度钱包企业版商户系统接入指南V2 service_code 服务编号 整数,目前必须为11 是 sp_no 百度钱包商户号 10位数字组成的字符串 是 order_no 订单号 不超过20个字符 是 output_type 响应数据的格式,默认XML 取值范围参见附录 是 output_charset 响应数据的字符编码,默认GBK 取值范围参见附录 是 version 接口的版本号 取值为2或3 是 sign 签名结果 取决于签名方法 是 sign_method 签名方法,默认MD5 取值范围参见附录 是 响应数据可以支持多种格式和编码,由output_type和output_charset参数指定。 响应数据: 参数名 参数含义 格式说明 是否必须 query_status 订单查询的错误码 取值范围参见附录 是 sp_no 百度钱包商户号 10位数字组成的字符串 是 order_no 订单号 不超过20个字符 是 bfb_order_no 百度钱包交易号 不超过30个字符 否;交易存在时才会有 bfb_order_create_time 百度钱包交易创建时间 YYYYMMDDHHMMSS 否;交易存在时才会有 pay_time 支付时间 YYYYMMDDHHMMSS 否;用户成功付过款才会有 pay_type 支付类型 取值范围参见附录 否;用户成功付过款才会有 bank_no 用于支付的银行编号 取值范围参见附录 否;用户使用网银支付和银行网关成功支付了才有 goods_name 商品的名称 允许包含中文;不超过128个字符或64个汉字 是 unit_amount 商品单价,以分为单位 非负整数 否 unit_count 商品数量 非负整数 否 transport_amount 运费,以分为单位 非负整数 否 total_amount 总金额,以分为单位 非负整数 是 cash_amount 交易现金金额,以分为单位 非负整数,当传入的version参数为3时返回该字段,若version为2,则不返回该字段 否 fee_amount 手续费,以分为单位 非负整数 是 百度在线网络技术(北京)有限公司 第 页 共 16 页 文档名称:百度钱包企业版商户系统接入指南V2 buyer_sp_username 买家在商户网站的用户名 允许包含中文;不超过64字符或32个汉字 否 currency 币种 取值范围参见附录 是 pay_result 支付结果代码 取值范围参见附录 是 sign 签名结果 取决于签名方法 是 sign_method 签名方法 取值范围参见附录 是 extra 商户自定义数据 不超过255个字符 否 示例: 商户的请求参数:version为2 参数名 参数值 参数值的说明 service_code 11 表示按订单号查询支付结果 sp_no 1234567890 百度钱包商户号 order_no 20080808123456123456 待查询的订单号 output_type 1 响应数据的格式为XML output_charset 1 响应数据的编码是GBK version 2 版本号是2 sign 5C7E1DBAC2C40764D9D00678D42B45C0 签名结果 sign_method 1 签名算法为MD5 签名: sign = MD5(order_no=20080808123456123456&output_charset=1&output_type=1&service_code=11 &sign_method=1&sp_no=1234567890&version=2&key=XXXXXXXXXXXXXXXX) = 5C7E1DBAC2C40764D9D00678D42B45C0 发送的URL: https://wallet.baidu.com/api/0/query/0/pay_result_by_order_no?order_no=12345678902008080808080812345671234567&output_type=1&output_charset=1&service_code=11&sign_method=1&sp_no=1234567890&version=2&sign=5C7E1DBAC2C40764D9D00678D42B45C0 响应数据(XML格式): 0 7D6C167DCE83AD23AD22851792D77F65 1 1234567890 20080808123456123456 20080808BFB20080808123456123456 20080808080808 20080808090909 3 201 使用百度钱包支付的商品 1000 百度在线网络技术(北京)有限公司 第 页 共 16 页 文档名称:百度钱包企业版商户系统接入指南V2 2 500 2500 0 1 jarfield 1 其中, sign = MD5(bank_no=201&bfb_order_create_time=20080808080808&bfb_order_no=20080808BFB20080808123456123456&buyer_sp_username=jarfield¤cy=1&fee_amount=0&goods_name=使用百度钱包支付的商品&order_no=20080808123456123456&pay_result=3&pay_time=20080808090909&pay_type=1&query_status=0&sign_method=1&sp_no=1234567890&total_amount=2500&transport_amount=500&unit_amount=1000&unit_count=2&key=XXXXXXXXXXXXXXXX) = 7D6C167DCE83AD23AD22851792D77F65 query_status表示查询的错误码,参见附录。 商户的请求参数:version为3 参数名 参数值 参数值的说明 service_code 11 表示按订单号查询支付结果 sp_no 1234567890 百度钱包商户号 order_no 20080808123456123456 待查询的订单号 output_type 1 响应数据的格式为XML output_charset 1 响应数据的编码是GBK version 3 版本号是3 sign 5C7E1DBAC2C40764D9D00678D42B45C0 签名结果 sign_method 1 签名算法为MD5 签名: sign = MD5(order_no=20080808123456123456&output_charset=1&output_type=1&service_code=11 &sign_method=1&sp_no=1234567890&version=3&key=XXXXXXXXXXXXXXXX) = 5C7E1DBAC2C40764D9D00678D42B45C0 发送的URL: https://wallet.baidu.com/api/0/query/0/pay_result_by_order_no?order_no=12345678902008080808080812345671234567&output_type=1&output_charset=1&service_code=11&sign_method=1&sp_no=1234567890&version=3&sign=5C7E1DBAC2C40764D9D00678D42B45C0 响应数据(XML格式): 百度在线网络技术(北京)有限公司 第 页 共 16 页 文档名称:百度钱包企业版商户系统接入指南V2 0 7D6C167DCE83AD23AD22851792D77F65 1 1234567890 20080808123456123456 20080808BFB20080808123456123456 20080808080808 2500 20080808090909 3 201 使用百度钱包支付的商品 1000 2 500 2500 0 1 jarfield 1 其中, sign = MD5(bank_no=201&bfb_order_create_time=20080808080808&bfb_order_no=20080808BFB20080808123456123456&buyer_sp_username=jarfield¤cy=1&fee_amount=0&goods_name=使用百度钱包支付的商品&order_no=20080808123456123456&pay_result=3&pay_time=20080808090909&pay_type=1&query_status=0&sign_method=1&sp_no=1234567890&total_amount=2500&transport_amount=500&unit_amount=1000&unit_count=2&key=XXXXXXXXXXXXXXXX) = 7D6C167DCE83AD23AD22851792D77F65 query_status表示查询的错误码,参见附录。 5.4 支付结果通知接口 URL:商户提供的return_url 请求方式:GET 请求参数: 参数名 参数含义 格式说明 是否必须 sp_no 百度钱包商户号 10位数字组成的字符串 是 order_no 商户订单号 不超过20个字符 是 bfb_order_no 百度钱包交易号 不超过32个字符 是 百度在线网络技术(北京)有限公司 第 页 共 16 页 文档名称:百度钱包企业版商户系统接入指南V2 bfb_order_create_time 百度钱包交易创建时间 YYYYMMDDHHMMSS 是 pay_time 支付时间 YYYYMMDDHHMMSS 是 pay_type 支付类型 取值范围参见附录 是 bank_no 用于支付的银行编号 取值范围参见附录 否;用户使用网银支付和银行网关支付时才有 unit_amount 商品单价,以分为单位 非负整数 否 unit_count 商品数量 非负整数 否 transport_amount 运费,以分为单位 非负整数 否 total_amount 总金额,以分为单位 非负整数 是 fee_amount 百度钱包收取商户的手续费,以分为单位 非负整数 是 currency 币种,目前仅支持人民币 取值范围参见附录 是 buyer_sp_username 买家在商户网站的用户名 允许包含中文;不超过64字符或32个汉字 否 pay_result 支付结果代码 取值范围参见附录 是 input_charset 请求参数的字符编码 取值范围参见附录 是 version 版本号 与支付请求中的version保持一致 是 sign 签名结果 取决于签名方法 是 sign_method 签名方法 取值范围参见附录 是 extra 商户自定义数据 不超过255个字符 否 说明: 1. 由于buyer_sp_username可能包含中文,因此必须传input_charset参数。Input_charset是必须参数,即使没有传buyer_sp_username,也必须传input_charset。 响应数据: 接收到百度钱包的后台通知后,商户须返回特定的HTML页面。该页面应该满足以下要求: HTML头部须包括 百度钱包只有检测到该字符串,才会认为商户已经成功接收到通知、已经验证过并且认可通知的内容。 示例: 通知参数: 参数名 参数值 参数值的说明 sp_no 1234567890 10位数字组成的字符串 order_no 20080808123456123456 订单号 bfb_order_no 20080808BFB20080808123456123456 百度钱包交易号 bfb_order_create_time 20080808080808 百度钱包交易创建时间 百度在线网络技术(北京)有限公司 第 页 共 16 页 文档名称:百度钱包企业版商户系统接入指南V2 pay_time 20080808090909 支付时间 pay_type 3 余额支付 bank_no 201 银行是招行 unit_amount 1000 商品单价为10元 unit_count 2 订单包含2件相同的商品 transport_amount 500 运费为5元 total_amount 2500 买家需要支付25元 fee_amount 0 手续费0元 currency 1 支付的币种是人民币 buyer_sp_username jarfield 卖家在商户网站的用户名 pay_result 1 支付成功 input_charset 1 中文编码是GBK version 2 版本号为2 sign B219D1A2784C1F12868FEE887374AFB2 签名结果 sign_method 1 签名算法为MD5 签名: sign = MD5(bank_no=201&bfb_order_create_time=20080808080808&bfb_order_no=20080808BFB20080808123456123456&buyer_sp_username=jarfield¤cy=1&fee_amount=0&input_charset=1&order_no=20080808123456123456&pay_result=1&pay_time=20080808090909&pay_type=3&sign_method=1&sp_no=1234567890&total_amount=2500&transport_amount=500&unit_amount=1000&unit_count=2&version=2&key=XXXXXXXXXXXXXXXX) = B219D1A2784C1F12868FEE887374AFB2 6 注意事项 在商户接入的过程中,有一些细节需要额外注意。如果忽略了这些细节,可能会延迟联调进度,更有可能导致资金问题。这些细节在功能概述、交互流程和接口规范这三节中都有重点描述,这里再汇总和强调一次。 6.1 重复的通知 对于支付系统,无论是后台通知还是前台通知,都有可能被重复发送,甚至同时发送。如果由于网络问题或商户系统维护,百度钱包没有收到商户对通知的正确响应,那么百度钱包会尝试重发通知。而且,用户可以通知点击付款结果页面上的page_url,触发前台通知,前台通知和后台通知有可能同时到达商户系统。 总之,通知到达商户系统的次数和时间都是不可预知。商户系统不能依赖于任何假设来保证系统的正确性。商户的系统必须对通知进行除重处理,对于同一笔订单的通知,必须只处理第一次通知,忽略后续的通知。特别是涉及到资金的操作,须额外谨慎。 百度钱包系统在通知成功的情况下,尽量不重复发送后台通知。但是为了避免掉单,重复发送后台通知的情况是不可避免的。 6.2 前台通知 百度在线网络技术(北京)有限公司 第 页 共 16 页 文档名称:百度钱包企业版商户系统接入指南V2 前台通知也可能造成重复通知。如果商户不希望接受前台通知,那么必须在即时到帐接口中给page_url参数设置一个“不处理支付结果通知参数”的地址值。如果不设置page_url,百度钱包则以return_url作为page_url的值,这样仍然会发送前台通知。 6.3 查单接口 发现很多商户都不使用查单接口。其实这个接口的作用还是比较大的,建议大家使用。目前,有两个场景很适合使用查单接口: 1. 处理支付结果通知。为了防止第三方伪造通知,商户系统在收到通知后立刻通过查单接口反查交易的支付结果。 2. 处理掉单情况。由于网络、系统升级等不可避免的因素,支付结果通知是有可能丢失的。百度钱包会加强通知机制,直到通知成功为止。但是,如果商户系统可以主动查单,那么基本可以杜绝掉单情况,并且在最短的时间内修复交易的状态,从而提高用户体验。 6.4 签名字符串和中文编码 在商户接入的过程中,出现最多的问题就是“5804 验签失败”。这个问题的原因往往有两个: 1. 签名字符串拼接方式的不对 2. 签名字符串中,中文参数没有使用正确的中文编码 签名字符串的拼接方式在 3.3 签名机制 中已经详细描述。但是,关于可选参数的拼接,还有有可能混淆。下面重点介绍一下。 假设参数A是必选的,其值为value_a;参数B是可选的,而且没有值;没有其他参数。那么,签名字符串有两种可能: A=value_a&B= 或 A=value_a 在签名时,对于可选参数,到底采用哪种拼接方式,取决与HTTP请求的参数。如果请求参数中包含B,但是没有值,那么就采用A=value_a&B=的方式。如果请求参数中不包含B,那么就采用A=value_a的方式。 在验签时,对于可选参数,到底采用哪种拼接方式,取决与HTTP响应的参数。如果响应参数中包含B,但是没有值,那么就采用A=value_a&B=的方式。如果响应参数中不包含B,那么就采用A=value_a的方式。 特别需要注意的是,考虑到接口的兼容性,商户系统需要特别注意签名和验签逻辑的编码方式。建议根据HTTP请求或响应中存在的参数来拼接签名字符串,而不要将包含在签名字符串中的参数写死。因为百度钱包以后可能会增加可选参数,如果硬编码,那么可能导致验签失败。 6.5 百度钱包合作密钥的管理 百度钱包合作密钥是百度钱包与商户系统交互安全的基础。如果密钥丢失,则可能发生伪造交易、通知等行为,进而引发资金风险。因此,商户须严格保护百度钱包合作密钥,绝不能让第三方知道。 在商户公司内部,知道百度钱包合作密钥的员工越少越好。如果相关的员工离职,最好联系百度钱包更换密钥。 7 附录 百度在线网络技术(北京)有限公司 第 页 共 16 页 文档名称:百度钱包企业版商户系统接入指南V2 7.1 ServiceCode列表 取值 含义 1 即时到账支付 11 按订单号查询支付结果 7.2 币种列表 取值 含义 1 人民币 7.3 即时到帐接口中支付方式列表 取值 含义 1 余额支付(必须登录百度钱包) 2 网银支付(在百度钱包页面上选择银行,可以不登录百度钱包) 3 银行网关支付(直接跳到银行的支付页面,无需登录百度钱包) 7.4 查单接口和通知接口中支付方式列表 取值 含义 1 余额支付(登录了百度钱包,使用百度钱包余额进行支付) 2 网银支付(登录了百度钱包,并在百度钱包页面上选择了银行) 3 纯网关支付(没有登录百度钱包,在百度钱包页面上选择了银行;或者直接跳转到银行的支付页面) 7.5 摘要算法列表 取值 含义 1 MD5 2 SHA-1 7.6 支付结果列表 取值 含义 1 支付成功 2 等待支付 3 退款成功 7.7 响应数据格式列表 取值 含义 1 XML 7.8 字符编码列表 取值 含义 百度在线网络技术(北京)有限公司 第 页 共 16 页 文档名称:百度钱包企业版商户系统接入指南V2 1 GBK 7.9 订单查询错误码列表 取值 含义 0 查询到结果 1002 查询结果为空 5801 缺少请求参数 5802 请求参数非法 5803 不支持的签名算法 5804 验签失败 5806 服务器内部错误 7.10 银行编号列表 取值 含义 11 银联 101 中国工商银行 201 中国招商银行 301 中国建设银行 401 中国农业银行 501 中信银行 601 浦东发展银行 701 中国光大银行 801 深圳发展银行 1101 交通银行 百度在线网络技术(北京)有限公司 第 页 共 16 页

下载文档,方便阅读与编辑

文档的实际排版效果,会与网站的显示效果略有不同!!

需要 10 金币 [ 分享文档获得金币 ]
0 人已下载

下载文档

相关文档