InvoiceGuard API

Business

Original Idea

Invoice Fraud Detector API An API that scores invoices for anomalies and returns clear risk explanations.

Product Requirements Document: InvoiceGuard API

1. Executive Summary

InvoiceGuard API is an enterprise-grade, AI-powered fraud detection engine designed to protect organizations from the multi-billion dollar threat of invoice fraud, including Business Email Compromise (BEC) and account takeovers. By leveraging a hybrid path of real-time synchronous scanning and deep asynchronous behavioral analysis, the API provides a risk score (0-100) with granular reason codes. Built on a 2026-standard tech stack, it integrates seamlessly with major ERPs (NetSuite, SAP) and financial verification services (Plaid, Stripe) to validate bank ownership and historical vendor patterns.

2. Problem Statement

Organizations face significant financial losses due to sophisticated social engineering and manual processing errors in Accounts Payable. Existing solutions are either manual and unscalable or "black-box" systems that lack the transparency required by financial controllers. There is a critical need for an automated, high-precision tool that can extract data from multiple invoice formats and flag anomalies—such as bank account changes or duplicate submissions—before payments are released.

3. Goals & Success Metrics

  • Accuracy: Maintain a Fraud Detection Rate (Recall) of >98% while keeping the False Positive Rate (FPR) below 2%.
  • Performance: Achieve sub-1.5s latency for synchronous API responses.
  • Adoption: Enable 1-day integration for developers via comprehensive documentation and a "Modern Stable" tech stack.
  • Compliance: Maintain SOC 2 Type II compliance with 100% automated evidence collection.

4. User Personas

  • Fintech Developer: Needs clean API docs, SDKs, and high-performance endpoints to embed fraud checks into custom AP software.
  • Financial Controller: Requires transparent reason codes and an audit trail to justify blocking payments.
  • ERP Architect: Responsible for integrating the API with NetSuite or SAP S/4HANA without compromising the "Clean Core."
  • AP Specialist: Uses the Human-in-the-loop (HITL) interface to review flagged invoices and train the ML model.

5. User Stories

  • As a Developer, I want to submit a base64 encoded PDF/Image via a POST request so that I can receive a structured risk assessment in real-time.
  • As a Controller, I want to see specific reason codes (e.g., AMT_OUTLIER, BANK_MODIFIED) so that I can provide an audit trail for blocked transactions.
  • As an AP Specialist, I want to confirm if a flagged invoice is a false positive so that the system learns and improves its accuracy.
  • As an ERP Architect, I want to use OAuth 2.0 and webhooks so that the integration is secure and handles asynchronous processing gracefully.

6. Functional Requirements

6.1 Multi-Format OCR & Extraction

  • Native PDF Parsing: High-speed extraction for digital-born PDFs using pdfplumber.
  • Scanned Document AI: Layout-aware extraction for JPEGs, PNGs, and scanned PDFs using DocTR or Mistral OCR 3.
  • Field Extraction: Mandatory capture of invoice_number, vendor_id, bank_account_number, routing_number, tax_id, and line_items.

6.2 Fraud Detection Engine

  • Hybrid Duplicate Detection: Use pgvector for semantic similarity search and pg_trgm for syntactic matching (e.g., "INV-101" vs "INV101").
  • Bank Ownership Verification: Integration with Plaid Identity Match and Stripe Ownership Match API to verify account holders.
  • Anomaly Detection: Baseline vendor behavior tracking (e.g., 20% price surge vs. historical average).
  • Sanction Screening: Cross-referencing vendors against global AML/sanction lists.

6.3 Risk Scoring & Explainability

  • Scoring (0-100): A unified score where >80 triggers an automatic block.
  • Reason Code Taxonomy: Categorized codes (Identity, Behavioral, Transactional) with weighted impact scores.
  • Explainable AI (XAI): Natural language justification for the score (e.g., "95% line-item similarity with Invoice #882").

7. Technical Requirements

7.1 Core Tech Stack (2026 Standards)

  • Frontend: Next.js 16.1.3 (LTS) with Tailwind CSS. Turbopack enabled for dashboard performance.
  • Backend: FastAPI 0.128.x using Python 3.12+.
  • Validation: Pydantic v3 (Rust-based core) for ultra-fast schema validation.
  • Database: PostgreSQL 18.1 with pgvector 0.8.1 and pgvectorscale.
  • Task Queue: AsyncTasQ (Native asyncio queue) for background behavioral analysis.
  • ML Serving: Models exported to ONNX and served via NVIDIA TensorRT with INT8 quantization.

7.2 Integration Patterns

  • NetSuite: SuiteScript 2.x RESTlets using OAuth 2.0.
  • SAP S/4HANA: SAP Business Technology Platform (BTP) integration via OData v4.
  • Webhooks: Secure webhook notifications with HMAC signatures for async scan results.

