SDK

更新时间: 2026-11-05 02:13

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

版本与下载

版本	状态	下载入口	描述
`1.2.1`	已发布（2026-11-04）	SDK JAR v1.2.1	实现公开接口版本 `1.0`，新增巴西 PIX recipient.accountType，保留代收 successUrl 和付款人邮箱、手机号；普通 JAR，外部依赖 OkHttp 和 Jackson。

GitHub Release v1.2.1

下载、校验与安装

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

bash

curl -fLO https://docs.paysea.global/downloads/sdk/1.2.1/sdk-api-intl-java-1.2.1.jar
curl -fLO https://docs.paysea.global/downloads/sdk/1.2.1/sdk-api-intl-java-1.2.1.jar.sha256
curl -fLO https://docs.paysea.global/downloads/sdk/1.2.1/pom.xml
curl -fLO https://docs.paysea.global/downloads/sdk/1.2.1/pom.xml.sha256
shasum -a 256 -c sdk-api-intl-java-1.2.1.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.2.1.jar \
  -DpomFile=pom.xml

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

xml

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

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

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

版本化下载集还提供 Apache-2.0 许可证、源码 JAR、Javadoc JAR、CycloneDX JSON 和 CycloneDX XML，以及相应 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)。

支付成功返回商户

从 1.2.0 起，PaymentOrderCreateRequest.successUrl 支持成功返回地址：

java

// 在原有代收创建请求上设置；商户自行指定 HTTPS 地址，产品须支持返回能力。
request.successUrl = "https://shop.example/pay/result?reference=DEMO_PAY_202606010001#done";
XPayIntlResponse response = client.createPaymentOrder(request);

返回功能仅对已开通能力的收银台产品及有效 HTTPS 域名地址生效；纯 QRPH 忽略该字段。省略、null、空串及其他不可用值均按未传处理。地址最多 2048 ASCII 字节，端口仅可省略或为 443，无需登记域名。SDK 保留原文，不裁剪、不重新编码；字段位于请求根对象，随整个 Body 签名，不放入 customData。

同一 merchantOrderNo 重试时须保持首次生效地址一致；被过滤的地址与未传等价。平台确认支付成功后，仅对有效返回目标提供返回按钮与可见页面 3 秒倒计时；平台不追加订单或状态参数。浏览器返回不能用于确认收款或发货，仍须依赖服务端查单或已验签 Webhook 并幂等处理。

按实际发送的完整请求签名，不在 SDK 中预删该字段。平台先验签，再将 HTTP、IP、非字符串、平台收银台同源及其他不可用地址按未传处理，不因该字段拒单；纯 QRPH 始终忽略该字段。响应不回显 successUrl，仍按响应原文验签。新订单被过滤地址与未传等价，合法地址变化仍返回 HTTP 409 MERCHANT_ORDER_NO_CONFLICT。完整规则见 API 规则。

旧 PH SDK 使用 Request.data Map，新增 orderReqMap.put("successUrl", targetUrl) 后沿用 RequestUtil.doJsonRequest 签名发送；该参数不能放在 Request 外层，也不能代替 notifyUrl。PH 参数或同号改参错误返回 respCode=02。

巴西 PIX 代付

SDK 1.2.1 为 BR_BRL_PAYOUT_INSTANT 提供 Recipient.accountType，可填 CPF、CNPJ、PHONE、EMAIL 或 EVP；对应 PIX Key 填入字符串 accountNo，不传 bankCode。既有银行代付仍使用 bankCode，不传 accountType。

手工工具中 recipientAccountType 与 recipientBankCode 必须恰配其一；同时配置或都未配置会在发送请求前失败。产品权限与字段格式仍由服务端最终校验；确认目标环境和原商户订单号前，不得开启写操作。

本地五接口手工联调工具

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

可直接运行的类	最终接口
`BalanceQueryLocalTestTool`	`GET /intl/v1/balance/query`
`PaymentCreateLocalTestTool`	`POST /intl/v1/payment/order/create`
`PaymentQueryLocalTestTool`	`GET /intl/v1/payment/order/query`
`PayoutCreateLocalTestTool`	`POST /intl/v1/payout/order/create`
`PayoutQueryLocalTestTool`	`GET /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 已由平台运营加入网关安全组白名单。

使用顺序

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

排障信息

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

SDK ​

版本与下载 ​

下载、校验与安装 ​

初始化 ​

支付成功返回商户 ​

巴西 PIX 代付 ​

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

使用指南 ​

使用顺序 ​

排障信息 ​

SDK