Java Integration

The Zoho Payments Java SDK is an official client library that provides Java developers with a type-safe interface to the Zoho Payments REST API v1. It handles HTTP communication, JSON serialization, and authentication so you can focus on building your payment integration.

The SDK source code is available on GitHub.

Install the SDK
Initialize the Client
Integration Steps
Token Management
Closing the Client
Supported Operations

Note: Ensure that Java 17 or later is installed on your system.

1. Install the SDK

You can add the Zoho Payments Java SDK to your project using Gradle, Maven, or by manually downloading the JARs.

Gradle

build.gradle

repositories {
    maven {
        url "https://static.zohocdn.com/zpayments/"
    }
    mavenCentral()
}

dependencies {
    implementation "com.zohopayments.java:sdk:1.0.0"
}

Maven

pom.xml

<repositories>
    <repository>
        <id>zohopayments-repo</id>
        <url>https://static.zohocdn.com/zpayments/</url>
    </repository>
</repositories>

<dependencies>
    <dependency>
        <groupId>com.zohopayments.java</groupId>
        <artifactId>sdk</artifactId>
        <version>1.0.0</version>
    </dependency>
</dependencies>

Manual Installation

If you are not using Gradle or Maven, you will need to manually install the following JARs:

Zoho Payments JAR: Download version 1.0.0 from the Zoho Payments SDK repository.
Google Gson: Download version 2.10.1 from Maven Central.

Add both JARs to your project’s classpath.

Note: The SDK uses the JDK built-in java.net.http.HttpClient for HTTP communication and Gson for JSON serialization/deserialization.

2. Initialize the Client

The builder validates the required fields (accountId, edition, and oauthToken) at build time and throws an exception immediately if any are missing or invalid.

Initialize ZohoPayments Client

ZohoPayments client = ZohoPayments.builder()
        .accountId("23137556")
        .edition(Edition.IN)
        .oauthToken("1000.access_token_here")
        .build();

Parameter	Required	Description
`accountId`	Yes	Your Zoho Payments Account ID.
`edition`	Yes	The edition to use: `Edition.US`, `Edition.IN`, or `Edition.IN_SANDBOX`.
`oauthToken`	Yes	A valid OAuth access token. Refer to the OAuth setup to generate tokens.

Note: The client is thread-safe. TokenManager uses AtomicReference<String> for lock-free token rotation. You can create a single instance and share it across your application.

3. Integration Steps

Once the SDK is installed and the client is initialized, you can use it to make API calls for your payment integration. The integration flow depends on your chosen integration method:

Use the SDK to create a payment session on your server, then pass the payment_session_id to the checkout widget on the client side. Follow the step-by-step guide in the Integrating Checkout Widget documentation.

Hosted Payment Page Integration

Use the SDK to create a payment session with hosted page parameters, then redirect the customer to the hosted payment page using the access_key. Follow the step-by-step guide in the Hosted Payment Page documentation.

For both methods, refer to the Payment Session Create API for the complete list of request parameters.

After the customer completes the payment, verify the payment status using the Payment Retrieve API, Payment Session Retrieve API, or your configured webhooks.

4. Token Management

The SDK does not automatically refresh tokens. When your OAuth token expires, refresh it explicitly and update the client.

Refresh Token

// Generate a new access token
OAuthToken freshToken = ZohoPayments.generateAccessToken(
        refreshToken, clientId, clientSecret, redirectUri, Edition.IN);

// Update the client with the new token
client.updateToken(freshToken);

Insight: Token refresh is intentionally explicit, the SDK does not silently retry with refresh tokens. This keeps behavior predictable and gives you full control over the authentication flow.

5. Closing the Client

When your application no longer needs the SDK client, call client.close() to release the resources held by the client. This ensures that HTTP connections, background threads, and cached authentication state are cleaned up properly.

You should call close() in the following scenarios:

At application shutdown.
After completing a short-lived batch job or standalone script.
Before re-initializing the client with new credentials or configuration.

Usage

There are two ways to close the client:

Explicit close: You manually call close() inside a finally block to ensure the client is always closed, even if an error occurs during API calls.

Explicit close

ZPaymentsClient client = new ZPaymentsClient(...);

try {
    // make API calls using client
} finally {
    client.close();
}

Try-with-resources (recommended): Java automatically calls close() at the end of the try block, so you don’t need to write a finally block. This is the cleaner and recommended approach.

Try-with-resources

try (ZPaymentsClient client = new ZPaymentsClient(...)) {
    // make API calls using client
}
// client.close() is invoked automatically

Note: Once closed, the client can no longer be used. Any subsequent API call will result in an error.

Supported Operations

The Java SDK supports the full range of Zoho Payments API operations. Refer to the API documentation for detailed endpoints.

Service	Description
Payment Session	Create and manage payment sessions.
Payments	Accept and manage payments.
Refunds	Process and track refunds.
Customers	Create and manage customer records.
Payment Links	Generate shareable payment links.
Mandates	Set up recurring payment mandates.
Virtual Accounts	Create and manage virtual accounts.

Note: Some services are edition-specific. Attempting to use a US-only service with an IN edition client (or vice versa) will throw an UnsupportedOperationException. Ensure your client is configured with the correct edition.