财付通(二)

<?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字符串格式
直接以简单字符串作为数据内容，一般用于后台通知模式的接口反馈，表示处理是否成功。
返回结果    结果说明
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.1MD5签名
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）支付结果。
建议商户服务器（notify_url）接收到财付通的消息后，立即使用通知id验证接口来判定确认此通知id的真伪。
7.1.2交互模式
请求：页面跳转交互模式
返回结果+通知：页面跳转交互模式+后台通知交互模式
7.1.3请求参数列表
请求url：https://gw.tenpay.com/gateway/pay.htm
通过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)  商品描述
商品名称    subject 是   String(32)  商品名称(中介交易时必填)
附加数据    attach  否   String(255) 附加数据，原样返回
返回URL   return_url  是   String(255) 交易完成后跳转的URL，需给绝对路径，255字符内，格式如:http://wap.tenpay.com/ tenpay.asp，通过该路径直接将支付结果以Get的方式返回
通知URL   notify_url  是   String(255) 接收财付通通知的URL，需给绝对路径，255字符内，格式如:http://wap.tenpay.com/ tenpay.asp
买方财付通账号 buyer_id    否   String(64)  买方的财付通账户(QQ 或EMAIL)。若商户没有传该参数，则在财付通支付页面，买家需要输入其财付通账户。
商户号 partner 是   String(10)  签名方商户号
财付通统一分配的10位正整数(12XXXXXXXX)号
商户订单号   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 需买方另支付的物流费用, 单位为分。如已包含在商品价格中，请填写0。如果不填，默认为0。
如果有值，必须保证transport_fee + product_fee=total_fee
商品费用    product_fee 否   Int 商品费用，单位为分。如果有值，必须保证transport_fee + product_fee=total_fee
商品标记    goods_tag   否   String(32)  商品标记，优惠券时可能用到
交易模式    trade_mode  否   Int 交易模式:
1即时到账(默认) 
2中介担保
3后台选择（买家进支付中心列表选择）
物流说明    transport_desc  否   String(32)  物流公司或物流方式说明
交易类型    trans_type  否   Int 交易类型：
1、实物交易
2、虚拟交易
交易模式为中介担保时此参数有效
代理商ID   agent_id    否   String(32)  平台ID
默认空
代理模式    agent_type  否   Int 代理模式:
0、无代理(默认)
1、表示卡易售模式
2、表示网店模式
卖家商户号   seller_id   否   String(10)  为空则等同于partner
7.1.4返回结果和通知参数列表1
页面返回通过请求中的return_url进行，采用get方式
后台通知通过请求中的notify_url进行，采用get方式
此参数适用范围：即时到账交易类型
参数如下：
字段名 变量名 必填  类型  说明  范围
协议参数    
签名方式    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_mode  是   Int 1-即时到账  即时
交易状态    trade_state 是   Int 交易模式为即时到帐时,支付结果：
0交易成功   即时
支付结果信息  pay_info    是   String(64)  支付结果信息，支付成功时为空  即时
商户号 partner 是   String(10)  商户号,由财付通统一分配的10位正整数(12XXXXXXXX)号    即时
付款银行    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)  财付通交易号，28位长的数值，其中前10位为商户号，之后8位为订单产生的日期，如20090415，最后10位是流水号。 即时
商户订单号   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返回结果和通知参数列表2
页面返回通过请求中的return_url进行，采用get方式
后台通知通过请求中的notify_url进行，采用get方式
此参数适用范围：中介担保交易类型
字段名 变量名 必填  类型  说明  范围
协议参数    
签名  sign    是   String(32)  签名  中介
业务参数    
交易模式    trade_mode  是   Int 2-中介担保  中介
交易状态    trade_state 是   Int 交易模式为中介担保时,支付结果：
0付款成功
1交易创建
2收获地址填写完毕
4卖家发货成功
5买家收货确认，交易成功
6交易关闭，未完成超时关闭
7修改交易价格成功
8买家发起退款
9退款成功
10退款关闭
当中介状态被更改的时候，财付通会主动发起通知交易到notify_url。    中介
商户订单号   out_trade_no    是   String(32)  商户系统的订单号，与请求一致。 中介
通知ID    notify_id   是   String(64)  支付结果通知id，对于某些特定商户，只返回通知id，要求商户据此查询交易结果  中介
财付通订单号  transaction_id  是   String(28)  财付通交易号，28位长的数值，其中前10位为商户号，之后8位为订单产生的日期，如20090415，最后10位是流水号。 中介
商户号 partner 是   String(10)  商户号,由财付通统一分配的10位正整数(12XXXXXXXX)号    中介
7.1.6后台通知结果反馈
财付通后台通过notify_url通知商户，商户做业务处理后，需要以字符串的形式反馈处理结果，内容如下：
返回结果    结果说明
Success 处理成功，财付通系统收到此结果后不再进行后续通知
注意：在中介类交易中,财付通系统如果收不到到此反馈结果，支付参数中的return_url会被忽略，而将跳转到财付通默认的支付成功页面(请务必1：在你的idc服务器上运行、测试;2:正确返回此标识给财付通)
fail或其它字符   处理不成功，财付通收到此结果或者没有收到任何结果，系统通过补单机制（详见第6节）再次通知

