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 (ZezoPay)
• 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 core services under the client instance:

• payment

  • providers(platform | { platform }) — Get available payment providers
  • quote(payload) — Calculate real-time payment quote breakdown
  • checkout(payload, platform?) — Create checkout session
  • coupon(payload) — Apply & verify coupon code
  • verify(orderId) — Verify payment status by order ID

• plan

  • list(query?) — List public subscription plans

• subscription

  • current(userId) — Get user's current subscription status & details
  • list(userId, query?) — List user subscriptions

• product

  • list(query?) — List public digital products
  • purchased(userId, query?) — List purchased products of user

Note: ZezoPay is not a service but a ready-to-use React component. It encapsulates these services internally for UI integration.

💻 ZezoPay Component

The ZezoPay 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 ZezoPayProps {
  publicKey: string;
  userInfo: UserInfo;
  items?: SummaryItem[];
  plan?: Plan;
  product?: Product;
  title?: string;
  voucher?: boolean;
  embedded?: boolean;
  buttonProps?: ButtonProps;
  callbacks?: Callbacks;
  handlePayment?: HandlePayment;
}

Example Usage

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

function CheckoutPage() {
  return (
    <ZezoPay
      publicKey="YOUR_PUBLIC_KEY"
      userInfo={{ id: 'user_123', name: 'John Doe', email: '[email protected]' }}
      items={[
        {
          id: 'item_1',
          name: 'Premium Subscription',
          price: 999,
          duration: '1 Month',
        },
      ]}
      voucher
      callbacks={{
        onSuccess: ({ response }) => console.log('Payment success:', response),
        onFailure: ({ error }) => console.error('Payment failed:', error),
        onClose: () => console.log('Checkout closed'),
      }}
    />
  );
}

📤 Examples

Payments

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

const client = new ZezoPayClient({ publicKey: 'pk_test_...' });

// Get payment providers
const providers = await client.payment.providers('web');

// Get real-time price quote
const quote = await client.payment.quote({
  amount: 499,
  currency: 'INR',
  user_info: { id: 'user_123', name: 'John Doe' },
  coupon_code: 'DISCOUNT20',
});

// Create checkout session
const checkout = await client.payment.checkout(
  {
    type: 'digital-product',
    userId: 'user_123',
    provider: PaymentProvider.RAZORPAY,
    digitalProductId: 'prod_001',
    metadata: { userInfo: { id: 'user_123', name: 'John Doe' } },
    currency: 'INR',
  },
  'web',
);

// Verify payment status
const status = await client.payment.verify('order_123');

Plans & Subscriptions

// List public subscription plans
const plans = await client.plan.list();

// Get user's current subscription
const currentSub = await client.subscription.current('user_123');

Products

// List public products
const products = await client.product.list({ page: 1, limit: 10 });

// List user purchased products
const purchases = await client.product.purchased('user_123');

🔄 Error Handling

try {
  await client.payment.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 ZezoPay?

  • Import ZezoPay 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