VeriPay

Agentic commerce for software contracts: AI audits code deliverables and autonomously executes policy-guarded PayPal milestone payouts.

Comment

💡 Inspiration

The global freelance and digital contractor economy exceeds $1.5 Trillion annually, yet existing freelancing platforms still charge 10% to 20% rake fees primarily to hold escrow and manually referee disputes.

On direct, private B2B contracts, parties face a trust deadlock:

  • Clients fear paying upfront before seeing working code, verified test suites, and documentation.
  • Contractors fear delivering work without guaranteed payment, frequently waiting weeks for manual sign-off.
  • Traditional automated payment tools are blind: they can trigger scheduled payments, but cannot evaluate whether technical deliverables actually satisfy contractual acceptance criteria.

We built VeriPay to bring agentic commerce to real-world software agreements: replacing slow human referees with an autonomous AI verification agent (VeriAgent) coupled directly with PayPal Developer APIs.

🤖 What It Does

VeriPay is an autonomous milestone escrow protocol designed for software contracts. Rather than acting as a passive chatbot that outputs static payment links, VeriPay operates as an active agent that reasons over real-world technical artifacts and commands PayPal rails under strict financial guardrails:

  1. Client Funds Milestone via PayPal Orders v2: The client deposits funds using PayPal Orders v2. VeriPay records the escrow balance and locks conditional release until contractual acceptance criteria are verified.
  2. Contractor Submits Deliverable Evidence: The contractor submits technical artifacts: GitHub pull request URLs, git commit hashes, AST code diffs, and automated unit test runner outputs.
  3. VeriAgent Audits Deliverables: The AI agent analyzes git diffs, verifies test assertions, checks code coverage percentages against contractual thresholds, and confirms OpenAPI documentation, calculating an explainable 0–100% Confidence Score.
  4. Zero-Trust Policy Firewall (Decoupled Financial Guardrails): Before any money moves, the decision passes through a deterministic policy engine:
  5. Tier 1 (Instant Autonomous Payout): Score ≥ 90% and Amount ≤ $500 ceiling → VeriPay autonomously commands the PayPal Payouts API to disburse funds to the contractor's PayPal email in ~2 seconds with zero human intervention.
  6. Tier 2 (Human-in-the-Loop Escalation): Score 70–89% OR Amount > $500 → Release is halted; an itemized audit dossier is generated, prompting the client for 1-click confirmation.
  7. Tier 3 (Remediation Punchlist): Score < 70% → Release is withheld in the vault; the agent issues an actionable remediation punchlist for the contractor.
  8. Automated PayPal Invoicing: Upon release, VeriPay automatically generates an itemized settlement invoice via the PayPal Invoicing API v2, linking the PayPal Transaction Reference (TX-PAYPAL...), Payout Batch ID, and audit score for accounting reconciliation.
  9. Enterprise AG Grid Ledger: An interactive matrix powered by AG Grid with real-time status chips, AI confidence meters, and CSV audit exports.
  10. Developer Telemetry Console: A dedicated Sandbox Console inspecting raw HTTP request/response payloads conforming to PayPal's REST specifications and monitoring real PayPal webhook event streams.

🛠 How We Built It

  • Payment Rails (Dual PayPal Architecture):
  • PayPal Orders v2 API (/v2/checkout/orders): Inbound milestone funding and balance capture.
  • PayPal Payouts REST API (/v1/payments/payouts): Autonomous contractor disbursements with deterministic, unique sender_batch_id values derived from milestone IDs to guarantee 30-day payout idempotency and prevent double-disbursement.
  • PayPal Invoicing API v2 (/v2/invoicing/invoices): Automated tax-compliant settlement receipts.
  • PayPal Webhooks Engine (/api/paypal/webhook): Asynchronous event processing for PAYMENT.CAPTURE.COMPLETED and PAYMENT.PAYOUTS-ITEM. SUCCEEDED.
  • AI Reasoning Engine (VeriAgent): Dual-engine architecture combining Google Gemini 1.5 Flash structured JSON reasoning with a deterministic AST/test-log heuristic evaluator for zero-latency, rate-limit-proof audits.
  • Frontend & UI: Next.js 14 (App Router), React 18, TypeScript, Tailwind CSS, Lucide Icons, and AG Grid Community (ag-grid-react v32).
  • Automated Quality Gates: Vitest test suite (tests/policy.test.ts) validating all three policy firewall boundary conditions in 500ms.
  • Deployment & Containerization: Dockerfile and Render Blueprint (render.yaml).

⚡ Challenges We Ran Into

  1. Preventing Double Disbursements: In automated financial loops, accidental retry storms or duplicate agent executions could drain escrow. We solved this by generating deterministic, SHA-256 derived idempotency keys (sender_batch_id = VP-BATCH-{contractId}-{milestoneId}) mapped strictly to PayPal's 30-day deduplication window.
  2. Decoupling AI Reasoning from Money Movement: Autonomous LLMs can suffer from hallucination or prompt injection. We established a strict architectural boundary: VeriAgent only outputs confidence scores and criteria analyses; an immutable, deterministic Policy Firewall holds the exclusive cryptographic credentials to trigger PayPal Payouts.
  3. Clean-Room Judge Reproducibility: Hackathon judges often run code without pre-configured sandbox keys. We engineered a transparent dual-mode simulator: the app runs with full functionality out of the box (🟡 PayPal Simulator: DEMO MODE), while seamlessly making live REST calls (🟢 PayPal Sandbox: LIVE API CALLS) as soon as sandbox credentials are provided in .env.local.

🏆 Accomplishments That We're Proud Of

  • True Agentic Commerce: Moving beyond simple "chatbot payment links" into autonomous evidence evaluation and policy-gated payment execution.
  • Deep 3-API PayPal Integration: Implementing the complete financial lifecycle: Inbound (Orders v2) → Autonomous Outbound (Payouts) → Accounting (Invoicing v2) → Telemetry (Webhooks).
  • Robust Test Coverage: 100% passing automated test suite for all policy firewall tiers running in under 500ms.
  • Production Polish: Enterprise AG Grid analytics, interactive dossier modals, and live developer telemetry console.

📚 What We Learned

  • How to design idempotent payment architectures that allow autonomous AI agents to interact safely with real financial rails.
  • Best practices for structured JSON outputs with Gemini 1.5 Flash and deterministic AST code diff evaluation.
  • The power of combining PayPal Orders v2 for inbound escrow with PayPal Payouts for instant outbound settlement.

🚀 What's Next for VeriPay

  • Multi-Signature Agentic Dispute Mediation: Allowing client agents and contractor agents to counter-propose punchlist revisions autonomously.
  • Cross-Chain & Fiat Multi-Currency Rails: Expanding PayPal's global currency support with automated FX hedging for international development teams.
  • GitHub Action & GitLab CI Native Integrations: Automatically triggering VeriAgent verification directly on pull request merge events.

Built With

Share this project:

Updates

Submission history