Inspiration
Freelancers and independent contractors face a frustrating bookkeeping problem: the amount invoiced to a client is rarely the exact amount that settles into their bank account or PayPal balance.
Consider a practical example under standard commercial processing rates (such as PayPal's illustrative US rate of 3.49% + $0.49):
- You invoice an international client for $1,200.00.
- The client pays the $1,200.00 invoice in full.
- PayPal automatically deducts its commercial processing fee:
- $1,200.00 × 0.0349 = $41.88
- $41.88 + $0.49 = $42.37
- The net proceeds deposited into your settlement balance are:
- $1,200.00 - $42.37 = $1,157.63
When accounting software or manual spreadsheets look strictly for an incoming deposit of $1,200.00, the match fails. The invoice sits open as "unpaid," while an unallocated $1,157.63 deposit floats in the bank feed.
The problem quickly compounds in real-world freelancing:
- Dynamic Fee Schedules: Processing fees vary significantly based on payment method, currency, and jurisdiction (for example, PayPal India international commercial payments start at 4.40% plus a fixed currency fee, compared to domestic US rates).
- Milestone Partial Payments: A client might split a $1,200.00 invoice into two $600.00 payments across different dates.
- Payer Identity Mismatches: Payments often originate from a founder’s personal PayPal account rather than the corporate business name listed on the invoice.
We built PayClear to bridge this gap: pairing deterministic financial matching with generative AI to make settlement discrepancies transparent, explainable, and effortless to reconcile.
What it does
PayClear separates payment recognition from settlement reconciliation through six core capabilities:
- Deterministic Gross vs. Net Reconciliation: Instead of trying to match net bank deposits directly to invoice totals, PayClear matches the client's gross payment against the invoice's outstanding balance, while booking the gateway fee deduction as an explicit, deductible operating expense.
- Heuristic Four-Tier Matching Engine: Incoming payments pass through a structured rule cascade that assigns a heuristic confidence score:
- Rule 1 (Score: 0.99 — Exact Reference): Direct regex identification of an invoice number whole-token within the transaction note or memo.
- Rule 2 (Score: 0.95 — Exact Identity & Balance): Case-insensitive customer email match where the gross transaction amount equals the invoice's outstanding balance.
- Rule 3 (Score: 0.90 — Fee-Adjusted Nominal Match): Verified payer name match where the gross transaction amount equals the outstanding balance.
- Rule 4 (Score: 0.75 — Partial Milestone Match): Verified payer identity where the gross payment is less than the remaining balance, indicating an incremental settlement.
- Natural-Language Discrepancy Explanations: For every proposed match, PayClear's integrated AI translates raw ledger numbers into plain English: > "Matched Invoice #INV-2025-001 ($1,200.00). Client Acme Corp paid $1,200.00 gross; PayPal deducted $42.37 in processing fees, yielding $1,157.63 net proceeds."
- Human-in-the-Loop 1-Click Confirmation: The AI never silently alters financial records. Users review match suggestions and confirm or reject them. Confirmations trigger atomic database transactions that update the invoice balance, mark the deposit as reconciled, and return explicit HTTP 409 status on any duplicate attempt.
- Fee Leakage Analytics & Exportable Ledger: PayClear visualizes cumulative gateway deductions over time through a Profit Guard dashboard and provides an exportable CSV reconciliation ledger for tax preparation and external accounting software.
- Scenario Simulator: A built-in 1-click testbed allows judges and users to instantly simulate complex edge cases (fee deductions, milestone payments, and corporate parent name mismatches) without needing manual database setup.
How we built it
- Frontend: Built with React 19 and Vite 8, structured into modular UI components (
MatchQueue,LedgerTables,ProfitGuard,CopilotDrawer,ReconciliationProgress,KpiCards). Styled with Tailwind CSS featuring class-based dual dark/light modes and responsive data tables. - Backend: Powered by a Node.js and Express 5 REST API. Database persistence and migrations are managed using Prisma ORM over SQLite.
- Authentication: Stateless authentication using JSON Web Tokens (JWT) and bcryptjs password hashing.
- Accounting Precision: To eliminate IEEE-754 floating-point rounding errors (e.g.,
0.1 + 0.2 = 0.30000000000000004), all financial figures are calculated and stored in integer minor units (cents). - Outstanding Balance Model: Invoices track cumulative settlements deterministically: $$\text{Outstanding Balance} = \text{Original Invoice Amount} - \sum \text{Valid Applied Gross Payments}$$
- PayPal API & Resilient Adapter:
- Connects to PayPal's standard REST endpoints: OAuth 2.0 token generation (
POST /v1/oauth2/token) and Invoicing v2 draft creation (POST /v2/invoicing/invoices). - Employs a Resilient Sandbox Adapter pattern: When working with personal developer sandbox accounts that lack merchant invoicing permissions (HTTP 403), the engine falls back gracefully to structured simulated identifiers (
INV2-SBX-XXXXXX). This ensures core matching and reconciliation flows remain testable regardless of sandbox account permission constraints.
- Connects to PayPal's standard REST endpoints: OAuth 2.0 token generation (
- AI Engine with Guardrails:
- Dual-provider setup (
aiService.js) using OpenRouter (nvidia/nemotron-3.5-super-vl:free/openrouter/free) with automatic failover to Google Gemini 3.5 Flash REST. - Zero AI Arithmetic: The LLM is restricted from performing math. The Node.js matching engine computes gross amounts, fee deductions, and remaining balances deterministically, providing precomputed figures to the LLM solely for natural-language narration, conversational ledger queries, and payment reminder drafting.
- Dual-provider setup (
Challenges we ran into
- PayPal Sandbox Invoicing Permissions: Calling PayPal’s Invoicing v2 draft endpoint requires a business sandbox account provisioned with specific merchant scopes. Personal developer accounts frequently receive
403 NOT_AUTHORIZED. We resolved this by building an adapter layer that validates live OAuth credentials while falling back to deterministic local sandbox references when permissions are constrained. - Preventing AI Math Hallucinations: Early iterations that asked the LLM to calculate the missing fee frequently produced minor arithmetic errors. We solved this by strictly separating responsibilities: JavaScript handles integer-cent math and rule evaluations, while the LLM acts purely as a narrator and conversational interface.
- Atomic Multi-Table State Updates: Reconciling an invoice requires updating the match status, setting the transaction to reconciled, and reducing the invoice's remaining balance. If any operation fails, the database becomes corrupt. We implemented Prisma's
$transactionAPI with explicit state validations to guarantee that all reconciliation writes succeed or roll back atomically, returning HTTP 409 on duplicate state attempts. - Context Window Management in the AI Copilot: Feeding an entire financial ledger into a prompt quickly exhausts token limits and increases latency. We built a dynamic context aggregator that summarizes KPI cards, filters unreconciled deposits, and formats recent matches into a compact JSON payload before invoking the model.
Accomplishments that we're proud of
- Strict Financial Correctness: Eliminating floating-point errors across the entire stack by enforcing minor-unit integer arithmetic and a mathematically sound balance tracking formula.
- Architectural Separation of Concerns: Establishing a clean boundary where deterministic code makes financial decisions and generative AI explains those decisions to humans.
- 1-Click Scenario Simulator: Providing a practical way to demonstrate real-world edge cases (fee deductions, milestone payments, and entity name mismatches) with zero manual setup.
- Resilient Adapter Implementation: Building fault-tolerant API integration patterns that keep development and demonstrations unblocked during third-party sandbox friction.
- Real-Time Streaming UX: Implementing Server-Sent Events (SSE) for the reconciliation engine, giving users visual progress updates as matching and AI explanations stream in.
What we learned
- Store in Minor Units, Display in Decimals: Using standard floating-point numbers for currency arithmetic is an anti-pattern. Integer-based minor unit representation is essential for reliable financial software.
- LLMs Belong in the Presentation Layer for FinTech: Language models excel at synthesizing context, explaining discrepancies, and answering questions in plain English, but they should never be entrusted with computing financial ledger math.
- Fee Transparency is an Overlooked Problem: Small transaction fees quietly eat into independent business revenue. Making fees visible as explicit, deductible business expenses provides immediate financial clarity.
- Human-in-the-Loop is Critical: Users must always maintain final approval over automated financial actions. Trust in bookkeeping tools depends on giving the user the final word.
What's next for PayClear | AI PayPal Reconciliation Engine
- Production PayPal Webhooks: Implement ingestion for
PAYMENT.CAPTURE.COMPLETEDevents, complete with HMAC-SHA256 signature verification and idempotency keys to prevent duplicate event processing. - Historical CSV Statement Ingestion: Add a statement uploader for users to backfill months of historical transactions instantly without sandbox indexing lag.
- Multi-Gateway Expansion: Extend the heuristic matching engine to reconcile settlements from Stripe, Wise, and raw bank CSV/OFX imports.
- Automated Regional Fee Schedules: Build dynamic fee schedule detection to automatically compare actual gateway deductions against published domestic and international merchant schedules (e.g., US domestic vs. EU vs. India cross-border rates), instantly flagging unexpected fee increases.