## Zoho Payments Documentation Index

Access the complete documentation index at:
https://www.zoho.com/in/payments/llms.txt

Use this file to discover all available documentation pages before proceeding.

# 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](https://github.com/zoho/zoho-payments-java-sdk "Zoho Payments Java SDK").

*   [Install the SDK](#install-sdk)
*   [Initialize the Client](#initialize-client)
*   [Integration Steps](#integration-steps)
*   [Token Management](#token-management)
*   [Closing the Client](#closing-client)
*   [Supported Operations](#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

Copy

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

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

### Maven

pom.xml

Copy

```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:

1.  **Zoho Payments JAR:** Download version 1.0.0 from the [Zoho Payments SDK repository](https://static.zohocdn.com/zpayments/com/zohopayments/java/sdk/1.0.0/sdk-1.0.0.jar "Download SDK").
2.  **Google Gson:** Download version 2.10.1 from [Maven Central](https://repo1.maven.org/maven2/com/google/code/gson/gson/2.10.1/gson-2.10.1.jar "Gson").

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

Copy

```java
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](/in/payments/developerdocs/web-integration/authentication/ "OAuth") 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:

### Checkout Widget Integration

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.](/in/payments/developerdocs/web-integration/integrate-widget/ "Checkout Widget")

### 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.](/in/payments/developerdocs/web-integration/hosted-payment-page/ "Hosted Payment Page")

For both methods, refer to the [Payment Session Create API](https://www.zoho.com/in/payments/api/v1/payment-session/#create-payment-session "Payment Session API") for the complete list of request parameters.

After the customer completes the payment, verify the payment status using the [Payment Retrieve API](https://www.zoho.com/in/payments/api/v1/payments/#retrieve-payment "Retrieve Payment"), [Payment Session Retrieve API](https://www.zoho.com/in/payments/api/v1/payment-session/#retrieve-payment-session "Retrieve Session"), or your [configured webhooks](/in/payments/developerdocs/webhooks/configure/ "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

Copy

```java
// 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

Copy

```java
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

Copy

```java
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](https://www.zoho.com/in/payments/api/v1/introduction/#overview "API Doc") 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.