8. Data Model

Entity: Invoice

  • id (UUID, Primary Key)
  • vendor_id (FK to Vendor)
  • raw_text (Text)
  • embedding (Vector 1536)
  • amount (Decimal)
  • bank_account_hash (String, encrypted)
  • status (Enum: Pending, Flagged, Approved)

Entity: Vendor

  • id (UUID, Primary Key)
  • tax_id (String, unique)
  • historical_avg_amount (Decimal)
  • verified_bank_accounts (JSONB)
  • last_scan_timestamp (DateTime)

Entity: RiskScan

  • id (UUID)
  • invoice_id (FK)
  • overall_score (Integer 0-100)
  • reason_codes (JSONB: code, impact, description)

9. API Specification (Example Endpoint)

POST /v1/scan

Request Body:

{
  "file_b64": "...",
  "file_type": "application/pdf",
  "metadata": {
    "erp_source": "NetSuite",
    "submitted_by": "user_456"
  }
}

Response Body:

{
  "scan_id": "scan_789",
  "risk_score": 85,
  "decision": "BLOCK",
  "reason_codes": [
    {
      "code": "BANK_MODIFIED",
      "impact": +60,
      "description": "Bank account number for Vendor ABC changed from historical record.",
      "category": "IDENTITY"
    },
    {
      "code": "AMT_OUTLIER",
      "impact": +25,
      "description": "Amount is 3x higher than vendor 6-month average.",
      "category": "TRANSACTIONAL"
    }
  ],
  "extracted_data": {
    "invoice_no": "INV-2026-001",
    "total": 15000.00,
    "currency": "USD"
  }
}

10. UI/UX Requirements

  • Developer Portal: Swagger/Redoc documentation, API key management, and a real-time request/response debugger.
  • HITL Interface: A "Comparison View" showing the current invoice side-by-side with the suspected duplicate or historical vendor baseline.
  • Dashboard: High-level metrics for "Total Value Saved" and "Fraud Trends by Category."

11. Non-Functional Requirements

  • Security: AES-256 encryption at rest. TLS 1.3 in transit. Implementation of Cryptographic Erasure (Crypto-shredding) for PII disposal.
  • Compliance: SOC 2 Type II logging (Immutable audit trails). GDPR "Right to Explanation" support via granular reason codes.
  • Scalability: Auto-scaling AWS Lambda/Fargate clusters to handle end-of-month billing surges.
  • Reliability: 99.99% uptime SLA with Multi-AZ PostgreSQL deployment.

12. Out of Scope

  • Automated payment execution (this is a detection/scoring API only).
  • Consumer-level invoice scanning (B2C).
  • Physical mail scanning/digitization services.

13. Risks & Mitigations

  • Risk: High False Positive Rate during initial deployment.
    • Mitigation: Implement a "Shadow Mode" where the API scores invoices without blocking, allowing for threshold calibration.
  • Risk: Sophisticated "Deepfake" Invoices bypassing OCR.
    • Mitigation: Utilize Multi-modal LLMs (Mistral OCR 3) that analyze layout and logic, not just text.
  • Risk: API Latency from Third-party checks (Plaid/Stripe).
    • Mitigation: Hybrid path—return an initial score based on internal data and update via webhook once third-party verification completes.

14. Implementation Tasks

Phase 1: Project Setup

  • [ ] Initialize FastAPI 0.128.x project with Pydantic v3
  • [ ] Set up Next.js 16.1.3 with Turbopack and Tailwind
  • [ ] Configure PostgreSQL 18.1 with pgvector 0.8.1
  • [ ] Set up Auth0 for API Key and JWT management

Phase 2: Document AI & Extraction

  • [ ] Implement pdfplumber for digital PDF parsing
  • [ ] Integrate DocTR for image/scanned PDF OCR
  • [ ] Build extraction pipeline for line items and bank details
  • [ ] Implement Pydantic models for strict financial data validation

Phase 3: Fraud Engine & Vector Search

  • [ ] Implement hybrid search (Trigram + Vector) for duplicate detection
  • [ ] Configure pgvector iterative index scanning for filtered queries
  • [ ] Integrate Plaid Identity Match Python SDK
  • [ ] Build the Risk Scoring weighted logic engine

Phase 4: Integrations & Async Processing

  • [ ] Set up AsyncTasQ with Redis backend
  • [ ] Build webhook event dispatcher for async scan completion
  • [ ] Implement NetSuite RESTlet boilerplate for pilot clients
  • [ ] Create Stripe Ownership Match webhook handlers

Phase 5: Security & Compliance

  • [ ] Implement AES-256 field-level encryption for PII
  • [ ] Build "Cryptographic Erasure" service for data retention policies
  • [ ] Configure immutable audit logging for SOC 2
  • [ ] Develop AI Explainability log generator for reason codes