## 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.

# Integrating Server SDK

Install and configure the Zoho Payments server SDK to accept payments, process refunds, and manage customers directly from your backend application. Select your language below and follow the instructions to install, initialize, and start using the SDK.

**Prerequisites:**

*   Create a Zoho Payments account and complete the verification process. Learn [how to get started.](https://www.zoho.com/in/payments/help/getting-started/setup/ "Get Started")
*   [Generate an OAuth token](/in/payments/developerdocs/web-integration/authentication/ "Authentication") to authenticate your API calls.

*   [Get Started](#get-started)
    *   [Install the SDK](#install-sdk)
    *   [Initialize the Client](#initialize-client)
    *   [Integrate your Application](#integration-steps)
*   [Manage Tokens](#token-management)
*   [Close the Client](#closing-client)
*   [Supported Operations](#supported-operations)

### Available SDKs

**Language**

**Minimum Version**

**Source Code**

Java

Java 17+

[GitHub](https://github.com/zoho/zoho-payments-java-sdk "Zoho Payments Java SDK")

Python

Python 3.11+

[GitHub](https://github.com/zoho/zoho-payments-python-sdk "Zoho Payments Python SDK")

* * *

## Get Started

To accept payments using the SDK, you need to install it in your project, initialize a client with your account credentials, and then use the client to create payment sessions and process transactions. Here’s how:

### 1\. Install the SDK

Gradle (build.gradle)

Java

Java

Python

Copy

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

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

```python
pip install zoho-payments
```

Maven

Java

Java

Python

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

```python
pip install zoho-payments
```

**Java:** The SDK uses the JDK built-in `java.net.http.HttpClient` for HTTP communication and **Gson** for JSON serialization/deserialization. If you are not using Gradle or Maven, download the [SDK JAR](https://static.zohocdn.com/zpayments/com/zohopayments/java/sdk/1.0.0/sdk-1.0.0.jar "Download SDK") and [Gson 2.10.1](https://repo1.maven.org/maven2/com/google/code/gson/gson/2.10.1/gson-2.10.1.jar "Gson") and add both to your classpath.

**Python:** The SDK uses the `requests` library as its only runtime dependency for HTTP communication and the standard library `json` module for JSON serialization. Response models are built using `@dataclass(frozen=True)` for immutability.

The SDK is now installed and ready to use in your project.

### 2\. Initialize the Client

Use the builder pattern to create a client instance. The builder validates the `accountId`, `edition`, and `oauthToken` at build time and raises an error if any are missing or invalid.

Initialize ZohoPayments Client

Java

Java

Python

Copy

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

```python
client = (
    ZohoPayments.builder()
    .account_id("23137556")
    .edition(Edition.IN)
    .oauth_token("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 documentation](/in/payments/developerdocs/web-integration/authentication/ "OAuth") to generate tokens.

**Note:** The client is thread-safe. You can create a single instance and share it across your application.

Your client is now initialized and ready to make API calls.

### 3\. Integrate your Application

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 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 Checkout Integration

Use the SDK to create a payment session with hosted checkout parameters, then redirect the customer to the hosted checkout page using the `access_key`. Follow the step-by-step guide in the [Hosted Checkout documentation.](https://www.zoho.com/in/payments/developerdocs/web-integration/hosted-checkout/ "Hosted Checkout")

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").

Your application is now integrated with Zoho Payments and can accept payments from customers.

* * *

## Manage Tokens

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

Refresh Token

Java

Java

Python

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);
```

```python
fresh = ZohoPayments.generate_access_token(
    refresh_token="...",
    client_id="...",
    client_secret="...",
    redirect_uri="...",
    edition=Edition.IN,
)
client.update_token(fresh.access_token)
```

**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.

The client is now updated with the new token and can continue making API calls.

* * *

## Close the Client

When your application no longer needs the SDK client, close it to release resources held by the underlying HTTP transport. This ensures that connections and session state are cleaned up properly.

You should close the client 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.

### Explicit Close

Explicit close

Java

Java

Python

Copy

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

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

```python
client = (
    ZohoPayments.builder()
    .account_id("23137556")
    .edition(Edition.IN)
    .oauth_token("1000.access_token_here")
    .build()
)

try:
    # make API calls using client
    ...
finally:
    client.close()
```

### Auto-Close

Auto-close

Java

Java

Python

Copy

```java
// Try-with-resources — close() is called automatically
try (ZohoPaymentsClient client = ZohoPayments.builder()
        .accountId("23137556")
        .edition(Edition.IN)
        .oauthToken("1000.access_token_here")
        .build()) {
    // make API calls using client
}
```

```python
with (
    ZohoPayments.builder()
    .account_id("23137556")
    .edition(Edition.IN)
    .oauth_token("1000.access_token_here")
    .build()
) as client:
    # make API calls using client
    ...
# client.close() runs automatically here, including on exceptions
```

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

The client is now closed and all underlying resources are released.

* * *

## Supported Operations

Both SDKs support 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.

Collect (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 result in an error. Ensure your client is configured with the correct edition.