Cross-Border Reconciliation Agent

An AI agent that reconciles cross-border PayPal payments, explains every decision, and acts inside hard guardrails. Live demo, three-command quickstart, 1:41 video.

Comment

Inspiration

Cross-border sellers get paid through PayPal — and the money rarely matches the invoice. Every mismatch costs an hour of manual spreadsheet work, or a chargeback. Built for the PayPal AI Hackathon: an agent that reconciles, explains, and acts — inside hard guardrails.

What it does

  • Reconciles payments against invoices across currencies (fees, FX, variance) and flags every mismatch: MATCHED / REVIEW / UNMATCHED.
  • Explains every decision in plain English, source labeled via llm or via fallback.
  • Answers questions about the ledger in natural language ("show unmatched payments over $50" → a real grid filter).
  • Negotiates two-agent contracts — buyer and seller haggle inside model-proof budgets and round caps; no action without a settled contract.
  • Acts inside hard guardrails: amount and rate limits, a full append-only audit trail (blocked attempts included), and a human-only red list — refunds, cancellations and dispute acceptance are never exposed to the model.

Live demo (no install): https://paypal-recon-agent.onrender.com Source + three-command quickstart: https://github.com/koztechie/paypal-recon-agent Demo video (1:41): https://youtu.be/7WFiknEULyU

How I built it

  • PayPal: the official PayPal Agent Toolkit over the sandbox — invoicing lifecycle (create, send, reminders incl. automatic, record-payment), orders, transactions, disputes — plus a thin REST client (catalog, billing plans, reporting) and a webhook receiver storing every sandbox event (16 event types observed end-to-end; INVOICE.PAID materializes the payments row the ledger reconciles).
  • AI: Gemini (gemini-3.5-flash-lite) behind a provider-agnostic layer, temperature 0, a 14s budget per call and deterministic rule-based fallbacks everywhere — the product never blocks on the model. AI drives agentic tool calling over whitelisted PayPal operations, payment classification, plain-English explanations, REMIND/WAIT decisions, NL → grid filters, and the two-agent negotiation.
  • UI & data: Next.js + AG Grid / AG Studio, SQLite, TypeScript/Node.
  • Hosting: Render.

Challenges I ran into

  • Money math: cross-currency fees and variance had to be exact — solved with ECB-based FX conversion and explicit zero-decimal currency formatting; every AI money path has a deterministic fallback.
  • Safety vs. autonomy: the model may call PayPal, but never the red-list operations — guardrails live in code, not in the prompt, and every attempt (blocked included) lands in an append-only audit trail.
  • Unreliable edges: strict webhook signature verification plus a self-healing ledger keep the books correct even when events arrive late or malformed.

What I learned

  • For money paths, determinism beats cleverness: a 14s budget plus rule-based fallbacks is more trustworthy than a faster prompt.
  • Guardrails must be enforced where the action happens — in code — and proven by an append-only trail, not promised in prose.

Verified

E2E sandbox cycles (paid → reconciled MATCHED; partial → REVIEW → human resolution), zero-touch agent runs, 5/5 final QA, judge cold-start in 63s, public video audited frame-by-frame. Full audit trail in the repo's evidence/ directory.

Built With

Share this project:

Updates

Submission history