POST /v1/verify/sessions HTTP/1.1
Host: verify-api.nubarewards.com
Content-Type: application/json
x-api-key: nuba_sk_<your_key>

Production:  https://verify-api.nubarewards.com
Sandbox:     use the Sandbox runner in your partner dashboard

type SessionStatus =
  | 'PENDING'        // Session created; awaiting document upload
  | 'EXTRACTING'     // Document uploaded; AI extraction in progress
  | 'PROCESSING'     // Tenant confirmed details; all layers running
  | 'PASSED'         // Score ≥ partner's pass mark threshold
  | 'MANUAL_REVIEW'  // Score between review and pass mark thresholds
  | 'FAILED'         // Score < partner's manual review threshold

type LayerStatus =
  | 'PENDING'    // Layer not yet started
  | 'RUNNING'    // Layer job in progress
  | 'EXTRACTED'  // Document layer: extraction complete, awaiting confirm
  | 'COMPLETE'   // Layer finished successfully with a score
  | 'FAILED'     // Layer failed (score is 0 or null)
  | 'SKIPPED'    // Layer intentionally bypassed (e.g. Open Banking when
                 //   financialVerificationEnabled = false on the partner)

type LayerType =
  | 'DOCUMENT'     // Layer 1 — AI document parsing & tampering detection (35%)
  | 'ADDRESS'      // Layer 2 — Address & rent benchmarking (25%)
  | 'OPEN_BANKING' // Layer 3 — Bank transaction matching via TrueLayer (25%)
  | 'LANDLORD'     // Layer 4 — Landlord/agent entity verification (15%)

interface CreateSessionRequest {
  tenantName:        string;            // Full name of the tenant
  tenantEmail:       string;            // Tenant's email address
  webhookUrl?:       string;            // URL to receive completion events (optional)
  redirectUrl?:      string;            // Where to redirect after wizard completes (optional)

  // ── BYO (Bring Your Own) banking data — added v1.5 ──────────────
  // Partners that already hold tenant transaction history can submit
  // it here instead of redirecting the tenant through TrueLayer.
  // Requires byoEnabled = true on your partner config; see the
  // Verification Config tab in your dashboard.
  transactionStream?: TransactionStream; // Pre-collected bank data
  byoMode?:           'fallback' | 'strict'; // Per-session override
}

interface TransactionStream {
  source:        string;             // Free-text source label (e.g. "Plaid", "in-house")
  attestedAt:    string;             // ISO 8601 — when the data was collected
  windowMonths:  number;             // How many months of history are included (1–24)
  account: {
    sortCode:      string;           // 6 digits
    accountNumber: string;           // 8 digits
    accountName?:  string;
  };
  transactions: Array<{
    date:        string;             // ISO 8601
    amount:      number;             // GBP, negative for outgoing
    description: string;
    reference?:  string;
  }>;
}

interface CreateSessionResponse {
  sessionId:       string;            // UUID — use in all subsequent calls
  status:          SessionStatus;     // Always 'PENDING' on creation
  verificationUrl: string;            // Tenant-facing wizard URL

  // Present only when transactionStream was supplied on the request.
  byo?: {
    accepted: boolean;                // false ⇒ stream rejected, see reason
    reason?:  string;                 // Why the stream was rejected (strict mode)
    mode:     'fallback' | 'strict';  // Effective mode used for this session
  };
}

interface ExtractedData {
  tenantName:        string;
  landlordName:      string;
  landlordEntityType: 'individual' | 'company';
  address:           string;       // Full address string from the document
  rentAmount:        number;       // Monthly rent in GBP
  tenancyStartDate:  string;       // ISO 8601 date
  bankSortCode:      string | null;
  bankAccountNumber: string | null;
  paymentReference:  string | null;
  bedrooms:          number | null;
  tamperingFlags:    string[];     // List of detected anomaly codes
  documentConfidence: number;      // 0–1 extraction confidence
}

