Node.js (Server)

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

import { Vouchmark } from "@vouchmark/node";

const vouchmark = new Vouchmark({
  secretKey: process.env.VOUCHMARK_SECRET_KEY!,
  environment: "live", // or "sandbox"
});

const session = await vouchmark.sessions.create({
  widgetId: "wgt_...",
  environment: "live",
  applicant: {
    email: "applicant@example.com",
    businessName: "Acme Ltd",
    registrationNumber: "RC123456",
  },
  referenceId: "your_internal_id_123",
});

// session.token → pass to client SDK
// session.expiresAt → ISO timestamp for when the token expires

// List all widgets
const widgets = await vouchmark.widgets.list();

// Get a specific widget
const widget = await vouchmark.widgets.get("wgt_...");

// Create a widget
const newWidget = await vouchmark.widgets.create({
  name: "Fintech Onboarding",
  steps: [
    { type: "company_search", label: "Find your company", required: true },
    { type: "document_upload", label: "Upload documents", required: true },
  ],
  redirectUrl: "https://app.example.com/onboarding/complete",
  brandColor: "#6466AE",
});

// Update widget configuration (partial WidgetConfig)
await vouchmark.widgets.update("wgt_...", {
  name: "Fintech Onboarding v2",
  brandColor: "#1a1a1a",
});

// Set widget status
await vouchmark.widgets.setStatus("wgt_...", "live");

// Delete a widget
await vouchmark.widgets.delete("wgt_...");

// List applicants for a widget
const applicants = await vouchmark.applicants.list({
  widgetId: "wgt_...",
  status: "submitted",
  page: 1,
  limit: 25,
});

// Get a specific applicant
const applicant = await vouchmark.applicants.get("app_...");

// Get verification runs for an applicant
const runs = await vouchmark.applicants.listRuns("app_...");

import { Vouchmark } from "@vouchmark/node";

const vouchmark = new Vouchmark({ secretKey: process.env.VOUCHMARK_SECRET_KEY! });

// Express example
app.post("/webhooks/vouchmark", express.raw({ type: "application/json" }), (req, res) => {
  const signature = req.headers["x-vouchmark-signature"] as string;
  const event = vouchmark.webhooks.verify(req.body, signature, process.env.VOUCHMARK_WEBHOOK_SECRET!);

  switch (event.type) {
    case "applicant.approved":
      // update your database
      break;
    case "applicant.rejected":
      // notify the user
      break;
    case "applicant.requires_review":
      // queue for manual review
      break;
  }

  res.status(200).json({ received: true });
});

// Get current balance
const wallet = await vouchmark.wallet.get();
// wallet.balance, wallet.currency, wallet.updatedAt

// List transactions
const transactions = await vouchmark.wallet.listTransactions({
  page: 1,
  limit: 50,
});

// Get pricing rates
const rates = await vouchmark.wallet.getPricingRates();

// List monitored vendors
const vendors = await vouchmark.monitoring.listVendors();

// Add vendor to watchlist
const vendor = await vouchmark.monitoring.addToWatchlist({ companyId: "cmp_..." });

// Get vendor events (pass the vendor ID)
const events = await vouchmark.monitoring.getVendorEvents(vendor.id);

// Get alerts
const alerts = await vouchmark.monitoring.listAlerts({ status: "open" });

// Remove a vendor from the watchlist
await vouchmark.monitoring.removeFromWatchlist(vendor.id);

import { VouchmarkError } from "@vouchmark/node";

try {
  await vouchmark.widgets.get("wgt_invalid");
} catch (error) {
  if (error instanceof VouchmarkError) {
    console.error(error.statusCode); // 404
    console.error(error.code);       // "NOT_FOUND"
    console.error(error.message);    // "Widget not found"
  }
}

import type {
  Widget,
  Applicant,
  VerificationRun,
  MonitoringEvent,
  WalletBalance,
} from "@vouchmark/node";