SDK

Updated: 2026-11-05 02:13

The SDK is for server-side Java 8 and later applications. It builds request headers, signs requests, sends HTTPS calls, verifies ordinary API response signatures and helps verify Webhooks. Your application is still responsible for storing API Secrets, Webhook Secrets, merchantOrderNo values and transaction results.

Versions and downloads

Version	Status	Download entry	Description
1.2.1	Released (2026-11-04)	SDK JAR v1.2.1	Implements public interface version 1.0, adds Brazil PIX recipient.accountType, and retains Payment successUrl and payer email/phone. It is a normal JAR with external OkHttp and Jackson dependencies.

GitHub Release v1.2.1

Download, verify and install

Download the JAR, POM and matching SHA-256 files from this developer platform, then verify and install them into the local Maven repository:

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

After installation, configure the SDK dependency in the application pom.xml:

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

The public interface version remains 1.0; the Maven artifact uses semantic version 1.2.1 for a backward-compatible SDK capability update.

The released artifact is a thin JAR. Keep the downloaded POM so Maven can resolve its OkHttp and Jackson dependencies. A company may publish the verified JAR and POM to its own internal artifact repository; repository credentials must stay in Maven settings.xml or CI Secrets, never in pom.xml. PaySEA does not currently provide a Merchant Portal Maven repository for this SDK.

The versioned download set also provides the Apache-2.0 license, source JAR, Javadoc JAR, CycloneDX JSON and CycloneDX XML, with matching SHA-256 checksums.

Initialization

Load API credentials from server-side environment variables:

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 must be the approved HTTPS API domain and must not include the /intl/v1 path prefix. Use test credentials for integration first; after go-live approval, switch to the production merchant number, API Key and API Secret.

Balance query defaults to all ACTIVE country and currency accounts. Use getBalancesByCountry(country), getBalancesByCurrency(currency) or getBalances(country, currency) when narrower balance data is required.

Return to the merchant after payment

SDK 1.2.0 and later support PaymentOrderCreateRequest.successUrl:

// Set on an existing Payment request for a supported cashier product; no domain registration is required.
request.successUrl = "https://shop.example/pay/result?reference=DEMO_PAY_202606010001#done";
XPayIntlResponse response = client.createPaymentOrder(request);

The return feature is enabled only for supported cashier products and valid HTTPS domain URLs; pure QRPH ignores the field. Omitted, null, empty and other unusable values are treated as absent. The target may contain at most 2048 ASCII bytes, with no port or port 443; no domain registration is required. The SDK preserves the literal value without trimming or re-encoding. This root field is signed with the complete Body; do not put it in customData.

Keep the first effective URL unchanged when retrying the same merchantOrderNo; filtered values equal absence. After authoritative payment success, the platform result page offers a button and a three-second visible countdown only for a valid return target. No order or status parameters are appended. Browser navigation is not proof of payment: use server-side lookup or verified Webhooks and fulfil idempotently.

Sign the complete request as sent without stripping the field in the SDK. After verification, the platform treats HTTP, IP, non-string, platform-cashier same-origin and other unusable values as absent without rejecting creation because of this field; pure QRPH always ignores it. Responses do not echo successUrl; verify their raw content as usual. For new orders, filtered values equal absence, while changes to accepted URLs still return HTTP 409 MERCHANT_ORDER_NO_CONFLICT. See API rules for the complete contract.

The legacy PH SDK uses a Request.data Map: add orderReqMap.put("successUrl", targetUrl) and send through the existing RequestUtil.doJsonRequest signing flow. Do not set it on the outer Request or replace notifyUrl. PH parameter or conflicting-retry errors use respCode=02.

Brazil PIX payouts

SDK 1.2.1 adds Recipient.accountType for BR_BRL_PAYOUT_INSTANT. Use CPF, CNPJ, PHONE, EMAIL or EVP, put the corresponding PIX Key in string accountNo, and omit bankCode. Existing bank payouts use bankCode and omit accountType.

In the manual tool, configure exactly one of recipientAccountType and recipientBankCode; neither or both causes failure before sending a request. The server remains responsible for product permissions and final field validation. Do not enable writes until the target environment and original merchant order number have been confirmed.

Local five-interface manual tools

The SDK source includes Keys.java and five independent manual classes under src/test/java/com/xpay/sdk/intl/manual/:

Runnable class	Final interface
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

Copy src/test/resources/intl-sdk-local.properties.example to the Git-ignored intl-sdk-local.properties, fill in the approved merchant configuration, and run the required class's main directly from the IDE. No operation selector is needed. All five classes read the same file. An optional sole program argument, or the JVM property -Dintl.config=..., can point to another local properties file.

The local file never needs to be committed. Create operations require enableWrites=true and a writeConfirmedBaseUrl that exactly equals the current apiBaseUrl, so switching targets invalidates the previous write confirmation. Every production call additionally requires allowProduction=true. Each class sends at most one request and never retries a create request automatically. It does not print the API Secret, but it prints the HTTP status, signature-verification result, all response Headers and the complete UTF-8 Body. The output may contain the response signature, order data and recipient data; do not share raw command-line output. HTTP 5xx, network exceptions, read timeouts or unverifiable responses mean the create result may be unknown; run the matching query class with the same persisted original merchantOrderNo and properties file. If repeated queries still find no order, resend only the unchanged request with that same merchantOrderNo.

Usage guide

• The SDK is Java 8 compatible, does not package a fat JAR and does not automatically retry business create requests.
• Create-request idempotency is based on merchantOrderNo under the same merchant number.
• HTTP 5xx, network exceptions, read timeouts and unverifiable responses mean the create result may be unknown. Query by the original merchantOrderNo; resend only the same unchanged request if repeated queries still find no order, never with a new order number. HTTP 200 means the API call succeeded; use status, query API or Webhook for the business result.
• Ordinary API response and Webhook verification must use the raw Body bytes before JSON parsing.
• Confirm platform operations approved the outbound IP at the gateway security group, WAF or API Gateway; API credentials contain no IP allowlist field.

Usage order

1. Read the Quickstart to confirm test integration, operations-managed security-group access and production credential switching.
2. Use this SDK page for signing, request sending and Webhook verification.
3. Run the Demo in the test environment first; enable production writes only after go-live approval.
4. Complete the Go-live checklist before production traffic.

Troubleshooting data

When opening a support case, provide only the environment, UTC time, merchant number, merchantOrderNo, HTTP status, the Request-Id response Header and response body error.code. Never send API Secrets, Webhook Secrets, full request bodies, signature values or full recipient account numbers.