How to Verify PAN in Node.js and Python (Tested Tutorial)

curl -X POST "https://api-b2b.stampmitra.in/v1/verify/pan" \
  -H "Authorization: Bearer $STAMPMITRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"pan":"ABCDE1234F","name":"Rahul Kumar"}'

{
  "referenceId": "SMV-20260927-8F42K7",
  "pan": "ABCDE1234F",
  "type": "Individual",
  "valid": true,
  "registeredName": "RAHUL KUMAR",
  "fatherName": "SURESH KUMAR",
  "panStatus": "VALID",
  "panStatusCode": "E",
  "panStatusDescription": "Existing and valid PAN",
  "nameMatchResult": "MATCH",
  "nameMatchScore": "100",
  "aadhaarSeedingStatus": "y",
  "aadhaarSeedingStatusDescription": "Aadhaar linked",
  "lastUpdatedAt": "2023-04-01",
  "message": "PAN is Valid"
}

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "pan must match the format ABCDE1234F",
    "requestId": "a1b2c3d4-e5f6-4a1b-8c2d-9f0e1a2b3c4d"
  }
}

{
  "error": {
    "code": "TOO_MANY_REQUESTS",
    "message": "Rate limit exceeded: 60 requests per 60 seconds for this endpoint.",
    "requestId": "a1b2c3d4-e5f6-4a1b-8c2d-9f0e1a2b3c4d"
  }
}

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Unable to reach the order/customer service right now",
    "requestId": "5c1c1e9e-2f7b-4b7a-9b0e-0f1a2b3c4d5e"
  }
}

mkdir pan-verify && cd pan-verify
npm init -y
npm install express
npm install -D typescript @types/node @types/express

{
  "name": "pan-verify-demo",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "engines": { "node": ">=22.18" },
  "scripts": {
    "start": "node src/server.ts",
    "test": "node --test \"test/*.test.ts\"",
    "typecheck": "tsc --noEmit"
  },
  "dependencies": { "express": "^5.1.0" },
  "devDependencies": {
    "@types/express": "^5.0.0",
    "@types/node": "^22.0.0",
    "typescript": "^5.6.0"
  }
}

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "noEmit": true,
    "allowImportingTsExtensions": true,
    "erasableSyntaxOnly": true,
    "skipLibCheck": true
  },
  "include": ["src", "test"]
}

mkdir pan-verify-py && cd pan-verify-py
python -m venv .venv && source .venv/bin/activate
pip install httpx requests fastapi uvicorn pytest

# file: .env.example
# Copy to .env (which is git-ignored) and fill in your sandbox key.
STAMPMITRA_API_KEY=sk_test_replace_me
# Optional. Defaults to https://api-b2b.stampmitra.in
# STAMPMITRA_BASE_URL=https://api-b2b.stampmitra.in

# file: .gitignore
.env
node_modules

// file: src/verify-basic.mjs
// Smallest possible call: node --env-file=.env src/verify-basic.mjs
const apiKey = process.env.STAMPMITRA_API_KEY;
if (!apiKey) {
  console.error("STAMPMITRA_API_KEY is not set");
  process.exit(1);
}

const res = await fetch("https://api-b2b.stampmitra.in/v1/verify/pan", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ pan: "ABCDE1234F", name: "Rahul Kumar" }),
  signal: AbortSignal.timeout(10_000),
});

const body = await res.json();
if (!res.ok) {
  console.error(res.status, body.error?.code, body.error?.requestId);
  process.exit(1);
}
console.log(body.referenceId, body.valid, body.nameMatchResult);

// file: src/errors.ts
export type ErrorKind =
  | "validation" // rejected locally, nothing was sent
  | "bad_request" // 400 from the API
  | "auth" // 401 or 403
  | "wallet" // 402
  | "rate_limited" // 429
  | "upstream" // 5xx
  | "timeout" // our timeout fired
  | "network" // DNS, TLS, connection reset
  | "unexpected"; // anything else, including a non-JSON body

export class StampMitraError extends Error {
  readonly kind: ErrorKind;
  readonly status: number | null;
  readonly code: string | null;
  readonly requestId: string | null;

  constructor(
    kind: ErrorKind,
    message: string,
    details: { status?: number; code?: string; requestId?: string; cause?: unknown } = {},
  ) {
    super(message, { cause: details.cause });
    this.name = "StampMitraError";
    this.kind = kind;
    this.status = details.status ?? null;
    this.code = details.code ?? null;
    this.requestId = details.requestId ?? null;
  }
}

export function kindForStatus(status: number): ErrorKind {
  if (status === 400) return "bad_request";
  if (status === 401 || status === 403) return "auth";
  if (status === 402) return "wallet";
  if (status === 429) return "rate_limited";
  if (status >= 500) return "upstream";
  return "unexpected";
}

/** The only statuses we retry: rate limiting and server-side failures. */
export function isRetryableStatus(status: number): boolean {
  return status === 429 || status >= 500;
}

// file: src/validate.ts
import { StampMitraError } from "./errors.ts";

// API docs: pan must match the format ABCDE1234F (5 letters, 4 digits, 1 letter).
const PAN_RE = /^[A-Z]{5}[0-9]{4}[A-Z]$/;
const NAME_MAX = 256; // API docs: name, max 256 chars

