lithic-sdk

A production-grade, fully-typed Node.js / TypeScript SDK for the Lithic API — card issuing, ledgers, payments, and embedded finance.

• Zero runtime dependencies — built on native fetch and the Web Crypto API, so it runs unmodified on Node.js 18+, Deno, Bun, Cloudflare Workers, and the browser.
• Dual ESM/CJS package with full TypeScript declarations (import and require both work out of the box).
• 26 resources, 220+ methods covering every endpoint in the Lithic API.
• Automatic retries with exponential backoff + jitter, idempotency keys on every mutating request, and configurable timeouts.
• Async-iterable cursor pagination — for await over a list call and it walks every page for you.
• Typed error hierarchy with .isNotFound(), .isRateLimit(), .isAuthError(), etc.
• Webhook signature verification for Event Subscriptions, Auth Stream Access, Tokenization Decisioning, and 3DS Decisioning.

Install

npm install lithic-sdk

Quickstart

import { LithicClient } from 'lithic-sdk';

const client = new LithicClient({
  apiKey: process.env.LITHIC_API_KEY, // or omit to read LITHIC_API_KEY automatically
  environment: 'sandbox', // 'production' | 'sandbox', default: 'production'
});

const card = await client.cards.create({
  type: 'VIRTUAL',
  memo: 'Marketing team card',
  spend_limit: 100_00,
  spend_limit_duration: 'MONTHLY',
});

console.log(card.token, card.last_four);

Pagination

Every list() method returns a PagePromise<T> — await it for the first page, or iterate it directly to transparently walk every page:

// Iterate every card across every page:
for await (const card of client.cards.list({ state: 'OPEN' })) {
  console.log(card.token);
}

// Or work with one page at a time:
let page = await client.transactions.list({ account_token });
while (true) {
  for (const txn of page.data) console.log(txn.token, txn.result);
  const next = await page.getNextPage();
  if (!next) break;
  page = next;
}

// Or eagerly collect everything (use with care on large datasets):
const allDisputes = await client.disputes.list().toArray();

Error handling

Every failure — HTTP error responses, network failures, and timeouts — is thrown as a single LithicError:

import { LithicClient, LithicError } from 'lithic-sdk';

try {
  await client.cards.retrieve('nonexistent-token');
} catch (err) {
  if (err instanceof LithicError) {
    if (err.isNotFound()) {
      // handle 404
    } else if (err.isRateLimit()) {
      // back off and retry
    }
    console.error(err.category, err.statusCode, err.requestId, err.message);
  }
}

| Category | Meaning | | -------------------- | ---------------------------------------------- | | auth_error | 401 — invalid or missing API key | | validation_error | 400 / 422 — invalid request parameters | | not_found | 404 | | rate_limit | 429 | | api_error | Any other non-2xx response | | network_error | Request failed before reaching Lithic | | timeout_error | Request exceeded its configured timeout | | decode_error | Response body wasn't valid JSON | | config_error | Misconfigured client (e.g. no fetch available) |

Retries, timeouts, and idempotency

const client = new LithicClient({
  apiKey: '...',
  maxRetries: 3, // default: 3 — retries network errors, timeouts, and 5xx responses
  retryBaseDelayMs: 500, // default: 500 — exponential backoff base
  retryMaxDelayMs: 30_000, // default: 30s — backoff ceiling
  timeoutMs: 30_000, // default: 30s — per-request timeout
});

// Override per-call:
await client.cards.create(params, { maxRetries: 0, timeoutMs: 5_000 });

// Supply your own idempotency key to safely retry an application-level operation:
await client.payments.create(params, { idempotencyKey: `payment-${orderId}` });

All POST, PATCH, and PUT requests get an auto-generated Idempotency-Key by default, so accidental duplicate calls (e.g. a client-side retry) are automatically deduplicated by Lithic.

Webhooks

import express from 'express';
import { LithicClient } from 'lithic-sdk';

const client = new LithicClient({ apiKey: process.env.LITHIC_API_KEY });
const app = express();

app.post('/webhooks/lithic', express.raw({ type: 'application/json' }), async (req, res) => {
  try {
    const event = await client.webhooks.verifyPayload(
      req.body.toString('utf8'),
      req.header('webhook-signature') ?? '',
      req.header('webhook-timestamp') ?? '',
      process.env.LITHIC_WEBHOOK_SECRET!,
    );
    // event is verified — safe to act on
    res.sendStatus(200);
  } catch {
    res.sendStatus(400);
  }
});

Use the raw request body (not a re-serialized JSON object) — signature verification is byte-sensitive.

Resources

| Resource | Property | | ------------------------ | ---------------------------- | | Accounts | client.accounts | | Account Holders (KYC/KYB) | client.accountHolders | | Auth Rules V2 | client.authRules | | Auth Stream Access | client.authStreamAccess | | Balances | client.balances | | Book Transfers | client.bookTransfers | | Card Bulk Orders | client.cardBulkOrders | | Cards | client.cards | | Chargebacks (legacy) | client.chargebacks | | Credit | client.credit | | Disputes V2 | client.disputes | | Events & Webhooks | client.events | | External Bank Accounts | client.externalBankAccounts | | External Payments | client.externalPayments | | Financial Accounts | client.financialAccounts | | Fraud Reports | client.fraudReports | | Funding Events | client.fundingEvents | | Holds | client.holds | | Management Operations | client.managementOperations | | Network | client.network | | Payments (ACH) | client.payments | | Settlement | client.settlement | | 3-D Secure | client.threeDS | | Tokenization | client.tokenization | | Transaction Monitoring | client.transactionMonitoring | | Transactions | client.transactions | | Webhook verification | client.webhooks |

Advanced configuration

const client = new LithicClient({
  apiKey: '...',
  baseURL: 'https://internal-proxy.example.com/v1', // overrides environment entirely
  defaultHeaders: { 'X-Client-Name': 'my-app' },
  fetch: myCustomFetch, // supply your own fetch (polyfills, instrumentation, proxies)
  logger: { debug: console.debug, warn: console.warn, error: console.error },
});

Field names throughout the SDK intentionally mirror the Lithic API's JSON wire format (snake_case) rather than being transformed to camelCase — this keeps request/response shapes byte-for-byte predictable against the API reference and avoids an entire class of case-mapping bugs.

Development

npm install
npm run verify   # typecheck + lint + test + build

License

MIT