Xypay Java SDK 使用说明

xypay-sdk-java 是面向开发者的支付能力 Java SDK，封装了支付、退款、分账等接口的签名、验签与 HTTP 调用细节，开发者只需构造业务参数模型并调用客户端即可完成接口对接。

接口文档：Xypay接口文档

签名与验签规则详见：签名与验签说明

一、环境要求

项目	要求
JDK	1.8 及以上
构建工具	Maven
字符编码	UTF-8

二、安装与引入

2.1 安装 SDK 到本地 Maven 仓库

SDK 的 jar 包需手动安装到本地 Maven 仓库（请将 -Dfile 参数替换为本地 jar 包实际所在路径）：

2.2 在项目中引入依赖

<dependency>
    <groupId>com.xiangyin</groupId>
    <artifactId>xypay-sdk-java</artifactId>
    <version>1.0.0</version>
</dependency>

三、调用前准备

调用接口前需准备好以下信息（由平台分配或商户自行生成）：

参数	说明
devOrgId	开发者机构ID
mchNo	商户号
appId	应用ID
apiBase	支付网关地址，默认 `http://pay.gdxiangyin.com/`，测试环境可通过 `XypayClient.getInstance` 第三个参数指定
apiKey	MD5 签名方式：开发者机构密钥（devSecret）
rsa2AppPrivateKey	RSA2 签名方式：商户 RSA 私钥（PKCS8 格式，Base64 字符串，不含 PEM 头尾）
rsa2PayPublicKey	RSA2 签名方式：支付系统 RSA 公钥（X509 格式，由平台提供，用于响应验签）

SDK 支持 MD5 与 RSA2 两种签名方式，签名规则详见 5_签名与验签说明.md。

四、快速开始

4.1 调用流程

所有接口的调用流程一致：

获取 XypayClient 实例 → 构造 XxxRequest → 设置业务模型 XxxReqModel → client.execute(request) → 处理 XxxResponse

4.2 MD5 签名方式（默认）

以"支付下单"为例：

4.3 RSA2 签名方式

使用 RSA2 方式时，客户端的 apiKey 位置传入商户 RSA 私钥，调用时使用 executeByRSA2，验签使用 checkSignByRsa2 / isSuccessByRsa2 并传入支付系统 RSA 公钥：

RSA2 密钥要求：私钥为 PKCS8 格式、公钥为 X509 格式，均为 Base64 字符串，不含 -----BEGIN/END----- 头尾标记。

五、响应处理与验签

响应对象（XypayResponse 子类）包含以下通用字段与方法：

方法	说明
`getCode()`	网关返回码，0 表示请求成功
`getMsg()`	网关返回信息
`getSign()`	响应数据签名
`getData()`	响应业务数据（JSON）
`get()`	各 Response 子类提供的业务模型获取方法
`checkSign(apiKey)` / `checkSignByRsa2(publicKey)`	校验响应数据签名
`isSuccess(apiKey)` / `isSuccessByRsa2(publicKey)`	code 为 0 且验签通过

处理建议：

先调用 isSuccess / isSuccessByRsa2 判断请求成功并验签，再读取业务数据；

失败时通过 getErrCode() / getErrMsg() 获取通道错误码与错误信息；

支付、退款、转账的异步结果以异步通知（notifyUrl）和查询接口为准，验签规则与响应验签一致。

六、高级配置

6.1 自定义 RequestOptions

默认情况下 XypayClient.execute 会根据请求自动构造 RequestOptions；如需更精细的控制（如自定义超时、重试次数），可自行构造：

注意：setUri 的接口路径不能以 / 开头；手动设置了 RequestOptions 后，客户端将直接使用该配置。

6.2 全局配置（Xypay）

七、异常说明

所有 SDK 层面异常均继承自 XypayException，调用 execute / executeByRSA2 时需捕获：

异常类	说明
APIConnectionException	网络连接异常（超时、连接失败等）
APIException	网关返回非成功状态码的 API 异常
InvalidRequestException	请求参数无效异常

XypayException 提供 getStatusCode() 获取 HTTP 状态码（如有），getMessage() 获取错误描述。

八、注意事项

金额均为整数，单位为分，不能带小数；

字符编码统一为 UTF-8；

商户订单号（mchOrderNo）、商户退款单号（mchRefundNo）等需保证全局唯一；

MD5 密钥、RSA2 私钥请妥善保管，切勿硬编码到代码仓库或对外泄露；

异步通知验签规则与响应验签一致，详见 5_签名与验签说明.md；

完整可运行的调用示例请参考 src/test/java/com/xiangyin/xypay 目录下的测试类：

PayOrderTest：支付下单 / 查询 / 关闭

PayOrderRSA2Test：RSA2 签名方式调用示例

RefundOrderTest：退款 / 退款查询

TransferOrderTest：转账 / 转账查询

BalanceDivisionExecTest、PayOrderDivisionReceiverExecTest：分账示例

SDK使用说明

Xypay Java SDK 使用说明#

一、环境要求#

二、安装与引入#

2.1 安装 SDK 到本地 Maven 仓库#

2.2 在项目中引入依赖#

三、调用前准备#

四、快速开始#

4.1 调用流程#

4.2 MD5 签名方式（默认）#

4.3 RSA2 签名方式#

五、响应处理与验签#

六、高级配置#

6.1 自定义 RequestOptions#

6.2 全局配置（Xypay）#

七、异常说明#

八、注意事项#