【精品】B2C退款业务接口使用技术指导

1、b2c退款业务接口使用技术指导version: 2.0public date: 200985 all copyright reservedt第1章文档描述1.1文档说明本操作手册用来指导财付通商户实现与财付通退款接口的顺利对接。请相关技术人员详细阅读本手册。文屮红色的内容表示要重点注意的内容。1.2版本修订日期修订内容修订版本修订人2007-6-18创建1.0erickenwu2009-8-5修订2.0magichu1.3预期读者和阅读建议商八开发人员财付通退款接口的所有开发、审批者。第2章业务描述2.1接口作用搭建一个商户应用系统到财付通后台系统的丸联通道，商户通过该通道町以进行退款, 简化

2、了商户对web页面的频繁操作，为商户提供了一个退款的灵活渠道。2.2名词约定1. 交易单h交易单是财付通系统屮川户买卖的凭证和依据，记录交易的类型、状态、资金额等信息。一笔交易单啡一确定一笔交易。2. b2c 交易:用户支付的时候在财付通网站处于登录状态，并口买家账号与登录账号一致，则交易单的交易类型为b2c交易。3. 快速交易:没有买家账号或者非登录的匿名交易。4. 银行类型h财付通系统中对用户支付时所用的银行卡的类型编码，交易单信息中记录银行类 型。根据各家银行类型接入情况不同，有的银行类型确定为信用卡支付，有的则可 能是信川卡支付和借记卡支付。银行类型会影响退款策略。2.3退款业务说明为

3、了方便商八进行退款操作后对账，说明一下退款方式和退款限制。2.3.1退款方式交易单信息中的银行类型和交易类型确定退款方式,退款方式则确定资金退到银行卡或 者财付通账号。了解退款方式方便商八对账，以及跟踪资金流向。退款方式按以下顺序确定：1. 如果银行类型能确定是信用卡支付，则退款到支付所用的信用卡，财付通商户管理系 统上显示退款方式为“信用卡退款”。2. 如果是b2c交易，则退款到买家财付通账号，财付通商户管理系统页而上显示退款 方式为“退单财付通”。3. 如果是快速交易，则可以选择退到支付所用银行卡或指定的财付通账号，退到银行卡 则显示退款方式为“退中银行”，退到财付通帐号则显示退款方式为“

4、转账退款”。说明：退到财付通帐号是即时到账；退到银行卡则是非实时的，每个银行的处理速度不 同，一般发起退款js 1-3个工作日内到账。2.3.2退款限制商户在退款操作时应该注意退款限制，避免发起不会成功的退款请求，下面是主要的退 款限制：1. 在财付通系统屮，只要退款累计金额不超过交易单支付总额，一笔交易单可以多次 退款，退款川请单号（退款接口中有此参数）唯一确定一次退款，而不是交易单号确定一 次退款。退款申请单号由商户生成，所以商户一定要保证退款申请单的唯一性。商家在退 款过程中要特别注意，只有在能确定退款失败的情况卜，才能重新发起另-笔退款。2. 如果在支付的时候使用了购物券，则该交易单第

5、一次退款的金额不能小于购物券的 金额。3. h前大多数银行都支持全额退款和部分退款，但是也有少数银行不支持全额退款或部 分退款，或者不支持追款。在这种情况下，商户对以与买家协调，退到指定的财付通帐号。系统描述第3章3.1总体描述3.1.1运行环境规定linux, apache3.1.2遵循的通用标准tcp/iphttpscgi的参数表示方式3.2设计说明财付通退款接口以cg1的形式提供，为了保证退款操作的安全性，商户应川系统通过https协议与财付通商户管理系统的退款接口进行通信。财付通会提供两个证书给商八：财付通根证书文件和商户证书证书文件（包含私钥文件）。财付通根证书川于验证财付通商户管理

6、系统的证书，商八证书川于标识商八的身份，财付通系统会验证此证书来确定商八的身份.商八应用程序应该按照标准https协议访问财付通退款接口。财付通web server第4章前置准备4.1.1业务准备由于在退款操作中，会验证商八发起退款请求的tp、退款权限等。所以衣此之前，需 要先进入业务流程，申请操作权限以及配置信任ip列表，只能在信任tp上发起退款请求。中请此功能业务，请联系财付通商务人员4.1.2技术准备因为该接口基于https的安全通信机制，根据现在不同的开发语言，设计有两种实现方 式，使用无法模拟https的开发语言，需要使用依赖方式实现，采用这种方式实现，需要安 装财付通提供的小间代理

7、服务，代为实现https。女装操作请参看财付通代理服务安装设置指引第5章接口说明接口协议源数据为xml格式字符串，源数据经过编码和加密之后生成接口参数，生成最 终的参数访问退款接口。实现方式对分为独立实现和依赖实现两种。独立实现：商户端需要独立完成加密，传输，证书验证等功能的开发。依赖实现：通过安装和使用财付通提供的屮间代理服务，商八端通过与代理服务直接明 文通信，不需要开发加密，传输，证书验证等功能5.1独立实现5.1.1 接入 urlhttps:/mch tenpay com/cgi-bin/mchbatchtransfer cgi支持post/get方式，cgi参数生成规则见4. 2和4

