Java SDK

The UQPAY Java SDK provides typed access to the UQPAY API, including automatic Access Token management, webhook verification, PGP-based authorization decision, and sandbox transaction simulation.

GitHub

GitHub Releases

The SDK requires Java 11 or later, with Maven 3.6+ or Gradle 7+. Version 1.2.0 is its first release in the coordinated client release line.

Installation

The Java SDK is distributed as a thin JAR through GitHub Releases. It is not published to Maven Central, so com.uqpay.sdk:uqpay-sdk-java:2.1.0 cannot be resolved from a public Maven repository. Download uqpay-sdk-java-2.1.0.jar from the v2.1.0 release and install it into your local Maven repository:

mvn install:install-file \
  -Dfile=uqpay-sdk-java-2.1.0.jar \
  -DgroupId=com.uqpay.sdk \
  -DartifactId=uqpay-sdk-java \
  -Dversion=2.1.0 \
  -Dpackaging=jar

You can then reference the locally installed artifact from Maven or Gradle. Because this is a thin JAR, your project must also declare the runtime dependencies listed in the SDK repository’s pom.xml, including Jackson, OkHttp, and Bouncy Castle.

Quick start

Before you begin, create a sandbox account and create API keys.

Sandbox
Production

import com.uqpay.sdk.UqpayClient;

UqpayClient client = UqpayClient.sandbox("your-client-id", "your-api-key");

import com.uqpay.sdk.UqpayClient;

UqpayClient client = UqpayClient.production("your-client-id", "your-api-key");

Authentication

The SDK uses your clientId and apiKey to retrieve a UQPAY Access Token, caches it, and retrieves a new Token before the current one expires. You do not need to manage Tokens manually.

Configuration

Custom HTTP client

import okhttp3.OkHttpClient;
import com.uqpay.sdk.config.Configuration;
import com.uqpay.sdk.config.Environment;

OkHttpClient httpClient = new OkHttpClient.Builder()
        .connectTimeout(Duration.ofSeconds(60))
        .readTimeout(Duration.ofSeconds(60))
        .build();

Configuration config = Configuration.builder()
        .clientId("your-client-id")
        .apiKey("your-api-key")
        .environment(Environment.PRODUCTION)
        .httpClient(httpClient)
        .build();

UqpayClient client = new UqpayClient(config);

Environments

Constant	Description
`Environment.SANDBOX`	Sandbox environment for testing and development
`Environment.PRODUCTION`	Production environment for live transactions

Pagination

All list methods return a paginated response with getData(), getTotalPages(), and getTotalItems():

ListCardsRequest req = new ListCardsRequest();
req.setPageNumber(1);
req.setPageSize(50);
ListCardsResponse page = client.issuing().getCards().list(req);

System.out.println(page.getData());       // List<Card>
System.out.println(page.getTotalPages()); // total number of pages
System.out.println(page.getTotalItems()); // total number of items

Webhooks

Verify incoming webhook signatures from UQPAY: Before implementing verification, configure a notification URL and review the webhook delivery and security model.

import com.uqpay.sdk.webhook.WebhookVerifier;
import com.uqpay.sdk.webhook.Event;
import com.uqpay.sdk.common.UqpayWebhookException;

WebhookVerifier verifier = new WebhookVerifier("your-webhook-secret");

try {
    Event event = verifier.verifyAndParse(
        requestBodyString,
        request.getHeader("x-wk-signature"),
        request.getHeader("x-wk-timestamp")
    );

    if (event.isCardTransactionEvent()) {
        // handle card transaction authorization, clearing, etc.
    } else if (Event.EVENT_NAME_CARDHOLDER_KYC.equals(event.getEventName())) {
        // handle KYC status update
    }
} catch (UqpayWebhookException e) {
    // signature invalid or timestamp expired
    response.setStatus(400);
}

The verifier checks the HMAC-SHA512 signature and rejects requests with a timestamp older than 300 seconds by default.

Authorization decision (PGP)

Handle real-time card transaction authorization decisions. UQPAY sends PGP-encrypted transactions to your endpoint; the SDK decrypts them, calls your handler, and returns an encrypted response. Before implementing the handler, review the authorization decision workflow, prerequisites, response codes, and timeout requirements.

import com.uqpay.sdk.issuing.AuthDecisionService;
import com.uqpay.sdk.issuing.AuthDecisionHandler;
import com.uqpay.sdk.issuing.model.AuthDecisionConfig;
import com.uqpay.sdk.issuing.model.AuthDecisionRequest;
import com.uqpay.sdk.issuing.model.AuthDecisionResponse;

// Configure PGP keys (once at startup)
AuthDecisionConfig config = new AuthDecisionConfig(
    "./keys/my-private.asc",
    System.getenv("PGP_PASSPHRASE"),
    "./keys/uqpay-public.asc"
);

AuthDecisionService authDecision = client.issuing().getAuthDecision();
authDecision.configure(config);

// Handle a decision request
AuthDecisionHandler handler = (AuthDecisionRequest tx) -> {
    if (tx.getBillingAmount() > 10000) {
        return AuthDecisionResponse.decline(tx.getTransactionId(), "51");
    }
    return AuthDecisionResponse.approve(tx.getTransactionId());
};

// In your HTTP handler, pass the raw encrypted body string:
String encryptedResponse = authDecision.processRequest(requestBodyString, handler);
response.getWriter().write(encryptedResponse);

Stablecoin Account (Ramp) is not included in the current SDK product scope.

Error handling

The SDK uses a hierarchy of exceptions:

Exception	Description
`UqpayException`	Base exception for all SDK errors
`UqpayApiException`	API returned an error response (includes HTTP status, error code, message)
`UqpayAuthException`	Authentication failed (invalid credentials or Token retrieval failure)
`UqpayNetworkException`	Network-level failure (timeout, connection refused)
`UqpayWebhookException`	Webhook signature verification failed

try {
    Balance balance = client.banking().getBalances().get("SGD");
} catch (UqpayApiException e) {
    System.err.printf("API error: status=%d, code=%s, message=%s%n",
            e.getStatusCode(), e.getCode(), e.getMessage());
} catch (UqpayAuthException e) {
    System.err.println("Authentication failed: " + e.getMessage());
} catch (UqpayNetworkException e) {
    System.err.println("Network error: " + e.getMessage());
} catch (UqpayException e) {
    System.err.println("SDK error: " + e.getMessage());
}

MCP

CLI

SDKs

GitHub

Installation

Quick start

Authentication

Configuration

Custom HTTP client

Environments

Webhooks

Authorization decision (PGP)

Error handling

GitHub

​Installation

​Quick start

​Authentication

​Configuration

​Custom HTTP client

​Environments

​Pagination

​Webhooks

​Authorization decision (PGP)

​Error handling

Installation

Quick start

Authentication

Configuration

Custom HTTP client

Environments

Pagination

Webhooks

Authorization decision (PGP)

Error handling