MANDATE- Collections Copilot

The model proposes Code decides. Policy bound finance agent for PayPal invoicing, collection, payouts and dispute defense by deterministic budget rules, human approvals and a SHA256 audit ledger.

Comment

About the Project

The Core Idea: "The Model Proposes. Code Decides."

MANDATE is a deterministic, policy-bound AI financial agent built for merchants, agencies, and cross-border businesses. It connects directly to the PayPal Developer Platform (Invoicing v2, Orders v2, Payouts v1, Disputes v1, and Webhooks) to autonomously draft invoices, schedule intelligent collections, execute split payouts to contractors, and auto-contest chargebacks with carrier delivery proofs.

Unlike traditional "black-box" LLM agents that execute financial operations unchecked, MANDATE introduces a hard architectural separation between intent generation and state execution. Every AI-proposed action passes through a deterministic Python Policy Engine, a human approval queue for high-value transactions, and a tamper-evident SHA-256 hash-chained audit ledger.

Inspiration

Small merchants and software agencies spend hundreds of hours chasing unpaid invoices, calculating manual contractor revenue splits, and defending against unwarranted payment disputes. While modern LLMs are capable of understanding nuanced financial instructions ("Send a 10% early-pay discount to Horizon Labs and split 15% to our contractor once paid"), granting an autonomous LLM raw write-access to business bank accounts or payment gateways is unacceptable without strict guardrails.

We were inspired to build a system where the AI acts as an astute copilot that handles financial reasoning, but where deterministic software guardrails enforce hard spending limits, approval thresholds, quiet-hour compliance, and cryptographic auditability.

How We Built It

  1. Policy-Bound Agent Architecture (Dual-Brain LLM Integration):

    • Built with Google Gemini 2.5 Flash (via strict function-calling schemas) and Anthropic Claude 3.5 Sonnet as fallback orchestration engines.
    • The LLM parses natural-language directives and translates them into structured tool calls against our Tool Registry.

  2. Deterministic Guardrails & Policy Engine:

    • Every agent tool call is intercepted by a policy matrix before hitting external APIs.
    • Guardrails enforce:
      • Auto-approval thresholds: invoices above $\$250$ require human signature.
      • Payout rate limits: maximum $\$500$ per transaction and $\$1,500$ per rolling 24-hour window.
      • Early-pay discount caps: strictly limited to $10\%$.
      • One-click cryptographic Kill Switch that instantaneously blocks all outbound financial operations.

  3. Live PayPal API Integration:

    • Invoicing v2: Generates synchronized invoice drafts, tracks payment states, dispatches reminders, and provides direct payer-view links.
    • Payouts v1: Executes approved split payouts to contractors with idempotent sender batch IDs.
    • Disputes v1 & Carrier Tracking: Evaluates dispute risk and packages verified carrier tracking numbers (FedEx, UPS, USPS, DHL) to increase win probability.
    • Webhooks & Poller Safety Net: Ingests INVOICING.INVOICE.PAID and PAYMENT.CAPTURE.COMPLETED events with HMAC validation and an asynchronous reconciliation worker.

  4. Tamper-Evident SHA-256 Audit Ledger:

    • Every business mutation, policy change, and agent action is recorded as a cryptographically chained block: $$H_i = \text{SHA-256}\left(H_{i-1} \parallel \text{seq} \parallel \text{timestamp} \parallel \text{tenant_id} \parallel \text{event} \parallel \text{payload}\right)$$
    • The hash chain is verifiable in real time via /audit/verify.

  5. Multi-Tenant Personalized Workspace & Financial Q&A Engine:

    • Fast, reactive single-page interface with a responsive glassmorphism dark theme.
    • Multi-tenant workspace isolation with salted PBKDF2 password hashing and instant sample seed data.
    • Ask Your Ledger: Natural-language financial question answering powered by live SQL analytics, computing Days Sales Outstanding: $$\text{DSO} = \left(\frac{\text{Total Accounts Receivable}}{\text{Total Credit Sales}}\right) \times N_{\text{days}}$$
    • Model Context Protocol (MCP) server integration (/mcp/sse) enabling desktop agents like Claude Desktop to interact with the merchant ledger.

What We Learned

  • LLM Function Calling Boundaries: Real-world payment schemas (like PayPal Invoicing v2) require strict type safety and field-level validation (e.g., regex checks on emails, currency code casing, string length boundaries) before payloads reach external gateways.
  • State Machine Resilience: In payment workflows, webhooks can arrive out of order, fail due to network partitions, or duplicate. Designing idempotent state transitions with fallback reconciliation pollers is essential for financial accuracy.
  • Tenant Cryptography: Partitioning hash-chained audit ledgers per tenant requires composite sequencing (tenant_id, seq) to allow independent verification without cross-tenant block collision.

Challenges We Faced

  • Schema Strictness Under Live Sandbox Conditions: Live PayPal Sandbox endpoints reject payload anomalies (e.g., recipient emails missing top-level domains or unformatted decimal strings). We engineered client-side sanitizers and robust backend normalization layers to deliver detailed, actionable error messages.
  • Deterministic Replayability in Tests: Testing asynchronous payment lifecycles and agent reasoning without flaky external API calls required building a dual-mode gateway: a mock provider for zero-network pytest suites and a live sandbox client for staging.
  • Harmonizing Design & Ergonomics: Crafting an interface that balances rich telemetry (aging buckets, cash flow timelines, real-time approval queues) without cluttered visual noise required custom glass surfaces, refined radii, and responsive layout grids.

What's Next for MANDATE

  • Automated Multi-Carrier Proof Webhooks: Real-time integration with shipping carrier webhooks (FedEx, UPS, DHL) to automatically attach delivery signatures the exact millisecond a buyer files an "Item Not Received" PayPal dispute.
  • Dynamic FX Hedging: Automated policy guardrails that propose early-pay settlement discounts when foreign exchange cross-currency volatility exceeds merchant-defined thresholds.
  • Mobile Push Approvals via WebAuthn: Biometric (Face ID / Touch ID) passkey verification for high-value payout and discount approvals directly from mobile devices.
  • Enterprise Accounting ERP Sync: Native bi-directional sync plugins for QuickBooks, Xero, and NetSuite to mirror reconciled ledger entries and SHA-256 audit logs into standard general ledgers.

Built With

Share this project:

Updates

Submission history