ZezoPay Client SDK (@zezosoft/zezopay-client)

Welcome to the ZezoPay Client SDK. This SDK is designed for frontend applications (web, mobile, etc.) to easily integrate payments, subscriptions, and digital products with your ZezoPay account.

📌 Overview

With the ZezoPay Client SDK you can:

• Fetch available payment providers
• Initiate payments for digital products and subscriptions
• Retrieve subscriptions (list & active)
• List publicly available digital products
• Integrate a ready-to-use React component for payment UI (ZezoPayUI)
• Use TypeScript typings for safer, cleaner code

⚠️ This SDK is client-only. For server-side verification and secure operations, use @zezosoft/zezopay.

🚀 Installation

npm install @zezosoft/zezopay-client
# or
yarn add @zezosoft/zezopay-client
# or
pnpm add @zezosoft/zezopay-client

🛠️ Setup & Initialization

import { ZezoPayClient } from '@zezosoft/zezopay-client';

const client = new ZezoPayClient({
  publicKey: 'YOUR_PUBLIC_KEY',
});

🔑 Obtaining Public Key

1. Visit the ZezoPay Dashboard: https://pay.zezo.in
2. Log in or create an account
3. Navigate to Settings → API Keys
4. Generate a new API Key and copy your Public Key

🔧 Services

The SDK exposes three core services under the client instance:

• payments

  • providers({ platform })
  • checkout(payload, platform?)
  • verifyCoupon(payload)

• subscriptions

  • list(query?)
  • active(userId, query?)

• digitalProducts

  • list()

Note: ZezoPayUI is not a service but a ready-to-use React component. It does not provide programmatic methods like payments or subscriptions, but encapsulates these services internally for UI integration.

💻 ZezoPayUI Component

The ZezoPayUI is a React component designed for web applications only. It provides a complete UI for handling payments, including summary, vouchers, and provider selection.

⚡ CSS Setup: For optimal performance, add ZezoPay styles to your global CSS (index.css or globals.css) instead of importing in individual components.

@import '@zezosoft/zezopay-client/styles';

This ensures the ZezoPay UI loads once globally, preventing duplicate styles and improving page load speed.

Props

export interface ZezoPayUIProps {
  publicKey: string;
  userInfo: UserInfo;
  handlePayment?: HandlePayment;
  callbacks?: ZezoPayCallbacks;
  redirectUrl?: string;
  payButtonProps?: PayButtonProps;
  summaryItems?: ISummaryItem[];
  validateVoucherCode?: (code: string) => number;
  subscriptionId?: string;
  productId?: string;
}

Example Usage

import { ZezoPayUI } from '@zezosoft/zezopay-client';
import '@zezosoft/zezopay-client/styles';

function CheckoutPage() {
  return (
    <ZezoPayUI
      publicKey="YOUR_PUBLIC_KEY"
      userInfo={{ _id: 'user_123', name: 'John Doe' }}
      handlePayment={async ({ provider, digitalProductId, userInfo }) => {
        // call client.payments.checkout here
        return await client.payments.checkout({
          type: 'digital-product',
          userId: userInfo._id,
          provider,
          digitalProductId,
          metadata: { userInfo },
          currency: 'INR',
        });
      }}
      callbacks={{
        onSuccess: (res) => console.log('Success', res),
        onFailure: (err) => console.error('Failure', err),
      }}
    />
  );
}

📤 Examples

Payments

const providers = await client.payments.providers({ platform: 'web' });

const checkout = await client.payments.checkout(
  {
    type: 'digital-product',
    userId: 'user_123',
    provider: 'razorpay',
    digitalProductId: 'prod_001',
    metadata: { userInfo: { _id: 'user_123', name: 'John Doe' } },
    currency: 'INR',
  },
  'web',
);

Subscriptions

const subs = await client.subscriptions.list({ page: 1, limit: 5 });
const active = await client.subscriptions.active('user_123');

Digital Products

const products = await client.digitalProducts.list();

🔄 Error Handling

try {
  await client.payments.checkout({
    /* ... */
  });
} catch (error) {
  console.error('API Error:', error);
}

Error format example:

{
  "type": "validation_error",
  "status": 400,
  "message": "Invalid email",
  "path": "email",
  "location": "body"
}

❓ FAQ

• Can I use this SDK on the server?

  • No. This package is client-only. Use @zezosoft/zezopay for backend operations.

• Does it support TypeScript?

  • Yes. Full TypeScript typings are included.

• Can I create/update digital products from the client?

  • No. Client SDK is read-only for subscriptions and products.

• How to use ZezoPayUI?

  • Import ZezoPayUI from @zezosoft/zezopay-client and pass the required props. It wraps the payment services internally.

🛠️ Contributing

• Contact: [email protected]
• Documentation: pay.zezo.in/docs

👨‍💻 Contributors

📜 License

Released under the MIT License