财付通接口

目前做的测试版本为无验证支付，只需要输入借记卡，以及开卡基本信息就可以，只要把例子里面的方法改成接口便可

例子下载

http://download.csdn.net/detail/qq873113580/5980471

 

下面是开发指南

 

 

 

财付通无卡支付开发指南

 

 

 

 

 

目  录

1....引言.......................................................... 4

1.1       文档概述............................................................................ 4

1.2       阅读对象............................................................................ 4

1.3       业务术语............................................................................ 4

2....方案概述...................................................... 5

2.1       行业背景............................................................................ 5

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       后台通知结果反馈............................................................. 17

7.2       验证码确认接口..................................................................... 17

7.2.1       业务功能..................................................................... 17

7.2.2       交互模式..................................................................... 17

7.2.3       请求参数列表................................................................. 17

7.2.4       应答参数列表................................................................. 18

7.3       通知查询接口....................................................................... 20

7.3.1       业务功能..................................................................... 20

7.3.2       交互模式..................................................................... 20

7.3.3       请求参数列表................................................................. 20

7.3.4       应答参数列表................................................................. 20

7.4       订单查询接口....................................................................... 22

7.4.1       业务功能..................................................................... 22

7.4.2       交互模式..................................................................... 22

7.4.3       请求参数列表................................................................. 22

7.4.4       应答参数列表................................................................. 23

7.4退款接口............................................................................. 24

7.4.1业务功能....................................................................... 24

7.4.2交互模式....................................................................... 25

7.4.3请求参数列表................................................................... 25

7.4.4       应答参数列表................................................................. 26

7.5退款明细查询接口..................................................................... 28

7.5.1业务功能....................................................................... 28

7.5.2交互模式....................................................................... 28

7.5.3请求参数列表................................................................... 28

7.5.4应答参数列表................................................................... 29

8....实例......................................................... 31

9....注意事项..................................................... 33

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    行业背景

财付通无卡支付是一款网上无磁支付产品，是对传统网上POS产品的优化升级。用户只要身份信息、手机号、卡号在银行端验证通过，就可通过卡号、有效期信息、CVV码或者取款密码即时完成支付。 不需要开通网银、不需要签约、额度大、支持存量卡和联名卡。

应用场景除了电子机票、酒店预订等实名制行业外，还应用于实物，如网上商城上有收货地址的实物交易场景。

2.2    接口介绍

 

接口名	请求URL	功能说明	结果说明
支付接口	https://mch.tenpay.com/cgi-bin/pay_i_access.cgi	调用该接口时指定支付参数，完成买家账户向商家账户的支付，采用后台系统调用交互模式和后台通知交互模式	结果分两路返回：一路为实时返回XML格式的信息；一路为后台在notify_url后添加参数返回，要求后台notify_url收到通知后进行响应。
验证码验证接口	https://mch.tenpay.com/cgi-bin/pay_i_verify.cgi	调用该接口验证验证码的有效性	验证结果以XML格式实时返回
通知查询接口	https://mch.tenpay.com/cgi-bin/fpay_querynotifyid.cgi	商户在收到后台通知后根据通知ID向财付通发起通知内容的查询，采用后台系统调用交互模式	财付通把具体的通知内容按XML格式实时返回
订单查询接口	https://mch.tenpay.com/cgi-bin/fpay_queryorder.cgi	商户在后台对任意一笔订单发起查询，采用后台系统调用交互模式	根据订单号以XML格式返回具体的订单内容和状态
退款接口	https://mch.tenpay.com/refundapi/gateway/refund.xml	商户在后台对一笔已支付订单发起退款，采用后台系统调用交互模式	退款成功、失败或者退款流程中的结果实时返回
退款明细查询接口	https://gw.tenpay.com/gateway/normalrefundquery.xml	根据退款ID查询具体的退款明细	退款明细数据实时返回

 

2.3    业务实现流程

2.3.1   电话回呼流程：

2.3.2       验证码验证流程：

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

采用HTTPS标准的GET或POST协议，为了保证接收方接收数据正确，传递的参数如果存在特殊字符（如&、=等）需要进行URL Encode。

GET或POST一般用于页面跳转交互模式的请求和通知、后台系统调用模式的请求、后台通知模式的请求。

4.2    XML数据格式

采用标准XML协议，所有参数只存在一级节点中，不采用多级节点嵌套。

<?xmlversion="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    字符串格式

