---
url: /zoho-payments-whmcs/guides/zoho-oauth.md
description: >-
  Step-by-step setup of Zoho Payments credentials for WHMCS — create a
  server-based OAuth app, generate a refresh token, add your Account ID and
  Widget API Key, and configure the webhook.
---

# Zoho OAuth setup

This guide connects WHMCS to your Zoho Payments account. You'll create an OAuth application in the
Zoho Developer Console, generate a **refresh token**, add your **Account ID** and **Widget API
Key**, and set up the signed **webhook**. Work top to bottom — each step feeds the next.

::: info Match your data centre first
Everything must be done in the **same Zoho data centre** as your account: India uses
`api-console.zoho.in`, the US uses `api-console.zoho.com`. Pick the matching **Data Center** value
(`IN` or `US`) in the gateway config and use the matching console throughout.
:::

## 1. Create a server-based OAuth app

### What you'll see

The **Zoho Developer Console** for your data centre, with an option to add a new client.

### What to do

Create a **Server-based Application**. When it's created, note the **Client ID** and **Client
Secret** — you'll need both in a moment. Add the redirect URI the console asks for so authorisation
can complete.

::: tip Keep the console tab open
You'll come back here if you ever need to re-generate the refresh token or check the redirect URI.
:::

## 2. Enter Client ID and Client Secret in WHMCS

### What you'll see

The gateway config at **Setup → Payment Gateways → Zoho Payments**, with empty credential fields.

### What to do

Paste the **Client ID** and **Client Secret** into their fields and click **Save Changes**. Saving
first is required so the helper link in the next step can use them.

![The gateway credential fields in WHMCS](/zoho-payments-whmcs/img/zoho-payments-zoho-oauth-credentials.png)
*Setup → Payment Gateways → Zoho Payments*

## 3. Generate the refresh token

### What you'll see

A **"Click Here to Generate Token"** helper link in the gateway settings.

### What to do

Click it, authorise the app with Zoho when prompted, and Zoho returns a **refresh token**. Paste
that token into the **Refresh Token** field and **Save Changes**. From now on the gateway refreshes
its access tokens automatically — you won't repeat this unless you revoke access in Zoho.

::: warning Token errors?
If token generation fails, double-check the **Client ID** / **Client Secret**, confirm the
**redirect URI** is added in the Developer Console, and make sure the **Data Center** matches the
console you used. Then generate the token again.
:::

## 4. Add your Account ID and Widget API Key

### What you'll see

The **Account ID** and **Widget API Key** fields in the gateway config.

### What to do

Enter your **Zoho Payments Account ID** and the **Widget API Key** from the Zoho Developer Space.
These initialise the [checkout widget](/zoho-payments-whmcs/features/widget-checkout) — if either is
wrong, the widget won't load.

## 5. Set up the webhook

### What you'll see

The webhook settings in your Zoho Payments dashboard, and the **Webhook Secret** field (which also
shows your **Webhook URL**) in WHMCS.

### What to do

In Zoho, add a webhook with:

* **Webhook URL:**
  `https://yourdomain.com/modules/gateways/zohopayments/webhooks/paylink_webhook.php`
* **Events:** **Payment completed** and **Payment Link paid**

Copy the webhook **secret** Zoho gives you into the **Webhook Secret** field in WHMCS and **Save
Changes**. Full detail is on the
[Webhooks and Payment Links](/zoho-payments-whmcs/features/webhooks-and-payment-links) page.

## You're connected

With the OAuth app, refresh token, Account ID, Widget API Key, and webhook all in place, turn on
**Test Mode** and run a test payment. When it works end to end, follow the
[going live guide](/zoho-payments-whmcs/guides/going-live).

## Related pages

* [Going live](/zoho-payments-whmcs/guides/going-live)
* [Widget checkout](/zoho-payments-whmcs/features/widget-checkout)
* [Webhooks and Payment Links](/zoho-payments-whmcs/features/webhooks-and-payment-links)
* [Configuration](/zoho-payments-whmcs/configuration)
* [Troubleshooting](/zoho-payments-whmcs/troubleshooting)