7.2通知id验证接口
7.2.1业务功能
类似于通知查询接口，本接口用于快速确认通知id是否来自于财付通,但不返回该通知id详细的交易信息，只确认此通知id的有效性，是一种轻量级的消息确认接口。
通知ID具有时效性，一般用于商家收到财付通主动下发消息的二次确认。
使用此接口能确保您的订单信息安全，推荐使用。
7.2.2交互模式
后台系统调用交互模式
7.2.3请求参数列表
请求url：https://gw.tenpay.com/gateway/simpleverifynotifyid.xml
通过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位正整数(12XXXXXXXX)号
通知ID    notify_id   是   String(64)  支付成功后，财付通系统反馈的通知ID
卖家商户号   seller_id   否   String(10)  为空则等同于partner
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表示此通知id是财付通发起,并在有效期内
88222005表示通知ID超时
其它未定义

8实例
假设场景如下：
商户开了一个服装网店，售卖各种男女式衬衫，一名用户小A在网店中选购了一件男式衬衫，然后通过财付通的账户支付了货款，商户在收到财付通的支付成功通知后，主动又发起一次通知查询请求，财付通实时返回了通知的内容，然后商户确认交易成功并提示用户注意查收货物。业务流程实现如下：

支付请求:
https://gw.tenpay.com/gateway/pay.htm?sign_type=MD5&bank_type=&body=男士衬衫一件&return_url=http://www.paipai.com/shop1/payresult.jsp&notify_url=http://www.paipai.com/shop1/paynotify.jsp&partner=1200000107&out_trade_no=2010051111380001&total_fee=19800&spbill_create_ip=192.168.0.122&sign=8DB4A013A8B515349C307F1E448CE836

支付返回结果：http://www.paipai.com/shop1/payresult.jsp?pay_result=0&pay_info=&partner=1200000107&bank_type=&total_fee=19800&notify_id=123456789012345678901234567890&transaction_id=1200000107201005111153328847&out_trade_no=2010051111380001&time_end=20100511115436&sign=8DB4A01356B515349C30788E448CE836

支付成功通知：
http://www.paipai.com/shop1/paynotify.jsp?pay_result=0&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发起通知查询请求：
https://gw.tenpay.com/gateway/simpleverifynotifyid.xml?partner=1200000107&notify_id=123456789012345678901234567890&sign=8DB4A01345B515349C30788E448CE836
财付通返回通知查询结果：
<?xml version="1.0" encoding="GBK"?>
<root>
  <input_charset>GBK</input_charset>
  <partner>2000054321</partner>
  <retcode>0</retcode>
  <retmsg />
  <sign>1C58B3A778D9F49F3FA91D30E9A831D2</sign>
  <sign_key_index>1</sign_key_index>
  <sign_type>MD5</sign_type>
</root>

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表单提交、<a href=""></a>方式跳转、HTTP头的redirect跳转。
8、如果你的是铁通，电信的网络，在提交支付请求时报“验证签名失败”的错误，请把sp_create_ip字段的值.修改为%2E，签名时还是按.，这样可以解决问题