直接以简单字符串作为数据内容，一般用于后台通知模式的接口反馈，表示处理是否成功。

 

返回结果	结果说明
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或超时，财付通认为通知失败，财付通会通过一定的策略定期重新发起通知，尽可能提高通知的成功率,但财付通不保证通知最终能成功。

由于存在重新发送后台通知的情况，因此同样的通知可能会多次发送给商户系统。商户系统必须能够正确处理重复的通知。

财付通推荐的做法是，当收到通知进行处理时，首先检查对应业务数据的状态，判断该通知是否已经处理过，如果没有处理过再进行处理，如果处理过直接返回success。在对业务数据进行状态检查和处理之前，要采用数据锁进行并发控制，以避免函数重入造成的数据混乱。

7  接口

7.1    支付接口

7.1.1       业务功能

买家在商户网站拍下商品后，商户系统调用财付通无卡支付接口，财付通处理扣款后直接返回结果（XML），同时服务器后台通知商户（notify_url）支付结果。

7.1.2       交互模式

后台调用交互模式+后台通知交互模式

7.1.3       请求参数列表

请求url：https://mch.tenpay.com/cgi-bin/pay_i_access.cgi

通过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)	银行类型，工行:ICBC，建行CCB,详情见9节银行列表
商品描述	body	是	String(32)	商品描述
附加数据	attach	否	String(255)	附加数据，原样返回
通知URL	notify_url	是	String(255)	接收财付通通知的URL，需给绝对路径，255字符内，格式如:http://wap.tenpay.com/ 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。该时间取自商户服务器。默认最长时间为24小时。
物流费用	transport_fee	否	Int	物流费用，单位为分。如果有值，必须保证transport_fee +  product_fee=total_fee
商品费用	product_fee	否	Int	商品费用，单位为分。如果有值，必须保证transport_fee + product_fee=total_fee
商品标记	goods_tag	否	String(32)
补充信息	additional_info	是	String(255)	该字段填写内容为： 机票：乘机人（姓名、证件类型和证件号码）、航班信息（名称、时间）、乘机人或联系人联系方式，共计6项内容。保险、旅游类的暂同机票类填写实际受保人或旅客的姓名，证件类型，证件号码，联系方式和商品名称。 说明：多张机票多个乘机人，填写其中一个的对应信息。 例： 格式为：行业类型^实际附加信息（都用^号分隔）  例如： 1^XXX姓名^身份证^410101XXXXX身份证号^北京--上海^2011-10-09^189XXXXXXXX手机号码
配送信息	delivery_info	否	String(255)	配送信息
卡类型	account_type	是	string（4）	银行类型：1 借记卡；2 信用卡
银行卡号	account_no	是	String(32)	银行卡号
客户姓名	account_name	是	String(64)	客户姓名
信用卡有效期	credit_valid	否	String(6)	若银行类型为信用卡，则必填。信用卡有效期,YYMM
证件类型	cert_type	是	Int	1身份证；2护照；3军官证；4士兵证；5回乡证；6临时身份证；7户口簿；8警官证；9台胞证；10营业执照；11其它证件
证件号码	cert_id	是	String(32)	证件号码
手机号码	mobile_number	是	String(32)	持卡人登记的手机号码，为裸号，不带国家码和地区号，如：13812345678
拨打号码	call_number	否	String(32)	持卡人的拨打号码，不带国家码
信用卡安全码	credit_cvv2	否	String(10)	信用卡CVV,3位数字
开户地区	account_area	否	string(6)	财付通提供的开户地区编码，暂时无需填写
开户城市	account_city	否	string(6)	财付通提供的开户城市编码，暂时无需填写
操作员	op_user_id	是	Int	操作员帐号,默认为商户号
操作员密码	op_user_passwd	是	String(32)	操作员密码,默认为商户后台登录密码，需MD5加密。
验证方式	verify_type	是	Int	支付渠道标识，取值0 默认指定方式，会转化为以下方式中的一种； 1 不校验，（此验证方式少量由于风控因素有可能转化为2）； 2 通过商户获取验证码校验； 3 电话支付回呼；

 

7.1.4       返回结果和通知参数列表