interface ConfirmDetailsRequest {
  tenantName?:           string;
  addressLine1:          string;   // required
  addressLine2?:         string;
  city:                  string;   // required
  postcode:              string;   // required
  propertyType:          'residential' | 'commercial';  // required
  bedrooms?:             number;   // required for residential
  furnished:             boolean;  // required
  rentAmount:            number;   // required — monthly GBP
  rentDueDate:           number;   // required — day of month 1–31
  landlordName:          string;   // required
  landlordType:          'individual' | 'company';   // required
  landlordEmail?:        string;
  accountName:           string;   // required — name on rent-receiving bank account
  landlordSortCode:      string;   // required — 6 digits
  landlordAccountNumber: string;   // required — 8 digits
  paymentReference?:     string;
  tenancyStartDate?:     string;   // ISO 8601
  tenancyEndDate?:       string;   // ISO 8601; omit for rolling tenancies
}

interface SessionDetails {
  sessionId:   string;
  status:      SessionStatus;
  totalScore:  number | null;   // 0–100; null while PENDING/EXTRACTING
  createdAt:   string;          // ISO 8601
  updatedAt:   string;

  tenant: {
    name:  string | null;
    email: string | null;
  };

  property: {
    addressLine1:  string | null;
    addressLine2:  string | null;
    city:          string | null;
    postcode:      string | null;
    propertyType:  'residential' | 'commercial';
    bedrooms:      number | null;
    furnished:     boolean | null;
  };

  tenancy: {
    rentAmount:  number | null;
    rentDueDate: number | null;  // day of month
    startDate:   string | null;
    endDate:     string | null;
  };

  rentRecipient: {
    accountName:      string | null;
    sortCode:         string | null;
    accountNumber:    string | null;
    paymentReference: string | null;
  };

  landlord: {
    name:  string | null;
    type:  'individual' | 'company' | null;
    email: string | null;
  };

  document: {
    url:            string | null;   // Presigned URL, expires in 1 hour
    mimeType:       string | null;
    fileSize:       number | null;   // bytes
    confidence:     number | null;   // 0–1
    tamperingFlags: string[];
  };

  verificationSummary: string | null;  // AI-generated plain-English summary
}

interface WebhookPayload {
  sessionId:  string;
  status:     SessionStatus;            // PASSED | MANUAL_REVIEW | FAILED
  totalScore: number;
  breakdown: {
    document:    { score: number; flags: string[] };
    address:     { score: number; propertyConfirmed: boolean; rentRatio: number };
    openBanking: { score: number; consecutiveMonthsFound: number; accountMatchConfirmed: boolean };
    landlord:    { score: number; entityType: 'individual' | 'company'; networkMatch: boolean };
  };
  summary: string | null;               // AI-generated plain-English summary
}

// Response — 201 Created
{
  "sessionId":       "e324ad63-1018-4f42-a0ae-db764682f5a6",
  "status":          "PENDING",
  "verificationUrl": "https://verify.nubarewards.com/verify/e324ad63-..."
}

// Response — 201 Created (with BYO transaction stream)
{
  "sessionId":       "e324ad63-...",
  "status":          "PENDING",
  "verificationUrl": "https://verify.nubarewards.com/verify/e324ad63-...",
  "byo": {
    "accepted": true,
    "mode":     "fallback"
  }
}

// Response — 422 (BYO rejected, strict mode)
{
  "error":   "BYO_VALIDATION_FAILED",
  "message": "transactionStream.windowMonths must be ≥ 6 for strict mode"
}

// Response — 202 Accepted
{
  "sessionId": "e324ad63-...",
  "status":    "EXTRACTING",
  "message":   "Document uploaded. Extraction in progress."
}

// Response — extraction complete
{
  "status": "EXTRACTED",
  "ready":  true,
  "extracted": {
    "tenantName":         "Jane Smith",
    "landlordName":       "Acme Properties Ltd",
    "landlordEntityType": "company",
    "address":            "42 Victoria Road, Manchester, M1 2JB",
    "rentAmount":         1200,
    "tenancyStartDate":   "2025-01-15",
    "bankSortCode":       "112233",
    "bankAccountNumber":  "87654321",
    "paymentReference":   "SMITH42",
    "bedrooms":           2,
    "tamperingFlags":     [],
    "documentConfidence": 0.97
  }
}