8、. 3节。5.1.2接口原理财付通退款接口接收两个参数，content和abstract,商户访问的形式是 https:/meh. tenpay. com/cgi-bin/mchbatchtranser. cgi?content*&abst:ract=*. 下 面描述这两个参数值的具体生成规则。1. 按照5. 1. 3节的规则生成xml字符串a；2. 对a进行base64编码牛成b；3. 对b进行md5生成c （小写）；4. c后面加上商户的key再进行一次md5,生成d （小写）;计算公式如下：content 的值为:base64_encode （xml 字符串）；abstract的

9、值为:md5 (md5 (content) +key),加号表示连接，不要参与md55.1.3输入xml参数格式源参数以xml方式组装，参数名均为小写，编码方式为gb2312,以下是参数格式以及相应描述。<?xml version二"1. 0" encoding = "gb2312"?><root><op_code>1003 固定值/op code><op_name>b2c_refund</op_name><op_user>提交人 id</op_user><o

10、p_passwd> 操作员密码 </op_passwd><op_time>操作吋间(yyyymmddhhmmsssss) </op_time><sp_id>商户机构 id</sp_id><trans_id>待退款交易单号</trans_id><refund_id>退款单id,生成规则:109 + spid+yyyymmdd+7位流水号。如果退款单号相 同，则视为同一个退款申请。/refund_id><client_ip>客户端 ip 地址</client_ip>&

11、lt;rec_acc>退款接收方财付通帐号(如为空则黙认为交易的买方账号，不为空h不是交易 的买方账号，则退到该指定账号)</rec_acc><rec_acc_truename>退款接收方财付通帐号对应的真实姓名。如rec_acc不为空，字 段必填。</rec acc truename><cur_type>币种(1：人民币)</cur_type><pay smt>退款金额(以分为单位，非分账商户口j支持部分退款，但分账商户只能全额退 款)</pay_amt><desc> 退款备注/desc&g

12、t;</root>5.1.4返回xml参数格式返冋数据将以明文方式返冋，具体如下：<?xml version=，zl. 0，z encoding = "gb2312"?><root><op code>1003</op code><op name> b2c refund </opname><op _time>操作时间(yyyymmddhhmmsssss) </op time><op_user>提交人 ld</op_user><retcode

13、>返冋码：0或00-退款成功，其他-见下而说明</retcode><retmsg>错误内容描述</retmsg ></root>5.2依赖实现5.2.1前置准备依赖实现方式需要的开发工作量较小，但是需要女装财付通提供的中间代理服务，女装操作请参看财付通代理服务安装设置指引5.2.2实现方法直接top连接中间代理服务，并像其发送5. 2. 3节屮的xml明文数据5.2.3输入xml参数格式<?xml version二"1.0" encoding = "gb2312"?><root>

14、;<op_code>1003 固定值</op_code><op_name>b2c_refund</op_name><op user>提交人 td</op user><op passwd>操作员密码</（）p passwd><op time>操作时间（yyyymmddhhmmsssss） </op time><sp_id>商户机构 id</sp_id><trans_id>待退款交易单号</trans_id><refund_i

15、d>退款单id,生成规则:109 + spid+yyyymmdd+7位流水号。如果退款单号相 同，则视为同一个退款申请。</refund_id><client_ip>客户端 ip 地址</client_ip><rec_acc>退款接收方财付通帐号（如为空则黙认为交易的买方账号，不为空且不是交易 的买方账号，则退到该指定账号）</rec_acc><rec_acc_truename>退款接收方财付通帐号对应的真实姓名。如rec_acc不为空，字 段必填。</rec_acc_truenamc><cur_t

16、ype>币种（1：人民币）</cur_type><pay_amt>退款金额（以分为单位，非分账商户川支持部分退款，但分账商户只能金额退 款）</pay_amt><desc> 退款备注/desc></root>5.2.4返回xml参数格式<?xml version="l. 0" encoding = "gb2312"?><root><op_code>1003</op_code><op_name> b2c_refund <

17、/opname><op time>操作时间(yyyymmddhhmmsssss) </op time><op user>提交人 ld</op user><retcode>返回码：0或00-退款成功，其他-见下面说明</retcode> <retmsg>错误内容描述</retmsg ></root>第6章附录和枚举6.1接口联系人职责业务支持姓名陈菁替电7756emailsuechentencent. comqq88881507职责技术支持姓名朱磊电话0

18、755-86013388-8285davidzhutencent. comqq944933417职责技术支持姓名陈进盛电8709miklchenqq888814816.2接口返回码返冋码是判断退款是否成功的依据，下表给出常见的返冋码以及建议的处理方式。返回码返回码说明建议处理方式0退款成功00退款成功03019001系统/网络繁忙保持参数不变，重复发起03020009访问过丁频繁稍后再发起03020010ip校验不通过检查是否已中请配置可信任的ip列表10010系统/网络繁忙保持参数不变，重复发起20921191累计退款金额人于交易金额检査要求退款金额是否合理1137验签不通过检杏content参数和abstract参数的生成规则1012接收方帐号未注册财付通换个己注册的财付通账号1003密码检验失败确认传入正确的密码1096商户余额不足卖!11商品z后，余额充足后再发起退款1132商户没有退款权限走业务流程，向财付通川请权限03