Inspiration

Inspiration

Small merchants and finance teams reconcile PayPal payments by hand. They compare a CSV or spreadsheet against what PayPal reports, and the usual failures are quiet: a wrong amount, a different currency, a duplicated order ID, or an order that was created but never captured. PayPilot AI makes those checks fast, consistent and explainable.

What it does

  • CSV reconciliation. Upload a file with merchant_reference, paypal_order_id, expected_amount, currency_code. Each row is checked against PayPal Sandbox Orders v2 and classified as matched, amount mismatch, currency mismatch, needs review, order not found, or lookup error.
  • Risk signals. Duplicates within a file and identifiers seen in earlier saved runs are flagged. Both duplicate rows go to "needs review" instead of guessing which one is right.
  • Investigation view. For a single order, PayPilot shows deterministic evidence such as order_created and capture_evidence_missing. It never claims settlement it cannot prove: settlement_verified is always false.
  • Plain-language AI explanation. Each finding gets a short explanation and a recommended next step. The AI never decides the verdict. The deterministic engine does, and the AI only explains it.
  • Saved runs and analytics. Runs are stored in SQLite, with cross-run historical matches and summary analytics.
  • Team access. Owner and employee roles, with no public registration. The owner creates, deactivates and reactivates employee accounts.

How we built it

  • Backend: FastAPI with SQLite persistence.
  • Frontend: Vanilla HTML and JavaScript, no build step.
  • PayPal: Sandbox Orders v2 (OAuth token, GET /v2/checkout/orders/{id}). The app is strictly read-only toward PayPal: it never captures, refunds or modifies anything.
  • AI: OpenRouter first, then Gemini, then a deterministic fallback, so the app still works with no AI key. The AI's structured output is validated before it is shown.
  • Auth and security: scrypt password hashing, hashed session and CSRF tokens, HttpOnly and SameSite=Strict cookies, CSRF header on state-changing routes, login throttling, and role checks on every route.
  • Quality: 280 backend tests and 35 frontend tests, plus ruff, bandit and pip-audit.

Challenges

  • Keeping the AI useful but never authoritative. We split the system into a deterministic verdict and an AI explanation, and we validate the AI's output.
  • Handling duplicates honestly. Flagging both rows as "needs review" is less flashy than picking a winner, but it is correct.
  • Adding real authentication late without weakening any existing test.

Accomplishments

A complete, tested reconciliation workflow that is honest about what it can and cannot verify, with a clean-clone install that passes its full test suite.

What we learned

Trustworthy payment tooling is mostly about refusing to overclaim: saying "needs review" and "capture evidence missing" is more valuable than a confident wrong answer.

What's next

Capture and settlement evidence through PayPal's transaction reporting, scheduled reconciliation runs, CSV templates for common accounting exports, and a hosted deployment once first-owner setup is locked down.

Built With

Share this project:

Updates

Submission history