@thepayulink/server 2.1.0 → 2.2.1

package/README.md

@@ -65,6 +65,34 @@ 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
+
+Payouts, `balance.fetch()` and `transactions.list()` need a **live key with Payouts access**
+and an **IP allowlist** (merchant panel → API Key → *Edit access*). Otherwise the API
+answers `403 KEY_NOT_PERMITTED`, `403 IP_NOT_ALLOWED`, or `400 TEST_MODE_UNSUPPORTED` for a
+test key. Keep that key only on the server that sends payouts; use a separate Checkout key
+for orders.
+
+```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

@@ -64,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;
@@ -94,9 +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>>;
+  };
+
+  /** Needs a live key with Payouts access, called from an IP on the key's allowlist. */
+  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>;
+  };
+
+  /** Needs a live key with Payouts access, called from an IP on the key's allowlist. */
+  balance: {
+    fetch(): Promise<Balance>;
+  };
+
+  /** Needs a live key with Payouts access, called from an IP on the key's allowlist. */
+  transactions: {
+    /** type: comma-separated names, e.g. "payout_lock,payout_debit" */
+    list(params?: ListParams & { type?: string }): Promise<Collection<Transaction>>;
   };
 
   webhooks: {
+    /** 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 | string[]): WebhookEvent;

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 ?? ""));
@@ -76,9 +86,27 @@ var PayuLink = class {
     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)
     };
@@ -150,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");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thepayulink/server",
-  "version": "2.1.0",
+  "version": "2.2.1",
   "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 ?? ''));
@@ -63,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),
@@ -138,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');