export interface PanInput {
  pan: string;
  name?: string;
}

/** Normalises and validates. Throws a "validation" error without echoing the PAN. */
export function normalisePanInput(input: PanInput): PanInput {
  const pan = typeof input.pan === "string" ? input.pan.trim().toUpperCase() : "";
  if (!PAN_RE.test(pan)) {
    throw new StampMitraError("validation", "pan must match the format ABCDE1234F");
  }
  if (input.name === undefined) return { pan };

  const name = typeof input.name === "string" ? input.name.trim() : "";
  if (name.length === 0) return { pan }; // treat blank as "not provided"
  if (name.length > NAME_MAX) {
    throw new StampMitraError("validation", `name must be at most ${NAME_MAX} characters`);
  }
  return { pan, name };
}

// file: src/client.ts
import { StampMitraError, isRetryableStatus, kindForStatus } from "./errors.ts";
import { type PanInput, normalisePanInput } from "./validate.ts";
import { type Logger, noopLogger } from "./logger.ts";

export const DEFAULT_BASE_URL = "https://api-b2b.stampmitra.in";

/** Fields shown in the docs example. Everything except referenceId and valid is
 *  typed optional so a sparse negative result does not break your code. */
export interface PanVerifyResult {
  referenceId: string;
  valid: boolean;
  pan?: string;
  type?: string;
  registeredName?: string;
  fatherName?: string;
  panStatus?: string;
  panStatusCode?: string;
  panStatusDescription?: string;
  nameMatchResult?: string;
  nameMatchScore?: string;
  aadhaarSeedingStatus?: string;
  aadhaarSeedingStatusDescription?: string;
  lastUpdatedAt?: string;
  message?: string;
}

export interface ClientOptions {
  apiKey: string;
  baseUrl?: string;
  timeoutMs?: number;
  maxAttempts?: number; // total tries, including the first
  baseDelayMs?: number;
  maxDelayMs?: number;
  logger?: Logger;
  // Injectable for tests.
  fetchImpl?: typeof fetch;
  sleep?: (ms: number) => Promise<void>;
  random?: () => number;
}

const realSleep = (ms: number) => new Promise<void>((r) => setTimeout(r, ms));

export class StampMitraClient {
  private readonly apiKey: string;
  private readonly baseUrl: string;
  private readonly timeoutMs: number;
  private readonly maxAttempts: number;
  private readonly baseDelayMs: number;
  private readonly maxDelayMs: number;
  private readonly log: Logger;
  private readonly fetchImpl: typeof fetch;
  private readonly sleep: (ms: number) => Promise<void>;
  private readonly random: () => number;

