开发者

简体中文

English

简体中文

English

Appearance

SDK ​

更新时间: 2026-09-04 23:35

SDK 适用于服务端 Java 8 及以上项目。SDK 负责生成请求头、计算请求签名、发送 HTTPS 请求、验证普通 API 响应签名，并辅助验证 Webhook；业务系统仍需自己保存 API Secret、 Webhook Secret、merchantOrderNo 和交易处理结果。

版本与下载 ​

版本状态下载入口描述
1.1.0已发布；2026-09-04GitHub Release v1.1.0实现公开接口版本 1.0，新增代收付款人邮箱与手机号类型化字段；普通 JAR，外部依赖 OkHttp 和 Jackson。

下载、校验与安装 ​

从 GitHub Release 下载 JAR、POM 及对应的 SHA-256 文件，校验后安装到本地 Maven 仓库：

bash
curl -fLO https://github.com/KingPaySea/sdk-api-intl-java/releases/download/v1.1.0/sdk-api-intl-java-1.1.0.jar
curl -fLO https://github.com/KingPaySea/sdk-api-intl-java/releases/download/v1.1.0/sdk-api-intl-java-1.1.0.jar.sha256
curl -fLO https://github.com/KingPaySea/sdk-api-intl-java/releases/download/v1.1.0/pom.xml
curl -fLO https://github.com/KingPaySea/sdk-api-intl-java/releases/download/v1.1.0/pom.xml.sha256
shasum -a 256 -c sdk-api-intl-java-1.1.0.jar.sha256
shasum -a 256 -c pom.xml.sha256
mvn -q org.apache.maven.plugins:maven-install-plugin:3.1.3:install-file \
  -Dfile=sdk-api-intl-java-1.1.0.jar \
  -DpomFile=pom.xml

安装完成后，在业务 pom.xml 配置 SDK 依赖：

xml
<dependency>
  <groupId>com.xpay</groupId>
  <artifactId>sdk-api-intl-java</artifactId>
  <version>1.1.0</version>
</dependency>

公开接口版本保持 1.0，Maven 制品使用语义版本 1.1.0 表示向后兼容的 SDK 能力升级。

发布制品是 thin JAR，请保留下载的 POM，让 Maven 解析 OkHttp 和 Jackson 依赖。企业如需统一制品管理， 可以把校验通过的 JAR 和 POM 发布到自己的内部制品仓库；仓库凭据只能放在 Maven settings.xml 或 CI Secret 中，禁止写入 pom.xml。PaySEA 当前不通过商户后台提供此 SDK 的 Maven 仓库。

GitHub Release 还提供 Apache-2.0 许可证、源码与 Javadoc JAR、CycloneDX SBOM，以及下载制品的 SHA-256 校验文件。

初始化 ​

API 凭据从服务端环境变量读取：

java
import com.xpay.sdk.intl.XPayIntlClient;
import com.xpay.sdk.intl.XPayIntlConfig;
import com.xpay.sdk.intl.XPayIntlResponse;

XPayIntlConfig config = new XPayIntlConfig(
    System.getenv("INTL_API_BASE_URL"),
    System.getenv("INTL_API_KEY"),
    System.getenv("INTL_API_SECRET"));

XPayIntlClient client = new XPayIntlClient(config);
XPayIntlResponse response = client.getBalances();

INTL_API_BASE_URL 必须是已批准的 HTTPS 接口域名，不能包含 /intl/v1 路径前缀。商户 先使用测试环境凭据完成联调，上线审批通过后再切换生产商户编号、API Key 和 API Secret。

余额查询默认返回当前商户全部 ACTIVE 国家币种账户；需要缩小范围时，可以调用 getBalancesByCountry(country)、getBalancesByCurrency(currency) 或 getBalances(country, currency)。

本地五接口手工联调工具 ​

SDK 源码在 src/test/java/com/xpay/sdk/intl/manual/ 下提供 Keys.java 和五个独立手工联调类：

可直接运行的类最终接口
BalanceQueryLocalTestToolGET /intl/v1/balance/query
PaymentCreateLocalTestToolPOST /intl/v1/payment/order/create
PaymentQueryLocalTestToolGET /intl/v1/payment/order/query
PayoutCreateLocalTestToolPOST /intl/v1/payout/order/create
PayoutQueryLocalTestToolGET /intl/v1/payout/order/query

把 src/test/resources/intl-sdk-local.properties.example 复制为已被 Git 忽略的 intl-sdk-local.properties，填写获批的商户配置后，在 IDE 中直接运行所需类的 main，无需再传操作名。 五个类统一读取这一个配置文件；也可以只传一个本地配置绝对路径，或使用 JVM 参数 -Dintl.config=... 指定其他配置文件。

实际凭据文件不能提交。创建操作必须显式设置 enableWrites=true，并把 writeConfirmedBaseUrl 配成与本次 apiBaseUrl 完全相同的完整地址，切换目标后旧写确认会失效；生产环境的任何调用还必须设置 allowProduction=true。每个类一次最多发送一个请求，不自动重试创建请求。工具不会输出 API Secret，但会输出 HTTP 状态、验签结果、全部响应 Header 和完整 UTF-8 Body；其中可能包含响应签名、订单信息和收款人信息，禁止 转发原始终端输出。HTTP 5xx、网络异常、读取超时或无法验证的响应，可能无法确认订单是否已经创建； 必须使用已持久化的原 merchantOrderNo 和同一配置文件运行对应查单类。连续查询一段时间仍查不到订单时， 才能用同一单号和完全一致的原请求重发。

使用指南 ​

  • SDK 兼容 Java 8，不制作 fat JAR，不自动重试业务创建请求。
  • 创建请求的业务幂等以同一商户编号下的 merchantOrderNo 为准。
  • HTTP 5xx、网络异常、读取超时或无法验证的响应，都先按原 merchantOrderNo 查单；连续查询一段时间仍查不到时，只能用同一单号和完全一致的请求重发，不得换单号。HTTP 200 表示接口调用成功，业务结果以 status、查单接口或 Webhook 为准。
  • 普通 API 响应和 Webhook 验签都必须使用原始 Body；验签通过后再解析 JSON。
  • 必须确认调用出口 IP 已由平台运营加入网关安全组白名单。

使用顺序 ​

  1. 先阅读快速开始，确认测试环境联调、运营侧安全组准入和生产凭据切换流程。
  2. 使用本 SDK 页面接入签名、请求发送和 Webhook 验签。
  3. 使用 Demo 先完成测试环境联调；上线审批通过后再开启生产写操作。
  4. 上线前完成上线检查清单。

排障信息 ​

向技术支持报障时只提供环境、UTC 时间、商户编号、merchantOrderNo、HTTP 状态、 Request-Id 响应 Header 和响应 Body error.code。禁止发送 API Secret、 Webhook Secret、完整请求 Body、签名值或收款人完整账号。