Java SDK下载

样例代码下载

引言

文档概述

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

阅读对象

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

业务术语

接口业务流程

支付流程

支付流程中，用户在财付通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说明

共享登录用户信息接口：

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

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

2 初始化请求对象PayRequest

3 设置请求系统级参数（应用ID等），例如PayRequest.setAppid(应用ID)

4 设置请求业务级参数，例如PayRequest.setParameters(参数名称, 参数值)

5 生成跳转URL，例如PayRequest.getURL()

6 将用户重定向到跳转URL，例如Servlet/JSP中的重定向方法response.sendRedirect()或用Javascript进行页面跳转

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

7 初始化请求对象，例如NotifyQueryRequest或OrderQueryRequest

8 设置请求系统级参数（应用ID等），例如NotifyQueryRequest.setAppid(应用ID)

9 设置请求业务级参数，例如NotifyQueryRequest.setParameters(参数名称, 参数值)

10 通过NotifyQueryRequest.send()方法将请求发送到接口并获得响应对象，例如NotifyQueryResponse response = NotifyQueryRequest.send()

11 判断订单支付状态，例如NotifyQueryResponse.isPaySuccessful()

12 从响应对象中获取参数值，进行相应处理，例如NotifyQueryResponse.getParameter(参数名)

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

13 构造一个Servlet或JSP接收开放平台的回调

14 初始化响应对象PayResponse

15 判断订单支付状态，例如PayResponse.isPaySuccessful()

16 从响应对象中获取参数值，进行相应处理，例如PayResponse.getParameter(参数名)

调用过程

支付类

支付跳转

·业务功能

买家在财付通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;

参数名称详见下表

·返回结果

com.tenpay.api.NotifyQueryResponse通知查询响应

方法列表

/**

* 判断支付结果

*

* @return true表示支付成功，false表示支付处于其他状态，需要调用getPayInfo()方法获取详细说明

*/

public boolean isPaySuccessful();

/**

* 获取支付结果信息

*

* @return 支付结果说明

*/

public String getPayInfo();

/**

* 获取响应参数

*

* @param key 参数名称

* @return 参数值

*/

public String getParameter(String key);

参数名称详见下表

·样例

// 应用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;

参数名称详见下表

·返回结果

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

·样例

// 签名密钥: 开发者注册时，由财付通分配

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();

枚举类型

银行编码

财付通API接口文档