@billium/node

npm install @billium/node
# or
pnpm add @billium/node
# or
yarn add @billium/node

import { Billium } from '@billium/node';

const billium = new Billium({
  apiKey: process.env.BILLIUM_API_KEY,          // sk_... or pk_...
  merchantId: process.env.BILLIUM_MERCHANT_ID,  // mer_...
  webhookSecret: process.env.BILLIUM_WEBHOOK_SECRET, // whsec_...
});

// ESM
import { Billium } from '@billium/node';

// CJS
const { Billium } = require('@billium/node');

import { randomUUID } from 'crypto';

const invoice = await billium.invoices.create(
  {
    name: 'Order #8821',
    rawAmount: 49.99,
    currency: 'USD',
    customerEmail: 'customer@example.com',
    redirectUrl: 'https://yoursite.com/thank-you',
  },
  { idempotencyKey: randomUUID() },
);

console.log(invoice.id);     // 'inv_...'
console.log(invoice.status); // 'AWAITING_PAYMENT'

const invoice = await billium.invoices.get('inv_...');

const result = await billium.invoices.list({ page: 1, limit: 20, search: 'order' });
// result.data  → Invoice[]
// result.total → number
// result.page  → number
// result.limit → number

const invoice = await billium.invoices.cancel('inv_...');
console.log(invoice.status); // 'CANCELLED'

interface Invoice {
  id: string;
  merchantId: string;
  customerId: string | null;
  productId: string | null;
  name: string;
  description: string | null;
  redirectUrl: string | null;
  rawAmount: string;   // e.g. "49.990000"
  endAmount: string;   // e.g. "49.990000" (rawAmount + fees, when applicable)
  currency: string;
  status: InvoiceStatus;
  expiresAt: string | null;
  createdAt: string;
  updatedAt: string;

  // Relations — always present on responses, never undefined
  customer: InvoiceCustomer | null;
  product: InvoiceProduct | null;
  payments: InvoicePayment[];
  invoiceTimeline: InvoiceTimelineEntry[];
}

const result = await billium.customers.list({ page: 1, limit: 20, search: 'jane' });
// result.data → Customer[]

const customer = await billium.customers.get('cus_...');

const stats = await billium.customers.stats('cus_...');
// { revenue, totalInvoices, paidInvoices, paidRate }

await billium.customers.update('cus_...', { name: 'Jane Doe' });

interface Customer {
  id: string;
  merchantId: string;
  email: string;
  name: string | null;
  address: string | null;
  phoneNumber: string | null;
  metadata: unknown;     // arbitrary JSON attached by Billium, or null
  createdAt: string;     // ISO 8601
  updatedAt: string;     // ISO 8601
  location?: {           // only on get(); each field may be null
    country: string | null;
    city: string | null;
  };
}

const product = await billium.products.create({
  name: 'Pro plan',
  price: 49.99,
  currency: 'USD',
});

const product = await billium.products.get('prd_...');
const result = await billium.products.list({ page: 1, limit: 20, search: 'plan' });
// result.data → Product[]

await billium.products.update('prd_...', { price: 59.99, isActive: false });

await billium.products.delete('prd_...');

interface Product {
  id: string;
  merchantId: string;
  name: string;
  description: string | null;
  price: string;            // decimal serialized as a string
  currency: 'USD' | 'EUR' | 'GBP' | 'CAD' | 'AUD' | 'JPY';
  isActive: boolean;
  askForName: boolean;
  askForAddress: boolean;
  askForPhoneNumber: boolean;
  image: string | null;        // raw storage key — treat as opaque
  signedImage?: string | null; // ready-to-render URL; prefer this for display
  createdAt: string;
  updatedAt: string;
}

const wallets = await billium.wallets.list(); // Wallet[]

const wallet = await billium.wallets.get('wal_...');

const wallet = await billium.wallets.create({
  cryptocurrency: 'BTC',
  network: 'BTC',
  walletType: 'DIRECT_WALLET',
  address: 'bc1q...',
});

await billium.wallets.update('wal_...', { isEnabled: false });

await billium.wallets.delete('wal_...');

interface Wallet {
  id: string;
  merchantId: string;
  cryptocurrency: 'BTC' | 'ETH' | 'USDT' | 'USDC' | 'BNB' | 'SHIB' | 'POL' | 'LTC' | 'DAI' | 'CRO' | 'TRX' | 'UNI';
  network: 'BTC' | 'ETH' | 'BNB' | 'POL' | 'LTC' | 'CRO' | 'TRX';
  walletType: 'DIRECT_WALLET' | 'XPUB_WALLET';
  isEnabled: boolean;
  requiredConfirmations: number;
  address: string | null;        // set for DIRECT_WALLET
  xpub: string | null;           // set for XPUB_WALLET (public key)
  derivationPath: string | null;
  createdAt: string;
  updatedAt: string;
}

// With webhookSecret set in the constructor:
const event = billium.webhooks.verify(
  rawBody,                     // Buffer | string — raw request body
  req.headers['x-signature'],  // x-signature header value
);

// Or pass the secret explicitly (overrides the constructor value):
const event = billium.webhooks.verify(rawBody, signature, 'whsec_...');

interface WebhookEvent {
  event: string;      // e.g. 'invoice.paid'
  id: string;         // unique event ID — use for deduplication
  data: unknown;      // event-specific payload
  timestamp: string;  // ISO 8601
}

const webhook = await billium.webhooks.create({
  url: 'https://yoursite.com/webhooks/billium',
  events: ['invoice.paid', 'invoice.expired'], // or ['invoice.*']
  description: 'Production order fulfillment',
});

// Store this secret now — it's only shown once.
const secret = webhook.webhookSecrets[0].secretKeyPreview; // 'whsec_...'

const webhooks = await billium.webhooks.list();

await billium.webhooks.update('wh_...', {
  events: ['invoice.*', 'payment.confirmed'],
});

await billium.webhooks.delete('wh_...');

await billium.webhooks.ping('wh_...');

import {
  BilliumError,
  BilliumApiError,
  BilliumWebhookSignatureError,
  BilliumWebhookTimestampError,
} from '@billium/node';

// API errors
try {
  const invoice = await billium.invoices.create({ /* ... */ });
} catch (err) {
  if (err instanceof BilliumApiError) {
    console.error(err.status);  // HTTP status code, e.g. 400, 401, 403
    console.error(err.code);    // optional error code from the API
    console.error(err.message); // human-readable message
  }
}

// Webhook errors
try {
  const event = billium.webhooks.verify(rawBody, signature);
} catch (err) {
  if (err instanceof BilliumWebhookTimestampError) {
    // Possible replay attack — reject
    return res.status(400).send();
  }
  if (err instanceof BilliumWebhookSignatureError) {
    // Invalid or tampered signature
    return res.status(400).send();
  }
  throw err;
}