数据按XML的格式实时返回，后台通知通过请求中的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
业务参数
返回状态码	retcode	否	Int	返回状态码，0表示成功，其他错误。 XML数据返回时才有此字段，且是一定返回。
返回信息	retmsg	否	String(64)	返回信息，如非0，为错误原因。 XML数据返回时才有此字段
交易状态	trade_state	是	Int	支付结果： 0 支付成功； 1 等待验证； 2 失败
交易结果信息	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-人民币
财付通订单号	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
验证方式	verify_type	是	Int	支付渠道标识，与原传值可能发生变化，已返回为准； 1 不校验，（此验证方式少量由于风控因素有可能转化为2）； 2 通过商户获取验证码校验； 3 电话支付回呼；

 

通知中参数，包含如下内容：

 

字段名	变量名	必填	类型	说明
协议参数
签名方式	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
业务参数
交易状态	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
验证方式	verify_type	是	Int	支付渠道标识，与原传值可能发生变化，已返回为准； 1 不校验，（此验证方式少量由于风控因素有可能转化为2）； 2 通过商户获取验证码校验； 3 电话支付回呼；

 

7.1.5       后台通知结果反馈

财付通后台通过notify_url通知商户，商户做业务处理后，需要以字符串的形式反馈处理结果，内容如下：

 

返回结果	结果说明
success	处理成功，财付通系统收到此结果后不再进行后续通知
fail或其它字符	处理不成功，财付通收到此结果或者没有收到任何结果，系统通过补单机制（详见第6节）再次通知

 

7.2    验证码确认接口

7.2.1       业务功能

商户接收到用户的验证码后，可以通过此接口发送验证码给财付通，财付通验证正确后完成支付。

7.2.2       交互模式

后台系统调用交互模式

7.2.3       请求参数列表

请求url：https://mch.tenpay.com/cgi-bin/pay_i_verify.cgi

通过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)号
验证码	verify_id	是	String(10)	短信验证码
商户订单号	out_trade_no	否	String(32)	商户系统内部的订单号, out_trade_no和transaction_id至少一个必填，同时存在时transaction_id优先
财付通订单号	transaction_id	否	String(28)	财付通交易号, out_trade_no和transaction_id至少一个必填，同时存在时transaction_id优先。对于采用财付通其他支付接口（非本文档7.1接口），查询时只能使用transaction_id，不能使用out_trade_no
手机号码	mobile_number	是	String(32)	用户获取验证码的手机号码，为裸号，不带国家码和地区号，如：13812345678
操作员	op_user_id	是	Int	操作员帐号,默认为商户号
操作员密码	op_user_passwd	是	String(32)	操作员密码,默认为商户后台登录密码，需MD5加密。

 

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表示成功，其他错误 XML数据返回时才有此字段，且是一定返回
返回信息	retmsg	否	String(64)	返回信息，如非0，为错误原因。 XML数据返回时才有此字段
交易状态	trade_state	是	Int	支付结果： 0 支付成功； 1 等待验证； 2 失败
交易结果信息	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-人民币
财付通订单号	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

 

 

7.3    通知查询接口

7.3.1       业务功能

(客户通过之后直接返回，后台再去干点啥，会返回一个ID区查到是否对应支付，然后在返回)

商户接收到财付通的支付成功通知后，可以通过此接口查询通知的具体内容，以确保通知是从财付通发起的，没有被伪造或篡改过。

7.3.2       交互模式

后台系统调用交互模式

7.3.3       请求参数列表

请求url：https://mch.tenpay.com/cgi-bin/fpay_querynotifyid.cgi

通过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
操作员	op_user_id	是	Int	操作员帐号,默认为商户号
操作员密码	op_user_passwd	是	String(32)	操作员密码,默认为商户后台登录密码，需MD5加密。

 

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表示成功，其他错误 XML数据返回时才有此字段，且是一定返回
返回信息	retmsg	否	String(64)	返回信息，如非0，为错误原因。 XML数据返回时才有此字段
交易状态	trade_state	是	Int	支付结果： 0 支付成功； 1 等待验证； 2 失败
交易结果信息	pay_info	否	String(64)	交易结果信息
商户号	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
验证方式	verify_type	是	Int	支付渠道标识，取值0默认指定方式，会转化为以下方式中的一种； 1 不校验，（此验证方式少量由于风控因素有可能转化为2）； 2 通过商户获取验证码校验； 3 电话支付回呼；

 

 

7.4    订单查询接口

7.4.1       业务功能

根据商户订单号或者财付通订单号查询财付通侧记录的具体订单信息。

7.4.2       交互模式

后台系统调用交互模式

