Payment Guardian

Payment Guardian is an AI-assisted payment reconciliation and anomaly-review agent for the PayPal Developer Platform (Sandbox). It never moves money.

WHAT IT DOES

• Pulls transactions from the PayPal Sandbox Transaction Search API (OAuth2 client credentials, paged reporting endpoint) and verifies webhooks against the Sandbox notifications API.
• Reconciles them with a merchant ledger by order reference, flagging AMOUNT_MISMATCH, CURRENCY_MISMATCH, DUPLICATE_CAPTURE, ORPHAN_PAYPAL, ORPHAN_LEDGER, REFUND_EXCEEDS_CAPTURE and STATUS_NOT_SETTLED.
• Detects anomalies: robust (MAD-based) amount outliers, per-payer velocity bursts (possible card testing) and round-amount spikes.
• Explains each finding in plain language. A local Qwen model served by Ollama on loopback (no cloud, USD 0) writes the explanation when available; otherwise a deterministic template is used. Each explanation records its source and fallback reason, so a template is never shown as AI output.
• Remediation is never automatic. Findings become proposals (for example HOLD_FOR_REVIEW) that only a named human can approve. Approval produces a simulated record, not a payment.
• Every step is written to an append-only, SHA-256 hash-chained audit log. The verify-audit command detects edits, deletions and reordering.
• Webhook events are deduplicated by event id, and proposals are idempotent per finding.

SAFETY The PayPal client is read/verify-only and refuses any host except api-m.sandbox.paypal.com. Payer identifiers are masked in every report.

EVIDENCE

• Real PayPal Sandbox runs on 2026-10-27 and 2026-10-30 (OAuth 200, Transaction Search 200).
• The 2026-10-30 run produced VELOCITY_BURST and AMOUNT_MISMATCH findings explained by ollama:qwen2.5:1.5b, a human-approved simulated proposal, and a verified audit chain. Artifacts: examples/evidence/sandbox-run-2026-10-30/ in the repository.
• 36 offline tests (synthetic data and a local PayPal mock) pass.

HOW IT WAS BUILT Python 3.10+ with zero third-party dependencies, MIT licensed. It runs end to end with synthetic data and needs no credentials. Sandbox mode needs only Sandbox REST credentials supplied as environment variables.

SUBMISSION PERIOD Developed during the submission period. The public repository was created on 2026-10-30.

NEXT STEPS Additional ledger connectors, live webhook-signature testing against the Sandbox, and a broader evaluation of the local model's explanations.

Built With

• ollama
• paypal
• python
• qwen