  constructor(opts: ClientOptions) {
    if (!opts.apiKey) throw new Error("StampMitra apiKey is required");
    this.apiKey = opts.apiKey;
    this.baseUrl = (opts.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
    this.timeoutMs = opts.timeoutMs ?? 10_000;
    this.maxAttempts = opts.maxAttempts ?? 3;
    this.baseDelayMs = opts.baseDelayMs ?? 500;
    this.maxDelayMs = opts.maxDelayMs ?? 5_000;
    this.log = opts.logger ?? noopLogger;
    this.fetchImpl = opts.fetchImpl ?? fetch;
    this.sleep = opts.sleep ?? realSleep;
    this.random = opts.random ?? Math.random;
  }

  /** Reads STAMPMITRA_API_KEY (and optional STAMPMITRA_BASE_URL) from the environment. */
  static fromEnv(overrides: Partial<ClientOptions> = {}): StampMitraClient {
    const apiKey = process.env.STAMPMITRA_API_KEY;
    if (!apiKey) throw new Error("STAMPMITRA_API_KEY is not set");
    return new StampMitraClient({
      apiKey,
      baseUrl: process.env.STAMPMITRA_BASE_URL,
      ...overrides,
    });
  }

  async verifyPan(input: PanInput): Promise<PanVerifyResult> {
    const body = normalisePanInput(input); // throws before any network call
    return this.post<PanVerifyResult>("/v1/verify/pan", body);
  }

  private backoff(attempt: number): number {
    // Full jitter: random between 0 and min(cap, base * 2^(attempt-1)).
    const ceiling = Math.min(this.maxDelayMs, this.baseDelayMs * 2 ** (attempt - 1));
    return Math.round(this.random() * ceiling);
  }

  private async post<T>(path: string, payload: object): Promise<T> {
    for (let attempt = 1; ; attempt++) {
      const started = Date.now();
      let res: Response;
      try {
        res = await this.fetchImpl(`${this.baseUrl}${path}`, {
          method: "POST",
          headers: {
            Authorization: `Bearer ${this.apiKey}`,
            "Content-Type": "application/json",
          },
          body: JSON.stringify(payload),
          signal: AbortSignal.timeout(this.timeoutMs),
        });
      } catch (err) {
        // Not retried: a request that timed out may still have completed (and been
        // billed) on the server, and the verify endpoints have no idempotency key.
        const timedOut = err instanceof Error && err.name === "TimeoutError";
        this.log({ event: "stampmitra.request_failed", path, attempt, kind: timedOut ? "timeout" : "network", ms: Date.now() - started });
        throw new StampMitraError(timedOut ? "timeout" : "network", timedOut ? "Request timed out" : "Network error", { cause: err });
      }

      const text = await res.text();
      let json: any = null;
      try {
        json = text ? JSON.parse(text) : null;
      } catch {
        json = null; // e.g. an HTML error page from a proxy
      }

      if (res.ok && json) {
        this.log({ event: "stampmitra.request_ok", path, attempt, status: res.status, referenceId: json.referenceId, ms: Date.now() - started });
        return json as T;
      }

      const requestId: string | undefined = json?.error?.requestId;
      const code: string | undefined = json?.error?.code;
      this.log({ event: "stampmitra.request_error", path, attempt, status: res.status, code, requestId, ms: Date.now() - started });

      if (isRetryableStatus(res.status) && attempt < this.maxAttempts) {
        await this.sleep(this.backoff(attempt));
        continue;
      }
      throw new StampMitraError(kindForStatus(res.status), json?.error?.message ?? `HTTP ${res.status}`, {
        status: res.status,
        code,
        requestId,
      });
    }
  }
}

import { StampMitraClient } from "./client.ts";
import { jsonLogger } from "./logger.ts";

const client = StampMitraClient.fromEnv({ logger: jsonLogger });
const result = await client.verifyPan({ pan: "abcde1234f", name: "Rahul Kumar" });

if (result.valid && result.nameMatchResult === "MATCH") {
  // proceed, and persist result.referenceId against your user record
}

# file: verify_basic.py
"""Smallest possible call. Run: python verify_basic.py  (key comes from the environment)."""
import os
import sys

import requests

api_key = os.environ.get("STAMPMITRA_API_KEY")
if not api_key:
    sys.exit("STAMPMITRA_API_KEY is not set")

res = requests.post(
    "https://api-b2b.stampmitra.in/v1/verify/pan",
    headers={"Authorization": f"Bearer {api_key}"},
    json={"pan": "ABCDE1234F", "name": "Rahul Kumar"},
    timeout=(3.05, 10),  # (connect, read) seconds
)
body = res.json()
if not res.ok:
    err = body.get("error", {})
    sys.exit(f"{res.status_code} {err.get('code')} {err.get('requestId')}")
print(body["referenceId"], body["valid"], body.get("nameMatchResult"))

# file: pan_demo/errors.py
from __future__ import annotations


class StampMitraError(Exception):
    """kind is one of: validation, bad_request, auth, wallet, rate_limited,
    upstream, timeout, network, unexpected."""

    def __init__(self, kind: str, message: str, *, status: int | None = None,
                 code: str | None = None, request_id: str | None = None) -> None:
        super().__init__(message)
        self.kind = kind
        self.status = status
        self.code = code
        self.request_id = request_id


def kind_for_status(status: int) -> str:
    if status == 400:
        return "bad_request"
    if status in (401, 403):
        return "auth"
    if status == 402:
        return "wallet"
    if status == 429:
        return "rate_limited"
    if status >= 500:
        return "upstream"
    return "unexpected"


def is_retryable_status(status: int) -> bool:
    """The only statuses we retry: rate limiting and server-side failures."""
    return status == 429 or status >= 500

# file: pan_demo/validation.py
from __future__ import annotations

import re

from .errors import StampMitraError

# API docs: pan must match the format ABCDE1234F (5 letters, 4 digits, 1 letter).
_PAN_RE = re.compile(r"[A-Z]{5}[0-9]{4}[A-Z]")
NAME_MAX = 256  # API docs: name, max 256 chars


def normalise_pan_input(pan: object, name: object = None) -> dict[str, str]:
    """Return the request body, or raise a 'validation' error without echoing the PAN."""
    clean = pan.strip().upper() if isinstance(pan, str) else ""
    if not _PAN_RE.fullmatch(clean):
        raise StampMitraError("validation", "pan must match the format ABCDE1234F")
    body = {"pan": clean}
    if isinstance(name, str) and name.strip():
        if len(name.strip()) > NAME_MAX:
            raise StampMitraError("validation", f"name must be at most {NAME_MAX} characters")
        body["name"] = name.strip()
    return body

# file: pan_demo/client.py
from __future__ import annotations

import logging
import os
import random
import time
from typing import Any, Callable

import httpx

from .errors import StampMitraError, is_retryable_status, kind_for_status
from .validation import normalise_pan_input

DEFAULT_BASE_URL = "https://api-b2b.stampmitra.in"
log = logging.getLogger("stampmitra")


class StampMitraClient:
    def __init__(
        self,
        api_key: str,
        *,
        base_url: str = DEFAULT_BASE_URL,
        timeout: httpx.Timeout | float = httpx.Timeout(10.0, connect=3.0),
        max_attempts: int = 3,
        base_delay: float = 0.5,
        max_delay: float = 5.0,
        transport: httpx.BaseTransport | None = None,  # injectable for tests
        sleep: Callable[[float], None] = time.sleep,
        rand: Callable[[], float] = random.random,
    ) -> None:
        if not api_key:
            raise ValueError("StampMitra api_key is required")
        self._http = httpx.Client(
            base_url=base_url.rstrip("/"),
            headers={"Authorization": f"Bearer {api_key}"},
            timeout=timeout,
            transport=transport,
        )
        self._max_attempts = max_attempts
        self._base_delay = base_delay
        self._max_delay = max_delay
        self._sleep = sleep
        self._rand = rand

