Your first integration, step by step.

Sign up for a Verath Console business account. You confirm your email, name your business and set up an authenticator app, and the sandbox is ready straight away. You accept the partner agreements in the console when you verify your company to go live.

Create a business account →

In the console, open Developers and create a test key. Your credentials are below. Keep them in a secrets manager, never in source control or client-side code.

• VERATH_API_KEY

  Identifies your partner account

• VERATH_SIGNING_SECRET

  Signs requests and verifies webhooks

• VERATH_HASH_KEY

  Hashes identity numbers (versioned)

• partner.crt / .key

  Client certificate for mutual TLS

At the moment you verify a NIN or BVN, compute an HMAC-SHA256 of the 11-digit number using your hash key. Send only the hash. The raw number never leaves your systems.

import { createHmac } from "node:crypto";

// hashKey is issued to you by Verath (one per key version).
export function identityHash(idNumber, hashKey) {
  const normalized = idNumber.replace(/\D/g, ""); // 11 digits, no spaces
  return createHmac("sha256", hashKey).update(normalized).digest("hex");
}

POST the event to /v1/events. Sign the request with a timestamp and HMAC of the body, and use your own reference as the idempotency key so retries are safe. Sending events should never block your customer flow; queue and retry in the background.

BODY='{
  "id_type": "BVN",
  "identity_hash": "3f9a…c21e",
  "hash_key_version": 1,
  "institution": { "name": "QuickLoan", "category": "digital_lender" },
  "purpose": "loan_application",
  "occurred_at": "2026-10-07T14:02:00+01:00",
  "partner_ref": "kyc-2026-10-07-55102"
}'
TS=$(date +%s)
SIG=$(printf "%s.%s" "$TS" "$BODY" | openssl dgst -sha256 -hmac "$VERATH_SIGNING_SECRET" | cut -d' ' -f2)

curl -X POST "$VERATH_BASE_URL/v1/events" \
  --cert partner.crt --key partner.key \
  -H "Authorization: Bearer $VERATH_API_KEY" \
  -H "Verath-Signature: t=$TS,v1=$SIG" \
  -H "Idempotency-Key: kyc-2026-10-07-55102" \
  -H "Content-Type: application/json" \
  -d "$BODY"

Register an HTTPS endpoint for owner responses. Always verify the Verath-Signature header against the raw request body before acting, and respond with 2xx quickly. Process the work asynchronously.

{
  "id": "whk_01J9X…",
  "type": "dispute.created",
  "created_at": "2026-10-07T14:03:11+01:00",
  "data": {
    "event_id": "evt_8f21c0a9",
    "partner_ref": "kyc-2026-10-07-55102",
    "id_type": "BVN",
    "purpose": "loan_application",
    "owner_response": "not_me",
    "dispute_id": "dsp_4c7e19"
  }
}

import { createHmac, timingSafeEqual } from "node:crypto";

// Verify a Verath webhook before trusting it.
export function verifyVerathWebhook(rawBody, header, secret, toleranceSec = 300) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > toleranceSec) return false; // replay protection
  const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest();
  const given = Buffer.from(parts.v1 ?? "", "hex");
  return given.length === expected.length && timingSafeEqual(given, expected);
}

Use the browser sandbox to see the full flow, then send test events from your sandbox account with test keys.

To go live, open Get started in the Verath Console and verify your company: company details, CAC documents (and your operating licence where your sector needs one) and the partner agreements. We usually review within 1–2 business days and email you the outcome. Once approved, create live API keys yourself in Developers.

• Events are sent for every NIN/BVN verification, including failures you choose to report
• Retries use exponential backoff and the same partner_ref
• Webhook signatures and timestamps are verified
• Your fraud team knows how to act on dispute.created
• Your company verification is approved in Get started