// Response — still processing
{
  "status": "RUNNING",
  "ready":  false,
  "extracted": null
}

// Response — 200 OK
{
  "sessionId":       "e324ad63-...",
  "status":          "PROCESSING",
  "truelayerAuthUrl": "https://auth.truelayer.com/?...",
  "message":         "Details confirmed. Verification in progress."
}

// Response — session in progress
{
  "sessionId":  "e324ad63-...",
  "status":     "PROCESSING",
  "totalScore": null,
  "layers": {
    "document":    { "status": "COMPLETE",  "score": 88 },
    "address":     { "status": "COMPLETE",  "score": 75 },
    "openBanking": { "status": "RUNNING",   "score": null },
    "landlord":    { "status": "RUNNING",   "score": null }
  },
  "theme": {
    "primaryColor":   "#E8A23A",
    "partnerName":    "Acme Rentals",
    "partnerLogoUrl": "https://..."
  }
}

// Response — session complete
{
  "sessionId":  "e324ad63-...",
  "status":     "PASSED",
  "totalScore": 82.5,
  "layers": {
    "document":    { "status": "COMPLETE", "score": 88 },
    "address":     { "status": "COMPLETE", "score": 75 },
    "openBanking": { "status": "COMPLETE", "score": 91 },
    "landlord":    { "status": "COMPLETE", "score": 70 }
  },
  "breakdown": {
    "document":    { "score": 88, "flags": [] },
    "address":     { "score": 75, "propertyConfirmed": true, "rentRatio": 1.1 },
    "openBanking": { "score": 91, "consecutiveMonthsFound": 6, "accountMatchConfirmed": true },
    "landlord":    { "score": 70, "entityType": "company", "networkMatch": true }
  }
}

// Response — 200 OK
{
  "sessionId":   "e324ad63-...",
  "status":      "PASSED",
  "totalScore":  82.5,
  "createdAt":   "2026-04-17T09:12:00.000Z",
  "updatedAt":   "2026-04-17T09:14:31.000Z",

  "tenant":  { "name": "Jane Smith", "email": "jane@example.com" },

  "property": {
    "addressLine1": "42 Victoria Road",
    "addressLine2": null,
    "city":         "Manchester",
    "postcode":     "M1 2JB",
    "propertyType": "residential",
    "bedrooms":     2,
    "furnished":    true
  },

  "tenancy": {
    "rentAmount":  1200,
    "rentDueDate": 1,
    "startDate":   "2025-01-15",
    "endDate":     "2026-01-14"
  },

  "rentRecipient": {
    "accountName":      "Acme Properties Ltd",
    "sortCode":         "112233",
    "accountNumber":    "87654321",
    "paymentReference": "SMITH42"
  },

  "landlord": {
    "name":  "Acme Properties Ltd",
    "type":  "company",
    "email": "info@acmeprops.co.uk"
  },

  "document": {
    "url":            "https://verify-api.nubarewards.com/...",
    "mimeType":       "application/pdf",
    "fileSize":       204800,
    "confidence":     0.97,
    "tamperingFlags": []
  },

  "verificationSummary": "The tenant has provided a valid tenancy agreement ..."
}

// Request body
interface LegacyVerifyRequest {
  tenantName:          string;
  tenantEmail:         string;
  documentBase64:      string;
  addressLine1:        string;
  city:                string;
  postcode:            string;
  bedrooms?:           number;
  furnished:           boolean;
  rentAmount:          number;
  landlordName:        string;
  landlordEmail?:      string;
  landlordSortCode:    string;
  landlordAccountNumber: string;
  webhookUrl?:         string;
}

// Response — 202 Accepted
{
  "sessionId":       "e324ad63-...",
  "truelayerAuthUrl": "https://auth.truelayer.com/?..."
}

