@thepayulink/server 2.0.1 → 2.2.0

package/README.md

@@ -22,8 +22,9 @@ Node 18+ (uses global `fetch`). Works with `import` and `require`.
 import PayuLink, { rupees } from '@thepayulink/server';
 
 const pl = new PayuLink({
-  keyId: process.env.PAYULINK_KEY_ID,          // pl_live_… / pl_test_…
-  keySecret: process.env.PAYULINK_KEY_SECRET,  // backend only — never ship this
+  keyId: process.env.PAYULINK_KEY_ID,                  // pl_live_… / pl_test_…
+  keySecret: process.env.PAYULINK_KEY_SECRET,          // backend only — never ship this
+  webhookSecret: process.env.PAYULINK_WEBHOOK_SECRET,  // whs_… from panel → Config (NOT keySecret)
 });
 
 // 1) Create an order for the TRUE amount, computed on your server.
@@ -64,6 +65,28 @@ toRupees(19950);  // 199.5
 | `orders.isPaid(orderId)` | boolean | Convenience. |
 | `verifyPaymentSignature({ payulink_order_id, payulink_payment_id, payulink_signature })` | boolean | Verify the client success handoff. |
 | `webhooks.constructEvent(rawBody, headers)` | event | Verify + parse a webhook (throws if invalid or stale). |
+| `webhooks.test()` | result | Send a `webhook.test` event to your callback URL. |
+| `orders.list({ count?, skip?, status?, receipt?, utr?, from?, to? })` | collection | List orders, e.g. find one by UTR. |
+| `payouts.create({ amount, mode, beneficiary, receipt?, narration? })` | payout | Pay out from your balance (`mode`: `bank` or `upi`). |
+| `payouts.fetch(id)` / `payouts.list({...})` | payout / collection | Payout status. |
+| `payouts.cancel(id)` | payout | Cancel a pending payout (bank: immediate; UPI: cancel request). |
+| `balance.fetch()` | balance | `available`, `locked`, `frozen`, `total` in paise. |
+| `transactions.list({ count?, skip?, type?, from?, to? })` | collection | Every balance movement. |
+
+### Payouts
+
+```js
+const payout = await pl.payouts.create({
+  amount: rupees(2500),                      // PAISE; UPI payouts must be whole rupees
+  mode: 'bank',                              // or 'upi' with beneficiary: { vpa }
+  receipt: 'withdrawal_981',                 // idempotency key
+  beneficiary: { name: 'Ravi Kumar', account_number: '918020012345678', ifsc: 'UTIB0000123' },
+});
+// -> { id: 'ZC…', status: 'pending', … }  the amount is locked from your available balance
+```
+
+Statuses: `pending` → `processing` → `processed`, or `cancelled` / `failed` / `rejected`.
+Listen for `payout.processing`, `payout.completed` and `payout.cancelled` webhooks.
 
 ### Idempotency
 

package/dist/index.d.ts

@@ -7,8 +7,12 @@ export interface PayuLinkOptions {
   keySecret: string;
   /** Gateway base URL. Default https://payulink.io/api */
   apiBase?: string;
-  /** Webhook signing secret (webhook_secret_v2). Falls back to keySecret. */
-  webhookSecret?: string;
+  /**
+   * Webhook signing secret (webhook_secret_v2, whs_…) from merchant panel → Config.
+   * Required to verify webhooks — it is NOT your keySecret. Pass [newSecret, oldSecret]
+   * while rotating.
+   */
+  webhookSecret?: string | string[];
   /** Request timeout in ms. Default 15000. */
   timeout?: number;
 }
@@ -24,7 +28,10 @@ export interface CreateOrderParams {
   notes?: Record<string, unknown>;
   /** Optional customer prefill. */
   customer?: { name?: string; contact?: string; email?: string };
-  /** Per-order webhook override. */
+  /**
+   * @deprecated Only affects legacy version-1 callbacks. Signed (v2) webhooks always go to
+   * the URL configured in the merchant panel.
+   */
   notifyUrl?: string;
 }
 
@@ -57,6 +64,81 @@ export interface PaymentHandoff {
   signature?: string;
 }
 
