Zoho

medusa-payment-zoho

Zoho Payments provider for Medusa v2 — India-first, with embedded checkout, hosted checkout, signed webhooks, and refunds.

medusa-payment-zoho connects a Medusa v2 store to Zoho Payments in India (region: "in", the default) or the United States (region: "us"). It creates Zoho payment sessions, opens the Zoho Checkout Widget or Hosted Checkout, verifies payments server-side, accepts signed webhooks, and supports full and partial refunds.

This is an independent community integration. It is not affiliated with, endorsed by, or maintained by Zoho Corporation or Medusa.

Features

• Embedded Zoho Checkout Widget for card, UPI, and other methods enabled on your Zoho account.
• Zoho Hosted Checkout for strict-CSP, no-JS, or redirect-based storefronts.
• Signed webhooks over the exact raw body, with account and live/test-mode checks.
• Correct money handling — ISO-4217 fraction digits, decimal major-unit strings, BigNumber arithmetic, no binary floating point.
• Full and partial refunds against captured payments, with a local replay guard.
• Automatic capture, stated honestly — successful Zoho payments are already captured; capturePayment verifies instead of pretending to capture.
• Safe authorization polling for widget results that arrive before Zoho's session status is final.
• Framework-agnostic browser helper with a typed, discriminated result and no Node.js or Medusa imports in the client bundle.
• Typed errors for configuration, authentication, API, validation, state, and webhook-verification failures.
• 100% test coverage enforced for lines, branches, functions, and statements.

Requirements

Required Zoho OAuth scopes:

Webhook-management scopes are not required: Zoho webhooks are registered manually in the dashboard.

Installation

Install the package in your Medusa application:

npm i medusa-payment-zoho

Release status: medusa-payment-zoho is published on npm. Install the latest release with the command above. The repository also contains the full test suite, source, and release verification so you can audit the exact tarball you install.

Using pnpm or yarn works too; the package ships ESM and CommonJS builds with TypeScript declarations.

Zoho setup

1. Create or confirm your Zoho Payments account in the correct data centre: India (payments.zoho.in) or US (payments.zoho.com). The account, OAuth client, and configured region must all match.

2. Create an OAuth client in the Zoho API console:

   • client type: ORG;
   • redirect URI: for example http://localhost:53682/callback (match the value used by the helper script);
   • scopes: the four scopes listed above.

3. Generate a refresh token with the repository helper: scripts/get-refresh-token.mjs. Configure the account ID, client ID, client secret, region, and redirect URI first, then run:

   The helper performs the one-time authorization-code exchange and prints a long-lived refresh token. It uses Node.js built-ins only and reads credentials from the environment. Treat the output as a secret: do not paste it into issues, logs, or commits.

4. Collect the credentials from Zoho:

   • Account ID — Payments account identifier, sent on every API call.
   • API key — Developer Space browser key, required only for widget mode. This key is publishable by design; it is not the OAuth client secret or signing key.
   • Signing key — Developer Space signing key used for webhooks and checkout signatures. Server-only.

5. Store every secret in environment variables on the Medusa server. See .env.example for the variable names.

Only a Zoho Account Owner or Admin can generate an org-level refresh token. A user can hold at most 20 refresh tokens; generating more removes the oldest.

Backend configuration

Register the provider under the Payment Module in medusa-config.ts. The default region is India and the default checkout mode is the embedded widget:

The provider identifier is zoho and the configured id is zoho, so Medusa stores the provider as pp_zoho_zoho. Keep that ID stable: it appears in payment sessions, the Admin, and the webhook URL. Use the /providers/zoho subpath exactly; the package root is not a module-provider default.

For hosted checkout, set checkoutMode: "hosted" and provide both URLs:

All options, validation rules, and defaults are documented in Configuration.

Webhooks

Register this URL in Zoho Payments under Settings → Developer Space → Webhooks:

https://<your-medusa-backend>/hooks/payment/zoho_zoho

Enable at least:

• payment.succeeded
• payment.pending
• payment.failed

The provider verifies X-Zoho-Webhook-Signature over the exact raw body and parses the event from those same verified bytes. It requires account_id, checks live_mode when configured, and validates the payment amount/currency. A missing signingKey fails closed.

payment.failed is emitted per failed attempt. The provider reconciles it against the Zoho session when Zoho supplies a session ID, so a later successful attempt in the same session still completes the order. Medusa 2.22's stock webhook subscriber ignores FAILED, PENDING, and PENDING_AUTHORIZATION actions; a terminal failure remains available for reconciliation rather than silently becoming paid. Refund events are acknowledged but map to NOT_SUPPORTED; reconcile refunds with retrieveRefund or your own job.

