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;
  payButtonProps?: PayButtonProps;
  summaryItems?: ISummaryItem[];
  subscriptionId?: string;
  digitalProductId?: string;
  metadata?: {
    isPaymentInitiatedEnabled?: boolean;
    userInfo?: UserInfo;
    summary?: ISummaryItem[] | (Record<string, any> & { items?: ISummaryItem[] });
    [key: string]: unknown;
  } | null;
  voucher?: boolean;
  embedded?: boolean;
}

Example Usage

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

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

  const handlePayment = async ({
    provider,
    digitalProductId,
    subscriptionId,
    userInfo,
    coupon_code,
    metadata,
    platform,
  }) => {
    const basePayload = {
      userId: userInfo._id,
      provider,
      metadata: { userInfo, ...metadata },
      currency: 'INR' as const,
      ...(coupon_code && { coupon_code }),
    };

    const payload = subscriptionId
      ? { ...basePayload, type: 'subscription' as const, subscriptionId }
      : digitalProductId
        ? { ...basePayload, type: 'digital-product' as const, digitalProductId }
        : { ...basePayload, type: 'normal' as const, price: 999 };

    const res = await client.payments.checkout(payload, platform);
    return res.data;
  };

  return (
    <ZezoPayUI
      publicKey="YOUR_PUBLIC_KEY"
      userInfo={{ _id: 'user_123', name: 'John Doe', email: '[email protected]' }}
      handlePayment={handlePayment}
      embedded
      voucher
      summaryItems={[
        {
          id: '1',
          name: 'Example Product',
          price: 999,
          duration: 'One-time',
        },
      ]}
      callbacks={{
        onSuccess: (res) => console.log('Success', res),
        onFailure: (err) => console.error('Failure', err),
        onClose: () => console.log('Checkout closed'),
      }}
      payButtonProps={{ currency: 'INR' }}
    />
  );
}

📤 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