腾讯财付通接口的开发

腾讯财付通接口的开发 财付通支付网关商户开发指南 目 录 1 引言 ........................................................... 4 1.1 文档概述 ............................................................................ 4 1.2 阅读对象 ............................................................................ 4 1.3 业务术语 ............................................................................ 4 2 概述 ....................................................... 4 2.1 行业背景 ............................................................................ 4 2.2 接口介绍 ............................................................................ 5 2.3 业务实现流程 ........................................................................ 6 3 交互模式 ....................................................... 6 3.1 页面跳转交互模式 .................................................................... 6 3.2 后台系统调用交互模式 ................................................................ 7 3.3 后台通知交互模式 .................................................................... 8 4 数据格式 ....................................................... 8 4.1 GET或POST .......................................................................... 8 4.2 XML数据格式 ........................................................................ 9 4.3 字符串格式 .......................................................................... 9 5 数字签名 ....................................................... 9 5.1 签名原始串 ......................................................................... 10 5.2 签名算法 ........................................................................... 10 5.2.1 MD5签名 ..................................................................... 10 6 补单机制 ...................................................... 10 7 接口 .......................................................... 11 7.1 支付接口 ........................................................................... 11 7.1.1 业务功能 ..................................................................... 11 7.1.2 交互模式 ..................................................................... 11 7.1.3 请求参数列表 ................................................................. 11 7.1.4 返回结果和通知参数列表 ....................................................... 13 7.1.5 后台通知结果反馈 ............................................................. 15 7.2 通知查询接口 ....................................................................... 15 7.2.1 业务功能 ..................................................................... 15 7.2.2 交互模式 ..................................................................... 15 7.2.3 请求参数列表 ................................................................. 15 ................................................................. 16 7.2.4 应答参数列表 7.3 订单查询接口 ....................................................................... 17 7.3.1 业务功能 ..................................................................... 17 7.3.2 交互模式 ..................................................................... 17 7.3.3 请求参数列表 ................................................................. 17 ................................................................. 18 7.3.4 应答参数列表 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 业务术语 术语 示例 说明 商户号 1900000107 机票平台的账号，只用于记账，由财付通自动分配 的10位数字 密钥 9ba2380ad9b2aacb96bca514eda27ac9 为保证通讯不被篡改，财付通与商户之间约定的32 位字符串，算签名sign时使用 账户 jpgyf@qq.com 财付通账户号，目前支持两种格式:qq号码和email 账户 金额 100000 金额，默认为RMB，以分为单位。1000表示RMB10.00 2 方案概述 2.1 行业背景 在电子商务中，商家、买家、中间服务方是交易活动中的三个环节。买家选购商品下发订单，商家确认订 单，买家通过中间服务方向商家支付货款，商家发货履行订单。在这个过程中商家的网站需要集成中间服务方的支付功能，让买家完成货款的支付。财付通作为一家专业的中间服务方除了提供支付接口外，还提供了支付结果查询接口和订单查询接口等，帮助商家货款的往来，让商家能把更多的精力集中到商品服务上。 商户的货款会按照约定以T0,T7的频率结算到商户的银行账户，同时收取手续费。这个过程由财付通自动完成，商户无需做相关开发工作。 2.2 接口介绍 接口名 请求URL 功能说明 结果说明 支付接口 调用该接口时指定支付参数，完结果分两路返回:一路为前台在 gateway/pay.htm 成买家账户向商家账户的支付，return_url后添加参数返回，表现 采用页面跳转交互模式和后台为页面跳转;一路为后台在 通知交互模式 notify_url后添加参数返回，要求 后台notify_url收到通知后进行 响应。 通知查询商户在收到后台通知后根据通财付通把具体的通知内容按XML格接口 gateway/verifynotifyid知ID向财付通发起通知内容的式实时返回 .xml 查询，采用后台系统调用交互模 式 订单查询商户在后台对任意一笔订单发根据订单号以XML格式返回具体的接口 gateway/normalorderque起查询，采用后台系统调用交互订单内容和状态 ry.xml 模式 退款接口 商户在后台对一笔已支付订单退款成功、失败或者退款流程中的 /refundapi/gateway/ref发起退款，采用后台系统调用交结果实时返回 und.xml 互模式 退款明细根据退款ID查询具体的退款明退款明细数据实时返回 查询接口 gateway/normalrefundqu细 ery.xml 2.3 业务实现流程 用户浏览器财付通服务器商户服务器 1.0选购商品 1.1生成订单 2.0到财付通页面完成订单支付 2.1返回支付成功页面 2.2同时后台通知支付结果 2.2.1确认收到通知 3.0根据通知ID查询验证支付结果 3.1返回通知内容 4.0确认支付成功，可以发货 2.0调用支付接口进行支付后，财付通返回支付结果给前台页面，同时会向商户的服务器发送支付是否成功的通知 3.0商户服务器在收到支付结果通知后可以根据通知ID查询通知内容，在确保支付成功后再向用户发送提示信息，这样可以进一步提高安全性，防止伪支付成功结果的诈骗。 3 交互模式 3.1 页面跳转交互模式 页面跳转交互模式是指商户系统与财付通系统的数据交互通过用户浏览器中转进行，是一种非实时的异步交互。 如买家下单买一个商品，商户系统会生成一个支付链接，此链接通过用户的浏览器跳转到财付通系统，财付通通过此链接获取支付请求的参数，这个支付请求用的就是页面跳转交易模式。 用户在财付通页面完成支付后，财付通通过return_url跳转到商户系统。 用户浏览器财付通服务器商户服务器 1.0选购商品 1.1生成订单 2.0跳转到财付通页面完成订单支付 2.1跳转到商户指定的支付成功页面 3.2 后台系统调用交互模式 后台系统调用交互模式是指商户系统向财付通系统发送请求数据，并同步等待财付通系统处理完毕后返回的响应数据。数据交互是商户服务器与财付通服务器直接通信，一般请求采用http的get或post，应答采用xml数据格式。 如用户在商户系统查询时，商户要确认用户某个订单是否支付成功，可以在服务器上发送一个查询请求，财付通收到请求后把查询结果以xml格式返回给商户，商户处理结果后再显示给用户。 财付通服务器商户服务器 1.0根据订单号查询订单状态 1.1返回详细的订单内容 3.3 后台通知交互模式 后台通知交互模式是指财付通系统主动向商户系统发送通知数据，并同步等待商户系统处理完毕后返回的响应数据。数据交互是财付通服务器与商户服务器直接通信，一般请求采用http的get或post，应答用字符串格式。 如用户在财付通支付成功后，财付通会在后台通过notify_url向商户系统发起通知，商户处理后成功返回success，失败返回fail或其他字符。 财付通服务器商户服务器 1.0后台通知商户支付结果 1.1商户确认收到通知 4 数据格式 4.1 GET或POST 采用HTTP的GET或POST，为了保证接收方接收数据正确，传递的参数如果存在特殊字符(如&、 =等)需要进行URL Encode。 GET或POST一般用于页面跳转交互模式的请求和通知、后台系统调用模式的请求、后台通知模式的请求。 4.2 XML数据格式 采用标准XML协议，所有参数只存在一级节点中，不采用多级节点嵌套。 0 1900000109 0 8DB4A013A8B515349C307F1E448CE836 一般有返回码retcode参数，0表示调用成功;非0表示调用失败，失败时结果不签名，只有retcode和返回信息retmsg。 XML一般用于后台系统调用模式的应答。 4.3 字符串格式 直接以简单字符串作为数据内容，一般用于后台通知模式的接口反馈，表示处理是否成功。 返回结果 结果说明 success 处理成功，财付通系统收到此结果后不再进行后续通知 fail或其他字符 处理不成功，财付通收到此结果或者没有收到任何结果，系统通过补单机制(详 见第6节)再次通知 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请求 字段名 变量名 必填 类型 说明 协议参数 签名方式 sign_type 否 String(8) 签名类型，取值:MD5、RSA，默认:MD5 接口版本 service_version 否 String(8) 版本号，默认为1.0 字符集 input_charset 否 String(8) 字符编码,取值:GBK、UTF-8，默认:GBK。 签名 sign 是 String(32) 签名 密钥序号 sign_key_index 否 Int 多密钥支持的密钥序号，默认1 业务参数 银行类型 bank_type 否 String(16) 银行类型，默认为“DEFAULT”,财付通支付 中心。银行直连编码及额度请与技术支持联 系 商品描述 body 是 String(32) 商品描述 附加数据 attach 否 String(255) 附加数据，原样返回 返回URL return_url 是 String(255) 交易完成后跳转的URL，需给绝对路径，255 字符内，格式如: tenpay.asp，通过该路径直接将支付结果以 Get的方式返回 通知URL notify_url 是 String(255) 接收财付通通知的URL，需给绝对路径，255 字符内，格式如: tenpay.asp 买方财付通账号 buyer_id 否 String(64) 买方的财付通账户(QQ 或EMAIL)。若商户没 有传该参数，则在财付通支付页面，买家需 要输入其财付通账户。 商户号 partner 是 String(10) 商户号,由财付通统一分配的10位正整数 (120XXXXXXX)号 商户订单号 out_trade_no 是 String(32) 商户系统内部的订单号,32个字符内、可包含 字母,确保在商户系统唯一 总金额 total_fee 是 Int 订单总金额，单位为分 币种 fee_type 是 Int 现金支付币种,取值:1(人民币),默认值是 1，暂只支持1 用户IP spbill_create_ip 是 String(15) 订单生成的机器IP，指用户浏览器端IP，不 是商户服务器IP 交易起始时间 time_start 否 String(14) 订单生成时间，格式为yyyymmddhhmmss，如 2009年12月25日9点10分10秒表示为 20091225091010。时区为GMT+8 beijing。该 时间取自商户服务器 交易结束时间 time_expire 否 String(14) 订单失效时间，格式为yyyymmddhhmmss，如 2009年12月27日9点10分10秒表示为 20091227091010。时区为GMT+8 beijing。该 时间取自商户服务器 物流费用 transport_fee 否 Int 物流费用，单位为分。如果有值，必须保证 transport_fee + product_fee=total_fee 商品费用 product_fee 否 Int 商品费用，单位为分。如果有值，必须保证 transport_fee + product_fee=total_fee 商品标记 goods_tag 否 String(32) 商品标记，优惠券时可能用到 7.1.4 返回结果和通知参数列表 页面返回通过请求中的return_url进行，采用get或post 后台通知通过请求中的notify_url进行，采用get或post 返回结果和通知中的参数一致，包含如下内容: 字段名 变量名 必填 类型 说明 协议参数 签名方式 sign_type 否 String(8) 签名类型，取值:MD5、RSA，默认:MD5 接口版本 service_version 否 String(8) 版本号，默认为1.0 字符集 input_charset 否 String(8) 字符编码,取值:GBK、UTF-8，默认:GBK。 签名 sign 是 String(32) 签名 密钥序号 sign_key_index 否 Int 多密钥支持的密钥序号，默认1 业务参数 1-即时到账 交易模式 trade_mode 是 Int 其他保留 支付结果: 交易状态 trade_state 是 Int 0—成功 1—失败 支付结果信息 pay_info 是 String(64) 支付结果信息，支付成功时为空 商户号 partner 是 String(10) 商户号,由财付通统一分配的10位正整数 (120XXXXXXX)号 付款银行 bank_type 是 String(16) 银行类型 银行订单号 bank_billno 否 String(32) 银行订单号，若为财付通余额支付则为空 总金额 total_fee 是 Int 支付金额，单位为分，如果discount有值， 通知的total_fee + discount = 请求的 total_fee 币种 fee_type 是 Int 现金支付币种,目前只支持人民币,默认值是 1-人民币 通知ID notify_id 是 String(64) 支付结果通知id，对于某些特定商户，只返 回通知id，要求商户据此查询交易结果 财付通订单号 transaction_id 是 String(28) 财付通交易号 商户订单号 out_trade_no 是 String(32) 商户系统的订单号，与请求一致。 商家数据包 attach 否 String(64) 商家数据包，原样返回 支付完成时间 time_end 是 String(14) 支付完成时间，格式为yyyymmddhhmmss，如 2009年12月27日9点10分10秒表示为 20091227091010。时区为GMT+8 beijing。该 时间取自财付通服务器 物流费用 transport_fee 否 Int 物流费用，单位分，默认0。如果有值，必须 保证transport_fee + product_fee = total_fee 物品费用 product_fee 否 Int 物品费用，单位分。如果有值，必须保证 transport_fee + product_fee=total_fee 折扣价格 discount 否 Int 折扣价格，单位分，如果有值，通知的 total_fee + discount = 请求的total_fee 买家别名 buyer_alias 否 String(64) 对应买家账号的一个加密串 7.1.5 后台通知结果反馈 财付通后台通过notify_url通知商户，商户做业务处理后，需要以字符串的形式反馈处理结果，内容如下: 返回结果 结果说明 success 处理成功，财付通系统收到此结果后不再进行后续通知 fail或其它字符 处理不成功，财付通收到此结果或者没有收到任何结果，系统通过补单机制(详见第6 节)再次通知 7.2 通知查询接口 7.2.1 业务功能 商户接收到财付通的支付成功通知后，可以通过此接口查询通知的具体内容，以确保通知是从财付通发起的，没有被伪造或篡改过。 7.2.2 交互模式 后台系统调用交互模式 7.2.3 请求参数列表 请求url: 通过get或post请求 字段名 变量名 必填 类型 说明 协议参数 签名方式 sign_type 否 String(8) 签名类型，取值:MD5、RSA，默认:MD5 接口版本 service_version 否 String(8) 版本号，默认为1.0 字符集 input_charset 否 String(8) 字符编码,取值:GBK、UTF-8，默认:GBK。 签名 sign 是 String(32) 签名 密钥序号 sign_key_index 否 Int 多密钥支持的密钥序号，默认1 业务参数 商户号 partner 是 String(10) 商户号,由财付通统一分配的10位正整数 (120XXXXXXX)号 通知ID notify_id 是 String(64) 支付成功后，财付通系统反馈的通知ID 7.2.4 应答参数列表 数据按XML的格式实时返回 字段名 变量名 必填 类型 说明 协议参数 签名方式 sign_type 否 String(8) 签名类型，取值:MD5、RSA，默认:MD5 接口版本 service_version 否 String(8) 版本号，默认为1.0 字符集 input_charset 否 String(8) 字符编码,取值:GBK、UTF-8，默认:GBK。 签名 sign 是 String(32) 签名 密钥序号 sign_key_index 否 Int 多密钥支持的密钥序号，默认1 业务参数 返回状态码 retcode 是 Int 返回状态码，0表示成功，其它未定义 支付状态码 trade_state 是 Int 支付结果状态码,0表示成功,其它为失败 返回信息 retmsg 否 String(64) 返回信息，如非空，为错误原因。 1-即时到账 交易模式 trade_mode 是 Int 其他保留 商户号 partner 是 String(10) 商户号 付款银行 bank_type 是 String(16) 银行类型 银行订单号 bank_billno 否 String(32) 银行订单号，若为财付通余额支付则为空 总金额 total_fee 是 Int 支付金额，单位为分，如果discount有值，通 知的total_fee + discount = 请求的 total_fee 币种 fee_type 是 Int 现金支付币种,目前只支持人民币,默认值是1- 人民币 财付通订单号 transaction_id 是 String(28) 财付通交易号 商户订单号 out_trade_no 是 String(32) 商户系统的订单号，与请求一致。 商家数据包 attach 否 String(64) 商家数据包，原样返回 支付完成时间 time_end 是 String(14) 支付完成时间，格式为yyyymmddhhmmss，如 2009年12月27日9点10分10秒表示为 20091227091010。时区为GMT+8 beijing。该 时间取自财付通服务器 物流费用 transport_fee 否 Int 物流费用，单位分，默认0。如果有值，必须 保证transport_fee + product_fee = total_fee 物品费用 product_fee 否 Int 物品费用，单位分。如果有值，必须保证 transport_fee + product_fee=total_fee 折扣掉价格 discount 否 Int 折扣掉价格，单位分，如果有值，通知的 total_fee + discount = 请求的total_fee 买家别名 buyer_alias 否 String(64) 对应买家账号的一个加密串 7.3 订单查询接口 7.3.1 业务功能 根据商户订单号或者财付通订单号查询财付通侧记录的具体订单信息。 7.3.2 交互模式 后台系统调用交互模式 7.3.3 请求参数列表 请求url: 通过get或post请求 字段名 变量名 必填 类型 说明 协议参数 签名方式 sign_type 否 String(8) 签名类型，取值:MD5、RSA，默认:MD5 接口版本 service_version 否 String(8) 版本号，默认为1.0 字符集 input_charset 否 String(8) 字符编码,取值:GBK、UTF-8，默认:GBK。 签名 sign 是 String(32) 签名 密钥序号 sign_key_index 否 Int 多密钥支持的密钥序号，默认1 业务参数 是 String(10) 商户号,由财付通统一分配的10位正整数商户号 partner (120XXXXXXX)号 否 String(32) 商户系统内部的订单号, out_trade_no和商户订单号 out_trade_no transaction_id至少一个必填，同时存在时 transaction_id优先 否 String(28) 财付通交易号, out_trade_no和财付通订单号 transaction_id transaction_id至少一个必填，同时存在时 transaction_id优先 7.3.4 应答参数列表 数据按XML的格式实时返回 字段名 变量名 必填 类型 说明 协议参数 签名方式 sign_type 否 String(8) 签名类型，取值:MD5、RSA，默认:MD5 接口版本 service_version 否 String(8) 版本号，默认为1.0 字符集 input_charset 否 String(8) 字符编码,取值:GBK、UTF-8，默认:GBK。 签名 sign 是 String(32) 签名 密钥序号 sign_key_index 否 Int 多密钥支持的密钥序号，默认1 业务参数 返回状态码 retcode 是 Int 返回状态码，0表示成功，其他未定义 支付状态码 trade_state 是 Int 支付结果状态码,0表示成功,其它为失败 返回信息 retmsg 否 String(64) 返回信息，如非空，为错误原因。 1-即时到账 交易模式 trade_mode 是 Int 其他保留 商户号 partner 是 String(10) 商户号 付款银行 bank_type 是 String(16) 银行类型，默认为“DEFAULT”,财付通，其余 参照第9节银行编码 银行订单号 bank_billno 否 String(32) 银行订单号，若为财付通余额支付则为空 总金额 total_fee 是 Int 支付金额，单位为分，如果discount有值，通 知的total_fee+ discount = 请求的 total_fee 币种 fee_type 是 Int 现金支付币种,目前只支持人民币,默认值是1- 人民币 财付通订单号 transaction_id 是 String(28) 财付通交易号 商户订单号 out_trade_no 是 String(32) 商户系统的订单号，与请求一致。 是否分账 is_split 是 boolean 是否分账，false无分账，true分账 是否退款 is_refund 是 boolean 是否退款，false无退款，true退款 商家数据包 attach 否 String(64) 商家数据包，原样返回 支付完成时间 time_end 是 String(14) 支付完成时间，格式为yyyymmddhhmmss，如 2009年12月27日9点10分10秒表示为 20091227091010。时区为GMT+8 beijing。该 时间取自财付通服务器 物流费用 transport_fee 否 Int 物流费用，单位分，默认0。如果有值，必须 保证transport_fee + product_fee = total_fee 物品费用 product_fee 否 Int 物品费用，单位分。如果有值，必须保证 transport_fee + product_fee = total_fee 折扣掉价格 discount 否 Int 折扣价格，单位分，如果有值，通知的 total_fee + discount = 请求的total_fee 买家别名 buyer_alias 否 String(64) 对应买家账号的一个加密串 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请求 字段名 变量名 必填 类型 说明 协议参数 签名方式 sign_type 否 String(8) 签名类型，取值:MD5、RSA，默认:MD5 字符集 input_charset 否 String(8) 字符编码,取值:GBK、UTF-8，默认:GBK。 签名 sign 是 String(32) 签名 密钥序号 sign_key_index 否 Int 多密钥支持的密钥序号，默认1 业务参数 是 String(10) 商户号,由财付通统一分配的10位正整数商户号 partner (120XXXXXXX)号 否 String(32) 商户系统内部的订单号, out_trade_no和商户订单号 out_trade_no transaction_id至少一个必填，同时存在时 transaction_id优先 否 String(28) 财付通交易号, out_trade_no和财付通订单号 transaction_id transaction_id至少一个必填，同时存在时 transaction_id优先 是 String(32) 商户退款单号，32个字符内、可包含字母,确商户退款单号 out_refund_no 保在商户系统唯一 总金额 total_fee 是 Int 订单总金额，单位为分 退款金额 refund_fee 是 Int 退款总金额,单位为分,可以做部分退款 操作员 op_user_id 是 Int 操作员帐号,默认为商户号 操作员密码 op_user_passwd 是 String(32) 操作员密码,默认为商户后台登录密码 接收人帐号 recv_user_id 否 String(64) 转账退款接收退款的财付通帐号。 一般无需填写，只有退银行失败，资金转入商 户号现金账号时(即状态为转入代发，查询返 回的refund_status是7或11)，填写原退款 单号并填写此字段，资金才会退到指定财付通 账号。其他情况此字段忽略 接收人姓名 reccv_user_name 否 String(32) 转账退款接收退款的姓名(需与接收退款的财 付通帐号绑定的姓名一致) 7.4.4 应答参数列表 数据按XML的格式实时返回 字段名 变量名 必填 类型 说明 协议参数 签名方式 sign_type 否 String(8) 签名类型，取值:MD5、RSA，默认:MD5 字符集 input_charset 否 String(8) 字符编码,取值:GBK、UTF-8，默认:GBK。 签名 sign 是 String(32) 签名 业务参数 返回状态码 retcode 是 Int 返回状态码，0表示成功，其他未定义 返回信息 retmsg 否 String(64) 返回信息，如非空，为错误原因。 商户号 partner 是 String(10) 商户号 财付通订单号 transaction_id 是 String(28) 财付通交易号 商户订单号 out_trade_no 是 String(32) 商户系统内部的订单号 商户退款单号 out_refund_no 是 String(32) 商户退款单号 财付通退款单是 String(28) refund_id 财付通退款单号 号 退款渠道 refund_channel 是 Int 退款渠道,0:退到财付通、1:退到银行 退款金额 refund_fee 是 Int 退款总金额,单位为分,可以做部分退款 是 Int 退款状态 1:待审批 退款状态 refund_status 2:审批流程中 3:审批失败 4:退款成功 5:退款失败 6:资料重填 7:转入代发 8:暂不处理 9:退款流程中 10:转入代发成功 11:转入代发中 12:分账回退中 13:分帐回退成功 接收人帐号 recv_user_id 否 String(64) 转账退款接收退款的财付通帐号 接收人姓名 reccv_user_name 否 String(32) 转账退款接收退款的姓名(需与接收退款的财 付通帐号绑定的姓名一致) 7.5退款明细查询接口 7.5.1业务功能 根据商户订单号、财付通订单号、商户退款单号、财付通退款单号查询退款记录的具体信息。 7.5.2交互模式 后台系统调用交互模式 7.5.3请求参数列表 请求url: 通过get或post请求 字段名 变量名 必填 类型 说明 协议参数 签名方式 sign_type 否 String(8) 签名类型，取值:MD5、RSA，默认:MD5 字符集 input_charset 否 String(8) 字符编码,取值:GBK、UTF-8，默认:GBK。 签名 sign 是 String(32) 签名 密钥序号 sign_key_index 否 Int 多密钥支持的密钥序号，默认1 业务参数 是 String(10) 商户号,由财付通统一分配的10位正整数商户号 partner (120XXXXXXX)号 否 String(32) 商户系统内部的订单号, out_trade_no和 transaction_id、out_refund_no、refund_id 至少一个必填，同时存在时以优先级高为准，商户订单号 out_trade_no 优先级为: refund_id>out_refund_no>transaction_id> out_trade_no 否 String(28) 财付通订单号, out_trade_no和 transaction_id、out_refund_no、refund_id 至少一个必填，同时存在时以优先级高为准，财付通订单号 transaction_id 优先级为: refund_id>out_refund_no>transaction_id> out_trade_no 否 String(32) 商户退款单号, out_trade_no和 transaction_id、out_refund_no、refund_id 至少一个必填，同时存在时以优先级高为准，商户退款单号 out_refund_no 优先级为: refund_id>out_refund_no>transaction_id> out_trade_no 否 String(28) 财付通退款单号, out_trade_no和 transaction_id、out_refund_no、refund_id财付通退款单至少一个必填，同时存在时以优先级高为准， refund_id 号 优先级为: refund_id>out_refund_no>transaction_id> out_trade_no 7.5.4应答参数列表 数据按XML的格式实时返回 字段名 变量名 必填 类型 说明 协议参数 签名方式 sign_type 否 String(8) 签名类型，取值:MD5、RSA，默认:MD5 字符集 input_charset 否 String(8) 字符编码,取值:GBK、UTF-8，默认:GBK。 签名 sign 是 String(32) 签名 业务参数 返回状态码 retcode 是 Int 返回状态码，0表示成功，其他未定义 返回信息 retmsg 否 String(64) 返回信息，如非空，为错误原因。 商户号 partner 是 String(10) 商户号 商户订单号 out_trade_no 是 String(32) 商户系统内部的订单号 财付通订单号 transaction_id 是 String(28) 财付通交易号 退款笔数 refund_count 是 Int 退款记录数 是 String(32) 商户退款单号，32个字符内、可包含字母,确商户退款单号 out_refund_no_$n 保在商户系统唯一 财付通退款单是 String(28) refund_id_$n 财付通退款单号 号 是 Int 退款类型,0为b2c退款、1为分账回退、2为退款类型 refund_type_$n 分账退款(包含分账退款、b2c退款) Refund_channel_$是 Int 退款渠道 退款渠道,0退到财付通、1退到银行 n 退款金额 refund_fee_$n 是 Int 退款总金额,单位为分,可以做部分退款 是 Int 退款状态 1:待审批 退款状态 refund_status_$n 2:审批流程中 3:审批失败 4:退款成功 5:退款失败 6:资料重填 7:转入代发 8:暂不处理 9:退款流程中 10:转入代发成功 11:转入代发中 12:分账回退中 13:分帐回退成功 接收人帐号 recv_user_id_$n 否 Int 转账退款接收退款的财付通帐号 接收人姓名 reccv_user_name_否 String(32) 转账退款接收退款的姓名(需与接收退款的财 $n 付通帐号绑定的姓名一致) PS: $n表示记录的序号，取值为0~($ refund_count -1)，例如refund_count指示返回的退款记录有2条。第一条序号为“0”，第二条序号为“1”。 8 实例 假设场景如下: 商户开了一个服装网店，售卖各种男女式衬衫，一名用户小A在网店中选购了一件男式衬衫，然后通过财付通的账户支付了货款，商户在收到财付通的支付成功通知后，主动又发起一次通知查询请求，财付通实时返回了通知的内容，然后商户确认交易成功并提示用户注意查收货物。过了一天小A又登录到商户网站上查询自己的订单状态，此时商户系统根据小A的订单号向财付通发起订单查询请求，财付通实时返回了订单的详细信息，商户根据收到的订单信息再结合自己的发货情况给小A返回了一个完整的订单执行情况。小A高兴地看到自己的衬衫已经发出。 业务流程实现如下: 支付请求: ;bank_type=&body=男士衬衫一件&return_url=;notify_url= notify.jsp&partner=1200000107&out_trade_no=2010051111380001&total_fee=19800&spbill_create_ip=192.168.0.122&sign=8DB4A013A8B515349C307F1E448CE836 支付返回结果: ;pay_info=&partner=1200000107&bank_type=&total_fee=19800¬ify_id=123456789012345678901234567890&transaction_id=1200000107201005111153328847&out_trade_no=2010051111380001&time_end=20100511115436&sign=8DB4A01356B515349C30788E448CE836 支付成功通知: ;pay_info=&partner=1200000107&bank_type=&total_fee=19800¬ify_id=123456789012345678901234567890&transaction_id=1200000107201005111153328847&out_trade_no=2010051111380001&time_end=20100511115436&sign=8DB4A01356B515349D30788E448CE836 商户接到通知后返回处理结果: success 商户根据通知ID发起通知查询请求: ;notify_id=123456789012345678901234567890&sign=8DB4A01345B515349C30788E448CE836 财付通返回通知查询结果: 0 0 1200000107 19800 1200000107201005111153328847 2010051111380001 20100511115436 8DB4A013A8B515347C307F1E448CE836 第二天商户向财付通发起订单查询请求: ;out_trade_no=2010051111380001 财付通返回订单查询结果: 0 0 1200000107 19800 1200000107201005111153328847 2010051111380001 20100511115436 false false 8DB4A013A8B515347C307F1E878CE836 9 注意事项 1、 out_trade_no需要保证在商户号下全局唯一，建议使用“日期+序列号”的方式。如果out_trade_no相同， 其它核心信息不同，财付通会拒绝支付;如果out_trade_no相同，其它核心信息也相同，财付通会当同个 订单处理。 2、 所有涉及到金额的单位都是分，最小的单位是1分，不能有小数出现 3、 notify_url是财付通服务器从后台直接发起请求到商户服务器，商户处理时不能检查用户的cookie或 session;商户更新DB等发货流程需要完整在notify_url完成，以确保掉单时，财付通补单能成功补上 4、 notify_url有可能重复通知，商户需要做去重处理，避免多次发货 5、 notify_url收到的通知，商户处理成功或检查订单已经处理，需要返回处理成功的标志“success”，以告 知财付通不再通知 6、 notify_id的有效期是2分钟，请商户收到通知后尽快发起查询 7、 为了防止诈骗，支付时财付通会获取HTTP相关信息与申请的域名相比较。为了保证HTTP相关信息能正常， 跳转到财付通支付网关时，不要使用window.location.href、window.open跳转，可以使用form表单提交、 方式跳转、HTTP头的redirect跳转。