ZezoPay Server SDK Documentation

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

📌 Overview

With the ZezoPay Server SDK you can:

• Initiate and manage payments (checkout, verify, quote, apply coupon, confirm)
• Fetch available payment providers
• Manage subscription plans (create, list, get, update, change status, sync to gateways, delete)
• Manage customer subscriptions (create, list, get, user subscriptions, update, toggle auto-renew, cancel)
• Manage discount coupons (create, list, get, update, change status, validate, delete)
• Manage digital products & purchases (create, list, get, update, bulk actions, delete)
• Use strong TypeScript typings for safe and seamless development

Security Note: This SDK is server-only. Never use or expose your secretKey in client-side / frontend applications.

🚀 Installation

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

🛠️ Setup & Initialization

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

const zezoPay = new ZezoPay({
  publicKey: "your_public_key",
  secretKey: "your_secret_key",
  // Optional: default headers sent with every request
  headers: {
    "x-tenant-id": "your_tenant_id",
  },
});

Notes

• Enforced Auth Headers: x-public-key and x-secret-key are automatically attached to all API requests.
• Custom Headers: Headers specified at initialization are applied across all requests; per-method headers merge on top for that specific call.

🔧 Services & Methods

Plans (zezoPay.plans)

• list(query?) – List all plans (merchant view) (GET /api/v1/plans/manage)
• public(query?) – List active public plans (customer view) (GET /api/v1/plans)
• get(id) – Get plan by ID (GET /api/v1/plans/manage/:id)
• create(payload) – Create a new plan (POST /api/v1/plans/manage)
• update(id, payload) – Update plan by ID (PUT /api/v1/plans/manage/:id)
• status(id, status) – Update plan status (PATCH /api/v1/plans/manage/:id/status)
• delete(planIds) – Delete one or more plans (DELETE /api/v1/plans/manage)
• sync(payload) – Sync plans to payment gateway (POST /api/v1/plans/manage/sync)

Subscriptions (zezoPay.subscriptions)

• list(query?) – List merchant subscriptions (GET /api/v1/subscriptions/manage)
• user(userId, query?) – List all subscriptions for a user (GET /api/v1/subscriptions/:user_id)
• current(userId) – Get user's active subscription (GET /api/v1/subscriptions/:user_id/current)
• get(id) – Get subscription by ID (GET /api/v1/subscriptions/manage/:id)
• create(payload) – Create a subscription (POST /api/v1/subscriptions/manage)
• update(id, payload) – Update subscription by ID (PUT /api/v1/subscriptions/manage/:id)
• status(id, status) – Update subscription status (PATCH /api/v1/subscriptions/manage/:id/status)
• autoRenew(id, autoRenew) – Toggle auto-renew (PATCH /api/v1/subscriptions/manage/:id/auto-renew)
• cancel(id) – Cancel a subscription (PATCH /api/v1/subscriptions/manage/:id/status)

Payments (zezoPay.payments)

• providers(platform?) – Get available payment providers (GET /api/v2/payment/ready)
• quote(payload) – Calculate payment quote with pricing breakdown (POST /api/v2/payment/quote)
• checkout(payload) – Create checkout session (POST /api/v1/payments/checkout)
• verify(orderId) – Verify payment status by order ID (GET /api/v1/payments/verify-payment/:order_id)
• coupon(payload) – Apply and verify coupon for checkout (POST /api/v1/payments/apply-coupon/:coupon_code)
• confirm(payload) – Confirm payment (POST /api/v1/payments/confirm)
• manualConfirm(payload) – Manually mark payment confirmed (POST /api/v1/payments/manual-confirm)
• list(query?) – List payment transactions (GET /api/v1/payments)
• delete(ids) – Delete payments (DELETE /api/v1/payments)

Coupons (zezoPay.coupons)

• list(query?) – List coupons (GET /api/coupons)
• get(id) – Get coupon by ID (GET /api/coupons/:id)
• create(payload) – Create a new coupon (POST /api/coupons)
• update(id, payload) – Update coupon by ID (PATCH /api/coupons/:id)
• status(ids, status) – Update status of multiple coupons (PATCH /api/coupons/update-status)
• validate(code, payload) – Validate coupon code against user cart (POST /api/coupons/validate/:coupon_code)
• delete(id) – Delete coupon by ID (DELETE /api/coupons/:id)

Digital Products (zezoPay.products)

• list(query?) – List digital products (GET /api/digital-products)
• public(query?) – List public products (GET /api/digital-products/public)
• get(id) – Get digital product by ID (GET /api/digital-products/:id)
• create(payload) – Create a digital product (POST /api/digital-products)
• update(id, payload) – Update digital product by ID (PUT /api/digital-products/:id)
• delete(id) – Delete digital product by ID (DELETE /api/digital-products/:id)
• bulk(payload) – Bulk actions on products (POST /api/digital-products/bulk-actions)
• purchases(query?) – List all product purchases (GET /api/digital-products/purchases)
• purchase(id) – Get single purchase by ID (GET /api/digital-products/purchases/:id)
• userPurchases(userId, query?) – List user's purchases (GET /api/digital-products/:userId/purchases)
• userPurchase(userId, id) – Get single user purchase (GET /api/digital-products/:userId/purchases/:id)
• bulkPurchases(payload) – Bulk actions on purchases (PATCH /api/digital-products/purchases/bulk-actions)

