## Zoho Payments Documentation Index Access the complete documentation index at: https://www.zoho.com/us/payments/llms.txt Use this file to discover all available documentation pages before proceeding. # Go-Live Checklist Before going live with your Zoho Payments integration, complete the checklists below. Checklist items persist locally so you can resume progress anytime. * [Account Setup](#account-setup) * [Set Up and Complete Verification](#set-up) * [Generate API Keys and OAuth Tokens](#Generate-api) * [Configure Connectivity and Notifications](#connectivity) * [Review API Error Handling](#error) * [Webhooks](#webhooks) * [Integrations](#integration-checklists) * [Web Integration](#tab-Web+Integration) * [Server SDK Integration](#tab-Server+SDK+Integration) * * * ## Account Setup Before integrating Zoho Payments, ensure your account is set up, verified, and configured. These foundational steps apply to every integration type. ### Set Up and Complete Verification Create your Zoho Payments account, complete verification, and configure your payment methods. Create a [Zoho Payments account](https://www.zoho.com/us/payments/signup/) and complete the [account verification process](https://www.zoho.com/us/payments/help/getting-started/verification/) (identity, business details, and bank account). Once verification is complete, ensure your account is active. Verify that the integration is managed by a user with Account Owner or Admin. Provide role-based access to a developer to configure and manage the integration. Enable the required payment methods (Cards and ACH) and notification preferences. To enable, go to Settings > Payment Methods. ### Generate API Keys and OAuth Tokens To start interacting with Zoho Payments, you need to generate secure API credentials. The API key allows embedding the payment widget, while the OAuth token ensures your app has authorized access. Generate an API key from Settings > Developer Space > Authentication Keys. Generate OAuth tokens to authenticate your API calls. Register your application in the [Zoho Developer Console](https://api-console.zoho.com/add?client_type=ORG), generate the authorization code with the required scopes, and exchange it for access and refresh tokens. Refer to the [OAuth guide](https://www.zoho.com/us/payments/developerdocs/web-integration/org-oauth/). Generate and store Signing Keys from Settings > Developer Space. This is for verifying payment widget responses and payment link return URLs. Store all credentials (client ID, client secret, API Key, signing key, tokens) securely, never in source code or version control. Ensure only authorized personnel can access these keys. Refresh access tokens before they expire in 1 hour. Refer to the [OAuth Doc (Step 5)](https://www.zoho.com/us/payments/developerdocs/web-integration/org-oauth/#generate-access-tokens-from-refresh-tokens) to regenerate access tokens. **Note:** Authorization code is valid for 1 minute only. Access tokens expire in 1 hour. ### Configure Connectivity and Notifications Ensure your environment is properly connected to Zoho Payments APIs and that notifications are configured. Verify whether you're using live API credentials and not test or placeholder credentials. Whitelist Zoho Payments domains and IP addresses if firewall restrictions are in place. [Contact support](https://www.zoho.com/us/payments/contact-us/) for the latest IP list. Ensure all endpoints (payment, webhook, redirect) use HTTPS with TLS 1.3. All Zoho Payments communications require HTTPS. Ensure SSL certificates are valid and avoid mixed-content warnings. Verify return and redirect URLs are publicly accessible and configured for both success and cancellation flows. Subscribe to account notifications for email for Payments, Payouts, Refunds, and Top-ups. Subscribe to customer notifications for Payments and Refunds. ### Review API Error Handling Ensure to verify your integration using the [error codes](https://www.zoho.com/us/payments/api/v1/errors/#error-codes "Errors") available in our API docs before going live. Test handling of unexpected or low-probability scenarios. Check that API error messages are logged clearly and handled properly. Validate that the system fails without impacting other processes or users. Implement exponential backoff and retry logic for 429 (rate limit) and 5xx (server error) responses. Implement and test authentication failure handling (expired tokens, invalid credentials). * * * ## Webhooks Webhooks notify your system in real time when events like payment or refund successes and failures occur. Configure event types and your endpoint URL to receive notifications. [Set up and register webhook endpoint URL](https://www.zoho.com/us/payments/help/settings/webhooks/#configure-webhooks) in Settings > Developer Space > Webhooks. Copy and store the webhook signing key securely after registration. Implement [signature verification using the X-Zoho-Webhook-Signature header](https://www.zoho.com/us/payments/developerdocs/webhooks/verification/) to ensure the authenticity of webhook notifications. **Tip:** Never expose your webhook signing key in client-side code. Perform verification exclusively on your server. Acknowledge webhook events with HTTP 2xx within 15 seconds to avoid retries. Verify that webhook notifications are received and processed correctly for all required integration events, including handling delayed and duplicate notifications. **Note:** Zoho Payments retries failed webhooks for up to 2 days, hourly on the first day and every 2 hours on the second day. Notification emails are sent after 6 hours and again after 1 day of continuous failures. If failures persist, the endpoint is disabled after 2 days, and you will be notified via email. You can have up to 5 webhook endpoints per account. * * * ## Integrations Complete the checklist for your specific integration type below. Web IntegrationServer SDK Integration ### Checkout Widget Integration The [Checkout Widget](https://www.zoho.com/us/payments/developerdocs/web-integration/integrate-widget/) is embedded directly into your website, giving you full control over the payment experience. [Integrate and embed the payment widget](https://www.zoho.com/us/payments/developerdocs/web-integration/integrate-widget/) into your website. Create a payment session from your backend and pass the `payment_session_id` to the widget on the client side. Confirm the business name displayed in the widget matches your brand. Verify success and failure messages during checkout across supported browsers and devices. Test payment checkout on both mobile and desktop browsers. Implement payment response [signature verification](https://www.zoho.com/us/payments/developerdocs/signature-verification/#widget-response) before processing any outcome. ### Payment Method Widget Integration The [Payment Method Widget](https://www.zoho.com/us/payments/developerdocs/web-integration/payment-method-widget/) lets customers save and manage their payment methods (cards and bank accounts) directly on your website, without processing a payment at the time of setup. [Integrate and embed the payment method widget](https://www.zoho.com/us/payments/developerdocs/web-integration/payment-method-widget/) into your website. Create a payment method session from your backend and pass the `payment_method_session_id` to the widget on the client side. Confirm the business name displayed in the payment method widget matches your brand. Verify success and failure messages when saving a payment method across supported browsers and devices. Test the payment method widget on both mobile and desktop browsers. Implement payment method response signature verification before processing any outcome. Verify that saved payment methods can be successfully used to [create payments](https://www.zoho.com/us/payments/api/v1/payments/#create-payment) via the API. ### Hosted Payment Page Integration The [Hosted Payment Page](https://www.zoho.com/us/payments/developerdocs/web-integration/hosted-payment-page/) is a Zoho Payments-hosted checkout page, no widget embedding required. You create a payment session, obtain the `access_key`, and redirect the customer to the hosted payment page URL. After payment, the customer returns to your site. Create a payment session with hosted page parameters from your backend and obtain the `access_key`. Redirect the customer to the hosted payment page URL using the `access_key`. Configure the return URL to handle both successful and cancelled payment flows. Implement [return URL signature verification](https://www.zoho.com/us/payments/developerdocs/web-integration/hosted-payment-page/#verify-signature) to validate the payment outcome. Verify the business name displayed on the hosted payment page matches your brand. Test the hosted payment page on both mobile and desktop browsers. ### Verify and Confirm Payments These steps apply to both Checkout Widget and Hosted Payment Page integrations. Test the complete payment flow across all [enabled payment methods](https://www.zoho.com/us/payments/help/settings/methods/), including both successful and failed transactions. Do not rely solely on client-side status. Verify payments from your server using the Payment ID. Ensure the payment status is correctly recorded on your server, using [webhooks](https://www.zoho.com/us/payments/api/v1/webhooks/#overview) or the [Payment Session Retrieve API](https://www.zoho.com/us/payments/api/v1/payment-session/#retrieve-payment-session), to confirm completion even if the client-side response is not received (for example, if the customer closes the browser or experiences network interruptions). Verify refunds (full and partial) are processed and recorded accurately. Test with invalid, incomplete, or duplicate data to ensure errors are handled correctly and duplicate processing is prevented. Validate that payment amount, currency, and order reference match your records before fulfilling orders. Ensure payment statuses are recorded accurately in your system. ### Install and Initialize the SDK If you are using the provided SDK, add it to your project and install the required dependencies. Initialize the SDK client with your account ID, edition, and OAuth token. Confirm the edition parameter matches your account region. Create a single shared client instance for your application. ### Integrate Payment Flows Create payment sessions from your server before rendering the [checkout widget](https://www.zoho.com/us/payments/developerdocs/web-integration/integrate-widget/) or [hosted payment page](https://www.zoho.com/us/payments/developerdocs/web-integration/hosted-payment-page/). Verify all required parameters (amount, currency, customer details) are passed correctly when creating payment sessions. Refer to the [Payment Session Create API](https://www.zoho.com/us/payments/api/v1/payment-session/#create-payment-session). Pass the `payment_session_id` (for Checkout Widget) or `access_key` (for Hosted Payment Page) to the client side correctly. Test refund processing (full and partial) and verify refund statuses are recorded accurately. ### Verify and Handle Responses After payment completion, verify the payment status server-side using the [Payment Retrieve API](https://www.zoho.com/us/payments/api/v1/payments/#retrieve-a-payment) or [Payment Session Retrieve API](https://www.zoho.com/us/payments/api/v1/payment-session/#retrieve-payment-session). Handle exceptions returned by the API responses properly. Implement retry logic with exponential backoff for 429 (rate limit) and 5xx (server error) responses. Log API calls, responses, and errors for debugging and audit purposes.