What PayVault does
PayVault is a payment reconciliation and exception-investigation workspace with a local AI copilot. It integrates the PayPal sandbox (Orders v2) for server-side order creation and capture, and reconciles payments against ledger and settlement records with penny-perfect, deterministic integer arithmetic - flagging exceptions and turning them into investigation cases the copilot explains with cited evidence.
Why
Reconciliation teams live in spreadsheets: amounts, fees, taxes, refunds, and payouts rarely line up cleanly, and finding out why an exception happened is slow, manual detective work.
How it works
- PayPal sandbox integration (Orders v2): server-side order creation and capture with server-controlled pricing and idempotent persistence. A webhook receiver verifies event signatures through PayPal's official
/v1/notifications/verify-webhook-signatureAPI, with deduplication and out-of-order event handling. - Deterministic reconciliation engine: integer-minor-unit arithmetic, idempotent captures (double-submits can't double-book), and an audit trail. Because payment sandboxes don't execute real bank settlements, the settlement side is a clearly labeled simulation layer.
- Local AI copilot: a local open-weight model (Qwen 2.5 via Ollama) plus a scikit-learn intent classifier (26 investigation intents). The copilot answers operator questions through deterministic tool calls - pulling case financials, calculating variance, citing evidence - and any raw model prose is isolated and labeled as unverified.
- Evaluation mode: a benchmark of 79 synthetic records with 24 injected exceptions, so judges can explore end-to-end.
What was built new for this hackathon
PayVault previously existed with a different payment provider (Razorpay) and a dormant local-AI path. During the submission period the old provider integration was removed and replaced with the PayPal sandbox integration (Orders v2 create/capture, webhook receiver with signature verification, idempotent persistence with restart durability), and the Ollama tool-calling copilot layer was built and wired into the investigation chat.
Honest limitations
- Live webhook delivery to a local environment needs a public tunnel; a signed delivery was rejected in testing and is not yet verified, so no working signed webhook is claimed.
- The reconciliation benchmark runs on synthetic, clearly labeled data - not real PayPal settlement reports.
- Small local models produce weak prose on their own; PayVault mitigates this by having the deterministic evidence layer own every number.
Notes
- Real sandbox checkout requires your own PayPal sandbox credentials; the synthetic benchmark mode runs with zero credentials.
- MIT licensed.