    @classmethod
    def from_env(cls, **kwargs: Any) -> "StampMitraClient":
        key = os.environ.get("STAMPMITRA_API_KEY")
        if not key:
            raise RuntimeError("STAMPMITRA_API_KEY is not set")
        base = os.environ.get("STAMPMITRA_BASE_URL")
        if base:
            kwargs.setdefault("base_url", base)
        return cls(key, **kwargs)

    def close(self) -> None:
        self._http.close()

    def verify_pan(self, pan: str, name: str | None = None) -> dict[str, Any]:
        body = normalise_pan_input(pan, name)  # raises before any network call
        return self._post("/v1/verify/pan", body)

    def _backoff(self, attempt: int) -> float:
        # Full jitter: random between 0 and min(cap, base * 2^(attempt-1)).
        return self._rand() * min(self._max_delay, self._base_delay * 2 ** (attempt - 1))

    def _post(self, path: str, payload: dict[str, str]) -> dict[str, Any]:
        attempt = 0
        while True:
            attempt += 1
            started = time.monotonic()
            try:
                res = self._http.post(path, json=payload)
            except httpx.TimeoutException as exc:
                # Not retried: the request may still have completed (and been billed)
                # server-side, and verify endpoints have no idempotency key.
                log.warning("stampmitra request failed path=%s attempt=%d kind=timeout", path, attempt)
                raise StampMitraError("timeout", "Request timed out") from exc
            except httpx.TransportError as exc:
                log.warning("stampmitra request failed path=%s attempt=%d kind=network", path, attempt)
                raise StampMitraError("network", "Network error") from exc

            ms = int((time.monotonic() - started) * 1000)
            try:
                data = res.json()
            except ValueError:
                data = None  # e.g. an HTML error page from a proxy

            if res.is_success and isinstance(data, dict):
                log.info("stampmitra ok path=%s attempt=%d status=%d referenceId=%s ms=%d",
                         path, attempt, res.status_code, data.get("referenceId"), ms)
                return data

            err = data.get("error", {}) if isinstance(data, dict) else {}
            request_id = err.get("requestId")
            log.warning("stampmitra error path=%s attempt=%d status=%d code=%s requestId=%s ms=%d",
                        path, attempt, res.status_code, err.get("code"), request_id, ms)

            if is_retryable_status(res.status_code) and attempt < self._max_attempts:
                self._sleep(self._backoff(attempt))
                continue
            raise StampMitraError(
                kind_for_status(res.status_code),
                err.get("message") or f"HTTP {res.status_code}",
                status=res.status_code,
                code=err.get("code"),
                request_id=request_id,
            )

from pan_demo.client import StampMitraClient

client = StampMitraClient.from_env()
result = client.verify_pan("abcde1234f", "Rahul Kumar")
if result["valid"] and result.get("nameMatchResult") == "MATCH":
    ...  # persist result["referenceId"] with the user record

// file: src/limiter.ts
/** Serialises calls and leaves at least `minIntervalMs` between their starts.
 *  1000 ms keeps one process at or under 60 calls per 60 seconds. */
export function createSpacer(minIntervalMs: number) {
  let nextSlot = 0;
  return async function schedule<T>(task: () => Promise<T>): Promise<T> {
    const now = Date.now();
    const start = Math.max(now, nextSlot);
    nextSlot = start + minIntervalMs;
    if (start > now) await new Promise<void>((r) => setTimeout(r, start - now));
    return task();
  };
}

const schedule = createSpacer(1000);
for (const row of rows) {
  const result = await schedule(() => client.verifyPan({ pan: row.pan, name: row.name }));
  // persist result.referenceId against row.id
}

# file: pan_demo/limiter.py
import threading
import time


class Spacer:
    """Blocks callers so successive calls start at least `min_interval` seconds apart.
    1.0 keeps one process at or under 60 calls per 60 seconds."""

    def __init__(self, min_interval: float) -> None:
        self._min = min_interval
        self._lock = threading.Lock()
        self._next = 0.0