+export interface ListParams {
+  /** 1–100, default 10 */
+  count?: number;
+  skip?: number;
+  /** epoch seconds */
+  from?: number;
+  to?: number;
+}
+
+export interface Collection<T> {
+  entity: 'collection';
+  count: number;
+  has_more: boolean;
+  items: T[];
+}
+
+export interface PayoutBeneficiary {
+  name?: string;
+  account_number?: string;
+  ifsc?: string;
+  vpa?: string;
+  mobile?: string;
+  email?: string;
+}
+
+export interface CreatePayoutParams {
+  /** PAISE. UPI payouts must be whole rupees. */
+  amount: number;
+  mode: 'bank' | 'upi';
+  /** bank: name + account_number + ifsc · upi: vpa (name optional) */
+  beneficiary: PayoutBeneficiary;
+  receipt?: string;
+  narration?: string;
+  currency?: 'INR';
+}
+
+export interface Payout {
+  /** ZC… (bank) or MR-… (UPI) */
+  id: string;
+  entity: 'payout';
+  mode: 'bank' | 'upi';
+  amount: number;
+  currency: string;
+  receipt: string | null;
+  status: 'pending' | 'processing' | 'processed' | 'cancelled' | 'failed' | 'rejected' | 'reversed';
+  beneficiary: PayoutBeneficiary;
+  narration: string | null;
+  utr: string | null;
+  cancel_requested?: boolean;
+  created_at: number;
+  processed_at: number | null;
+}
+
+export interface Balance {
+  entity: 'balance';
+  currency: string;
+  available: number;
+  locked: number;
+  frozen: number;
+  total: number;
+}
+
+export interface Transaction {
+  id: string;
+  entity: 'transaction';
+  type: string;
+  direction: 'credit' | 'debit' | 'lock' | 'locked_spent' | 'other';
+  amount: number;
+  currency: string;
+  available_before: number | null;
+  available_after: number | null;
+  description: string | null;
+  created_at: number;
+}
+
 export interface WebhookEvent {
   id?: string;
   event_type?: string;
@@ -87,12 +169,32 @@ export default class PayuLink {
     create(params: CreateOrderParams): Promise<Order>;
     fetch(orderId: string): Promise<Order>;
     isPaid(orderId: string): Promise<boolean>;
+    list(params?: ListParams & { status?: string; receipt?: string; utr?: string }): Promise<Collection<Order>>;
+  };
+
+  payouts: {
+    create(params: CreatePayoutParams): Promise<Payout>;
+    fetch(payoutId: string): Promise<Payout>;
+    list(params?: ListParams & { status?: Payout['status']; mode?: 'bank' | 'upi'; receipt?: string; utr?: string }): Promise<Collection<Payout>>;
+    /** Bank: cancels a pending payout. UPI: files a cancel request (HTTP 202, cancel_requested: true). */
+    cancel(payoutId: string, params?: { reason?: string }): Promise<Payout>;
+  };
+
+  balance: {
+    fetch(): Promise<Balance>;
+  };
+
+  transactions: {
+    /** type: comma-separated names, e.g. "payout_lock,payout_debit" */
+    list(params?: ListParams & { type?: string }): Promise<Collection<Transaction>>;
   };
 
   webhooks: {
-    verify(rawBody: string | Buffer, signature: string, timestamp: string | number, secret?: string): boolean;
+    /** Sends a webhook.test event to your callback URL. */
+    test(): Promise<{ entity: 'webhook_test'; status: 'queued' | 'not_sent'; event_id?: string; reason?: string }>;
+    verify(rawBody: string | Buffer, signature: string, timestamp: string | number, secret?: string | string[]): boolean;
     /** Verifies signature + ±5min timestamp tolerance. Throws PayuLinkError if invalid. */
-    constructEvent(rawBody: string | Buffer, headers: Record<string, any>, secret?: string): WebhookEvent;
+    constructEvent(rawBody: string | Buffer, headers: Record<string, any>, secret?: string | string[]): WebhookEvent;
   };
 
   /** signature = HMAC_SHA256(order_id + "|" + payment_id, key_secret) */

package/dist/payulink-server.cjs

@@ -47,6 +47,16 @@ var PayuLinkError = class extends Error {
     this.body = body;
   }
 };
