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
Webhooks
Integrations
- Web Integration
- 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 and complete the account verification process (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, generate the authorization code with the required scopes, and exchange it for access and refresh tokens. Refer to the OAuth guide.

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) 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 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 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 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 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.

Go-Live Checklist

Account Setup

Set Up and Complete Verification

Generate API Keys and OAuth Tokens

Configure Connectivity and Notifications

Review API Error Handling

Webhooks

Integrations

Checkout Widget Integration

Payment Method Widget Integration

Hosted Payment Page Integration

Verify and Confirm Payments

Install and Initialize the SDK

Integrate Payment Flows

Verify and Handle Responses

Let us simplify payments

What to expect in the demo

Request a demo