    def wait(self) -> None:
        with self._lock:
            now = time.monotonic()
            start = max(now, self._next)
            self._next = start + self._min
        if start > now:
            time.sleep(start - now)

spacer = Spacer(1.0)
for row in rows:
    spacer.wait()
    result = client.verify_pan(row["pan"], row.get("name"))

// file: test/fixtures.ts
export const OK_BODY = {
  referenceId: "SMV-20260927-8F42K7",
  pan: "ABCDE1234F",
  type: "Individual",
  valid: true,
  registeredName: "RAHUL KUMAR",
  fatherName: "SURESH KUMAR",
  panStatus: "VALID",
  panStatusCode: "E",
  panStatusDescription: "Existing and valid PAN",
  nameMatchResult: "MATCH",
  nameMatchScore: "100",
  aadhaarSeedingStatus: "y",
  aadhaarSeedingStatusDescription: "Aadhaar linked",
  lastUpdatedAt: "2023-04-01",
  message: "PAN is Valid",
};

export function errorBody(code: string, message: string) {
  return { error: { code, message, requestId: "a1b2c3d4-e5f6-4a1b-8c2d-9f0e1a2b3c4d" } };
}

export function jsonResponse(status: number, body: unknown): Response {
  return new Response(JSON.stringify(body), { status, headers: { "Content-Type": "application/json" } });
}

// file: test/client.test.ts
import { test } from "node:test";
import assert from "node:assert/strict";
import { StampMitraClient } from "../src/client.ts";
import { StampMitraError } from "../src/errors.ts";
import type { LogFields } from "../src/logger.ts";
import { OK_BODY, errorBody, jsonResponse } from "./fixtures.ts";

type Call = { url: string; init: RequestInit };

function makeClient(responses: Array<Response | Error>, extra: { logs?: LogFields[] } = {}) {
  const calls: Call[] = [];
  const delays: number[] = [];
  const queue = [...responses];
  const fetchImpl = (async (url: string | URL | Request, init?: RequestInit) => {
    calls.push({ url: String(url), init: init ?? {} });
    const next = queue.shift();
    if (!next) throw new Error("no more mocked responses");
    if (next instanceof Error) throw next;
    return next;
  }) as typeof fetch;
  const client = new StampMitraClient({
    apiKey: "sk_test_dummy",
    fetchImpl,
    sleep: async (ms) => void delays.push(ms),
    random: () => 1, // always the full ceiling, so delays are predictable
    logger: (f) => extra.logs?.push(f),
  });
  return { client, calls, delays };
}

test("sends the documented request shape", async () => {
  const { client, calls } = makeClient([jsonResponse(200, OK_BODY)]);
  const r = await client.verifyPan({ pan: " abcde1234f ", name: "Rahul Kumar" });
  assert.equal(r.referenceId, "SMV-20260927-8F42K7");
  assert.equal(calls.length, 1);
  assert.equal(calls[0].url, "https://api-b2b.stampmitra.in/v1/verify/pan");
  const headers = calls[0].init.headers as Record<string, string>;
  assert.equal(headers.Authorization, "Bearer sk_test_dummy");
  assert.deepEqual(JSON.parse(calls[0].init.body as string), { pan: "ABCDE1234F", name: "Rahul Kumar" });
});

test("a valid:false result is a normal return, not an error", async () => {
  const { client } = makeClient([jsonResponse(200, { referenceId: "SMV-20260927-0000000", valid: false })]);
  const r = await client.verifyPan({ pan: "ABCDE1234F" });
  assert.equal(r.valid, false);
});

test("invalid PAN is rejected locally with zero network calls", async () => {
  const { client, calls } = makeClient([]);
  await assert.rejects(() => client.verifyPan({ pan: "1234567890" }), (e: unknown) => e instanceof StampMitraError && e.kind === "validation");
  assert.equal(calls.length, 0);
});

test("400 is not retried and keeps the requestId", async () => {
  const { client, calls } = makeClient([jsonResponse(400, errorBody("BAD_REQUEST", "pan must match the format ABCDE1234F"))]);
  await assert.rejects(
    () => client.verifyPan({ pan: "ABCDE1234F" }),
    (e: unknown) => e instanceof StampMitraError && e.kind === "bad_request" && e.requestId === "a1b2c3d4-e5f6-4a1b-8c2d-9f0e1a2b3c4d",
  );
  assert.equal(calls.length, 1);
});

for (const [status, kind, code] of [
  [401, "auth", "UNAUTHORIZED"],
  [403, "auth", "FORBIDDEN"],
  [402, "wallet", "PAYMENT_REQUIRED"],
] as const) {
  test(`${status} is not retried`, async () => {
    const { client, calls } = makeClient([jsonResponse(status, errorBody(code, "x"))]);
    await assert.rejects(() => client.verifyPan({ pan: "ABCDE1234F" }), (e: unknown) => e instanceof StampMitraError && e.kind === kind);
    assert.equal(calls.length, 1);
  });
}

test("429 then success: retried once with backoff", async () => {
  const { client, calls, delays } = makeClient([
    jsonResponse(429, errorBody("TOO_MANY_REQUESTS", "Rate limit exceeded: 60 requests per 60 seconds for this endpoint.")),
    jsonResponse(200, OK_BODY),
  ]);
  const r = await client.verifyPan({ pan: "ABCDE1234F" });
  assert.equal(r.valid, true);
  assert.equal(calls.length, 2);
  assert.deepEqual(delays, [500]);
});

test("502 three times: gives up after maxAttempts with exponential delays", async () => {
  const bad = () => jsonResponse(502, errorBody("INTERNAL_ERROR", "Unable to reach the order/customer service right now"));
  const { client, calls, delays } = makeClient([bad(), bad(), bad()]);
  await assert.rejects(() => client.verifyPan({ pan: "ABCDE1234F" }), (e: unknown) => e instanceof StampMitraError && e.kind === "upstream" && e.status === 502);
  assert.equal(calls.length, 3);
  assert.deepEqual(delays, [500, 1000]);
});

test("timeout is surfaced and not retried", async () => {
  const timeout = Object.assign(new Error("timed out"), { name: "TimeoutError" });
  const { client, calls } = makeClient([timeout]);
  await assert.rejects(() => client.verifyPan({ pan: "ABCDE1234F" }), (e: unknown) => e instanceof StampMitraError && e.kind === "timeout");
  assert.equal(calls.length, 1);
});

test("an HTML error page from a proxy becomes a clean upstream error", async () => {
  const html = () => new Response("<html>Bad gateway</html>", { status: 502 });
  const { client } = makeClient([html(), html(), html()]);
  await assert.rejects(() => client.verifyPan({ pan: "ABCDE1234F" }), (e: unknown) => e instanceof StampMitraError && e.kind === "upstream");
});

test("logs never contain the PAN, the name or the API key", async () => {
  const logs: LogFields[] = [];
  const { client } = makeClient([jsonResponse(200, OK_BODY)], { logs });
  await client.verifyPan({ pan: "ABCDE1234F", name: "Rahul Kumar" });
  const dump = JSON.stringify(logs);
  assert.ok(logs.length > 0);
  assert.ok(!dump.includes("ABCDE1234F"));
  assert.ok(!dump.includes("Rahul"));
  assert.ok(!dump.includes("sk_test_dummy"));
  assert.ok(dump.includes("SMV-20260927-8F42K7"));
});

// file: test/app.test.ts
import { test } from "node:test";
import assert from "node:assert/strict";
import type { AddressInfo } from "node:net";
import { createApp } from "../src/app.ts";
import { StampMitraClient } from "../src/client.ts";
import { OK_BODY, errorBody, jsonResponse } from "./fixtures.ts";

async function withServer(upstream: Response[], run: (base: string) => Promise<void>) {
  const queue = [...upstream];
  const client = new StampMitraClient({
    apiKey: "sk_test_dummy",
    fetchImpl: (async () => queue.shift()!) as typeof fetch,
    sleep: async () => {},
  });
  const server = createApp(client).listen(0);
  try {
    await run(`http://127.0.0.1:${(server.address() as AddressInfo).port}`);
  } finally {
    server.close();
  }
}

const post = (base: string, body: unknown) =>
  fetch(`${base}/api/pan/verify`, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(body) });

