Connect Zoho Payments

Use this guide to connect the school's own Zoho Payments account to the School ERP. The card is called Zoho Payments. It needs five values: Account ID, Client ID, Client secret, Refresh token and Webhook signing key. In Zoho Payments, sandbox and live are two different accounts, each with its own values.

Before you start#

• The school has a Zoho Payments account approved for India. For testing, it also has a Zoho Payments sandbox account.
• The person generating the refresh token is the account owner or an administrator in Zoho Payments.
• You have the school administrator's login for the School ERP.
• Read Set up a gateway in Payment Configuration once.

Zoho's screens change from time to time. If a menu below looks different, follow Zoho Payments' own API documentation.

Collect the values from Zoho#

1. Sign in to the Zoho Payments sandbox account and note its Account ID from the account settings.
2. In Zoho's developer portal for API clients, create a self client for this account. Copy its Client ID and Client secret.
3. As the account owner or an administrator, generate a refresh token from that self client, with the scopes that let it create and read payments. The help text under Refresh token on the ERP screen names the exact scopes, including the separate sandbox ones.
4. Generate the refresh token once, on purpose. Zoho allows each user only a limited number of refresh tokens and quietly removes the oldest when a new one is made, so generating tokens again and again can break an older connection.
5. Find the webhook signing key in the Zoho Payments developer settings. Zoho also shows it when a webhook is created. It is not the same as the client secret.
6. Keep all five values safely until they are pasted into the ERP.

Enter them in the School ERP#

1. Open General Settings › Payment Configuration.
2. Set Environment to Test / sandbox, then select Configure on the Zoho Payments card.
3. Check that Test environment is selected.
4. Paste into Account ID, Client ID, Client secret, Refresh token and Webhook signing key. All five are required.
5. Select Save settings. The ERP now shows the Webhook URL.
6. Select Test connection.

Point the Zoho webhook at the ERP#

1. In the ERP, select Copy Webhook URL.
2. In Zoho Payments, open the developer settings and create a webhook with this address for payment and refund events, or edit your existing webhook to use it.
3. Check the signing key Zoho shows for this webhook. If it differs from the one you saved, paste the new key into Webhook signing key and select Save settings.
4. Saving changed values gives the gateway a new Webhook URL. If the address on the ERP screen changed, update the webhook's address in Zoho Payments to match.

Test, then go live#

1. Select Start sandbox payment and complete a test payment. See Test a payment end to end.
2. Repeat the steps above with the live Zoho Payments account: its Account ID, a self client, a refresh token with the live scopes, and a live webhook.
3. In the ERP panel select Live environment, paste the live values, tick Enable and use this gateway for fee payments and select Save settings.
4. Copy the live Webhook URL and make sure the live webhook in Zoho Payments uses it.

Good to know#

• A single Zoho Payments payment can be from ₹1 to ₹10,00,000.
• The Zoho payment window opens on the school's secure payment page. The parent has 15 minutes to finish. After that the page says the checkout expired, and the parent starts a new payment from the portal or app.
• If the Zoho payment window cannot load on the parent's device, the parent cannot pay through Zoho Payments. Offering a second gateway gives families another way.
• Zoho Payments settlements are not fetched into the ERP. Record each bank settlement by hand. See Reconciliation and settlements.
• Refund from the ERP, not from the Zoho Payments dashboard. See Refund an online payment.

Troubleshooting#