@vouchmark/node

Server-side Node.js SDK for the Vouchmark REST API. Create sessions, verify webhooks, and manage widgets and applicants programmatically.

Requirements

• Node.js 18 or later (uses native fetch)

Installation

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

Quick start

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

const vouchmark = new Vouchmark({
  secretKey: "sk_live_your_secret_key",
});

Creating a session

Generate a signed session token for embedding the verification widget:

const session = await vouchmark.sessions.create({
  widgetId: "wgt_abc123",
  environment: "live",
  applicant: {
    email: "[email protected]",
    businessName: "Acme Inc",
  },
  referenceId: "your-internal-id",
});

// session.token — pass this to the frontend widget
// session.expiresAt — ISO timestamp

Managing widgets

const widgets = await vouchmark.widgets.list();

const widget = await vouchmark.widgets.create({
  name: "Vendor 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",
});

await vouchmark.widgets.setStatus(widget.id, "live");

Working with applicants

const applicants = await vouchmark.applicants.list({
  widgetId: "wgt_abc123",
  status: "completed",
  page: 1,
  limit: 25,
});

const applicant = await vouchmark.applicants.get("app_xyz789");
const runs = await vouchmark.applicants.listRuns("app_xyz789");

Monitoring

const vendors = await vouchmark.monitoring.listVendors();

await vouchmark.monitoring.addToWatchlist({
  companyId: "company_abc",
});

const events = await vouchmark.monitoring.getVendorEvents("vnd_123");
const alerts = await vouchmark.monitoring.listAlerts({ status: "open" });

Wallet

const balance = await vouchmark.wallet.get();
const transactions = await vouchmark.wallet.listTransactions({ page: 1, limit: 50 });
const pricing = await vouchmark.wallet.getPricingRates();

Verifying webhooks

Verify incoming webhook signatures in your server handler:

import express from "express";
import { Vouchmark, VouchmarkError } from "@vouchmark/node";

const app = express();
const vouchmark = new Vouchmark({ secretKey: "sk_live_..." });

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

    switch (event.event) {
      case "kyb.applicant.decision":
        // event.data: { applicantId, widgetId, referenceId, status, riskScore, decisionReason, submittedAt, decidedAt }
        break;
      case "verification.cac.completed":
        // event.data: { companyId, verified, requiresMemart }
        break;
      case "verification.tin.completed":
        // event.data: { companyId, tin, verified }
        break;
    }

    res.sendStatus(200);
  } catch (error) {
    if (error instanceof VouchmarkError) {
      res.status(400).json({ error: error.message });
      return;
    }
    res.sendStatus(500);
  }
});

Error handling

All API errors throw a VouchmarkError with structured information:

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

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

Configuration

const vouchmark = new Vouchmark({
  secretKey: "sk_live_...",       // Required
  environment: "sandbox",         // "sandbox" | "live" (default: "live")
  baseUrl: "https://custom.api",  // Override API URL
  timeout: 15000,                 // Request timeout in ms (default: 30000)
});

License

MIT