test("200 returns only the fields the UI needs", async () => {
  await withServer([jsonResponse(200, OK_BODY)], async (base) => {
    const res = await post(base, { pan: "ABCDE1234F", name: "Rahul Kumar" });
    assert.equal(res.status, 200);
    assert.deepEqual(await res.json(), { referenceId: "SMV-20260927-8F42K7", valid: true, nameMatchResult: "MATCH", message: "PAN is Valid" });
  });
});

test("bad PAN returns 400 without touching upstream", async () => {
  await withServer([], async (base) => {
    const res = await post(base, { pan: "nope" });
    assert.equal(res.status, 400);
  });
});

test("upstream 402 is hidden from the caller as a generic 500", async () => {
  await withServer([jsonResponse(402, errorBody("PAYMENT_REQUIRED", "Insufficient fulfilment wallet balance to cover this call."))], async (base) => {
    const res = await post(base, { pan: "ABCDE1234F" });
    assert.equal(res.status, 500);
    assert.ok(!JSON.stringify(await res.json()).toLowerCase().includes("wallet"));
  });
});

# file: tests/conftest.py
import httpx
import pytest

from pan_demo.client import StampMitraClient

OK_BODY = {
    "referenceId": "SMV-20260927-8F42K7", "pan": "ABCDE1234F", "type": "Individual", "valid": True,
    "registeredName": "RAHUL KUMAR", "fatherName": "SURESH KUMAR", "panStatus": "VALID",
    "panStatusCode": "E", "panStatusDescription": "Existing and valid PAN",
    "nameMatchResult": "MATCH", "nameMatchScore": "100", "aadhaarSeedingStatus": "y",
    "aadhaarSeedingStatusDescription": "Aadhaar linked", "lastUpdatedAt": "2023-04-01",
    "message": "PAN is Valid",
}


def error_body(code: str, message: str) -> dict:
    return {"error": {"code": code, "message": message, "requestId": "a1b2c3d4-e5f6-4a1b-8c2d-9f0e1a2b3c4d"}}


@pytest.fixture
def make_client():
    """Build a client whose HTTP layer replays `responses` in order and records requests."""

    def factory(responses):
        queue = list(responses)
        requests: list[httpx.Request] = []
        delays: list[float] = []

        def handler(request: httpx.Request) -> httpx.Response:
            requests.append(request)
            item = queue.pop(0)
            if isinstance(item, Exception):
                raise item
            return item

        client = StampMitraClient(
            "sk_test_dummy",
            transport=httpx.MockTransport(handler),
            sleep=delays.append,
            rand=lambda: 1.0,  # always the full ceiling, so delays are predictable
        )
        return client, requests, delays

    return factory

# file: tests/test_client.py
import json
import logging

import httpx
import pytest

from pan_demo.errors import StampMitraError
from .conftest import OK_BODY, error_body


