Authenticating APIs
Authentication ensures secure access to Zoho Payments’ APIs, verifying that only authorised users can make requests. Developers can authenticate their applications using OAuth and API keys. OAuth allows for secure token-based access, while API keys provide a simpler and more direct method for authentication. OAuth and API Keys are required to secure access to Zoho Payments' APIs.
Once authenticated, developers can interact with the API built on REST principles. The API offers consistent URL structures that simplify development and adhere strictly to HTTP protocols for secure data transmission. The API Root Endpoint provides access to each resource via a unique URL.
API Keys
API keys authenticate your account for secure access, ensuring that only authorised systems can process payments or access payment data.
Note: Only users with Account Owner, Admin, or Developer roles in Zoho Payments can generate and view API keys.
To generate a new API key:
- Open the Zoho Payments application.
- Go to Settings and select Developer Space.
- Select the API keys tab and click Generate Key.
Insight: If the session has been inactive for an extended period or expired, you’ll get a pop-up to re-authenticate with your credentials before generating the key.
Your API key will be generated, and payments will be authenticated through our checkout widget using this key. You can access the API key from Settings anytime by clicking the Eye icon to view or hide the key.
Insight: Do not share or post the API key anywhere since it is used for authentication in client code.
OAuth
OAuth 2.0 in Zoho Payments allows third-party applications to securely access user data without sharing passwords. It uses access tokens for limited, time-bound access to specific resources, ensuring that only trusted apps can interact with Zoho Payments.
Watch this video or follow the steps below to access Zoho Payments' APIs using OAuth 2.0.
1. Register a New Self Client & Generate an Authorisation Code
First, you must register your application with Zoho’s Developer Console to obtain your Client ID and Client Secret.
To register your application:
- Visit Zoho's Developer Console.
- Choose Self Client under Applications.
- Go to the Generate Code tab and enter the scopes you need to access. Use commas to separate multiple scopes.
Scopes in Zoho Payments:
| Scope | Description | Available Types |
|---|---|---|
| Payments | Access to Payments-related APIs. | ZohoPay.payments.CREATE,ZohoPay.payments.READ |
| Refunds | Access to Refunds-related APIs. | ZohoPay.refunds.CREATE,ZohoPay.refunds.READ |
-
Select the Time Duration for the authorisation code’s expiry. By default, it is 3 minutes.
-
Enter the Description and click CREATE.
An authorisation code will be generated. You can copy or download the code in the popup that is being displayed.
Note: Keep these credentials secure, and do not share them with anyone.
2. Generate Access and Refresh Tokens
Once you have the authorisation code from the previous step, make a POST request with the required parameters to generate an access_token. Use the following URL: https://accounts.zoho.in/oauth/v2/token?
| Parameter | Description |
|---|---|
| code* | The code obtained from the previous step. |
| client_id* | A unique ID displayed under Self Client > Client Secret. |
| client_secret* | A unique confidential string displayed under Self Client > Client Secret. |
| grant_type* | This will be authorization_code. |
* Indicates mandatory fields.
The response to your request will include both an access_token and a refresh_token :
access_token: Expires after a certain period, as indicated by theexpires_inparameter in the response.refresh_token: Permanent and can be used to generate a newaccess_tokenonce the current one expires.
Note: A user can have up to 20 refresh tokens. If this limit is exceeded, the oldest refresh token will be automatically deleted, even if it is in use.
Request Example:
`https://accounts.zoho.in/oauth/v2/token?code=1000.dd7exxxxxxxxxxxxxxxxxxxxxxxx9bb8.b6c0xxxxxxxxxxxxxxxxxxxxxxxxdca4&client_id=1000.0SRSxxxxxxxxxxxxxxxxxxxx239V&client_secret=fb01xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx8abf&grant_type=authorisation_code`
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}
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 with the given parameters to the following URL: 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 will be refresh_token. |
Request Example:
`https://accounts.zoho.in/oauth/v2/token?refresh_token=1000.8ecdxxxxxxxxxxxxxxxxxxxxx5cb7.4638xxxxxxxxxxxxxxxxxxxxxxebdc&client_id=1000.0SRSxxxxxxxxxxxxxxxxxxxx239V&client_secret=fb01xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx8abf&grant_type=refresh_token`
5. Revoke Refresh Token
To revoke a refresh token, make a POST request with the given parameters to the following URL: https://accounts.zoho.in/oauth/v2/token/revoke?
| Parameter | Description |
|---|---|
| token | The refresh token that you want to revoke. |
Request Example:
`https://accounts.zoho.in/oauth/v2/token/revoke?token=1000.8ecdxxxxxxxxxxxxxxxxxxxxxxxx5cb7.4638xxxxxxxxxxxxxxxxxxxxxxxxebdc`
Your refresh tokens have now been revoked, and you can’t use them to generate new access tokens to initiate API calls
If you wish to generate tokens again, you will need to repeat the entire process.
