1 引言
1.1 文档概述
本文件描述财付通针对手机支付行业提供的支付解决方案。供内部相关开发和技术支持人员与商户平台服务方技术人员使用。文档分别从交互模式、签名、接口、注意事项等方面详细介绍了财付通的工作方式和开发过程，可以帮助开发人员快速入门并掌握开发技能，同时也可以作为日后接口参数以及参数类型的速查手册。
1.2 阅读对象
供财付通开发人员与商户平台服务方技术或业务人员参考和查询。
1.3 业务术语
术语 示例 说明
商户号 1900000109 机票平台的账号，只用于记账，由财付通自动分配的10位数字
密钥 9ba2380ad9b2aacb96bca514eda27ac9 为保证通讯不被篡改，财付通与商户之间约定的32位字符串，算签名sign时使用
账户 jpgyf@qq.com
财付通账户号，目前支持两种格式：qq号码和email账户
金额 100000 金额，默认为RMB，以分为单位。1000表示RMB10.00
2 方案概述
2.1 行业背景
在电子商务中，商家、买家、中间服务方是交易活动中的三个环节。买家选购商品下发订单，商家确认订单，买家通过中间服务方向商家支付货款，商家发货履行订单。在这个过程中商家的网站需要集成中间服务方的支付功能，让买家完成货款的支付。财付通作为一家专业的中间服务方除了提供支付接口外，还提供了支付结果查询接口和订单查询接口等，帮助商家记录货款的往来，让商家能把更多的精力集中到商品服务上。
商户的货款会按照合同约定以T0～T7的频率结算到商户的银行账户，同时收取手续费。这个过程由财付通自动完成，商户无需做相关开发工作。
2.2 接口介绍
接口名 请求URL 功能说明 结果说明
初始化接口 https://wap.tenpay.com/cgi-bin/wappayv2.0/wappay_init.cgi 调用该接口时指定支付参数，完成买家账户向商家账户的支付，采用页面跳转交互模式和后台通知交互模式 初始化wap请求，通过生成token_id来进行交互验证。
支付接口 https://wap.tenpay.com/cgi-bin/wappayv2.0/wappay_gate.cgi
调用该接口时指定支付参数，完成买家账户向商家账户的支付，采用页面跳转交互模式和后台通知交互模式 结果分两路返回：一路为前台在callback_url后添加参数返回，表现为页面跳转；一路为后台在notify_url后添加参数返回，要求后台notify_url收到通知后进行响应。
订单查询接口 http://wap.tenpay.com/cgi-bin/wapmainv2.0/wm_query_order.cgi 商户在后台对任意一笔订单发起查询，采用后台系统调用交互模式 根据订单号以XML格式返回具体的订单内容和状态
2.3 业务实现流程
其中蓝色直线箭头表示系统调用，黑色直线箭头表示页面跳转。
1) 商户请求交易初始化：商户根据客户的支付行为生成订单，包括商户号、商户订单号、金额、等支付要素。并提交请求进行交易初始化和获取token_id。
2) 财付通接收到商户的交易初始化请求后，系统创建财付通交易单，同时生成token_id，并返回该token_id。
3) 商户请求WAP支付：商户根据token_id生成WAP支付请求，通过页面跳转方式引导用户进入到财付通手机支付中心。
4) 用户在财付通手机支付中心完成支付后，财付通调用notify_url通知商户交易结果。
5) 商户返回通知结果：根据扣款成功通知，做发货等逻辑处理，并返回财付通处理结果。
财付通确认交易完成并回跳至商户的callback_url。
2.4 页面回跳callback_url
callback_url应为WAP页面，给买家展示支付结果。
2.5 结果通知notify_url
notify_url接收财付通从后台发出的支付结果通知。
在此通知接口模式中，商户需要确保notify_url稳定可靠。该notify_url完成接收财付通发送的支付结果信息，交易结果信息将以GET方式传递至商户。财付通只将支付成功的订单进行返回。
3 数据格式
3.1 GET或POST
采用HTTP标准的GET或POST协议，为了保证接收方接收数据正确，传递的参数如果存在特殊字符（如&、=等）需要进行URL Encode。
GET或POST一般用于页面跳转交互模式的请求和通知、后台系统调用模式的请求、后台通知模式的请求。
3.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一般用于后台系统调用模式的应答。
3.3 字符串格式
直接以简单字符串作为数据内容，一般用于后台通知模式的接口反馈，表示处理是否成功。
返回结果 结果说明
success 处理成功，财付通系统收到此结果后不再进行后续通知
fail或其他字符 处理不成功，财付通收到此结果或者没有收到任何结果，系统通过补单机制（详见第6节）再次通知
4 数字签名
为了保证数据传输过程中的数据真实性和完整性，我们需要对数据进行数字签名，在接收签名数据之后进行签名校验。
数字签名有两个步骤，先按一定规则拼接要签名的原始串，再选择具体的算法和密钥计算出签名结果。
一般失败的结果不签名。
4.1 签名原始串
无论是请求还是应答，无论是用get、post还是xml，签名原始串按以下方式组装成字符串：
1、除sign字段外，所有参数按照字段名的ascii码从小到大排序后使用QueryString的格式（即key1=value1&key2=value2…）拼接而成，空值不传递，不参与签名组串。
2、所有参数是指通信过程中实际出现的所有非空参数，即使是接口中无描述的字段，也需要参与签名组串。如退款接口中无test字段，如果商户请求时或财付通应答时，test有值，test字段也得参与参与签名组串
3、签名原始串中，字段名和字段值都采用原始值，不进行URL Encode。
4、财付通返回的应答或通知消息可能会由于升级增加参数，请验证应答签名时注意允许这种情况。
举例：
调用某个接口，接口有如下字段：
partner、total_fee、desc、attach
实际调用接口时，各字段的值：
partner=1900000109，total_fee=1，desc=a&b，attach=，test=1
正确的签名原始串是：
desc=a&b&partner=1900000109&test=1&total_fee=1
常见的错误有：
desc=a%26b&partner=1900000109&test=1&total_fee=1
desc=a&b&partner=1900000109&total_fee=1
attach=&desc=a&b&partner=1900000109&test=1&total_fee=1
partner=1900000109&total_fee=1&desc=a&b&test=1
注意：Wap支付接口中的返回结果参数列表（6.2.4）比较特殊，第2点不适合，即所有参数指的是文档中描述该接口的参数。
4.2 签名算法
目前暂只支持MD5签名
MD5签名
MD5 是一种摘要生成算法，通过在签名原始串后加上商户通信密钥的内容，进行MD5运算，形成的摘要字符串即为签名结果。为了方便比较，签名结果统一转换为大写字符。
注意：签名时将字符串转化成字节流时指定的字符集input_charset一致。
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
5 补单机制
对后台通知交互模式，如果财付通收到商户的应答不是success或超时，财付通认为通知失败，财付通会通过一定的策略（如30分钟共8次）定期重新发起通知，尽可能提高通知的成功率，但财付通不保证通知最终能成功。
由于存在重新发送后台通知的情况，因此同样的通知可能会多次发送给商户系统。商户系统必须能够正确处理重复的通知。
财付通推荐的做法是，当收到通知进行处理时，首先检查对应业务数据的状态，判断该通知是否已经处理过，如果没有处理过再进行处理，如果处理过直接返回success。在对业务数据进行状态检查和处理之前，要采用数据锁进行并发控制，以避免函数重入造成的数据混乱。
6 接口
6.1 初始化请求接口
6.1.1 业务功能
初始化wap请求，通过生成token_id来进行交互验证。
6.1.2 交互模式
请求：页面跳转交互模式
返回结果+通知：页面跳转交互模式+后台通知交互模式
6.1.3 请求参数列表
请求url：https://wap.tenpay.com/cgi-bin/wappayv2.0/wappay_init.cgi
通过get或post请求
字段名 变量名 必填 类型 说明
业务参数
版本号 ver 是 String(8) 版本号，ver默认值是1.0，目前版本ver取值应为2.0
字符集 charset 是 String(8) 1 UTF-8, 2 GB2312， 默认为1
银行类型 bank_type 是 String(16) 银行类型:财付通支付填0
商品描述 desc 是 String(255) 商品描述，32个字符以内
买方财付通账号 purchaser_id 否 String(20) 用户(买方)的财付通帐户(QQ )。若商户没有传该参数，则在财付通支付页面，买家需要输入其财付通帐户。
商户号 bargainor_id 是 String(10) 商户号，由财付通统一分配的10位正整数(120XXXXXXX)号
商户订单号 sp_billno 是 String(32) 商户系统内部的定单号，32个字符内、可包含字母
总金额 total_fee 是 Int 总金额，以分为单位，不允许包含任何字、符号
币种 fee_type 是 Int 现金支付币种，目前只支持人民币，默认值是1：人民币
通知地址 notify_url 是 String(255) 接收财付通通知的URL，需给绝对路径，255字符内格式如:http://wap.tenpay.com/tenpay.asp
前台地址 callback_url 是 String(255) 交易完成后跳转的URL，需给绝对路径，255字符内格式如:http://wap.tenpay.com/tenpay.asp
附加信息 attach 否 String(255) 商户附加信息，可做扩展参数，255字符内
订单生成时间 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。该时间取自商户服务器
签名 sign 是 String(32) MD5签名结果，详见“第4章 MD5签名规则”
6.1.4 返回结果和通知参数列表
数据按XML的格式实时返回
字段名 变量名 必填 类型 说明
业务参数
动态口令 token_id 是 String(64) 财付通生成的token_id。
成功示例：
<?xml version="1.0" encoding="GB2312" ?>
<root>
<token_id>20081113f9d49c20e8e5c8e40b6107ec42259e41</token_id>
</root>
出错示例：
<?xml version="1.0" encoding="GB2312" ?>
<root>
<err_info>错误信息</err_info>
</root>
6.2 Wap支付接口
6.2.1 业务功能
用户通过Wap支付接口完成订单支付。
6.2.2 交互模式
请求：页面跳转交互模式
返回结果：页面跳转交互模式
通知：后台通知交互模式
6.2.3 请求参数列表
请求url：https://wap.tenpay.com/cgi-bin/wappayv2.0/wappay_gate.cgi
通过get或post请求
字段名 变量名 必填 类型 说明
业务参数
动态口令 token_id 是 String(64) 财付通生成的token_id。
6.2.4 返回结果参数列表
页面返回通过请求中的callback_url进行，采用get或post
字段名 变量名 必填 类型 说明
业务参数
返回状态码 ver 是 String(8) 版本号，ver默认值是1.0。目前版本ver取值应为2.0
字符集 charset 是 String(8) 字符编码，取值：GBK、UTF-8，默认：GBK。
支付结果 pay_result 是 Int 支付结果：0—成功；其它—失败
财付通订单号 transaction_id 是 String(28) 财付通交易号，28位长的数值，其中前10位为商户号，之后8位为订单产生的日期，如20090415，最后10位是流水号。
商户订单号 sp_billno 是 String(32) 商户系统内部的定单号，32个字符内、可包含字母
总金额 total_fee 是 Int 总金额，以分为单位，不允许包含任何字、符号
币种 fee_type 是 Int 现金支付币种，1-人民币
商户号 bargainor_id 是 String(10) 卖方账号（商户spid）
附加信息 attach 否 String(255) 商家数据包，原样返回
签名 sign 是 String(32) MD5签名结果
只对通知返回的协议参数进行签名。
6.2.5 通知结果参数列表
后台通知通过请求中的notify_url进行，采用get或post
字段名 变量名 必填 类型 说明
业务参数
版本号 ver 是 String(8) 版本号，ver默认值是1.0。目前版本ver取值应为2.0
字符集 charset 是 String(8) 字符编码，取值：GB2312、UTF-8，默认：GB2312。
支付结果 pay_result 是 Int 支付结果：0—成功；其它—失败
支付结果信息 pay_info 否 String(64) 支付结果信息，支付成功时为空
财付通订单号 transaction_id 是 String(28) 财付通交易号，28位长的数值，其中前10位为商户号，之后8位为订单产生的日期，如20090415，最后10位是流水号。
商户订单号 sp_billno 是 String(32) 商户系统内部的定单号，32个字符内、可包含字母
总金额 total_fee 是 Int 总金额，以分为单位，不允许包含任何字、符号
币种 fee_type 是 Int 现金支付币种，1-人民币
商户号 bargainor_id 是 String(10) 卖方账号（商户spid）
附加信息 attach 否 String(255) 商家数据包，原样返回
签名 sign 是 String(32) MD5签名结果
付款银行 bank_type 是 String(16) 银行类型
银行订单号 bank_billno 否 String(32) 银行订单号，若为财付通余额支付则为空
支付完成时间 time_end 是 String(14) 支付完成时间，格式为yyyyMMddhhmmss，如2009年12月27日9点10分10秒表示为20091227091010。时区为GMT+8 beijing。该时间取自财付通服务器
买家别名 purchase_alias 否 String(64) 对应买家账号的一个加密串
6.2.6 后台通知结果反馈
财付通后台通过notify_url通知商户，商户做业务处理后，需要以字符串的形式反馈处理结果，内容如下：
返回结果 结果说明
success 处理成功，财付通系统收到此结果后不再进行后续通知
fail或其它字符 处理不成功，财付通收到此结果或者没有收到任何结果，系统通过补单机制（详见第5节）再次通知
6.3 订单查询接口
6.3.1 业务功能
根据商户订单号或者财付通订单号查询财付通侧记录的具体订单信息。
6.3.2 交互模式
后台系统调用交互模式
6.3.3 请求参数列表
请求url：http://wap.tenpay.com/cgi-bin/wapmainv2.0/wm_query_order.cgi
通过get或post请求
字段名 变量名 必填 类型 说明
业务参数
版本号 ver 是 String(8) 版本号，ver默认值是1.0。目前版本ver取值应为2.0
商户号 bargainor_id 是 String(10) 卖方账号（商户spid）
商户订单号 sp_billno 否 String(32) 商户系统内部的订单号， sp_billno和transaction_id至少一个必填，同时存在时transaction_id优先
财付通订单号 transaction_id 否 String(28) 财付通交易号， sp_billno和transaction_id至少一个必填，同时存在时transaction_id优先。
附加信息 attach 否 String(255) 商家数据包，原样返回
字符集 charset 是 String(8) 字符编码，取值：GB2312、UTF-8，默认：GB2312。
签名 sign 是 String(32) MD5签名结果
6.3.4 应答参数列表
数据按XML的格式实时返回
字段名 变量名 必填 类型 说明
业务参数
版本号 ver 是 String(8) 版本号，ver默认值是1.0。目前版本ver取值应为2.0
字符集 charset 是 String(8) 字符编码，取值：GB2312、UTF-8，默认：GB2312。
支付结果 pay_result 是 Int 支付结果：0—成功；其它—失败
支付结果信息 pay_info 否 String(64) 支付结果信息，支付成功时为空
财付通订单号 transaction_id 是 String(28) 财付通交易号，28位长的数值，其中前10位为商户号，之后8位为订单产生的日期，如20090415，最后10位是流水号。
商户订单号 sp_billno 是 String(32) 商户系统内部的定单号，32个字符内、可包含字母
总金额 total_fee 是 Int 总金额，以分为单位，不允许包含任何字、符号
币种 fee_type 是 Int 现金支付币种，1-人民币
商户号 bargainor_id 是 String(10) 卖方账号（商户spid）
附加信息 attach 否 String(255) 商家数据包，原样返回
签名 sign 是 String(32) MD5签名结果
付款银行 bank_type 是 String(16) 银行类型
银行订单号 bank_billno 否 String(32) 银行订单号，若为财付通余额支付则为空
支付完成时间 time_end 是 String(14) 支付完成时间，格式为yyyyMMddhhmmss，如2009年12月27日9点10分10秒表示为20091227091010。时区为GMT+8 beijing。该时间取自财付通服务器
买家别名 purchase_alias 否 String(64) 对应买家账号的一个加密串
7 注意事项
1、 所有涉及到金额的单位都是分，最小的单位是1分，不能有小数出现
2、 notify_url是财付通服务器从后台直接发起请求到商户服务器，商户处理时不能检查用户的cookie或session；商户更新DB等发货流程需要完整在notify_url完成，以确保掉单时，财付通补单能成功补上
3、 notify_url有可能重复通知，商户需要做去重处理，避免多次发货
4、 notify_url收到的通知，商户处理成功或检查订单已经处理，需要返回处理成功的标志“success”，以告知财付通不再通知
5、 notify_id的有效期是2分钟，请商户收到通知后尽快发起查询
Unitrans世联翻译公司在您身边,离您最近的翻译公司,心贴心的专业服务translation company,全球领先的翻译与技术解决方案供应商,北京翻译公司、上海翻译公司顶级品牌。无论在本地,还是广州、深圳、天津、重庆、苏州、香港、澳门、台北,海外,Unitrans.cn世联的英文翻译等专业服务为您的事业加速！
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