7.4.3       请求参数列表

请求url：https://mch.tenpay.com/cgi-bin/fpay_queryorder.cgi

通过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)号
商户订单号	out_trade_no	否	String(32)	商户系统内部的订单号, out_trade_no和transaction_id至少一个必填，同时存在时transaction_id优先
财付通订单号	transaction_id	否	String(28)	财付通交易号, out_trade_no和transaction_id至少一个必填，同时存在时transaction_id优先。对于采用财付通其他支付接口（非本文档7.1接口），查询时只能使用transaction_id，不能使用out_trade_no

 

7.4.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表示成功，其他错误 XML数据返回时才有此字段，且是一定返回
返回信息	retmsg	否	String(64)	返回信息，如非0，为错误原因。 XML数据返回时才有此字段
交易状态	trade_state	是	Int	支付结果： 0 支付成功； 1 等待验证； 2 失败
交易结果信息	pay_info	否	String(64)	交易结果信息
商户号	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
验证方式	verify_type	是	Int	支付渠道标识，取值0默认指定方式，会转化为以下方式中的一种； 1 不校验，（此验证方式少量由于风控因素有可能转化为2）； 2 通过商户获取验证码校验； 3 电话支付回呼；

 

7.5退款接口

7.5.1业务功能

商户针对某一个已经成功支付的订单发起退款，操作结果在同一会话中同步返回。

一、退款方式

1.退款到支付所用的信用卡，财付通商户管理系统上显示退款方式为“信用卡退款”

2.当退银行时，如果退银行失败，资金会退到商户号的现金账号中，商户可以登录mch.tenpay.com手工处理或调用转账退款接口退给指定财付通账号。

说明：退到银行卡则是非实时的，每个银行的处理速度不同，一般发起退款后1-10个工作日内到账。

二、退款限制

商户在退款操作时应该注意退款限制，避免发起不会成功的退款请求，下面是主要的退款限制：

1.在财付通系统中，只要退款累计金额不超过交易单支付总额，一笔交易单可以多次退款，退款申请单号（退款接口中有此参数）唯一确定一次退款，而不是交易单号确定一次退款。退款申请单号由商户生成，所以商户一定要保证退款申请单的唯一性。商家在退款过程中要特别注意，只有在能确定退款失败的情况下，才能重新发起另一笔退款。

2.目前大多数银行都支持全额退款和部分退款，但是也有少数银行不支持全额退款或部分退款，或者不支持退款。在这种情况下，商户可以与买家协调，退到指定的财付通帐号。

7.5.2交互模式

后台系统调用交互模式

7.5.3请求参数列表

请求url：https://mch.tenpay.com/refundapi/gateway/refund.xml

通过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
业务参数
商户号	partner	是	String(10)	商户号,由财付通统一分配的10位正整数(120XXXXXXX)号
商户订单号	out_trade_no	否	String(32)	商户系统内部的订单号, out_trade_no和transaction_id至少一个必填，同时存在时transaction_id优先
财付通订单号	transaction_id	否	String(28)	财付通交易号, out_trade_no和transaction_id至少一个必填，同时存在时transaction_id优先
商户退款单号	out_refund_no	是	String(32)	商户退款单号，32个字符内、可包含字母,确保在商户系统唯一。同个退款单号多次请求，财付通当一个单处理，只会退一次款。如果出现退款不成功，请采用原退款单号重新发起，避免出现重复退款。
总金额	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.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)	商户号
财付通订单号	transaction_id	是	String(28)	财付通交易号
商户订单号	out_trade_no	是	String(32)	商户系统内部的订单号
商户退款单号	out_refund_no	是	String(32)	商户退款单号
财付通退款单号	refund_id	是	String(28)	财付通退款单号
退款渠道	refund_channel	是	Int	退款渠道,0:退到财付通、1:退到银行
退款金额	refund_fee	是	Int	退款总金额,单位为分,可以做部分退款
退款状态	refund_status	是	Int	退款状态 1:待审批 2:审批流程中 3:审批失败 4:退款成功 5:退款失败 6:资料重填 7:转入代发 8:暂不处理 9:退款流程中 10:转入代发成功 11:转入代发中 12:分账回退中 13:分帐回退成功
接收人帐号	recv_user_id	否	String(64)	转账退款接收退款的财付通帐号
接收人姓名	reccv_user_name	否	String(32)	转账退款接收退款的姓名(需与接收退款的财付通帐号绑定的姓名一致)

 

