Inspiration

A failed payment is usually a customer who wanted to pay. A card bounces for a soft reason, a subscription renewal hits an expired card, and most merchants never hear from that customer again. Stripe merchants have had Smart Retries and a whole category of dunning tools for years. PayPal merchants have almost nothing.

The obvious fix today is "put an AI agent on it," and that's exactly why fintech teams don't. Language models hallucinate. A hallucinated retry breaks card-network rules, a hallucinated message promises a discount nobody authorised, and a message sent at 2 a.m. breaks contact rules. So I set myself one constraint before writing any code:

The model proposes. Deterministic code disposes. Nobody is ever charged.

What it does

When a PayPal payment fails, Vesper opens a case and moves it through five steps, and the UI labels who acts at each one:

  1. Failed (PayPal): the failure arrives from a checkout decline or a webhook.
  2. Diagnosed (Claude): plain-English cause and customer context.
  3. Proposed (Claude): exactly one of four actions, plus a message template in the customer's language.
  4. Checked (code): eight rules run before anything reaches the customer.
  5. Recovered (customer): they pay a PayPal invoice, and a signed webhook closes the loop.

The model's whole output space is

$$ \mathcal{A} = {\texttt{SEND_INVOICE},\ \texttt{WAIT},\ \texttt{ESCALATE},\ \texttt{NONE}} $$

and its schemas contain no numeric fields at all. Every amount $a$ on an invoice is read from the case record PayPal created, so no model output can change it. The model writes words around slots like {amount} and {due_date}, and code fills them in. The demo shows this in Spanish and Hindi.

How I built it

  • API: FastAPI with Pydantic v2, SQLAlchemy and Alembic, Postgres 17 on Render.
  • Web: Next.js 15 and Tailwind. A server-side proxy holds the dashboard token, so the browser never sees it.
  • PayPal: Orders v2, using the sandbox negative-testing header to force a real INSTRUMENT_DECLINED; Invoicing v2 as the only customer-facing channel; Webhooks verified with verify-webhook-signature against the raw request bytes and de-duplicated by event id.
  • Claude: exactly two calls per case, using structured JSON output and validated by Pydantic with one retry. A second failure escalates the case to a person.

The rules are pure functions. Each returns a verdict $v_i \in {\text{allow}, \text{defer}, \text{approve}, \text{refuse}}$, all eight always run, and the final outcome is the most restrictive:

$$ \text{outcome} = \max_{\preceq}\,(v_1, \dots, v_8), \qquad \text{allow} \prec \text{defer} \prec \text{approve} \prec \text{refuse} $$

A few of them, written out:

  • Contact window: send only if $9 \le h_{\text{local}}(t) < 20$ in the customer's time zone, otherwise defer to the next 09:00 local. In the video, it's 03:20 in Austin, so Alex's invoice waits.
  • Frequency cap: allow only if $n_{\text{case}} < 2$ and $n_{30\text{d}} < 3$.
  • Approval threshold: if $a \ge \theta$ with $\theta = \$500$, a person decides. Approving re-runs the timing and limit checks, and a double click can't send twice.
  • Hard failures: decided from PayPal's error code, never from the model's opinion. A model that calls a hard decline "soft" changes a sentence on screen and nothing else.

Every guarantee is a test: 124 tests, run in CI on SQLite and on Postgres 17. A checksum on the security-invariant table fails the build if any of those tests is renamed or deleted.

Challenges I ran into

  • My sandbox buyer was in India. The first real invoice failed with INR_FOREIGN_CURRENCY_BLOCKED, because PayPal won't invoice recipients in India. The fix was a US sandbox buyer, and the code had already done the right thing: no retry, case held, reason recorded.
  • Simulated webhooks reuse one event id per type. Vesper's de-duplication correctly dropped every repeat, so the "Fail a payment" button only ever worked once. Loosening a security invariant for a demo felt wrong, so the button now seeds the case directly. Everything after the failure is still live: Claude, the rules, the PayPal invoice and the payment webhook.
  • Signature verification needs the exact bytes. Re-serialising the JSON can change what PayPal signed, so the raw body is spliced into the verification request byte for byte.
  • SQLite hid a real bug. Approve and decline locked the case row with FOR UPDATE across an outer join, which Postgres rejects. Every approval would have returned a 500 in production. Running the full suite on Postgres caught it before judges did.
  • Flaky builds. Fetching the font at build time failed about one clean build in three, so the font is now bundled.
  • My own shortcuts. I once pushed with a failing invariant test, because a pipeline checked tail's exit code instead of pytest's. The end-to-end script also imported the one module allowed to capture payments. I kept the invariant and redesigned the script instead.
  • The model guessed pronouns from names. Both prompts now say to use the customer's first name or "they".
  • Explaining without drowning. The first UI explained everything everywhere and put a tick on every rule. The trimmed version said too little. The version that worked gives one plain sentence per step, lists only the rules that stepped in (with their reasons), and folds the rest into "7 other rules allowed it · see why".

What I learned

  • A safety story is only as strong as the tests that enforce it. The invariant tests caught my shortcuts more often than anything else.
  • Let the model write words, never values. Slot templates plus validation (approved placeholders only, no digits, no links, no promises, correct language) made the AI part both useful and boring to audit.
  • Test on the database you deploy to, and verify every platform detail against the live API rather than memory.
  • Free hosting has real consequences. A queued invoice never went out because the free instance was asleep at 09:00, which is why I'd run the API on a paid instance for real use.

What's next

  • Retry transient sends. While recording the demo, one PayPal sandbox call failed transiently during an invoice send, and the case stayed in Checked without saying why. A retry worked. It should retry with backoff, and record the failure on the case's timeline when it gives up.
  • The PayPal Agent Toolkit as read-only context inside the proposal step, behind an allowlist checked at startup.
  • Abandoned-checkout detection.
  • More languages for the fallback templates.
  • A live mode, but only as a separate, reviewed change, never a config flip.

Built With

Share this project:

Updates

Submission history