Medusa's payment webhook route returns HTTP 200 before the provider finishes handling the event. A rejected signature therefore does not trigger a Zoho retry: monitor ZOHO_WEBHOOK_VERIFICATION_ERROR and reconcile. See Webhooks for the full setup, retry behaviour, and a signed curl test.

Enable the provider in Medusa Admin

1. Start the Medusa backend after adding the module.
2. Open Settings → Regions and edit the region that uses the matching currency.
3. Under Payment Providers, enable Zoho (pp_zoho_zoho).
4. Save the region and refresh the storefront.

If Zoho does not appear, confirm the module resolves, the backend restarted without configuration errors, and the region is saved. See Troubleshooting.

Storefront quickstart: embedded widget

The checkout flow is:

1. Create or refresh the Medusa payment session for Zoho.
2. Re-read the cart and pass the session's public data to payWithZohoCheckout.
3. Let the customer pay in the Zoho widget.
4. Call cart.complete(). Medusa asks the provider to verify the payment with Zoho; client-reported success is never trusted.

The widget result is a hint; cart.complete() is the authoritative step. If Zoho is still processing an asynchronous method, the order may be created with the payment pending until a signed webhook or status poll confirms capture.

The provider stores only publishable checkout data in the Medusa payment session: zohoSessionId, checkoutMode, amount, currencyCode, currencySymbol, description, invoiceNumber, expiresAt, medusaSessionId, and widget (widget mode) or checkoutUrl (hosted mode). OAuth secrets and the signing key are never included.

Full guide, session-expiry handling, CSP, and server-side widget signature verification: Storefront widget.

Storefront quickstart: hosted checkout

Set checkoutMode: "hosted" and configure successUrl and failureUrl. Then redirect the browser:

On the return URL, verify Zoho's hosted-checkout signature on your server, then call sdk.store.cart.complete(cartId). A redirect is not proof of settlement: ACH can return in_progress, and the webhook is the backstop if the customer closes the browser. Success/failure route examples: Storefront hosted checkout.

Configuration options

Environment variable names used in the examples:

These variables are read by your medusa-config.ts, not automatically by the provider. See Configuration for the full reference.

What is supported

A successful Zoho payment is already captured. There is no separate capture step, no partial capture, and no cancel API. capturePayment re-reads the payment and confirms the capture; it never creates a second charge. Refund settlement can be asynchronous; the provider records Zoho's refund status and logs pending/initiated refunds for reconciliation.

Security

• Secrets stay server-side. clientSecret, refreshToken, signingKey, and access tokens are never placed in payment-session data, logs, errors, or browser bundles. The widget apiKey is publishable by design.
• Webhooks fail closed. The signature is verified over the exact raw body before any field is trusted. There is no development mode that skips verification.
• Account and mode are checked. A valid signature from another Zoho account or from test mode does not complete a live payment.
• Payment ownership is verified. Storefront-supplied session data cannot inject a prior payment or Zoho session ID; authorization checks the Zoho payment's reference and metadata against the current Medusa payment session.
• Amount and currency are reconciled. Zoho amounts are compared with the Medusa session before an order is treated as captured, and positive amounts that round below the currency's precision are rejected.
• The storefront never decides success. It may display a hint, but Medusa asks the provider to retrieve the Zoho session/payment before creating a payment.
• Hosted checkout URLs are capabilities. They contain Zoho's access_key; do not log them, send them to analytics, or expose them in referrer URLs.
• No card data touches your server. Using Zoho's widget or hosted page keeps card entry on Zoho's infrastructure. This reduces, but does not eliminate, PCI DSS scope; confirm your obligations with your acquirer and a qualified assessor.

Report vulnerabilities privately via the process in SECURITY.md.

Testing

pnpm test:coverage enforces 100% lines, branches, functions, and statements. The suite covers amount formatting, status mapping, all three signature schemes, OAuth caching and retries, HTTP retry policy, both checkout modes, webhook authorization, failed-attempt reconciliation, refunds, and browser-helper behaviour.

Documentation

• Configuration
• Storefront: embedded widget
• Storefront: hosted checkout
• Webhooks
• Signature verification
• Troubleshooting
• Architecture
• Compatibility and limitations
• Contributing
• Security policy

License

MIT © Jayashakthi Vishnu.

Zoho, Zoho Payments, and related marks are trademarks of Zoho Corporation. Medusa is a trademark of Medusa, Inc. This project is an independent community integration and is not affiliated with either company.