腾讯财付通开放小钱包平台，第三方应用可以有机会进驻QQ小钱包(转）

http://open.tenpay.com

 

http://open.tenpay.com/main/cftController.jhtm?method=gotodevsdkjava&&sdk_tab=2

 

Java SDK下载

当前版本	发布日期	下载链接	文件大小
1.0.0	2010-6-30	openapi-JAVA-SDK-1.0.0.zip	129k
		sdk-javadoc.zip	128k

样例代码下载

当前版本	发布日期	下载链接	文件大小
1.0.0	2010-6-30	appdemo-movieticket-1.0.0.zip	1.28M

引言

文档概述

本文描述了财付通开放平台的JAVA SDK，帮助开发者轻松实现在线支付、收付款等功能。文档详细介绍了财付通开放平台的工作方式和开发过程，可以帮助开发人员快速入门并掌握开发技能，同时 也可以作为日后接口参数以及参数类型的速查手册。

阅读对象

具有WEB程序开发背景，了解JAVA语言。

业务术语

类名	说明
ISV	独立软件供应商 / Independent Software Vendor，可以是商户、个人或者第三方中介开发者
财付通APP	指ISV使用财付通开放平台SDK开发的WEB应用程序，运行于第三方服务器上为最终用户提供服务
商户	指财付通的商户，商家可以是ISV。
开放平台	财付通提供给ISV的开发注册、应用管理、沙箱测试平台。
最终用户	指通过财付通开放平台使用财付通APP的财付通用户

接口业务流程

支付流程

支付流程中，用户在财付通APP中购买业务，通过财付通支付平台进行支付。典型业务流程如下：

买家在财付通APP上浏览下单购买一个商品，财付通APP会生成一个支付链接，此链接通过用户的浏览器跳转到财付通开放平 台，财付通通过此链接获取支付请求的参数，引导用户完成支付过程。用户在财付通完成支付后，财付通通过return_url将用户浏览重新定向到财付通 APP，财付通APP向用户提示订单状态和后续操作。同时，财付通会通过后台回调财付通APP的notify_url，财付通APP在收到支付结果通知后 可以根据通知ID查询通知内容，在确保支付成功后再进行业务逻辑处理（例如发货），这样可以进一步提高安全性，防止伪支付成功结果的欺诈。

通知查询/订单查询流程

通知查询/订单查询是指财付通APP向财付通系统发送查询请求，并同步等待财付通系统处理完毕后返回的响应数据。数据交互 是财付通APP与财付通服务器直接通信。例如用户在财付通APP查询时，财付通APP要确认用户某个订单是否支付成功，可以向财付通发送一个查询请求，财 付通收到请求后返回查询结果，财付通APP处理结果后再显示给用户。

后台通知流程

后台通知是指财付通系统主动向财付通APP发送通知数据，并同步等待财付通APP处理完毕后返回的响应数据。数据交互是财 付通服务器与财付通APP直接通信，一般请求采用http的get或post，应答用字符串格式。用户在财付通支付成功后，财付通会在后台通过 notify_url向财付通APP发起通知，财付通APP处理后成功返回success，失败返回fail或其他字符。

补单机制

对后台通知流程，如果财付通收到财付通APP的应答不是success或由于网络异常超时，财付通认为通知失败，财付通会 通过一定的策略（如1分钟、2分钟、4分钟、8分钟、16分钟、32分钟，共6次）定期重新发起通知，尽可能提高通知的成功率，但财付通不保证通知最终能 成功。

由于上述原因，可能存在同样的通知多次发送给财付通APP的情况。财付通APP必须能 够正确处理，在收到重复的后台通知不重复引发业务流程（例如发货）。

财付通推荐的做法是，当收到财付通发送的通知消息时，需要检查本系统内订单的状态，判断该 通知是否已经处理过。为防止并发产生的问题，在对业务数据进行状态检查和处理之前，要求采用加锁判断进行并发控制。

功能划分

财付通APP负责与之业务相关的代码和页面。
财付通开放平台提供支付相关的业务功能和页面。具体业务功能请参照后 面章节SDK说明

支付页面如下：

在小钱包中：

在普通浏览器中：

SDK说明

概述

API说明

类名	说明
com.tenpay.api.PayRequest	支付请求
com.tenpay.api.PayResponse	支付响应
com.tenpay.api.OrderQueryRequest	订单查询请求
com.tenpay.api.OrderQueryResponse	订单查询响应
com.tenpay.api.NotifyQueryRequest	通知查询请求
com.tenpay.api.NotifyQueryResponse	通知查询响应
com.tenpay.api.ShareLoginState	共享登录用户信息

共享登录用户信息接口：

1. 用户跳转到应用时，初始化ShareLoginState对 象,ShareLoginState.getUserId()即可获得当前用户的id

支付接口，常见开发步骤如下：

1. 初始化请求对象PayRequest
2. 设置请求系统级参数（应用ID等），例如PayRequest.setAppid(应用ID)
3. 设置请求业务级参数，例如PayRequest.setParameters(参数名称, 参数值)
4. 生成跳转URL，例如PayRequest.getURL()
5. 将用户重定向到跳转URL，例如Servlet/JSP中的重定向方法 response.sendRedirect()或用Javascript进行页面跳转

通知查询或订单查询，常见开发步骤如下：

1. 初始化请求对象，例如NotifyQueryRequest或OrderQueryRequest
2. 设置请求系统级参数（应用ID等），例如NotifyQueryRequest.setAppid(应用ID)
3. 设置请求业务级参数，例如NotifyQueryRequest.setParameters(参数名称, 参数值)
4. 通过NotifyQueryRequest.send()方法将请求发送到接口并获得响应对象，例如 NotifyQueryResponse response = NotifyQueryRequest.send()
5. 判断订单支付状态，例如NotifyQueryResponse.isPaySuccessful()
6. 从响应对象中获取参数值，进行相应处理，例如 NotifyQueryResponse.getParameter(参数名)

后台通知交互模式，常见开发步骤如下：

1. 构造一个Servlet或JSP接收开放平台的回调
2. 初始化响应对象PayResponse
3. 判断订单支付状态，例如PayResponse.isPaySuccessful()
4. 从响应对象中获取参数值，进行相应处理，例如PayResponse.getParameter(参数名)

SDK调用过程

支付类

支付跳转

·业务功能

买家在财付通APP中下订单后付款，财付通APP调用财付通开放平台支付接口生成支付URL，页面跳转到财付通支付中心或 银行。用户完成支付后，财付通把用户引导回财付通APP指定的页面（return_url），并通过回调支付请求中的notify_url反馈支付结果。

·接口调用方向

开发者开发应用调用财付通开放接口

·请求

    com.tenpay.api.NotifyQueryRequest        通知查询请求
    方法列表
    /**
    * 构造方法
    * @param secretKey
    */
    public NotifyQueryRequest(String secretKey);
    /**
    * 设置应用ID
    * 
    * @param appid
    *            应用ID
    */
    public void setAppid(String appid);

    /**
    * 设置是否在沙箱环境
    * 
    * @param inSandBox
    *            true表示请求发送到沙箱环境，false表示请求发送到正式环境
    */
    public void setInSandBox(boolean inSandBox);

    /**
    * 设置业务参数
    * 
    * @param key
    *            参数名称
    * @param value
    *            参数值
    */
    public void setParameter(String key, String value);

    /**
    * 调用开放平台接口发送请求，获取响应
    * 
    * @return 接口调用的返回结果
    * @throws Exception
    */
    public CommonResponse send() throws Exception;
            

参数名称详见下表

参数名称	必填	类型	说明
notify_id	是	String(64)	支付成功后，财付通系统反馈的通知ID此参数来源详见3.1.2.5章节参数列表中的 notify_id
sign_key_index	否	Int	多密钥支持的密钥序号，默认1
sign_type	否	String(8)	签名类型，取值：MD5、RSA，默认：MD5，暂只支持MD5
service_version	否	String(8)	版本号，默认为1.0

·返回结果

    com.tenpay.api.NotifyQueryResponse通知查询响应
    方法列表
    /**
     * 判断支付结果
     * 
     * @return true表示支付成功，false表示支付处于其他状态，需要调用getPayInfo()方法获取详细说明
     */
    public boolean isPaySuccessful();

    /**
     * 获取支付结果信息
     * 
     * @return 支付结果说明
     */
    public String getPayInfo();

    /**
     * 获取响应参数
     * 
     * @param key 参数名称
     * @return 参数值
     */
    public String getParameter(String key);
            

参数名称详见下表

参数名称	必填	类型	说明
total_fee	是	Int	用户实际支付的金额，单位为分，如果 discount有值，通知的total_fee + discount = 请求的total_fee
transaction_id	是	String(28)	财付通交易号
out_trade_no	是	String(32)	财付通APP系统的订单号，与请求一致。
time_end	是	String(14)	支付完成时间，格式为yyyymmddhhmmss，如2009年12月27日9点10分10秒表示为 20091227091010。时区为GMT+8 beijing。该时间取自财付通服务器
input_charset	否	String(8)	字符编码,取值：GBK、UTF-8，默认：GBK。
sign_key_index	否	Int	多密钥支持的密钥序号，默认1
attach	否	String(64)	商家数据包，原样返回
bank_type	否	String(16)	银行类型，默认为“DEFAULT”－财付通，其余参照第4.1节银行编码
fee_type	否	Int	现金支付币种,目前只支持人民币,默认值是1-人民币
transport_fee	否	Int	物流费用，单位分，默认0。如果有值，必须保证transport_fee + procedure_fee = total_fee
procedure_fee	否	Int	物品费用，单位分。如果有值，必须保证transport_fee + procedure_fee=total_fee
discount	否	Int	折扣价格，单位分，如果有值，通知的total_fee + discount = 请求的total_fee
buyer_alias	否	String(64)	对应买家账号的一个加密串
sign_type	否	String(8)	签名类型，取值：MD5、RSA，默认：MD5，暂只支持MD5
service_version	否	String(8)	版本号，默认为1.0

·样例

    // 应用ID
    String appid = "0000000155";
    // 密钥
    String secretKey = "123456";
    // 是否沙箱测试
    boolean isSandBox = true;

    // 初始化通知查询请求
    NotifyQueryRequest request = new NotifyQueryRequest(secretKey);
    request.setAppid(appid);// 设置应用ID
    request.setInSandBox(isSandBox);// 请求发送到沙箱
    // 设置业务参数
    request.setParameter("notify_id", "xxxxxxxxxxxxxxx");// 通知查询ID，此ID来源于支付之后的回调

    try {
    // 发起接口调用
    NotifyQueryResponse response = request.send();
    if (response.isPaySuccessful()) {
    // 支付成功
    // 处理业务逻辑
    // ......
    } else {
    // 支付处于其他状态
    System.out.println(response.getPayInfo()); // 获取详细状态说明
    }
    } catch (Exception e) {
    // 异常处理
    }
            

订单查询

·业务功能

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

·接口调用方向

开发者开发应用调用财付通开放接口。

·请求

    com.tenpay.api.OrderQueryRequest订单查询请求
    方法列表
        /**
     * 构造方法
     * @param secretKey
     */
    public OrderQueryRequest(String secretKey);

    /**
     * 设置应用ID
     * 
     * @param appid
     *            应用ID
     */
    public void setAppid(String appid);

    /**
     * 设置是否在沙箱环境
     * 
     * @param inSandBox
     *            true表示请求发送到沙箱环境，false表示请求发送到正式环境
     */
    public void setInSandBox(boolean inSandBox);

    /**
     * 设置业务参数
     * 
     * @param key
     *            参数名称
     * @param value
     *            参数值
     */
    public void setParameter(String key, String value);

    /**
     * 调用开放平台接口发送请求，获取响应
     * 
     * @return 接口调用的返回结果
     * @throws Exception
     */
    public CommonResponse send() throws Exception;
            

参数名称详见下表

参数名称	必填	类型	说明
out_trade_no	二者必填 其一	String(32)	财付通APP内部的订单号, out_trade_no和transaction_id至少一个必填，同时存在时transaction_id优先
transaction_id		String(28)	财付通交易号, out_trade_no和transaction_id至少一个必填，同时存在时transaction_id优先
sign_key_index	否	Int	多密钥支持的密钥序号，默认1
sign_type	否	String(8)	签名类型，取值：MD5、RSA，默认：MD5，暂只支持MD5
service_version	否	String(8)	版本号，默认为1.0

·返回结果

订单查询返回结果与通知查询返回结果相同，参见“3.3.1.5返回结果”

·样例

    // 签名密钥: 开发者注册时，由财付通分配
    String secretKey = "64507558218450442324574381315452";
    // 初始化订单查询请求
    OrderQueryRequest req = new OrderQueryRequest(secretKey);
    // 设置在沙箱中运行:正式环境请设置为false
    req.setInSandBox(true);
    // 设置财付通App-id
    req.setAppid("0000000201");
    // 设置财付通App订单号:财付通APP的订单号
    req.setParameter("out_trade_no", "test000000001");
    // 发送请求，并获取返回对象
    OrderQueryResponse res = req.send();
    if (res.isPayed()) {// 已经支付
          // 已经支付财付通app订单号
          System.out.println("支付成功，应用订单号：" + res.getParameter("out_trade_no"));
           // 财付通app订单号对应的财付通订单号
          System.out.println("财付通订单号:" + res.getParameter("transaction_id"));
          // 支付金额，单位：分
          System.out.println("支付金额:" + res.getParameter("total_fee") + "分");
          // 支付完成时间,格式为yyyymmddhhmmss,如20091227091010
          System.out.println("支付完成时间:" + res.getParameter("time_end"));
    }
    else {// 未正常支付，或者调用异常，如调用超时、网络异常
          System.out.println("支付未成功状态说明:" + res.getPayInfo());
    }
            

其他类

共享登录

·业务功能

买家转到APP中时，系统将买家的ID传入APP，方便用户订单生成、用户状态更新等相关操作。

·交互模式

买家点击跳转到APP时，id等相关信息将签名后通过url一起发往APP。

·样例

    // 签名密钥: 开发者注册时，由财付通分配
    String secretKey = "64507558218450442324574381315452";
    //创建共享登陆态对象
    ShareLoginState state = new ShareLoginState(req, secretKey);
    // 获取用户id
    String userID =  state.getUserId();
            

枚举类型

银行编码

编码	含义	说明
DEFAULT	财付通，支持的各类支付方式包括（银行，财付通账户，一点通等）
ICBC	中国工商银行	支持信用卡
CMB	招商银行	支持信用卡
CCB	中国建设银行	支持信用卡
ABC	中国农业银行	支持信用卡
SPDB	上海浦东发展银行	支持信用卡
SDB	深圳发展银行	支持信用卡
CIB	兴业银行	不支持信用卡
BOB	北京银行	支持信用卡
CEB	中国光大银行	支持信用卡
CMBC	中国民生银行	支持信用卡
CITIC	中信银行	支持信用卡
GDB	广东发展银行	支持信用卡
PAB	平安银行	支持信用卡
BOC	中国银行	支持信用卡
COMM	交通银行	支持信用卡
ICBCB2B	中国工商银行(企业)	企业网银
CMBB2B	招商银行(企业)	企业网银
POSTGC	中国邮政储蓄银行(银联)
BOC_EPOS	中行EPOS
ICBC_EPOS	工行EPOS
CCB_EPOS	建行EPOS