腾讯财付通接口的开发.docx
- 文档编号:30029412
- 上传时间:2023-08-04
- 格式:DOCX
- 页数:43
- 大小:79.94KB
腾讯财付通接口的开发.docx
《腾讯财付通接口的开发.docx》由会员分享,可在线阅读,更多相关《腾讯财付通接口的开发.docx(43页珍藏版)》请在冰豆网上搜索。
腾讯财付通接口的开发
财付通支付网关商户开发指南
目录
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.1GET或POST8
4.2XML数据格式9
4.3字符串格式9
5数字签名9
5.1签名原始串10
5.2签名算法10
5.2.1MD5签名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后台通知结果反馈14
7.2通知查询接口15
7.2.1业务功能15
7.2.2交互模式15
7.2.3请求参数列表15
7.2.4应答参数列表16
7.3订单查询接口17
7.3.1业务功能17
7.3.2交互模式17
7.3.3请求参数列表17
7.3.4应答参数列表18
7.4退款接口20
7.4.1业务功能20
7.4.2交互模式20
7.4.3请求参数列表20
7.4.4应答参数列表21
7.5退款明细查询接口23
7.5.1业务功能23
7.5.2交互模式23
7.5.3请求参数列表23
7.5.4应答参数列表24
8实例26
9注意事项28
引言
文档概述
本文描述了财付通针对合作商户提供的支付解决方案,帮助商户轻松实现在线收款的功能。
文档分别从交互模式、签名、接口、注意事项等方面详细介绍了财付通的工作方式和开发过程,可以帮助开发人员快速入门并掌握开发技能,同时也可以作为日后接口参数以及参数类型的速查手册。
阅读对象
合作商户系统的技术开发人员,要求具有WEB程序开发背景,了解http和https请求和应答的格式和过程,对XML格式有所掌握。
业务术语
术语
示例
说明
商户号
1900000107
机票平台的账号,只用于记账,由财付通自动分配的10位数字
密钥
9ba2380ad9b2aacb96bca514eda27ac9
为保证通讯不被篡改,财付通与商户之间约定的32位字符串,算签名sign时使用
账户
jpgyf@
财付通账户号,目前支持两种格式:
qq号码和email账户
金额
100000
金额,默认为RMB,以分为单位。
1000表示RMB10.00
方案概述
行业背景
在电子商务中,商家、买家、中间服务方是交易活动中的三个环节。
买家选购商品下发订单,商家确认订单,买家通过中间服务方向商家支付货款,商家发货履行订单。
在这个过程中商家的网站需要集成中间服务方的支付功能,让买家完成货款的支付。
财付通作为一家专业的中间服务方除了提供支付接口外,还提供了支付结果查询接口和订单查询接口等,帮助商家记录货款的往来,让商家能把更多的精力集中到商品服务上。
商户的货款会按照合同约定以T0~T7的频率结算到商户的银行账户,同时收取手续费。
这个过程由财付通自动完成,商户无需做相关开发工作。
接口介绍
接口名
请求URL
功能说明
结果说明
支付接口
调用该接口时指定支付参数,完成买家账户向商家账户的支付,采用页面跳转交互模式和后台通知交互模式
结果分两路返回:
一路为前台在return_url后添加参数返回,表现为页面跳转;一路为后台在notify_url后添加参数返回,要求后台notify_url收到通知后进行响应。
通知查询接口
商户在收到后台通知后根据通知ID向财付通发起通知内容的查询,采用后台系统调用交互模式
财付通把具体的通知内容按XML格式实时返回
订单查询接口
商户在后台对任意一笔订单发起查询,采用后台系统调用交互模式
根据订单号以XML格式返回具体的订单内容和状态
退款接口
商户在后台对一笔已支付订单发起退款,采用后台系统调用交互模式
退款成功、失败或者退款流程中的结果实时返回
退款明细查询接口
根据退款ID查询具体的退款明细
退款明细数据实时返回
业务实现流程
2.0调用支付接口进行支付后,财付通返回支付结果给前台页面,同时会向商户的服务器发送支付是否成功的通知
3.0商户服务器在收到支付结果通知后可以根据通知ID查询通知内容,在确保支付成功后再向用户发送提示信息,这样可以进一步提高安全性,防止伪支付成功结果的诈骗。
交互模式
页面跳转交互模式
页面跳转交互模式是指商户系统与财付通系统的数据交互通过用户浏览器中转进行,是一种非实时的异步交互。
如买家下单买一个商品,商户系统会生成一个支付链接,此链接通过用户的浏览器跳转到财付通系统,财付通通过此链接获取支付请求的参数,这个支付请求用的就是页面跳转交易模式。
用户在财付通页面完成支付后,财付通通过return_url跳转到商户系统。
后台系统调用交互模式
后台系统调用交互模式是指商户系统向财付通系统发送请求数据,并同步等待财付通系统处理完毕后返回的响应数据。
数据交互是商户服务器与财付通服务器直接通信,一般请求采用http的get或post,应答采用xml数据格式。
如用户在商户系统查询时,商户要确认用户某个订单是否支付成功,可以在服务器上发送一个查询请求,财付通收到请求后把查询结果以xml格式返回给商户,商户处理结果后再显示给用户。
后台通知交互模式
后台通知交互模式是指财付通系统主动向商户系统发送通知数据,并同步等待商户系统处理完毕后返回的响应数据。
数据交互是财付通服务器与商户服务器直接通信,一般请求采用http的get或post,应答用字符串格式。
如用户在财付通支付成功后,财付通会在后台通过notify_url向商户系统发起通知,商户处理后成功返回success,失败返回fail或其他字符。
数据格式
GET或POST
采用HTTP标准的GET或POST协议,为了保证接收方接收数据正确,传递的参数如果存在特殊字符(如&、=等)需要进行URLEncode。
GET或POST一般用于页面跳转交互模式的请求和通知、后台系统调用模式的请求、后台通知模式的请求。
XML数据格式
采用标准XML协议,所有参数只存在一级节点中,不采用多级节点嵌套。
xmlversion="1.0"encoding="gb2312"?
>
一般有返回码retcode参数,0表示调用成功;非0表示调用失败,失败时结果不签名,只有retcode和返回信息retmsg。
XML一般用于后台系统调用模式的应答。
字符串格式
直接以简单字符串作为数据内容,一般用于后台通知模式的接口反馈,表示处理是否成功。
返回结果
结果说明
success
处理成功,财付通系统收到此结果后不再进行后续通知
fail或其他字符
处理不成功,财付通收到此结果或者没有收到任何结果,系统通过补单机制(详见第6节)再次通知
数字签名
为了保证数据传输过程中的数据真实性和完整性,我们需要对数据进行数字签名,在接收签名数据之后进行签名校验。
数字签名有两个步骤,先按一定规则拼接要签名的原始串,再选择具体的算法和密钥计算出签名结果。
一般失败的结果不签名。
签名原始串
无论是用get、post还是xml,签名原始串组串方式都一致,除sign字段外,待签名参数按照字段名的ascii码从小到大排序后使用QueryString的格式(即key1=value1&key2=value2…)拼接而成,空值不传递,不参与签名。
签名时字段名和字段值都采用原始值,不进行URLEncode。
签名的字段包括请求中有所的get或post字段,除了接口中描述的字段外,还应包括请求中出现的其它字段。
签名算法
目前暂只支持MD5签名
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
补单机制
对后台通知交互模式,如果财付通收到商户的应答不是success或超时,财付通认为通知失败,财付通会通过一定的策略(如1分钟、2分钟、4分钟、8分钟、16分钟、32分钟,共6次)定期重新发起通知,尽可能提高通知的成功率,但财付通不保证通知最终能成功。
由于存在重新发送后台通知的情况,因此同样的通知可能会多次发送给商户系统。
商户系统必须能够正确处理重复的通知。
财付通推荐的做法是,当收到通知进行处理时,首先检查对应业务数据的状态,判断该通知是否已经处理过,如果没有处理过再进行处理,如果处理过直接返回success。
在对业务数据进行状态检查和处理之前,要采用数据锁进行并发控制,以避免函数重入造成的数据混乱。
接口
支付接口
业务功能
买家在商户网站拍下商品后,选择财付通付款,商户系统调用财付通支付接口,页面跳转到财付通支付中心或银行。
用户完成支付后,财付通把用户引导回商户页面(return_url),同时服务器后台通知商户服务器(notify_url)支付结果。
交互模式
请求:
页面跳转交互模式
返回结果+通知:
页面跳转交互模式+后台通知交互模式
请求参数列表
请求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+8beijing。
该时间取自商户服务器
交易结束时间
time_expire
否
String(14)
订单失效时间,格式为yyyymmddhhmmss,如2009年12月27日9点10分10秒表示为20091227091010。
时区为GMT+8beijing。
该时间取自商户服务器
物流费用
transport_fee
否
Int
物流费用,单位为分。
如果有值,必须保证transport_fee+product_fee=total_fee
商品费用
product_fee
否
Int
商品费用,单位为分。
如果有值,必须保证transport_fee+product_fee=total_fee
商品标记
goods_tag
否
String(32)
商品标记,优惠券时可能用到
返回结果和通知参数列表
页面返回通过请求中的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
业务参数
交易模式
trade_mode
是
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+8beijing。
该时间取自财付通服务器
物流费用
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)
对应买家账号的一个加密串
后台通知结果反馈
财付通后台通过notify_url通知商户,商户做业务处理后,需要以字符串的形式反馈处理结果,内容如下:
返回结果
结果说明
success
处理成功,财付通系统收到此结果后不再进行后续通知
fail或其它字符
处理不成功,财付通收到此结果或者没有收到任何结果,系统通过补单机制(详见第6节)再次通知
通知查询接口
业务功能
商户接收到财付通的支付成功通知后,可以通过此接口查询通知的具体内容,以确保通知是从财付通发起的,没有被伪造或篡改过。
交互模式
后台系统调用交互模式
请求参数列表
请求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
应答参数列表
数据按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)
返回信息,如非空,为错误原因。
交易模式
trade_mode
是
Int
1-即时到账
其他保留
商户号
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+8beijing。
该时间取自财付通服务器
物流费用
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)
对应买家账号的一个加密串
订单查询接口
业务功能
根据商户订单号或者财付通订单号查询财付通侧记录的具体订单信息。
交互模式
后台系统调用交互模式
请求参数列表
请求url:
通过get或post请求
字段名
变量名
必填
类型
说明
协议参数
签名
- 配套讲稿:
如PPT文件的首页显示word图标,表示该PPT已包含配套word讲稿。双击word图标可打开word文档。
- 特殊限制:
部分文档作品中含有的国旗、国徽等图片,仅作为作品整体效果示例展示,禁止商用。设计者仅对作品中独创性部分享有著作权。
- 关 键 词:
- 腾讯 财付通 接口 开发