Introduction

Zoho Payments API uses the OAuth 2.0 protocol for authorization and authentication. It provides secure access to resources and reduces the need for repeated username and password entries, keeping your API interactions secure and efficient.

Data Center	Domain	Base API URI
United States	.com	https://accounts.zoho.com/

Scopes in Zoho Payments:

Scope	Description	Available Types
Customers	Access to Customer-related APIs.	`ZohoPay.customers.CREATE, ZohoPay.customers.READ`
Payment Methods	Access to Payment Method-related APIs.	`ZohoPay.paymentmethods.READ, ZohoPay.paymentmethods.UPDATE, ZohoPay.paymentmethods.DELETE`
Payments	Access to Payments-related APIs.	`ZohoPay.payments.CREATE, ZohoPay.payments.READ`
Refunds	Access to Refunds-related APIs.	`ZohoPay.refunds.CREATE, ZohoPay.refunds.READ`
Payouts	Access to Payouts-related APIs.	`ZohoPay.payouts.READ`

OAuth

Step 1: Register a New Client

To begin, register your application in the Zoho's Developer Console to obtain your Client ID and Client Secret.

Note: Only users with the Account Owner or Admin role in Zoho Payments can generate an OAuth token.

To register your application:

1. Go to the Zoho Developer Console and ensure that the client type is set to ORG in the URL.

2. Enter the Client Name, Homepage URL, and the Authorized Redirect URIs.

Parameter	Description
Client Name	A name to identify your application.
Homepage URL	The URL of your application's homepage or main website.
Authorized Redirect URIs	The URL to which you'll be redirected once access is granted. Ensure it's the same as the one used in your OAuth requests.

3. Click CREATE.

Your Client ID and Client Secret will be generated. You can access them from the Client Secret tab in the Zoho Developer Console.

Keep your credentials secure and do not share them with anyone.

Step 2: Generate an Authorization Code

Once you have the client credentials, make a GET with the required parameters to generate the authorization url to retrieve the authorization_code:

https://accounts.zoho.com/oauth/v2/org/auth?

Parameter	Description
scope^*	Enter the scopes you need to access. Use commas to separate multiple scopes. You can refer above for the required scopes.
client_id^*	The unique ID available under Developer Console > Your Client > Client Secret.
soid^*	This is your Zoho Payments account ID, and its format should be `zohopay.{account_id}`.
response_type^*	This must be set to `code`.
redirect_uri^*	Your callback URL with an authorization code and response token. This should be the same URI that you used during registration.
state	A random string value (can be a number, a character, or a string of characters) used to describe the authorization request.
access_type	This can be set to `online` or `offline`. Online: Provides an `access_token` valid for one hour. Offline: Provides an `access_token` and a `refresh_token`.

Note: Fields marked with * are mandatory

Once the URL is constructed, copy and paste the GET URL in your browser. This will list the account for which you want to grant access.

Click ACCEPT to grant access to your Zoho Payments account data.


https://accounts.zoho.com/oauth/v2/org/auth?scope=ZohoPay.payments.CREATE,ZohoPay.payments.READ&client_id=1005xxxxxxxxxxxxxxxxxxxxxxxxx&soid=zohopay.8xxxxxxxx3&state=To generate payments access token&response_type=code&redirect_uri=https://www.zylker.com/&access_type=offline

After granting access, you'll be redirected to the specified Redirect URI. You can retrieve the authorization_code from the code parameter, along with other parameters.

Note: Only the data associated with the scopes you've specified will be accessible after the user grants permission.


https://www.zylker.com/?state=To generate payments access token&code=1005.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxc&location=us&accounts-server=https%3A%2F%2Faccounts.zoho.com

Step 3: Generate Access and Refresh Tokens

Once you have the code, make a POST request to the following URL with the required parameters to generate the access_token:

https://accounts.zoho.com/oauth/v2/token?

Parameter	Description
code^*	The code obtained from the previous step.
client_id^*	The unique ID available under Developer Console > Your Client > Client Secret.
client_secret^*	The Client Secret available under Developer Console > Your Client > Client Secret.
redirect_uri^*	Your callback URL.
grant_type^*	This must be set to `authorization_code`.

Note: Fields marked with * are mandatory

You will receive a response containing an access_token and a refresh_token:

access_token: Expires after a certain period, as indicated by the expires_in parameter in the response.
refresh_token: Used to generate a new access_token once the current one expires. The refresh token remains valid unless it is revoked or expired.

Note: A user can have a maximum of 20 refresh tokens. Exceeding this limit will result in the oldest refresh token being deleted automatically, regardless of whether it is in use.


https://accounts.zoho.com/oauth/v2/token?code=1000.dd7exxxxxxxxxxxxxxxxxxxxxxxx9bb8.b6c0xxxxxxxxxxxxxxxxxxxxxxxxdca4&client_id=1000.0SRSxxxxxxxxxxxxxxxxxxxx239V&client_secret=fb01xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx8abf&grant_type=authorization_code&redirect_uri=https://www.zylker.com/

Step 4: Call an API

When calling an API, include the access_token in the request header. Do not pass it as a request parameter.

Header Name: Authorization
Header Value: Zoho-oauthtoken {access_token}

Step 5: Generate Access Tokens from Refresh Tokens

Access tokens, typically expire in one hour, but can be used without restriction during this time. Once expired, your application must use the refresh token to obtain a new access token.

To generate a new access token, make a POST request to the following URL with the given parameters:

https://accounts.zoho.com/oauth/v2/token?

Parameter	Description
refresh_token	The refresh token obtained from the previous step.
client_id	The unique ID available under Developer Console > Your Client > Client Secret.
client_secret	The Client Secret available under Developer Console > Your Client > Client Secret.
redirect_uri	Your callback URL.
grant_type	This must be set to `refresh_token`.


https://accounts.zoho.com/oauth/v2/token?refresh_token=1000.8ecdxxxxxxxxxxxxxxxxxxxxx5cb7.4638xxxxxxxxxxxxxxxxxxxxxxebdc&client_id=1000.0SRSxxxxxxxxxxxxxxxxxxxx239V&client_secret=fb01xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx8abf&grant_type=refresh_token

Step 6: Revoke a Refresh Token

To revoke a refresh token, call the following POST URL with the given parameters:

https://accounts.zoho.com/oauth/v2/token/revoke?

Parameter	Description
token	The refresh token that you want to revoke.


https://accounts.zoho.com/oauth/v2/token/revoke?token=1000.8ecdxxxxxxxxxxxxxxxxxxxxxxxx5cb7.4638xxxxxxxxxxxxxxxxxxxxxxxxebdc