7.6退款明细查询接口

7.6.1业务功能

根据商户订单号、财付通订单号、商户退款单号、财付通退款单号查询退款记录的具体信息。

7.6.2交互模式

后台系统调用交互模式

7.6.3请求参数列表

请求url： https://gw.tenpay.com/gateway/normalrefundquery.xml

通过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
业务参数
商户号	partner	是	String(10)	商户号,由财付通统一分配的10位正整数(120XXXXXXX)号
商户订单号	out_trade_no	否	String(32)	商户系统内部的订单号, out_trade_no和transaction_id、out_refund_no、refund_id至少一个必填，同时存在时以优先级高为准，优先级为： refund_id>out_refund_no>transaction_id>out_trade_no
财付通订单号	transaction_id	否	String(28)	财付通订单号, out_trade_no和transaction_id、out_refund_no、refund_id至少一个必填，同时存在时以优先级高为准，优先级为： refund_id>out_refund_no>transaction_id>out_trade_no
商户退款单号	out_refund_no	否	String(32)	商户退款单号, out_trade_no和transaction_id、out_refund_no、refund_id至少一个必填，同时存在时以优先级高为准，优先级为： refund_id>out_refund_no>transaction_id>out_trade_no
财付通退款单号	refund_id	否	String(28)	财付通退款单号, out_trade_no和transaction_id、out_refund_no、refund_id至少一个必填，同时存在时以优先级高为准，优先级为： refund_id>out_refund_no>transaction_id>out_trade_no

 

7.6.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	退款记录数
商户退款单号	out_refund_no_$n	是	String(32)	商户退款单号，32个字符内、可包含字母,确保在商户系统唯一
财付通退款单号	refund_id_$n	是	String(28)	财付通退款单号
退款渠道	Refund_channel_$n	是	Int	退款渠道,0退到财付通、1退到银行
退款金额	refund_fee_$n	是	Int	退款总金额,单位为分,可以做部分退款
退款状态	refund_state_$n	是	Int	退款状态 1:待审批 2:审批流程中 3:审批失败 4:退款成功 5:退款失败 6:资料重填 7:转入代发 8:暂不处理 9:退款流程中 10:转入代发成功 11:转入代发中 12:分账回退中 13:分帐回退成功
接收人帐号	recv_user_id_$n	否	Int	转账退款接收退款的财付通帐号
接收人姓名	reccv_user_name_$n	否	String(32)	转账退款接收退款的姓名(需与接收退款的财付通帐号绑定的姓名一致)

 

PS:

    $n表示记录的序号，取值为0~($ refund_count -1)，例如refund_count指示返回的退款记录有2条。第一条序号为“0”，第二条序号为“1”。

8  注意事项

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分钟，请商户收到通知后尽快发起查询

9  银行列表

 

银行		直接扣款		短信扣款		回呼扣款
		是否开通	额度	是否开通	额度	是否开通	额度
信用卡	工商银行 ICBC	Y	5000	Y	5000	-	-
	农业银行 ABC	Y	5000	Y	5000	-	-
	建设银行 CCB	Y	5000	Y	5000	-	-
	中国银行 BOC	Y	5000	Y	5000	-	-
	光大银行 CEB	Y	5000	Y	5000	-	-
	平安银行 PAB	Y	5000	Y	5000	-	-
借 记 卡	农业银行ABC	Y	5000	Y	5000	Y	5000
	建设银行 CCB	Y	5000	Y	5000	-	-
	光大银行 CEB	Y	5000	Y	5000	-	-
	交通银行COMM	-	-	-	-	Y	5000
	招商银行 CMB	-	-	-	-	Y	5000
	中信银行 CITIC	-	-	-	-	Y	5000
5000元是标准开放额度，具体额度可根据商户价值另行商量。

 

 

 

{notify_url}?bank_billno=208168976312&fee_type=1&notify_id=87FACA9B64178BE121BF2FA90923A0E607DCF77831B79949C366AFBFFCB929DB2724DF66446890651E6456CF6FBDEC0F&out_trade_no=2013081609530A&partner=1900000109&product_fee=1&time_end=2013-08-16+09%3A39%3A39&total_fee=1&trade_state=0&transaction_id=1900000109201308160339227905&transport_fee=0&sign=f9887a89d7f5b1b86678e14dae6f8a38