🔑 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 Key and Secret Key
5. Store your Secret Key securely in server environment variables (e.g. process.env.ZEZOPAY_SECRET_KEY)

📤 Usage Examples

1. Plans

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

const zezoPay = new ZezoPay({
  publicKey: process.env.ZEZOPAY_PUBLIC_KEY!,
  secretKey: process.env.ZEZOPAY_SECRET_KEY!,
});

// Create a plan
const newPlan = await zezoPay.plans.create({
  name: "Pro Annual",
  description: "Full access for 1 year",
  price: 1999,
  currency: "INR",
  duration_days: 365,
  duration_label: "1 Year",
  features: ["HD Streaming", "Unlimited Downloads", "Priority Support"],
  status: "public",
  is_popular: true,
});

// Update a plan
await zezoPay.plans.update(newPlan.id, {
  price: 2499,
  is_popular: false,
});

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

// Change plan status
await zezoPay.plans.status(newPlan.id, "archived");

// Delete plan
await zezoPay.plans.delete([newPlan.id]);

2. Subscriptions

// Create subscription for a customer
const sub = await zezoPay.subscriptions.create({
  customer_id: "660c1e8f9b1d8b001a1e8f9b",
  plan_id: "660c1e8f9b1d8b001a1e8f9c",
  auto_renew: true,
});

// Get active subscription for a user
const current = await zezoPay.subscriptions.current("usr_123");

// Update subscription
await zezoPay.subscriptions.update(sub.id, {
  auto_renew: false,
});

// Toggle auto-renewal
await zezoPay.subscriptions.autoRenew(sub.id, true);

// Cancel subscription
await zezoPay.subscriptions.cancel(sub.id);

3. Payments

// 1. Get available payment providers
const providers = await zezoPay.payments.providers("web");

// 2. Calculate quote
const quote = await zezoPay.payments.quote({
  currency: "INR",
  payment_gateway: "razorpay",
  platform: "web",
  user_info: {
    name: "Naresh Dhamu",
    email: "[email protected]",
    phone: "9876543210",
  },
  plan_id: "plan_123",
  coupon_code: "WELCOME20",
});

// 3. Create checkout session
const checkout = await zezoPay.payments.checkout({
  type: "subscription",
  userId: "usr_123",
  provider: "razorpay",
  subscriptionId: "sub_123",
  currency: "INR",
  coupon_code: "WELCOME20",
  metadata: {
    isPaymentInitiatedEnabled: true,
    userInfo: {
      _id: "usr_123",
      name: "Naresh Dhamu",
      email: "[email protected]",
      phone: "9876543210",
    },
  },
});

// 4. Verify payment
const result = await zezoPay.payments.verify(checkout.orderId);

4. Coupons

// Create a coupon
const coupon = await zezoPay.coupons.create({
  coupon_code: "FLAT50",
  name: "Flat 50 OFF",
  description: "Flat ₹50 discount on all plans",
  discount: 50,
  currency: "INR",
  type: "amount",
  validity: {
    start_date: "2026-01-01",
    end_date: "2026-12-31",
  },
  max_uses: 500,
  status: "active",
});

// Update coupon
await zezoPay.coupons.update(coupon.id, {
  discount: 60,
  max_uses: 1000,
});

// Validate coupon for user cart
const check = await zezoPay.coupons.validate("FLAT50", {
  userId: "usr_123",
  userInfo: {
    name: "Naresh Dhamu",
    email: "[email protected]",
  },
  price: 999,
});

// Delete coupon
await zezoPay.coupons.delete(coupon.id);

5. Digital Products

// Create digital product
const product = await zezoPay.products.create({
  name: "Advanced Node.js Guide",
  slug: "advanced-nodejs-guide",
  description: "Comprehensive guide to microservices and scalability",
  price: 499,
  currency: "INR",
  status: "public",
  category: "ebook",
  isPopular: true,
  tvod_type: "BUY",
});

// Update product
await zezoPay.products.update(product.id, {
  price: 599,
});

// List all purchases
const purchases = await zezoPay.products.purchases({ page: 1, limit: 20 });

// Bulk action on purchases
await zezoPay.products.bulkPurchases({
  ids: ["pur_123"],
  action: "refund",
});

🔄 Error Handling

All failed API requests reject with a structured error object:

try {
  await zezoPay.subscriptions.create({
    customer_id: "invalid_id",
    plan_id: "invalid_plan",
  });
} catch (error) {
  console.error("ZezoPay Error:", error);
}

Sample error response:

{
  "type": "backend_error",
  "status": 400,
  "message": "Validation failed",
  "path": "customer_id",
  "location": "body"
}

❓ FAQ

• Is this SDK available for frontend usage?
  No. This SDK is server-only. Never expose your secretKey in browsers or client apps.

• Are TypeScript typings provided?
  Yes. Complete typings are bundled out-of-the-box (ICreatePlanPayload, IUpdatePlanPayload, ICreateSubPayload, IUpdateSubPayload, etc.).

🛠️ Contributing & Support

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

👨‍💻 Contributors

📜 License

Released under the MIT License