com.xpay.sdk.intl

Class XPayIntlClient

java.lang.Object

com.xpay.sdk.intl.XPayIntlClient

public class XPayIntlClient
extends Object

XPay 国际版 OpenAPI Java 客户端。

客户端严格封装开发者平台最终发布的余额查询、收款创建/查单和代付创建/查单五个接口，并在平台 HTTPS 接口域名后统一拼接 /intl/v1 版本路径，负责 lowerCamelCase JSON 序列化、五行请求签名、 标准 Header 发送和普通响应验签。SDK 不保存交易状态、不自动重试创建请求、不推断产品或路由能力； 已验签 HTTP 503 ORDER_RESULT_UNKNOWN 或网络结果不可验证时，商户必须先按原 merchantOrderNo 查单，有界查询后仅可用同一单号和完全一致的请求串行安全重试。

Constructor Summary

Constructors

Constructor and Description
XPayIntlClient(XPayIntlConfig config) 创建可复用的国际版 API 客户端。

Method Summary

Modifier and Type	Method and Description
XPayIntlResponse	createPaymentOrder(PaymentOrderCreateRequest request) 创建国际版收款订单。
XPayIntlResponse	createPayout(PayoutCreateRequest request) 创建国际版代付订单。
XPayIntlResponse	getBalances() 查询商户全部可用国家币种账户余额。
XPayIntlResponse	getBalances(String country, String currency) 按可选国家和币种筛选查询商户余额列表。
XPayIntlResponse	getBalancesByCountry(String country) 按国家查询商户余额列表。
XPayIntlResponse	getBalancesByCurrency(String currency) 按币种查询商户余额列表。
XPayIntlResponse	getPaymentOrderByMerchantOrderNo(String merchantOrderNo) 按商户订单号查询国际版收款订单。
XPayIntlResponse	getPayoutByMerchantOrderNo(String merchantOrderNo) 按商户订单号查询国际版代付订单。

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

XPayIntlClient

public XPayIntlClient(XPayIntlConfig config)

创建可复用的国际版 API 客户端。

客户端和底层 OkHttpClient 可被多个线程共享；构造过程不访问网络、数据库或缓存，不启动事务或异步任务。 配置为空时立即 fail-close 抛出参数异常。

Parameters:

config - 已校验的 HTTPS 接口域名、API Key、API Secret 和响应验签配置

Throws:

IllegalArgumentException - 配置为空时抛出

Method Detail

getBalances

public XPayIntlResponse getBalances()

查询商户全部可用国家币种账户余额。

方法只执行签名 HTTPS GET，不开启本地事务、不缓存余额，也不自动重试；响应在返回前必须通过 API Secret 验签。调用方不得把一次余额快照当作后续路由或资金可用性的永久保证。

Returns:

已通过响应验签的原始 HTTP 响应，Body 为 balances 列表

Throws:

XPayIntlException - 网络或响应验签失败时抛出；无签名非2xx前置错误作为不可信诊断响应返回

getBalancesByCountry

public XPayIntlResponse getBalancesByCountry(String country)

按国家查询商户余额列表。

本方法只把国家作为可选筛选拼入签名 requestUrl，不修改交易状态、不缓存结果、不自动重试。筛选无匹配时 服务端返回空 balances 列表。

Parameters:

country - ISO 3166-1 alpha-2 国家编码，例如 PH

Returns:

已通过响应验签的原始 HTTP 响应，Body 为 balances 列表

Throws:

IllegalArgumentException - country 为空时抛出

XPayIntlException - 网络或响应验签失败时抛出

getBalancesByCurrency

public XPayIntlResponse getBalancesByCurrency(String currency)

按币种查询商户余额列表。

本方法只把币种作为可选筛选拼入签名 requestUrl，不修改交易状态、不缓存结果、不自动重试。筛选无匹配时 服务端返回空 balances 列表。

Parameters:

currency - ISO 4217 币种编码，例如 PHP

Returns:

已通过响应验签的原始 HTTP 响应，Body 为 balances 列表

Throws:

IllegalArgumentException - currency 为空时抛出

XPayIntlException - 网络或响应验签失败时抛出

