腾讯财付通接口的开发

腾讯财付通接口的开发 财付通支付网关商户开发指南 目 录 1 引言 .............................................................. 4 1.1 1.2 1.3 文档概述 ........................................................................... 4 阅读对 象 ........................................................................... 4 业务术 语 ........................................................................... 4 2 概 述 .......................................................... 4 2.1 2.2 2.3 行业背景 ........................................................................... 4 接口介 绍 ........................................................................... 5 业务实现流 程 ....................................................................... 6 3 交互模 式 .......................................................... 6 3.1 3.2 3.3 页面跳转交互模式 ................................................................... 6 后台系统调 用交互模式 ............................................................... 7 后台通知交互模 式 ................................................................... 8 4 数据格 式 .......................................................... 8 4.1 4.2 4.3 GET或POST ......................................................................... 8 XML数据格 式 ........................................................................ 9 字符串格 式 ......................................................................... 9 5 数字签 名 .......................................................... 9 5.1 5.2 签名原始串 ........................................................................ 10 签名算 法 .......................................................................... 10 5.2.1 MD5签名 ..................................................................... 10 6 补单机 制 ......................................................... 10 7 接 口 ............................................................. 11 7.1 支付接口 .......................................................................... 11 7.1.1 业务功能 .................................................................... 11 7.1.2 7.1.3 7.1.4 7.1.5 7.2 交互模式 .................................................................... 11 请求参数列 表 ................................................................ 11 返回结果和通知参数列 表 ...................................................... 13 后台通知结果反 馈 ............................................................ 15 通知查询接 口 ...................................................................... 15 7.2.1 7.2.2 7.2.3 7.2.4 业务功能 .................................................................... 15 交互模 式 .................................................................... 15 请求参数列 表 ................................................................ 15 应答参数列 表 ................................................................ 16 7.3 订单查询接口 ...................................................................... 17 7.3.1 7.3.2 7.3.3 7.3.4 业务功能 .................................................................... 17 交互模 式 .................................................................... 17 请求参数列 表 ................................................................ 17 应答参数列 表 ................................................................ 18 7.4退款接口 ............................................................................. 20 7.4.1业务功能 ....................................................................... 20 7.4.2交互模式 ....................................................................... 20 7.4.3请求参数列表 ................................................................... 21 7.4.4 应答参数列表 ................................................................ 22 7.5退款明细查询接口 ..................................................................... 23 7.5.1业务功能 ....................................................................... 23 7.5.2交互模式 ....................................................................... 23 7.5.3请求参数列表 ................................................................... 23 7.5.4应答参数列表 ................................................................... 25 8 实 例 ............................................................. 26 9 注意事 项 ......................................................... 28 1 引言 1.1 文档概述 1.2 阅读对象 合作商户系统的技术开发人员，要求具有WEB程序开发背景，了解http和https 请求和应答的格式和过程，对XML格式有所掌握。 1.3 业务术语 2 方案概述 2.1 行业背景 在电子商务中，商家、买家、中间服务方是交易活动中的三个环节。买家选购商品下发订单，商家确认订 单，买家通过中间服务方向商家支付货款，商家发货履行订单。在这个过程中商家的网站需要集成中间服务方的支付功能，让买家完成货款的支付。财付通作为一家专业的中间服务方除了提供支付接口外，还提供了支付结果查询接口和订单查询接口等，帮助商家记录货款的往来，让商家能把更多的精力集中到商品服务上。 商户的货款会按照约定以T0,T7的频率结算到商户的银行账户，同时收取手续费。这个过程由财付通自动完成，商户无需做相关开发工作。 2.2 接口介绍 2.3 业务实现 2.0调用支付接口进行支付后，财付通返回支付结果给前台页面，同时会向商户的服务器发送支付是否成功的通知 3.0商户服务器在收到支付结果通知后可以根据通知ID查询通知内容，在确保支付成功后再向用户发送提示信息，这样可以进一步提高安全性，防止伪支付成功结果的诈骗。 3 交互模式 3.1 页面跳转交互模式 页面跳转交互模式是指商户系统与财付通系统的数据交互通过用户浏览器中转进行，是一种非实时的异步交互。 如买家下单买一个商品，商户系统会生成一个支付链接，此链接通过用户的浏览器跳转到财付通系统，财付通通过此链接获取支付请求的参数，这个支付请求用的就是页面跳转交易模式。 用户在财付通页面完成支付后，财付通通过return_url跳转到商户系统。 3.2 后台系统调用交互模式 后台系统调用交互模式是指商户系统向财付通系统发送请求数据，并同步等待财付通系统处理完毕后返回的响应数据。数据交互是商户服务器与财付通服务器直接通信，一般请求采用http的get或post，应答采用xml数据格式。 如用户在商户系统查询时，商户要确认用户某个订单是否支付成功，可以在服务器上发送一个查询请求，财付通收到请求后把查询结果以xml格式返回给商户，商户处理结果后再显示给用户。 3.3 后台通知交互模式 后台通知交互模式是指财付通系统主动向商户系统发送通知数据，并同步等待商户系统处理完毕后返回的响应数据。数据交互是财付通服务器与商户服务器直接通信，一般请求采用http的get或post，应答用字符串格式。 如用户在财付通支付成功后，财付通会在后台通过notify_url向商户系统发起通知，商户处理后成功返回success，失败返回fail或其他字符。 4 数据格式 4.1 GET或POST 采用HTTP的GET或POST，为了保证接收方接收数据正确，传递的参数如果存在特殊字符(如&、 =等)需要进行URL Encode。 GET或POST一般用于页面跳转交互模式的请求和通知、后台系统调用模式的请求、后台通知模式的请求。 4.2 XML数据格式 采用标准XML协议，所有参数只存在一级节点中，不采用多级节点嵌套。 <?xml version="1.0" encoding="gb2312" ?> <root> <retcode>0</retcode> <retmsg></retmsg> <partner>1900000109</partner> <status>0</status> <sign>8DB4A013A8B515349C307F1E448CE836</sign> </root> 一般有返回码retcode参数，0表示调用成功;非0表示调用失败，失败时结果不签名，只有retcode和返回信息retmsg。 XML一般用于后台系统调用模式的应答。 4.3 字符串格式 直接以简单字符串作为数据内容，一般用于后台通知模式的接口反馈，表示处理是否成功。 5 数字签名 为了保证数据传输过程中的数据真实性和完整性，我们需要对数据进行数字签名，在接收签名数据之后进行签名校验。 数字签名有两个步骤，先按一定规则拼接要签名的原始串，再选择具体的算法和密钥计算出签名结果。 一般失败的结果不签名。 5.1 签名原始串 无论是用get、post还是xml，签名原始串组串方式都一致，除sign字段外，待签名参数按照字段名的ascii码从小到大排序后使用QueryString的格式(即key1=value1&key2=value2„)拼接而成，空值不传递，不参与签名。 签名时字段名和字段值都采用原始值，不进行URL Encode。 签名的字段包括请求中有所的get或post字段，除了接口中描述的字段外，还应包括请求中出现的其它字段。 5.2 签名算法 目前暂只支持MD5签名 5.2.1 MD5签名 MD5 是一种摘要生成算法，通过在签名原始串后加上商户通信密钥的内容，进行MD5运算，形成的摘要字符串即为签名结果。为了方便比较，签名结果统一转换为大写字符。 MD5签名计算公式: sign = Md5(原字符串&key=商户密钥). toUpperCase 如: 签名原始串是:input_charset=GBK&partner=1900000109&total_fee=1 商户密钥是:8db4a013a8b515349c307f1e448ce836 签名的结果为: sign=md5(input_charset=GBK&partner=1900000109&total_fee=1& key=8934e7d15453e97507ef794cf7b0519d)= 8DB4A013A8B515349C307F1E448CE836 6 补单机制 对后台通知交互模式，如果财付通收到商户的应答不是success或超时，财付通认为通知失败，财付通会通过一定的策略(如1分钟、2分钟、4分钟、8分钟、16分钟、32分钟，共6次)定期重新发起通知，尽可能提高通知的成功率,但财付通不保证通知最终能成功。 由于存在重新发送后台通知的情况，因此同样的通知可能会多次发送给商户系统。商户系统必须能够正确处理重复的通知。 财付通推荐的做法是，当收到通知进行处理时，首先检查对应业务数据的状态，判断该通知是否已经处理过，如果没有处理过再进行处理，如果处理过直接返回success。在对业务数据进行状态检查和处理之前，要采用数据锁进行并发控制，以避免函数重入造成的数据混乱。 7 接口 7.1 支付接口 7.1.1 业务功能 买家在商户网站拍下商品后，选择财付通付款，商户系统调用财付通支付接口，页面跳转到财付通支付中心或银行。用户完成支付后，财付通把用户引导回商户页面(return_url)，同时服务器后台通知商户服务器(notify_url)支付结果。 7.1.2 交互模式 请求:页面跳转交互模式 返回结果+通知:页面跳转交互模式+后台通知交互模式 7.1.3 请求参数列表 请求url: 通过get或post请求 7.1.4 返回结果和通知参数列表 页面返回通过请求中的return_url进行，采用get或post 后台通知通过请求中的notify_url进行，采用get或post 返回结果和通知中的参数一致，包含如下内容: 7.1.5 后台通知结果反馈 财付通后台通过notify_url通知商户，商户做业务处理后，需要以字符串的形式反馈处理结果，内容如下: 7.2 通知查询接口 7.2.1 业务功能 商户接收到财付通的支付成功通知后，可以通过此接口查询通知的具体内容，以确保通知是从财付通发起的，没有被伪造或篡改过。 7.2.2 交互模式 后台系统调用交互模式 7.2.3 请求参数列表 请求url: 通过get或post请求 7.2.4 应答参数列表 数据按XML的格式实时返回 7.3 订单查询接口 7.3.1 业务功能 根据商户订单号或者财付通订单号查询财付通侧记录的具体订单信息。 7.3.2 交互模式 后台系统调用交互模式 7.3.3 请求参数列表 请求url:通过get或post 请求 7.3.4 应答参数列表 数据按XML的格式实时返回 7.4退款接口 7.4.1业务功能 商户针对某一个已经成功支付的订单发起退款，操作结果在同一会话中同步返回。 一、退款方式 交易单信息中的银行类型和交易类型确定退款方式，退款方式则确定资金退到银行卡或者财付通账号。 1.如果银行类型能确定是信用卡支付，则退款到支付所用的信用卡，财付通商户管理系统上显示退款方式为“信用卡退款” 2.如果是财付通账户支付，则退款到买家财付通账号，财付通商户管理系统页面上显示退款方式为“退单财付通” 3.如果是快速交易，则可以选择退到支付所用银行卡或指定的财付通账号，退到银行卡则显示退款方式为“退单银行”，退到财付通帐号则显示退款方式为“转账退款” 4.当退银行时，如果退银行失败，资金会退到商户号的现金账号中，商户可以登录mch.tenpay.com手工处理或调用转账退款接口退给指定财付通账号。 说明:退到财付通帐号是即时到账;退到银行卡则是非实时的，每个银行的处理速度不同，一般发起退款后1-3个工作日内到账。 二、退款限制 商户在退款操作时应该注意退款限制，避免发起不会成功的退款请求，下面是主要的退款限制: 1.在财付通系统中，只要退款累计金额不超过交易单支付总额，一笔交易单可以多次退款，退款申请单号(退款接口中有此参数)唯一确定一次退款，而不是交易单号确定一次退款。退款申请单号由商户生成，所以商户一定要保证退款申请单的唯一性。商家在退款过程中要特别注意，只有在能确定退款失败的情况下，才能重新发起另一笔退款。 2.目前大多数银行都支持全额退款和部分退款，但是也有少数银行不支持全额退款或部分退款，或者不支持退款。在这种情况下，商户可以与买家协调，退到指定的财付通帐号。 7.4.2交互模式 后台系统调用交互模式 7.4.3请求参数列表 请求url:通过get或post请求 7.4.4 应答参数列表 数据按XML的格式实时返回 7.5退款明细查询接口 7.5.1业务功能 根据商户订单号、财付通订单号、商户退款单号、财付通退款单号查询退款记录的具体信息。 7.5.2交互模式 后台系统调用交互模式 7.5.3请求参数列表 请求url: 通过get或post请求 7.5.4应答参数列表 数据按XML的格式实时返回 PS: $n表示记录的序号，取值为0~($ refund_count -1)，例如refund_count指示返回 的退款记录有2条。第 一条序号为“0”，第二条序号为“1”。 8 实例 假设场景如下: 商户开了一个服装网店，售卖各种男女式衬衫，一名用户小A在网店中选购了 一件男式衬衫，然后通过财付通的账户支付了货款，商户在收到财付通的支付成 功通知后，主动又发起一次通知查询请求，财付通实时返回了通知的内容，然后 商户确认交易成功并提示用户注意查收货物。过了一天小A又登录到商户网站 上查询自己的订单状态，此时商户系统根据小A的订单号向财付通发起订单查 询请求，财付通实时返回了订单的详细信息，商户根据收到的订单信息再结合自 己的发货情况给小A返回了一个完整的订单执行情况。小A高兴地看到自己的 衬衫已经发出。 业务流程实现如下: 支付请求: ;amp;bank_type=&b ody=男士衬衫一件 &return_url=;amp;notify_url=http: //www.paipai.com/shop1/pay notify.jsp&partner=1200000107&out_trade_no=2010051111380001&am p;total_fee=19800&spbill_create_ip=192.168.0.122&sign=8DB4A013A8B 515349C307F1E448CE836 支付返回结果: ;amp;pay_info=&partner=1200000107&bank_type=&total_fee=19800&notify_id=123456789012345678901234567890&transaction_id=1200000107201005111153328847&out_trade_no=2010051111380001&time_end=20100511115436&sign=8DB4A01356B515349C30788E448CE836 支付成功通知: ;amp;pay_info=&partner=1200000107&bank_type=&total_fee=19800&notify_id=123456789012345678901234567890&transaction_id=1200000107201005111153328847&out_trade_no=2010051111380001&time_end=20100511115436&sign=8DB4A01356B515349D30788E448CE836 商户接到通知后返回处理结果: success 商户根据通知ID发起通知查询请求: ;amp;notify_id=123456789012345678901234567890&sign=8DB4A01345B515349C30788E448CE836 财付通返回通知查询结果: <?xml version="1.0" encoding="gb2312" ?> <root> <retcode>0</retcode> <retmsg></retmsg> <trade_state>0</trade_state> <partner>1200000107</partner> <bank_type></bank_type> <total_fee>19800</total_fee> <transaction_id>1200000107201005111153328847</transaction_id> <out_trade_no>2010051111380001</out_trade_no> <time_end>20100511115436</time_end> <sign>8DB4A013A8B515347C307F1E448CE836</sign> </root> 第二天商户向财付通发起订单查询请求: ;amp;out_trade_no=2010051111380001 财付通返回订单查询结果: <?xml version="1.0" encoding="gb2312" ?> <root> <retcode>0</retcode> <retmsg></retmsg> <trade_state>0</trade_state> <partner>1200000107</partner> <bank_type></bank_type> <total_fee>19800</total_fee> <transaction_id>1200000107201005111153328847</transaction_id> <out_trade_no>2010051111380001</out_trade_no> <time_end>20100511115436</time_end> <is_split>false</is_split> <is_refund>false</is_refund> <sign>8DB4A013A8B515347C307F1E878CE836</sign> </root> 9 注意事项 1、 out_trade_no需要保证在商户号下全局唯一，建议使用“日期+序列号”的方式。如果out_trade_no相同， 其它核心信息不同，财付通会拒绝支付;如果out_trade_no相同，其它核心信息也相同，财付通会当同个订单处理。 2、 所有涉及到金额的单位都是分，最小的单位是1分，不能有小数出现 3、 notify_url是财付通服务器从后台直接发起请求到商户服务器，商户处理时不能检查用户的cookie或 商户更新DB等发货流程需要完整在notify_url完成，以确保掉单时， session; 财付通补单能成功补上 4、 notify_url有可能重复通知，商户需要做去重处理，避免多次发货 5、 notify_url收到的通知，商户处理成功或检查订单已经处理，需要返回处理成功的标志“success”，以告 知财付通不再通知 6、 notify_id的有效期是2分钟，请商户收到通知后尽快发起查询 7、 为了防止诈骗，支付时财付通会获取HTTP相关信息与申请的域名相比较。为了保证HTTP相关信息能正常， 跳转到财付通支付网关时，不要使用window.location.href、window.open跳转，可以使用form表单提交、<a href=""></a>方式跳转、HTTP头的redirect跳转。