Inspiration

Every merchant who takes bookings has lived this: a customer pays, then the venue closes, the instructor gets sick, or the slot is double-booked. Now three systems disagree. The booking says paid. The merchant says cannot fulfill. PayPal says funds held. Resolving it by hand is slow and risky. Refund twice and the merchant loses money. Refund the wrong amount and the customer is shortchanged. Trust a dropped network response and nobody knows whether the refund happened. We wanted a system that makes the safe path the only path: one refund, for the right amount, with proof.

What it does

Encore Recovery is a merchant-side refund-recovery system built on the PayPal Sandbox.

  1. A customer books and pays through PayPal. The capture is verified server-side with a direct read.
  2. The merchant marks the booking unfulfillable, which opens a recovery case.
  3. An AI model reads a server-built snapshot of the booking, policy and payment, and returns a schema-validated diagnosis. It can cite evidence, but it has no field that can carry an amount, a recipient or a URL.
  4. Deterministic eligibility rules build the refund plan. The plan is bound to a fingerprint of the facts it was built from, so any change makes it stale.
  5. The merchant approves. A durable outbox job sends the refund with a stable PayPal-Request-Id.
  6. PayPal responses and signature-verified webhooks are reduced to a final state, and an immutable evidence receipt is sealed.

The UI shows three source-of-truth cards (booking, fulfillment, PayPal) with a mismatch ribbon, so the disagreement is visible at a glance, and an evidence receipt with a replayable event trail at the end.

How we built it

  • Next.js 16 (App Router, TypeScript, Tailwind 4) with route handlers that enforce a session cookie, a CSRF double-submit token, a same-origin check and strict schemas.
  • PayPal Sandbox Orders and Payments APIs for checkout, capture and refunds, plus verified webhooks for refund events.
  • Postgres on Neon with plain pg and ordered SQL migrations (no ORM), because money logic depends on exact transaction behavior. An in-process PGlite fallback lets anyone run the whole system, including the integration tests, with zero credentials.
  • A durable outbox: approving a plan writes the money operation, the audit event and the job in one transaction, before any network call. A crash at any point leaves a recoverable state.
  • Pure reducers for eligibility and refund state, so the hardest logic is unit-tested exhaustively. Completion requires a verified COMPLETED read where amount, currency and invoice id all match.
  • AI SDK via Vercel AI Gateway with structured output, model fallback and a single repair attempt. The model is advisory only.
  • AG Studio custom widgets for the live case queue, recovery preview and evidence receipt.
  • 56 automated tests covering dropped responses, refunds the database never recorded, replayed and out-of-order webhooks, forged signatures, CSRF and origin attacks, and tampered inputs.

Challenges we ran into

  • The lost response problem. If PayPal accepts a refund but the response never arrives, retrying with a new key double-refunds, and giving up leaves the customer unpaid. We model this as a first-class UNKNOWN state that is replayed only with the same request id inside a bounded window, and resolved by a verified read or webhook.
  • Keeping the AI useful but harmless. We removed every field through which a model could influence money, and rebuilt the plan from deterministic rules and verified records.
  • Out-of-order webhooks. A late PENDING event must never move a completed refund backward, so webhooks and direct reads go through the same monotonic reducer.
  • Sandbox realities. A non-US business account triggered a compliance rejection on capture, so we added a US merchant account override and verified a real sandbox capture end to end.

Accomplishments that we're proud of

  • A refund path where double-refund is blocked by construction (one operation per booking, a stable request id, a partial unique index), not by hoping retries behave.
  • Forged webhooks leave no trace in operations, jobs or audit data.
  • A full real PayPal Sandbox capture and refund verified end to end, plus a fixture mode so reviewers can try it with no setup.
  • A repository with architecture docs, a security model and CI, not just a demo.

What we learned

Idempotency is not a header, it is a design. The model should explain, the rules should decide, and the human should approve. And the honest state ("we do not know yet") is better than a confident wrong one.

What's next for Encore Recovery

  • Partial refunds and multi-currency cases
  • Real merchant authentication and multiple workspaces
  • Per-merchant refund policies with versioning and approvals
  • Notifications to the customer when a refund completes
  • Disputes and chargeback awareness in the diagnosis

Built With

Share this project:

Updates

Submission history