Identity Verification

POST /api/v1/applications/app_20251222_143023_usr123/identity/upload
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: multipart/form-data

// Form Fields:
document_type: "passport"  // or "driving_licence"
document_side: "front"     // or "back" for driving licence
file: // Binary image data (JPG/PNG/PDF, max 10MB)
capture_method: "camera"  // or "upload"

{
  "request_id": "req_cm04_20251222_143512",
  "status": "success",
  "verification_id": "onfido_check_abc123xyz",
  "verification_result": {
    "status": "complete",
    "result": "clear",
    "extracted_data": {
      "full_name": "John Smith",
      "date_of_birth": "1985-06-15",
      "document_type": "UK Passport",
      "document_number": "123456789",
      "expiry_date": "2030-06-15",
      "nationality": "British"
    },
    "checks_performed": {
      "document_authenticity": {
        "status": "clear",
        "confidence": 0.99
      },
      "facial_similarity": {
        "status": "clear",
        "confidence": 0.98
      },
      "aml_screening": {
        "status": "clear",
        "pep_match": false,
        "sanctions_match": false,
        "watchlist_match": false
      },
      "director_match": {
        "status": "clear",
        "matched_company": "Smith's Artisan Café Ltd",
        "company_number": "12345678"
      }
    }
  },
  "processing_time_ms": 12340,
  "timestamp": "2025-12-22T14:35:24Z"
}

{
  "verification_id": "onfido_check_abc123xyz",
  "status": "in_progress",  // or "complete", "failed"
  "current_step": "facial_similarity",
  "progress_percentage": 60,
  "estimated_completion_seconds": 8
}

// Verification Orchestration Flow

async function verifyIdentity(applicationId, documentFile) {
  
  // 1. Create Onfido Applicant
  const applicant = await onfido.createApplicant({
    first_name: customer.firstName,
    last_name: customer.lastName,
    email: customer.email
  });
  
  // 2. Upload Document
  const document = await onfido.uploadDocument({
    applicant_id: applicant.id,
    type: 'passport',
    file: documentFile,
    side: 'front'
  });
  
  // 3. Create Check (runs all verifications)
  const check = await onfido.createCheck({
    applicant_id: applicant.id,
    report_names: [
      'document',           // Authenticity + OCR
      'facial_similarity_photo', // Face match
      'watchlist_aml'       // PEP/Sanctions
    ]
  });
  
  // 4. Poll for Results (or use webhook)
  const result = await pollCheckStatus(check.id);
  
  // 5. Parse and Return
  return {
    status: result.status,  // 'complete'
    result: result.result,  // 'clear', 'consider', 'reject'
    extractedData: parseOnfidoData(result),
    checksPerformed: aggregateChecks(result.reports)
  };
}

function determineVerificationOutcome(onfidoResult) {
  
  // Extract individual check results
  const documentCheck = onfidoResult.reports.find(r => r.name === 'document');
  const facialCheck = onfidoResult.reports.find(r => r.name === 'facial_similarity_photo');
  const amlCheck = onfidoResult.reports.find(r => r.name === 'watchlist_aml');
  
  // Auto-Reject Criteria
  if (documentCheck.result === 'rejected') {
    return {
      decision: 'REJECT',
      reason: 'Document authenticity failed',
      requiresManualReview: false
    };
  }
  
  if (amlCheck.properties.matches.length > 0) {
    return {
      decision: 'REJECT',
      reason: 'PEP or sanctions match found',
      requiresManualReview: true,  // Compliance review
      matches: amlCheck.properties.matches
    };
  }
  
  // Consider (Manual Review)
  if (documentCheck.result === 'consider' || 
      facialCheck.properties.score < 0.95) {
    return {
      decision: 'CONSIDER',
      reason: 'Document quality or facial match below threshold',
      requiresManualReview: true
    };
  }
  
  // Auto-Approve
  return {
    decision: 'CLEAR',
    reason: 'All checks passed',
    requiresManualReview: false
  };
}

POST /webhooks/onfido
X-SHA2-Signature: {signature}

{
  "payload": {
    "resource_type": "check",
    "action": "check.completed",
    "object": {
      "id": "onfido_check_abc123xyz",
      "status": "complete",
      "result": "clear",
      "href": "/v3/checks/onfido_check_abc123xyz"
    }
  }
}

// Handler logic:
// 1. Validate webhook signature
// 2. Fetch full check details from Onfido API
// 3. Update application status in database
// 4. Send real-time update to customer UI (WebSocket)

CREATE TABLE identity_verifications (
  verification_id     VARCHAR(50) PRIMARY KEY,
  application_id      VARCHAR(50) REFERENCES applications,
  onfido_check_id     VARCHAR(50),
  onfido_applicant_id VARCHAR(50),
  
  -- Extracted Identity Data (Encrypted)
  full_name           TEXT,
  date_of_birth       DATE,
  document_type       VARCHAR(50),
  document_number     TEXT,
  expiry_date         DATE,
  nationality         VARCHAR(50),
  
  -- Verification Results
  status              VARCHAR(20),  -- 'clear', 'consider', 'reject'
  authenticity_score  DECIMAL(3,2),
  facial_match_score  DECIMAL(3,2),
  aml_status          VARCHAR(20),
  pep_match           BOOLEAN,
  sanctions_match     BOOLEAN,
  director_verified   BOOLEAN,
  
  -- Metadata
  document_image_url  TEXT,  -- S3 pre-signed URL
  processing_time_ms  INTEGER,
  created_at          TIMESTAMP,
  updated_at          TIMESTAMP
);

CREATE INDEX idx_app_id ON identity_verifications(application_id);
CREATE INDEX idx_status ON identity_verifications(status);

UPDATE applications
SET 
  status = 'identity_verified',
  verified_name = 'John Smith',
  verified_dob = '1985-06-15',
  kyc_passed = true,
  kyc_completed_at = '2025-12-22 14:35:24',
  updated_at = '2025-12-22 14:35:24'
WHERE application_id = 'app_20251222_143023_usr123';

// Log 1: Document uploaded
{
  "log_id": "log_cm04_20251222_143512",
  "event_type": "identity_document_uploaded",
  "screen": "CM04",
  "user_id": "usr_olivia_thompson",
  "application_id": "app_20251222_143023_usr123",
  "timestamp": "2025-12-22T14:35:12Z",
  "details": {
    "document_type": "passport",
    "file_size_bytes": 2458000,
    "capture_method": "camera",
    "device": "iPhone 14 Pro"
  }
}

// Log 2: Verification completed
{
  "log_id": "log_cm04_20251222_143524",
  "event_type": "identity_verification_completed",
  "screen": "CM04",
  "user_id": "usr_olivia_thompson",
  "timestamp": "2025-12-22T14:35:24Z",
  "details": {
    "onfido_check_id": "onfido_check_abc123xyz",
    "status": "clear",
    "checks_passed": {
      "document_authenticity": true,
      "facial_similarity": true,
      "aml_screening": true,
      "director_match": true
    },
    "extracted_name": "John Smith",
    "extracted_dob": "1985-06-15",
    "processing_time_ms": 12340
  }
}