interface SubmitTransactionsRequest {
  transactions: Array<{
    transactionId?:              string;   // Your internal ID — used as idempotency key if present
    date:                        string;   // ISO 8601
    amountPence:                 number;   // Negative for outgoing (tenant → landlord)
    description:                 string;
    reference?:                  string;
    counterpartySortCode?:       string;   // Optional but improves match confidence
    counterpartyAccountNumber?:  string;   // Optional but improves match confidence
  }>;
}

// Response — 200 OK (synchronous)
{
  "sessionId": "e324ad63-...",
  "received":  4,
  "matched":   1,
  "matches": [
    {
      "transactionId":    "boogi_txn_8829",
      "matchId":          "pm_a3f2...",
      "paidOnDate":       "2026-04-21",
      "amountPence":      120000,
      "matchedReference": "SMITH42",
      "confidence":       0.94,
      "billingPeriod":    "2026-04"
    }
  ],
  "duplicates": 0
}

// Response — 202 Accepted (async or batch > 100)
{
  "jobId":     "pmscan_...",
  "received":  428,
  "statusUrl": "/v1/verify/sessions/e324ad63-.../transactions/pmscan_..."
}

// Response — 200 OK
{
  "sessionId": "e324ad63-...",
  "matches": [
    {
      "matchId":          "pm_a3f2...",
      "paidOnDate":       "2026-04-21",
      "amountPence":      120000,
      "matchedReference": "SMITH42",
      "confidence":       0.94,
      "billingPeriod":    "2026-04",
      "createdAt":        "2026-04-21T18:32:11.000Z"
    },
    ...
  ],
  "nextCursor": null
}

// Response — job complete
{
  "jobId":   "pmscan_...",
  "status":  "COMPLETE",
  "matched": 12,
  "matches": [ /* same shape as synchronous response */ ],
  "duplicates": 3
}

{
  "event":            "payment.confirmed",
  "sessionId":        "e324ad63-...",
  "matchId":          "pm_a3f2...",
  "paidOnDate":       "2026-04-21",
  "amountPence":      120000,
  "matchedReference": "SMITH42",
  "confidence":       0.94,
  "billingPeriod":    "2026-04"
}

import { createHmac, timingSafeEqual } from 'crypto';

function verifySignature(rawBody: string, header: string, secret: string): boolean {
  // Header format: "t=1734567890,v1=abc123…"
  const parts = Object.fromEntries(
    header.split(',').map((kv) => kv.split('=') as [string, string]),
  );
  const t = parts.t;
  const v1 = parts.v1;
  if (!t || !v1) return false;

  // Reject stale deliveries (replay protection).
  const ageSeconds = Math.floor(Date.now() / 1000) - Number(t);
  if (Number.isNaN(ageSeconds) || ageSeconds > 300) return false;

  const expected = createHmac('sha256', secret)
    .update(`${t}.${rawBody}`)
    .digest('hex');

  // Constant-time comparison.
  const a = Buffer.from(expected, 'hex');
  const b = Buffer.from(v1, 'hex');
  return a.length === b.length && timingSafeEqual(a, b);
}

// Express (must use express.raw, not express.json)
app.post('/webhooks/nuba', express.raw({ type: 'application/json' }), (req, res) => {
  const sig = req.headers['x-nuba-signature'] as string;
  if (!verifySignature(req.body.toString(), sig, process.env.NUBA_WEBHOOK_SECRET!)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  const event = JSON.parse(req.body) as WebhookPayload;

  switch (event.status) {
    case 'PASSED':
      await onPassed(event);
      break;
    case 'MANUAL_REVIEW':
      await flagForReview(event);
      break;
    case 'FAILED':
      await onFailed(event);
      break;
  }

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

interface ErrorResponse {
  error:    string;           // Short machine-readable message
  details?: Record<string, string[]>;  // Per-field validation errors (400 only)
  message?: string;           // Additional context
}