def test_sends_documented_request_shape(make_client):
    client, requests, _ = make_client([httpx.Response(200, json=OK_BODY)])
    r = client.verify_pan(" abcde1234f ", "Rahul Kumar")
    assert r["referenceId"] == "SMV-20260927-8F42K7"
    req = requests[0]
    assert str(req.url) == "https://api-b2b.stampmitra.in/v1/verify/pan"
    assert req.headers["authorization"] == "Bearer sk_test_dummy"
    assert json.loads(req.content) == {"pan": "ABCDE1234F", "name": "Rahul Kumar"}


def test_valid_false_is_a_normal_return(make_client):
    client, _, _ = make_client([httpx.Response(200, json={"referenceId": "SMV-20260927-0000000", "valid": False})])
    assert client.verify_pan("ABCDE1234F")["valid"] is False


def test_invalid_pan_makes_no_request(make_client):
    client, requests, _ = make_client([])
    with pytest.raises(StampMitraError) as exc:
        client.verify_pan("1234567890")
    assert exc.value.kind == "validation"
    assert requests == []


@pytest.mark.parametrize("status,kind,code", [
    (400, "bad_request", "BAD_REQUEST"),
    (401, "auth", "UNAUTHORIZED"),
    (402, "wallet", "PAYMENT_REQUIRED"),
    (403, "auth", "FORBIDDEN"),
])
def test_client_errors_are_not_retried(make_client, status, kind, code):
    client, requests, _ = make_client([httpx.Response(status, json=error_body(code, "x"))])
    with pytest.raises(StampMitraError) as exc:
        client.verify_pan("ABCDE1234F")
    assert exc.value.kind == kind
    assert exc.value.request_id == "a1b2c3d4-e5f6-4a1b-8c2d-9f0e1a2b3c4d"
    assert len(requests) == 1


def test_429_then_success_retries_once(make_client):
    limited = httpx.Response(429, json=error_body("TOO_MANY_REQUESTS", "Rate limit exceeded: 60 requests per 60 seconds for this endpoint."))
    client, requests, delays = make_client([limited, httpx.Response(200, json=OK_BODY)])
    assert client.verify_pan("ABCDE1234F")["valid"] is True
    assert len(requests) == 2
    assert delays == [0.5]


def test_502_exhausts_attempts_with_exponential_delays(make_client):
    bad = lambda: httpx.Response(502, json=error_body("INTERNAL_ERROR", "Unable to reach the order/customer service right now"))
    client, requests, delays = make_client([bad(), bad(), bad()])
    with pytest.raises(StampMitraError) as exc:
        client.verify_pan("ABCDE1234F")
    assert (exc.value.kind, exc.value.status) == ("upstream", 502)
    assert len(requests) == 3
    assert delays == [0.5, 1.0]


def test_timeout_is_surfaced_not_retried(make_client):
    client, requests, _ = make_client([httpx.ReadTimeout("slow")])
    with pytest.raises(StampMitraError) as exc:
        client.verify_pan("ABCDE1234F")
    assert exc.value.kind == "timeout"
    assert len(requests) == 1


def test_html_error_page_becomes_upstream_error(make_client):
    page = lambda: httpx.Response(502, text="<html>Bad gateway</html>")
    client, _, _ = make_client([page(), page(), page()])
    with pytest.raises(StampMitraError) as exc:
        client.verify_pan("ABCDE1234F")
    assert exc.value.kind == "upstream"


def test_logs_never_contain_pan_name_or_key(make_client, caplog):
    caplog.set_level(logging.DEBUG, logger="stampmitra")
    client, _, _ = make_client([httpx.Response(200, json=OK_BODY)])
    client.verify_pan("ABCDE1234F", "Rahul Kumar")
    text = caplog.text
    assert "SMV-20260927-8F42K7" in text
    for secret in ("ABCDE1234F", "Rahul", "sk_test_dummy"):
        assert secret not in text

# file: tests/test_app.py
import httpx
import pytest
from fastapi.testclient import TestClient

from pan_demo.app import app, get_client
from .conftest import OK_BODY, error_body


@pytest.fixture
def api(make_client):
    def build(responses):
        client, requests, _ = make_client(responses)
        app.dependency_overrides[get_client] = lambda: client
        return TestClient(app), requests

    yield build
    app.dependency_overrides.clear()


def test_200_returns_only_ui_fields(api):
    tc, _ = api([httpx.Response(200, json=OK_BODY)])
    res = tc.post("/api/pan/verify", json={"pan": "ABCDE1234F", "name": "Rahul Kumar"})
    assert res.status_code == 200
    assert res.json() == {"referenceId": "SMV-20260927-8F42K7", "valid": True,
                          "nameMatchResult": "MATCH", "message": "PAN is Valid"}


def test_bad_pan_is_400_without_upstream_call(api):
    tc, requests = api([])
    res = tc.post("/api/pan/verify", json={"pan": "nope"})
    assert res.status_code == 400
    assert requests == []


def test_upstream_402_is_hidden_as_generic_500(api):
    tc, _ = api([httpx.Response(402, json=error_body("PAYMENT_REQUIRED", "Insufficient fulfilment wallet balance to cover this call."))])
    res = tc.post("/api/pan/verify", json={"pan": "ABCDE1234F"})
    assert res.status_code == 500
    assert "wallet" not in res.text.lower()

