@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[];
}

// 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;
}