getBalances

public XPayIntlResponse getBalances(String country,
                                    String currency)

按可选国家和币种筛选查询商户余额列表。

country 与 currency 均可为空；都为空表示查询当前商户全部 ACTIVE 国家币种账户，只传其中之一表示按该维度 过滤，同时传入表示查询精确国家币种账户。SDK 会按实际传参生成签名 requestUrl，不发送空Query参数。

Parameters:

country - 可选 ISO 3166-1 alpha-2 国家编码，例如 PH；为空表示不限国家

currency - 可选 ISO 4217 币种编码，例如 PHP；为空表示不限币种

Returns:

已通过响应验签的原始 HTTP 响应，Body 为 balances 列表

Throws:

IllegalArgumentException - country 或 currency 传入空白字符串时抛出

XPayIntlException - 网络或响应验签失败时抛出；无签名非2xx前置错误作为不可信诊断响应返回

createPaymentOrder

public XPayIntlResponse createPaymentOrder(PaymentOrderCreateRequest request)

创建国际版收款订单。

服务端以 merchantOrderNo 实现创建幂等；SDK 不发送额外幂等 Header、不自动重试，也不参与平台交易 事务。已验签 HTTP 503 ORDER_RESULT_UNKNOWN 不包含平台订单号；调用方必须先按原商户订单号查单， 有界查询后仅可用同一单号和完全一致的请求串行重试。超时、断连或无法验证的响应也按该保守边界恢复。

Parameters:

request - lowerCamelCase 收款订单创建请求，不能为空

Returns:

已通过响应验签的原始 HTTP 响应；HTTP 200 仍需按 Body status 判断业务状态，503未知结果仅含错误体

Throws:

IllegalArgumentException - request 为空时抛出

XPayIntlException - 网络、JSON 序列化或响应验签失败时抛出

getPaymentOrderByMerchantOrderNo

public XPayIntlResponse getPaymentOrderByMerchantOrderNo(String merchantOrderNo)

按商户订单号查询国际版收款订单。

本方法用于常规查单和创建请求未知结果恢复，不开启本地事务、不缓存结果且不自动重试；返回前执行响应 fail-close 验签。并发查询只读取平台当前状态，不替调用方解决本地状态更新并发。

Parameters:

merchantOrderNo - 创建时使用的商户订单号

Returns:

已通过响应验签的原始 HTTP 响应

Throws:

IllegalArgumentException - merchantOrderNo 为空时抛出

XPayIntlException - 网络或响应验签失败时抛出

createPayout

public XPayIntlResponse createPayout(PayoutCreateRequest request)

创建国际版代付订单。

服务端以 merchantOrderNo 实现创建幂等；SDK 不发送额外幂等 Header、不自动重试，也不参与扣款、 路由或渠道事务。已验签 HTTP 503 ORDER_RESULT_UNKNOWN 不包含平台订单号；必须先按原商户订单号查单， 有界查询后仅可用同一单号和完全一致的请求串行重试，避免资金类重复提交。超时、断连或无法验证的响应也按该保守边界恢复。

Parameters:

request - lowerCamelCase 代付订单创建请求，包含字符串账号和金额对象，不能为空

Returns:

已通过响应验签的原始 HTTP 响应；HTTP 200 不代表代付终态成功，503未知结果仅含错误体

Throws:

IllegalArgumentException - request 为空时抛出

XPayIntlException - 网络、JSON 序列化或响应验签失败时抛出

getPayoutByMerchantOrderNo

public XPayIntlResponse getPayoutByMerchantOrderNo(String merchantOrderNo)

按商户订单号查询国际版代付订单。

本方法是资金类创建未知结果的必需恢复路径，不开启本地事务、不缓存结果且不自动重试；响应签名无效时 fail-close 抛出异常，调用方不得使用未验证 Body 更新资金状态。

Parameters:

merchantOrderNo - 创建时使用的商户订单号

Returns:

已通过响应验签的原始 HTTP 响应

Throws:

IllegalArgumentException - merchantOrderNo 为空时抛出

XPayIntlException - 网络或响应验签失败时抛出