// file: src/app.ts
import express from "express";
import type { Request, Response } from "express";
import { StampMitraClient } from "./client.ts";
import { StampMitraError } from "./errors.ts";

type Mapped = { status: number; code: string; message: string };

/** Translate a library error into OUR API's response. Upstream messages are never
 *  forwarded, and credential or wallet problems are not the caller's to fix. */
export function mapError(err: unknown): Mapped {
  if (!(err instanceof StampMitraError)) {
    return { status: 500, code: "INTERNAL_ERROR", message: "Something went wrong." };
  }
  switch (err.kind) {
    case "validation":
    case "bad_request":
      return { status: 400, code: "INVALID_INPUT", message: "Enter a PAN in the format ABCDE1234F." };
    case "rate_limited":
      return { status: 503, code: "TRY_AGAIN_LATER", message: "Verification is busy. Please retry shortly." };
    case "timeout":
    case "network":
    case "upstream":
      return { status: 502, code: "VERIFICATION_UNAVAILABLE", message: "Verification is temporarily unavailable." };
    case "auth":
    case "wallet":
    default:
      // Our configuration or balance problem: page someone, show the user nothing specific.
      return { status: 500, code: "INTERNAL_ERROR", message: "Something went wrong." };
  }
}

export function createApp(client: StampMitraClient) {
  const app = express();
  app.disable("x-powered-by");
  app.use(express.json({ limit: "4kb" }));

  app.post("/api/pan/verify", async (req: Request, res: Response) => {
    try {
      const { pan, name } = req.body ?? {};
      const r = await client.verifyPan({ pan, name });
      // Return only what the UI needs. Store r.referenceId with your user record.
      res.json({
        referenceId: r.referenceId,
        valid: r.valid,
        nameMatchResult: r.nameMatchResult ?? null,
        message: r.message ?? null,
      });
    } catch (err) {
      const m = mapError(err);
      const e = err instanceof StampMitraError ? err : null;
      console.error(JSON.stringify({ event: "pan_verify_failed", kind: e?.kind, status: e?.status, requestId: e?.requestId }));
      res.status(m.status).json({ error: { code: m.code, message: m.message } });
    }
  });

  return app;
}

// file: src/server.ts
import { StampMitraClient } from "./client.ts";
import { createApp } from "./app.ts";
import { jsonLogger } from "./logger.ts";

const client = StampMitraClient.fromEnv({ logger: jsonLogger }); // fails fast if the key is missing
const port = Number(process.env.PORT ?? 3000);
createApp(client).listen(port, () => console.log(`listening on :${port}`));

curl -X POST http://localhost:3000/api/pan/verify \
  -H "Content-Type: application/json" \
  -d '{"pan":"ABCDE1234F","name":"Rahul Kumar"}'

{
  "referenceId": "SMV-20260927-8F42K7",
  "valid": true,
  "nameMatchResult": "MATCH",
  "message": "PAN is Valid"
}

# file: pan_demo/app.py
from __future__ import annotations

import logging
from typing import Annotated

from fastapi import Depends, FastAPI, Request
from fastapi.responses import JSONResponse
from pydantic import BaseModel, Field

from .client import StampMitraClient
from .errors import StampMitraError

logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s")
log = logging.getLogger("pan_demo")

app = FastAPI()
_client: StampMitraClient | None = None


def get_client() -> StampMitraClient:
    global _client
    if _client is None:
        _client = StampMitraClient.from_env()  # fails fast if the key is missing
    return _client


class PanRequest(BaseModel):
    pan: str = Field(max_length=32)  # cheap size cap; strict format check is in the client
    name: str | None = Field(default=None, max_length=300)


def map_error(err: StampMitraError) -> tuple[int, str, str]:
    """Translate a library error into OUR API's response. Upstream messages are never forwarded."""
    if err.kind in ("validation", "bad_request"):
        return 400, "INVALID_INPUT", "Enter a PAN in the format ABCDE1234F."
    if err.kind == "rate_limited":
        return 503, "TRY_AGAIN_LATER", "Verification is busy. Please retry shortly."
    if err.kind in ("timeout", "network", "upstream"):
        return 502, "VERIFICATION_UNAVAILABLE", "Verification is temporarily unavailable."
    # auth, wallet, unexpected: our configuration or balance problem, not the caller's.
    return 500, "INTERNAL_ERROR", "Something went wrong."


@app.exception_handler(StampMitraError)
async def stampmitra_error_handler(_: Request, err: StampMitraError) -> JSONResponse:
    status, code, message = map_error(err)
    log.error("pan_verify_failed kind=%s status=%s requestId=%s", err.kind, err.status, err.request_id)
    return JSONResponse({"error": {"code": code, "message": message}}, status_code=status)


# A plain `def` endpoint runs in FastAPI's threadpool, so the blocking client is safe here.
@app.post("/api/pan/verify")
def verify_pan(body: PanRequest, client: Annotated[StampMitraClient, Depends(get_client)]) -> dict:
    r = client.verify_pan(body.pan, body.name)
    return {
        "referenceId": r["referenceId"],
        "valid": r["valid"],
        "nameMatchResult": r.get("nameMatchResult"),
        "message": r.get("message"),
    }