ZezoPay Server SDK Documentation

Welcome to the ZezoPay Server SDK. This SDK is designed for backend environments to securely integrate payments, subscriptions, coupons, and digital products with your ZezoPay account.

📌 Overview

With the ZezoPay Server SDK you can:

• Initiate and manage payments (checkout, verify)
• Fetch available payment providers
• Manage subscriptions (list, get active, create, update, delete, manual purchase)
• Manage coupons (list, create, update, delete, get by ID)
• Manage digital products (list, create, update, delete)
• Use TypeScript typings for safer, cleaner code

This SDK is server-only. Do not use or expose your secretKey in frontend code.

🚀 Installation

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

🛠️ Setup & Initialization

import { ZezoPay } from "@zezosoft/zezopay";

const serverSDK = new ZezoPay({
  publicKey: "your_public_key",
  secretKey: "your_secret_key",
});

🔧 Services

The SDK exposes several services under the server instance:

Payments

• getProviders()
• checkout(payload)
• verify(orderId)
• verifyCoupon({ code, userId })

Subscriptions

• list(query?) – List all subscriptions
• publicList(query?) – List public subscriptions
• active({ userId, query? }) – Get active subscription for a user
• create() – Create a subscription
• update({ id, payload }) – Update subscription
• delete({ ids }) – Delete subscription(s)
• manualPurchase(payload) – Manually purchase a subscription

Coupons

• list(query?) – List all coupons
• getById({ id }) – Get a coupon by ID
• create(payload) – Create a new coupon
• update({ id, payload }) – Update a coupon
• delete({ id }) – Delete a coupon

Digital Products

• list(query?)
• create({ payload })
• update({ productId, payload })
• delete({ productId })

🔑 Obtaining API Key & Secret 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 and Secret Keys
5. Store your Secret Key securely (server-side only)

📤 Examples

Coupons

// List coupons
const coupons = await serverSDK.coupons.list({ page: 1, limit: 10 });

// Create coupon
const newCoupon = await serverSDK.coupons.create({
  code: "DISCOUNT10",
  discount: 10,
  type: "percentage",
  expiresAt: "2025-12-31",
});

// Update coupon
await serverSDK.coupons.update({
  id: "coupon_abc123",
  payload: { discount: 15 },
});

// Delete coupon
await serverSDK.coupons.delete({ id: "coupon_abc123" });

// Get coupon by ID
const couponDetails = await serverSDK.coupons.getById({ id: "coupon_abc123" });

Subscriptions

// List subscriptions
const subs = await serverSDK.subscriptions.list({ page: 1, limit: 10 });

// Public subscription list
const publicSubs = await serverSDK.subscriptions.publicList({
  page: 1,
  limit: 5,
});

// Active subscription for a user
const activeSub = await serverSDK.subscriptions.active({ userId: "123456789" });

// Create subscription
const newSub = await serverSDK.subscriptions.create();

// Update subscription
await serverSDK.subscriptions.update({
  id: "sub_abc123",
  payload: { price: 199, status: "active" },
});

// Delete subscriptions
await serverSDK.subscriptions.delete({ ids: ["sub_abc123"] });

// Manual purchase
await serverSDK.subscriptions.manualPurchase({
  subscriptionId: "sub_abc123",
  userId: "user_123456",
});

Payments

// Get payment providers
const providers = await serverSDK.payments.getProviders();

// Normal Payment
const normalCheckout = await serverSDK.payments.checkout({
  type: "normal",
  userId: "user_123456",
  price: 100,
  provider: "razorpay",
  metadata: {
    isPaymentInitiatedEnabled: true,
    userInfo: {
      _id: "user_123456",
      name: "John Doe",
      email: "[email protected]",
      phone: "9999999999",
    },
  },
  currency: "INR",
});

// Subscription Payment
const subscriptionCheckout = await serverSDK.payments.checkout({
  type: "subscription",
  userId: "user_123456",
  subscriptionId: "sub_abc123",
  provider: "razorpay",
  metadata: {
    isPaymentInitiatedEnabled: true,
    userInfo: {
      _id: "user_123456",
      name: "John Doe",
      email: "[email protected]",
      phone: "9999999999",
    },
  },
  currency: "INR",
  coupon_code: "DISCOUNT10",
});

// Digital Product Payment
const digitalProductCheckout = await serverSDK.payments.checkout({
  type: "digital-product",
  userId: "user_123456",
  digitalProductId: "prod_abc123",
  provider: "razorpay",
  metadata: {
    isPaymentInitiatedEnabled: true,
    userInfo: {
      _id: "user_123456",
      name: "John Doe",
      email: "[email protected]",
      phone: "9999999999",
    },
  },
  currency: "INR",
});

// Verify payment
const verification = await serverSDK.payments.verify(normalCheckout.orderId);

// ✅ Verify Coupon
const couponVerification = await serverSDK.payments.verifyCoupon({
  code: "DISCOUNT10",
  userId: "user_123456",
});

Digital Products

// List digital products
const products = await serverSDK.digitalProducts.list();

// Create product
await serverSDK.digitalProducts.create({
  payload: {
    name: "E-book",
    slug: "ebook-advanced-js",
    description: "Learn advanced JS",
    category: "books",
    price: 199,
    currency: "INR",
    isPopular: true,
    status: "public",
    thumbnail: "https://example.com/cover.png",
    expiry_days: 30,
    expiry_label: "30 days access",
    tvod_type: "BUY",
    metadata: { author: "John Doe", level: "advanced" },
  },
});

// Update product
await serverSDK.digitalProducts.update({
  productId: "prod_abc123",
  payload: {
    name: "E-book (Updated)",
    slug: "ebook-advanced-js",
    price: 249,
    currency: "INR",
    status: "public",
    tvod_type: "BOTH",
    metadata: { author: "John Doe", edition: 2 },
  },
});

// Delete product
await serverSDK.digitalProducts.delete({ productId: "prod_abc123" });

🔄 Error Handling

try {
  await serverSDK.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

• Is this SDK available for frontend usage?

  • No. This package is server-only. Do not expose your secretKey.

• Can I manage coupons and subscriptions via the SDK?

  • Yes. Full CRUD is supported on the server.

• Is TypeScript supported?

  • Yes. Full TypeScript typings are included.

🛠️ Contributing

• Pull requests welcome
• Contact: [email protected]
• Documentation: https://pay.zezo.in/docs

👨‍💻 Contributors

📜 License

Released under the MIT License