PayTrace AI

Catch the payments your app missed. PayTrace AI finds where PayPal and your records disagree, explains why with AI, and lets a person approve the fix safely.

Comment

Inspiration

Every merchant who takes payments online eventually hits the same quiet failure: PayPal captures the money, but the store never records it. A webhook gets lost, the server crashes between capture and saving, or an event arrives late and overwrites newer state. The customer is charged and nothing ships, and usually nobody notices until a support ticket arrives.

We wanted a tool that treats PayPal as the source of truth, catches these gaps automatically, and helps an operator fix them without risking a second mistake, such as a duplicate refund.

What it does

  • Takes real PayPal payments (Sandbox) through PayPal Checkout and the Orders API, and keeps the merchant's own record of each order.
  • Ingests PayPal webhooks safely. Every event is signature-verified through PayPal's API and de-duplicated by event ID. Events are ordered by their resource update_time, so a late event can never move a payment backwards.
  • Reconciles continuously. It compares PayPal's live order state with the merchant's record and opens an incident on any mismatch (state, amount or missing record), with a severity and the money at risk.
  • Investigates with AI. The investigator reads the live PayPal order, the local record, the webhook history and past actions. It returns a root cause with confidence, financial and customer impact, and recommended recovery actions, as schema-validated structured output.
  • Keeps humans in charge. AI and the system can only propose. A different person must approve; refunds need an explicit "this moves money" confirmation; PayPal is re-checked right before anything runs; every step goes into an audit trail.
  • Handles refund timeouts safely. Each refund gets one PayPal-Request-Id and invoice_id at approval, reused on every retry. A timed-out refund becomes "Outcome unknown" and can only be retried with the same ID, so it can never become a duplicate refund.
  • Gives operators an AG Grid console for incidents, transactions, webhook events and recovery actions, with status views and live counts, severity ranking, reconciliation state and an activity feed.

How we built it

  • Next.js 16 + TypeScript, deployed on Railway with a persistent volume.
  • PayPal REST APIs: Orders v2 (create, get, capture), Payments v2 (refunds and refund lookup), Webhooks (verify-webhook-signature), and the PayPal JS SDK for checkout.
  • AG Grid Community as the operations surface: custom renderers for severity, status and reconciliation, numeric money columns, quick filter, pagination, pinned columns and status views.
  • AI: OpenAI or Anthropic Claude behind one provider interface, with a shared Zod schema so either model returns the same validated structure. Webhook payloads are treated as evidence, never as instructions.
  • Safety: atomic claims prevent double execution, refunds are idempotent, the approver passcode is checked in constant time with a brute-force lockout, buyer-data endpoints are gated, and security headers block clickjacking.

Challenges we ran into

  • Uncertain refunds. A refund that times out may still have succeeded, and a naive retry with a new request ID would refund twice. We redesigned refunds around a stored request identity, an UNCERTAIN state, and a PayPal lookup before every retry.
  • Webhook ordering. PayPal doesn't guarantee delivery order. A late CHECKOUT.ORDER.APPROVED after capture must not regress the order, so we combined a status ranking with resource update_time checks.
  • Keeping the AI honest. Early runs blamed the webhook handler for a mismatch we had simulated. Clearer webhook outcomes ("Confirmed" vs "Ignored") and field descriptions let the AI reconstruct the real timeline.

Accomplishments that we're proud of

  • The full loop runs live: real PayPal payment, verified webhook, mismatch detected, AI explanation, human approval, execution, incident resolved, audit trail.
  • Refund recovery that stays safe even when PayPal doesn't answer.
  • An AI that works from structured payment evidence and cannot move money on its own.

What we learned

  • In payments, the hardest bugs are about uncertainty, not errors. Idempotency keys and "we don't know yet" states matter more than happy paths.
  • AI is most useful as an investigator that cites evidence, and safest when every action it suggests still goes through human approval.

What's next for PayTrace AI

  • Webhook backfill from PayPal's event history and scheduled reconciliation.
  • Real user accounts and roles instead of a shared passcode.
  • PostgreSQL storage and multi-merchant support.
  • Disputes and chargebacks as new incident types.

Built With

Share this project:

Updates

Submission history