TypeScript / Node

The TypeScript SDK is the primary client library for the Lumeo API. It is a thin, type-safe wrapper around the REST API with built-in retry logic and automatic token management.

Install

npm install @lumeo/sdk

pnpm add @lumeo/sdk

yarn add @lumeo/sdk

Initialise

import { LumeoClient } from "@lumeo/sdk";

const lumeo = new LumeoClient({
  apiKey: process.env.LUMEO_API_KEY!, // sk_sandbox_... or sk_live_...
});

For sandbox, pass the base URL explicitly:

const lumeo = new LumeoClient({
  apiKey: process.env.LUMEO_SANDBOX_KEY!,
  baseUrl: "https://api-sandbox.lumeo.co.in/api/v1",
});

Payments

Initiate a payout

import { randomUUID } from "crypto";

const payment = await lumeo.payments.initiate(
  {
    amount: 500.0,
    currency: "USD",
    destinationAddress: "GADQ...56CHARS",
    purposeCode: "P0801",
    invoiceRef: "invoice-2026-0001",
  },
  { idempotencyKey: randomUUID() },
);

console.log(payment.id);     // "clx1a2b3c..."
console.log(payment.status); // "INITIATED"

Confirm a payout

const confirmed = await lumeo.payments.confirm(
  {
    id: payment.id,
    destinationAddress: "GADQ...56CHARS",
    amount: payment.amount.toString(),
    currency: payment.currency,
    vaultId: process.env.LUMEO_VAULT_ID!,
  },
  { idempotencyKey: randomUUID() },
);

console.log(confirmed.status); // "COMPLIANCE_CHECK"

Get payout status

const status = await lumeo.payments.get(payment.id);
console.log(status.status); // "CONFIRMED"

Compliance

Fetch a FIRA

const fira = await lumeo.compliance.getFira("fira_01j4abc");
console.log(fira.amountInr);      // 41750
console.log(fira.downloadUrl);    // PDF link

ITR-4 prefill

const prefill = await lumeo.compliance.getItr4Prefill({ fy: "2026-27" });
console.log(prefill.grossReceipts);           // 584250
console.log(prefill.presumptiveTaxableIncome); // 292125

Webhooks

Register an endpoint

const endpoint = await lumeo.webhooks.register({
  url: "https://yourapp.com/webhooks/lumeo",
  events: ["payout.settled", "payout.failed", "fira.generated"],
});

console.log(endpoint.id);     // "wh_01j4abc"
console.log(endpoint.secret); // signing secret — store this

Verify a delivery

import { verifyLumeoSignature } from "@lumeo/sdk/webhooks";

// Express raw body middleware required
app.post("/webhooks/lumeo", express.raw({ type: "application/json" }), (req, res) => {
  const sig = req.headers["x-lumeo-signature"] as string;
  const verified = verifyLumeoSignature(
    req.body,
    sig,
    process.env.LUMEO_WEBHOOK_SECRET!,
  );
  if (!verified) return res.sendStatus(403);

  const event = JSON.parse(req.body.toString());
  // handle event.type ...
  res.sendStatus(200);
});

Ledger

Account balance

const balance = await lumeo.ledger.getBalance("acc_01j4abc");
console.log(balance.settled / 100); // ₹1,84,200.50

Reconciliation status

const recon = await lumeo.ledger.getReconciliation(payment.id);
if (recon.status === "PENDING_RECONCILIATION") {
  await lumeo.ledger.resolveReconciliation(payment.id, {
    invoiceRef: "invoice-2026-0001",
  });
}

Error handling

The SDK throws typed errors for all non-2xx responses:

import { LumeoApiError } from "@lumeo/sdk";

try {
  await lumeo.payments.initiate({ ... });
} catch (err) {
  if (err instanceof LumeoApiError) {
    console.log(err.statusCode); // 429
    console.log(err.code);       // "RATE_LIMITED"
    console.log(err.message);    // "Too many requests — retry after..."
  }
}

TypeScript types

All request and response shapes are fully typed and exported:

import type {
  PaymentInitiateRequest,
  PaymentConfirmRequest,
  Payment,
  Fira,
  ReconciliationStatus,
  LumeoEvent,
} from "@lumeo/sdk";

On this page