API Docs
/
No Results Found
Authentication

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
India .in https://accounts.zoho.in/

Scopes in Zoho Payments:

Scope Description Available Types
Payments Access to Payments-related APIs. ZohoPay.payments.CREATE,ZohoPay.payments.READ,ZohoPay.payments.UPDATE
Refunds Access to Refunds-related APIs. ZohoPay.refunds.CREATE,ZohoPay.refunds.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.

Org OAuth Console

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

Org OAuth Client

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.in/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 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.

    Org OAuth Grant Access

    Request Example

    Click to copy
    https://accounts.zoho.in/oauth/v2/org/auth?scope=ZohoPay.payments.CREATE,ZohoPay.payments.READ,ZohoPay.payments.UPDATE&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.

    Response Example

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

    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.in/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:

    1. access_token: Expires after a certain period, as indicated by the expires_in parameter in the response.
    2. 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.

    Request Example

    Click to copy
    https://accounts.zoho.in/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.in/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.

    Request Example

    Click to copy
    https://accounts.zoho.in/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.in/oauth/v2/token/revoke?

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

    Request Example

    Click to copy
    https://accounts.zoho.in/oauth/v2/token/revoke?token=1000.8ecdxxxxxxxxxxxxxxxxxxxxxxxx5cb7.4638xxxxxxxxxxxxxxxxxxxxxxxxebdc

    OAuth (Deprecated Soon)

    Note: This flow is available only for existing users. We recommend migrating to the new OAuth flow, as this version will be deprecated soon.

    Watch this video or follow the steps below to access Zoho Payments' APIs using OAuth 2.0:

    Step 1: Register a new Self Client & Generate an authorization code

    First, you must register your application with Zoho's Developer Console to obtain your Client ID and Client Secret.

    To register your application:

     1. Visit Zoho's Developer Console at https://accounts.zoho.in/developerconsole

     2. Kindly choose Self Client option.

     3. In the Generate Code tab, Enter the scopes you need to access. Use commas to separate multiple scopes. You can refer above for the required scopes.

     4. Select an expiry time for the authorization code. By default, it is 3 minutes.

     5. Enter a description for the required scopes.

    Self Client

    6. Click CREATE. An authorization code will be generated and displayed.

    Generated Code

    7. Copy or download the authorization code.

    Keep these credentials secure, and do not share them.

    Step 2: Generate Access and Refresh Tokens

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

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

    Parameter Description
    code* The code obtained from the previous step.
    client_id* The unique ID displayed under Self Client > Client Secret.
    client_secret* The unique confidential secret displayed under Self Client > Client Secret.
    grant_type* This is authorization_code.

    Note: Fields marked with * are mandatory

    The response to your request will include both an access_token and a refresh_token :

    1. access_token: Expires after a certain period, as indicated by the expires_in parameter in the response.
    2. refresh_token: Permanent and can be used to generate a new access_token once the current one expires.

    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.

    Request Example

    Click to copy
    https://accounts.zoho.in/oauth/v2/token?code=1000.dd7exxxxxxxxxxxxxxxxxxxxxxxx9bb8.b6c0xxxxxxxxxxxxxxxxxxxxxxxxdca4&client_id=1000.0SRSxxxxxxxxxxxxxxxxxxxx239V&client_secret=fb01xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx8abf&grant_type=authorization_code

    Step 3: Call an API

    When calling an API, the access token must be included in the request header and cannot be passed as a request parameter.

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

    Step 4: Generate Access Tokens from Refresh Tokens

    Access tokens have limited validity, typically expiring in one hour, but can be used without restriction during this time. Once an access token expires, 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.in/oauth/v2/token?

    Parameter Description
    refresh_token The refresh token obtained from the previous step.
    client_id The Client ID received during client registration.
    client_secret The Client Secret received during client registration.
    grant_type This is refresh_token .

    Request Example

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

    Step 5: Revoke a Refresh Token

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

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

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

    Request Example

    Click to copy
    https://accounts.zoho.in/oauth/v2/token/revoke?token=1000.8ecdxxxxxxxxxxxxxxxxxxxxxxxx5cb7.4638xxxxxxxxxxxxxxxxxxxxxxxxebdc