+function query(params = {}) {
+  const q = new URLSearchParams();
+  for (const [k, v] of Object.entries(params || {})) if (v !== void 0 && v !== null && v !== "") q.set(k, String(v));
+  const s = q.toString();
+  return s ? `?${s}` : "";
+}
+function requireId(id, name) {
+  if (!id) throw new PayuLinkError(`${name} is required`);
+  return id;
+}
 function safeEqual(a, b) {
   const ba = Buffer.from(String(a ?? ""));
   const bb = Buffer.from(String(b ?? ""));
@@ -58,8 +68,10 @@ var PayuLink = class {
    * @param {string} opts.keyId          Publishable key (pl_live_… / pl_test_…).
    * @param {string} opts.keySecret      Secret key. BACKEND ONLY — never ship this.
    * @param {string} [opts.apiBase]      Default https://payulink.io/api
-   * @param {string} [opts.webhookSecret] Webhook signing secret (webhook_secret_v2 from your
-   *                                      merchant panel). Falls back to keySecret.
+   * @param {string|string[]} [opts.webhookSecret] Webhook signing secret (webhook_secret_v2,
+   *                                      whs_…, from merchant panel → Config). Required to verify
+   *                                      webhooks. Pass [new, old] while rotating — see constructEvent.
+   *                                      It is NOT your keySecret: the two are different secrets.
    * @param {number} [opts.timeout]      Request timeout ms. Default 15000.
    */
   constructor(opts = {}) {
@@ -68,15 +80,33 @@ var PayuLink = class {
     this.keyId = opts.keyId;
     this.keySecret = opts.keySecret;
     this.apiBase = String(opts.apiBase || "https://payulink.io/api").replace(/\/$/, "");
-    this.webhookSecret = opts.webhookSecret || opts.keySecret;
+    this.webhookSecret = opts.webhookSecret || null;
     this.timeout = opts.timeout || 15e3;
     this.mode = /^pl_test_/.test(opts.keyId) ? "test" : "live";
     this.orders = {
       create: (params) => this._createOrder(params),
       fetch: (orderId) => this._fetchOrder(orderId),
-      isPaid: async (orderId) => (await this._fetchOrder(orderId)).status === "paid"
+      isPaid: async (orderId) => (await this._fetchOrder(orderId)).status === "paid",
+      list: (params) => this._request("GET", "/v1/orders" + query(params))
+    };
+    this.payouts = {
+      create: (params) => this._createPayout(params),
+      fetch: (payoutId) => this._request("GET", `/v1/payouts/${encodeURIComponent(requireId(payoutId, "payoutId"))}`),
+      list: (params) => this._request("GET", "/v1/payouts" + query(params)),
+      cancel: (payoutId, params = {}) => this._request(
+        "POST",
+        `/v1/payouts/${encodeURIComponent(requireId(payoutId, "payoutId"))}/cancel`,
+        { body: params }
+      )
+    };
+    this.balance = {
+      fetch: () => this._request("GET", "/v1/balance")
+    };
+    this.transactions = {
+      list: (params) => this._request("GET", "/v1/transactions" + query(params))
     };
     this.webhooks = {
+      test: () => this._request("POST", "/v1/webhooks/test"),
       verify: (rawBody, signature, timestamp, secret) => this._verifyWebhook(rawBody, signature, timestamp, secret),
       constructEvent: (rawBody, headers, secret) => this._constructEvent(rawBody, headers, secret)
     };
@@ -125,6 +155,10 @@ var PayuLink = class {
    * @param {string} [p.receipt]   Your reference. Unique per merchant — reusing it
    *                               returns the SAME order, which makes retries safe.
    * @param {object} [p.notes]     Arbitrary key/value metadata.
+   * @param {object} [p.customer]  { name, contact, email } — prefill for the checkout.
+   *
+   * Webhooks always go to the URL set in the merchant panel. (`notifyUrl` is still sent for
+   * backward compatibility but only affects legacy version-1 callbacks, not signed webhooks.)
    */
   _createOrder(p = {}) {
     const amount = Math.round(Number(p.amount));
@@ -144,6 +178,33 @@ var PayuLink = class {
       }
     });
   }
+  /**
+   * Pay money out from your PayuLink balance. The amount is locked immediately.
+   * @param {object} p
+   * @param {number} p.amount      PAISE. UPI payouts must be whole rupees.
+   * @param {'bank'|'upi'} p.mode
+   * @param {object} p.beneficiary bank: { name, account_number, ifsc } · upi: { vpa, name? } · optional mobile, email
+   * @param {string} [p.receipt]   Your reference; reusing it returns the same payout.
+   * @param {string} [p.narration]
+   */
+  _createPayout(p = {}) {
+    const amount = Math.round(Number(p.amount));
+    if (!Number.isFinite(amount) || amount < 100) {
+      throw new PayuLinkError("`amount` is required, in PAISE, and must be >= 100 (\u20B91).");
+    }
+    if (p.mode !== "bank" && p.mode !== "upi") throw new PayuLinkError('`mode` must be "bank" or "upi".');
+    if (!p.beneficiary) throw new PayuLinkError("`beneficiary` is required.");
+    return this._request("POST", "/v1/payouts", {
+      body: {
+        amount,
+        currency: p.currency || "INR",
+        mode: p.mode,
+        beneficiary: p.beneficiary,
+        receipt: p.receipt,
+        narration: p.narration
+      }
+    });
+  }
   /** Authoritative order status. */
   _fetchOrder(orderId) {
     if (!orderId) throw new PayuLinkError("orderId is required");
@@ -176,9 +237,11 @@ var PayuLink = class {
    */
   _verifyWebhook(rawBody, signature, timestamp, secret) {
     if (!signature || !timestamp) return false;
-    const key = secret || this.webhookSecret;
-    const expected = "sha256=" + import_node_crypto.default.createHmac("sha256", key).update(`${timestamp}.${String(rawBody)}`).digest("hex");
-    return safeEqual(expected, signature);
+    const keys = [].concat(secret || this.webhookSecret || []).filter(Boolean);
+    if (keys.length === 0) {
+      throw new PayuLinkError("No webhook secret: pass `webhookSecret` (whs_\u2026, merchant panel \u2192 Config) to new PayuLink({...}). Webhooks are not signed with your keySecret.");
+    }
+    return keys.some((key) => safeEqual("sha256=" + import_node_crypto.default.createHmac("sha256", key).update(`${timestamp}.${String(rawBody)}`).digest("hex"), signature));
   }
   /**
    * Verify + parse a webhook. Throws if the signature is bad or the timestamp is
@@ -194,7 +257,7 @@ var PayuLink = class {
    *
    * @param {string|Buffer} rawBody
    * @param {object} headers  The request headers object.
-   * @param {string} [secret]
+   * @param {string|string[]} [secret]  Overrides opts.webhookSecret.
    * @param {number} [toleranceSec=300]
    */
   _constructEvent(rawBody, headers = {}, secret, toleranceSec = 300) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thepayulink/server",
-  "version": "2.0.1",
+  "version": "2.2.0",
   "description": "PayuLink server SDK — create orders and verify payments/webhooks with your key_secret.",
   "type": "module",
   "main": "./dist/payulink-server.cjs",

package/src/index.js

@@ -29,6 +29,18 @@ export class PayuLinkError extends Error {
   }
 }
 
+function query(params = {}) {
+  const q = new URLSearchParams();
+  for (const [k, v] of Object.entries(params || {})) if (v !== undefined && v !== null && v !== '') q.set(k, String(v));
+  const s = q.toString();
+  return s ? `?${s}` : '';
+}
+
+function requireId(id, name) {
+  if (!id) throw new PayuLinkError(`${name} is required`);
+  return id;
+}
+
 function safeEqual(a, b) {
   const ba = Buffer.from(String(a ?? ''));
   const bb = Buffer.from(String(b ?? ''));
@@ -41,8 +53,10 @@ export default class PayuLink {
    * @param {string} opts.keyId          Publishable key (pl_live_… / pl_test_…).
    * @param {string} opts.keySecret      Secret key. BACKEND ONLY — never ship this.
    * @param {string} [opts.apiBase]      Default https://payulink.io/api
-   * @param {string} [opts.webhookSecret] Webhook signing secret (webhook_secret_v2 from your
-   *                                      merchant panel). Falls back to keySecret.
+   * @param {string|string[]} [opts.webhookSecret] Webhook signing secret (webhook_secret_v2,
+   *                                      whs_…, from merchant panel → Config). Required to verify
+   *                                      webhooks. Pass [new, old] while rotating — see constructEvent.
+   *                                      It is NOT your keySecret: the two are different secrets.
    * @param {number} [opts.timeout]      Request timeout ms. Default 15000.
    */
   constructor(opts = {}) {
@@ -51,7 +65,9 @@ export default class PayuLink {
     this.keyId = opts.keyId;
     this.keySecret = opts.keySecret;
     this.apiBase = String(opts.apiBase || 'https://payulink.io/api').replace(/\/$/, '');
-    this.webhookSecret = opts.webhookSecret || opts.keySecret;
+    // No fallback to keySecret. Webhooks are never signed with it, so the old fallback
+    // turned a missing env var into "every webhook fails signature" with no clue why.
+    this.webhookSecret = opts.webhookSecret || null;
     this.timeout = opts.timeout || 15000;
     this.mode = /^pl_test_/.test(opts.keyId) ? 'test' : 'live';
 
@@ -59,8 +75,24 @@ export default class PayuLink {
       create: (params) => this._createOrder(params),
       fetch: (orderId) => this._fetchOrder(orderId),
       isPaid: async (orderId) => (await this._fetchOrder(orderId)).status === 'paid',
+      list: (params) => this._request('GET', '/v1/orders' + query(params)),
+    };
+    // Payouts, balance and transactions replace the legacy /openapi payout + acct endpoints.
+    this.payouts = {
+      create: (params) => this._createPayout(params),
+      fetch: (payoutId) => this._request('GET', `/v1/payouts/${encodeURIComponent(requireId(payoutId, 'payoutId'))}`),
+      list: (params) => this._request('GET', '/v1/payouts' + query(params)),
+      cancel: (payoutId, params = {}) => this._request('POST',
+        `/v1/payouts/${encodeURIComponent(requireId(payoutId, 'payoutId'))}/cancel`, { body: params }),
+    };
+    this.balance = {
+      fetch: () => this._request('GET', '/v1/balance'),
+    };
+    this.transactions = {
+      list: (params) => this._request('GET', '/v1/transactions' + query(params)),
     };
     this.webhooks = {
+      test: () => this._request('POST', '/v1/webhooks/test'),
       verify: (rawBody, signature, timestamp, secret) =>
         this._verifyWebhook(rawBody, signature, timestamp, secret),
       constructEvent: (rawBody, headers, secret) => this._constructEvent(rawBody, headers, secret),
@@ -109,6 +141,10 @@ export default class PayuLink {
    * @param {string} [p.receipt]   Your reference. Unique per merchant — reusing it
    *                               returns the SAME order, which makes retries safe.
    * @param {object} [p.notes]     Arbitrary key/value metadata.
+   * @param {object} [p.customer]  { name, contact, email } — prefill for the checkout.
+   *
+   * Webhooks always go to the URL set in the merchant panel. (`notifyUrl` is still sent for
+   * backward compatibility but only affects legacy version-1 callbacks, not signed webhooks.)
    */
   _createOrder(p = {}) {
     const amount = Math.round(Number(p.amount));
@@ -130,6 +166,28 @@ export default class PayuLink {
     });
   }
 
+  /**
+   * Pay money out from your PayuLink balance. The amount is locked immediately.
+   * @param {object} p
+   * @param {number} p.amount      PAISE. UPI payouts must be whole rupees.
+   * @param {'bank'|'upi'} p.mode
+   * @param {object} p.beneficiary bank: { name, account_number, ifsc } · upi: { vpa, name? } · optional mobile, email
+   * @param {string} [p.receipt]   Your reference; reusing it returns the same payout.
+   * @param {string} [p.narration]
+   */
+  _createPayout(p = {}) {
+    const amount = Math.round(Number(p.amount));
+    if (!Number.isFinite(amount) || amount < 100) {
+      throw new PayuLinkError('`amount` is required, in PAISE, and must be >= 100 (₹1).');
+    }
+    if (p.mode !== 'bank' && p.mode !== 'upi') throw new PayuLinkError('`mode` must be "bank" or "upi".');
+    if (!p.beneficiary) throw new PayuLinkError('`beneficiary` is required.');
+    return this._request('POST', '/v1/payouts', {
+      body: { amount, currency: p.currency || 'INR', mode: p.mode, beneficiary: p.beneficiary,
+        receipt: p.receipt, narration: p.narration },
+    });
+  }
+
   /** Authoritative order status. */
   _fetchOrder(orderId) {
     if (!orderId) throw new PayuLinkError('orderId is required');
@@ -165,10 +223,16 @@ export default class PayuLink {
    */
   _verifyWebhook(rawBody, signature, timestamp, secret) {
     if (!signature || !timestamp) return false;
-    const key = secret || this.webhookSecret;
-    const expected = 'sha256=' + crypto.createHmac('sha256', key)
-      .update(`${timestamp}.${String(rawBody)}`).digest('hex');
-    return safeEqual(expected, signature);
+    const keys = [].concat(secret || this.webhookSecret || []).filter(Boolean);
+    if (keys.length === 0) {
+      throw new PayuLinkError('No webhook secret: pass `webhookSecret` (whs_…, merchant panel → Config) '
+        + 'to new PayuLink({...}). Webhooks are not signed with your keySecret.');
+    }
+    // Several secrets are accepted so a rotation never drops events: deliveries already
+    // queued (and their retries, for up to ~30h) stay signed with the secret that was
+    // current when each event was created.
+    return keys.some((key) => safeEqual('sha256=' + crypto.createHmac('sha256', key)
+      .update(`${timestamp}.${String(rawBody)}`).digest('hex'), signature));
   }
 
   /**
@@ -185,7 +249,7 @@ export default class PayuLink {
    *
    * @param {string|Buffer} rawBody
    * @param {object} headers  The request headers object.
-   * @param {string} [secret]
+   * @param {string|string[]} [secret]  Overrides opts.webhookSecret.
    * @param {number} [toleranceSec=300]
    */
   _constructEvent(rawBody, headers = {}, secret, toleranceSec = 300) {