pinelabs-node

Official TypeScript / Node.js SDK for the Pine Labs Online Payment Gateway (Plural).

ESM-only. This package ships as ES modules. Use import from a project with "type": "module" or use dynamic import(). require('pinelabs-node') will fail with ERR_PACKAGE_PATH_NOT_EXPORTED.

Install

npm install pinelabs-node
# or
pnpm add pinelabs-node
# or
yarn add pinelabs-node

Requires Node.js ≥ 18.

Quickstart

The Pine Labs API uses OAuth2 client_credentials. Exchange your client_id / client_secret for an access token, then pass it to PinelabsApiClient.

import { PinelabsApiClient } from "pinelabs-node";

// 1. Get a token (use the bare client without `token` for the auth call)
const auth = new PinelabsApiClient({
  baseUrl: "https://pluraluat.v2.pinepg.in", // or "https://api.pluralpay.in" for prod
  token: "", // not required for the token endpoint
});

const tokenResponse = await auth.authentication.generateToken({
  grant_type: "client_credentials",
  client_id: process.env.PINELABS_CLIENT_ID!,
  client_secret: process.env.PINELABS_CLIENT_SECRET!,
});

// 2. Build an authenticated client
const client = new PinelabsApiClient({
  baseUrl: "https://pluraluat.v2.pinepg.in",
  token: tokenResponse.access_token,
});

// 3. Call any operation
const order = await client.orders.createOrder({
  merchant_order_reference: "order-001",
  order_amount: { value: 50000, currency: "INR" }, // ₹500.00
  // ...see API reference for full schema
});

console.log(order);

For long-running processes, refresh the token before it expires using a token-supplier callback (see Auto-refreshing token below).

Environments

| Environment | Base URL | | ----------- | ----------------------------------- | | UAT | https://pluraluat.v2.pinepg.in | | Production | https://api.pluralpay.in |

Pass the URL via baseUrl. The PinelabsApiEnvironment enum currently exposes only Production; for UAT, set baseUrl explicitly.

Auto-refreshing token

Pass a token function instead of a string. It is invoked on every request — including the auth endpoint, so guard against re-entrancy:

import { PinelabsApiClient } from "pinelabs-node";

const baseUrl = "https://pluraluat.v2.pinepg.in";
const auth = new PinelabsApiClient({ baseUrl, token: "" });

let cached: { value: string; expiresAt: number } | undefined;
let fetching = false;

async function getToken(): Promise<string | undefined> {
  if (fetching) return undefined; // re-entrancy guard for auth call itself
  if (cached && Date.now() < cached.expiresAt - 30_000) return cached.value;

  fetching = true;
  try {
    const r = await auth.authentication.generateToken({
      grant_type: "client_credentials",
      client_id: process.env.PINELABS_CLIENT_ID!,
      client_secret: process.env.PINELABS_CLIENT_SECRET!,
    });
    cached = {
      value: r.access_token,
      expiresAt: Date.now() + r.expires_in * 1000,
    };
    return cached.value;
  } finally {
    fetching = false;
  }
}

const client = new PinelabsApiClient({ baseUrl, token: getToken });

Sub-clients

PinelabsApiClient exposes one sub-client per API tag. All are lazy-loaded:

| Sub-client | Purpose | | ------------------------------ | -------------------------------------------------- | | client.authentication | OAuth token generation | | client.orders | Create / capture / cancel / fetch orders | | client.refunds | Create and look up refunds | | client.settlements | Settlement reports + UTR lookup | | client.checkout | Hosted-checkout related operations | | client.paymentLinks | Single + bulk payment links | | client.cardPayments | Direct card payment + OTP | | client.bnpl | Buy-Now-Pay-Later flows | | client.convenienceFee | Convenience-fee config + computation | | client.eChallans | Government e-challan integration | | client.applePay | Apple Pay session + decryption | | client.internationalPayments | Cross-border payments | | client.customers | Customer profile management | | client.tokenization | Card / network tokenization | | client.payouts | Payouts: balance, create, cancel, list | | client.subscriptionsPlans | Recurring-billing plans | | client.subscriptionsSubscriptions | Subscription lifecycle | | client.subscriptionsPresentations | Subscription debit presentations | | client.payByPoints | Loyalty / points-based payments | | client.affordabilitySuite | EMI / offer eligibility | | client.splitSettlements | Split settlements between sub-merchants |

For the full operation list, see the API reference.

Error handling

import {
  PinelabsApiClient,
  PinelabsApiError,
  PinelabsApiTimeoutError,
} from "pinelabs-node";

try {
  await client.orders.getOrderById({ order_id: "missing" });
} catch (err) {
  if (err instanceof PinelabsApiError) {
    console.error("HTTP", err.statusCode, err.body);
  } else if (err instanceof PinelabsApiTimeoutError) {
    console.error("Request timed out");
  } else {
    throw err;
  }
}

Per-request options

Every operation accepts an optional second argument:

await client.orders.createOrder(body, {
  timeoutInSeconds: 30,
  maxRetries: 2,
  abortSignal: controller.signal,
  headers: { "x-correlation-id": "abc" },
});

TypeScript

Full type definitions ship with the package. Strict mode (tsc --strict) is supported. Minimum tsconfig lib for the runtime fetcher: ["ES2023", "DOM", "DOM.Iterable"].

License

MIT