Paypilot Ach Returns MCP

PayPilot

An AI dunning agent that recovers failed subscription payments.

[Live demo -> paypilot.fly.dev](https://paypilot.fly.dev/) - try it in the browser, no setup or API key required.

When a recurring charge fails, most of that revenue is recoverable - the customer didn't *decide* to churn, their card just expired or a payment bounced. PayPilot turns each invoice.payment_failed event into a grounded, on-brand recovery action: it diagnoses *why* the payment failed, picks the right retry strategy for that reason, and drafts a warm, one-click dunning email - all in a single API call.

It's built as a small, readable LangGraph agent with retrieval-augmented generation (RAG) over a dunning playbook, exposed through a FastAPI endpoint. The whole thing runs its test suite with no API key and no network.

---

How it works

A failed-payment event flows through a seven-node LangGraph StateGraph. Each node enriches a shared, typed RecoveryState and hands it to the next:

flowchart LR

A[retrieve_context] --> R[assess_risk] R --> B[diagnose_reason] B --> C[choose_strategy] C --> S[schedule_retry] S --> D[draft_message] D --> E[finalize] E --> F([END])

Why RAG?

The recovery quality depends on dunning best-practice - retry timing, tone, when to offer a grace period. Rather than bake that into prompts, PayPilot keeps it in an editable knowledge source (data/playbook.md) that the retriever feeds into the diagnosis and drafting nodes.

Which retriever depends on configuration, and it is worth being precise about this. With OPENAI_API_KEY set, app/ingest.py builds a FAISS index over the playbook using OpenAI embeddings (k=3). With no key - which is how the public demo runs - it falls back to a lexical keyword retriever, so no FAISS index and no embedding call is involved in anything a visitor sees.

And the playbook only changes the output on the LLM path. On the default zero-inference path the committed templates are rendered as-is and retrieved context is not consulted, so editing playbook.md changes nothing until PAYPILOT_LLM_DRAFT=1 is set. Playbook edits are input to the build-time generation step, not to every request.

Why a deterministic strategy node?

choose_strategy is intentionally *not* an LLM call. Retry cadence and the chosen action come from a fixed rules table (app/decision.py) keyed on the failure code, which comes from Stripe, Recharge, Chargebee or Loop:

The LLM writes the *message*; the *policy* stays predictable.

irreversible-reach maps which model-produced values in an agent can reach an action that cannot be undone. Its PayPilot manifest marks sending an email as PayPilot's only irreversible action, with deterministic guards in front of it; remove those guards and it fails. A manifest describes code, it does not test it.

Risk-aware escalation

assess_risk reads the dunning attempt number and the customer's recent payment history (from data/customers.json) and buckets churn risk. When it's high - a third attempt, or a run of recent failures - choose_strategy tightens the retry cadence and marks the strategy escalated, the diagnosis calls out the urgency, and impact discounts the recovery odds for a customer who keeps bouncing. So the agent reasons about *history*, not just the single event in front of it.

---

Quickstart

# 1. Install

python -m venv .venv && source .venv/bin/activate pip install -r requirements.txt

2. Configure (only needed to call the live LLM; tests don't need it)

cp .env.example .env # then add your OPENAI_API_KEY

3. Run the API. PAYPILOT_TENANT=demo serves the bundled demo fixtures (data/customers.json).

PAYPILOT_TENANT=demo uvicorn app.api:app --reload

Call it

curl -s http://localhost:8000/payment-failed \

-H 'Content-Type: application/json' \ -d '{ "customer_id": "cust_001", "amount": 1499.0, "currency": "usd", "failure_code": "card_expired", "attempt": 1 }' | jq

{

"diagnosis": "The card on file for Acme Robotics has expired, so the Scale renewal couldn't be charged; ...", "risk": { "attempt": 1, "prior_failures": 0, "churn_risk": "low", "escalate": false }, "strategy": { "action": "request_card_update", "retry_in_days": 1, "offer": "...", "escalated": false }, "schedule": { "retry_in_days": 1, "next_retry_at": "2026-07-02T09:00:00+00:00", "retry_on": "2026-07-02", "timezone": "UTC" }, "message": "Hello Acme Robotics, we tried to renew your Scale plan but the card we have on file has expired ...", "impact": { "amount_at_risk": 1499.0, "currency": "USD", "recovery_likelihood": 0.7, "expected_recovered": 1049.3, "annual_value_at_risk": 17988.0, "churn_risk": "low" } }

GET /health returns {"status": "ok"} for liveness checks. The full response schema (typed with pydantic) is browsable at /docs.

The endpoint is rate limited per client IP, and the response payload is a typed RecoveryResponse (diagnosis, risk, strategy, schedule, message, impact), so the contract shows up precisely in the OpenAPI docs.

POST /payment-failed/batch runs a whole billing run (up to 50 events) in one call and adds a portfolio aggregate - total at risk, total expected recovered, and how many accounts are high churn risk. GET /portfolio-impact rolls that up across the demo customers and powers the recoverable-revenue headline on the landing page.

Speaks Stripe

Status: no client traffic reaches this deployment, so no merchant's live Stripe delivery has either. The handler is exercised offline by tests/test_stripe.py.

POST /webhooks/stripe accepts a real Stripe invoice.payment_failed event. It verifies the Stripe-Signature header (HMAC-SHA256) when STRIPE_WEBHOOK_SECRET is set, acknowledges other event types with a 200 so Stripe won't retry, maps Stripe decline codes (expired_card, insufficient_funds, ...) to PayPilot's failure codes, and runs the recovery graph. Point a webhook (or stripe trigger invoice.payment_failed) at it; add metadata.paypilot_customer_id to resolve a demo customer.

Speaks Recharge

Status: this deployment carries no client traffic, so no merchant's live Recharge delivery has reached it. The handler is exercised offline by tests/test_recharge.py.

POST /webhooks/recharge accepts Recharge charge/failed and charge/max_retries_reached deliveries for Shopify subscription stores. It checks X-Recharge-Hmac-Sha256 against RECHARGE_CLIENT_SECRET the way Recharge documents it, and maps every one of Recharge's 109 published error types to a PayPilot failure code (the full table). Recharge runs its own retries, so when it will retry, its retry_date is reported as the schedule with source="recharge" and no customer email is drafted (message_suppressed: "recharge_retry_scheduled"). Errors that are not a payment problem the customer can fix (inventory, shipping, tax, test mode) and error types PayPilot does not recognise are acknowledged and not run, so no customer gets an email about them.

A merchant comes on in three steps. They create an API token and copy the API Client Secret from their Recharge admin; the secret goes on the deployment as RECHARGE_CLIENT_SECRET; then RECHARGE_API_TOKEN=... python scripts/recharge_register_webhooks.py --apply registers both webhooks against this deployment (dry run without --apply, and safe to re-run).

The webhook is idempotent on the Stripe event id, so a retried delivery replays the stored result instead of re-running the graph. POST /payment-failed and /batch accept an optional Idempotency-Key header for the same guarantee. Every response carries X-Process-Time and X-Request-ID headers, emits a structured JSON access log, and 429s include Retry-After. GET /metrics (admin token required) returns a JSON snapshot (request counts by status, average latency, recoveries run, total expected recovered). Batches roll up per currency, so a mixed USD/EUR/GBP billing run stays correct (aggregate.by_currency).

For discovery, the app also serves /robots.txt, /sitemap.xml, and an /llms.txt summary for AI answer engines, and the landing page ships SoftwareApplication + FAQPage JSON-LD.

---

The closed recovery loop

PayPilot does not stop at drafting. It records what failed, what it sent, and what happened next, so "we recovered X" is a figure you can audit rather than a claim.

invoice.payment_failed  ->  record  ->  strategy  ->  portal link  ->  email

| invoice.paid / payment_succeeded -> recovered <---------------+ customer.subscription.deleted -> churned

Per-invoice state machine: failed -> messaged -> clicked -> recovered | churned | exhausted. Illegal moves raise rather than silently overwrite, so the dashboard can never contradict revenue it already reported. Amounts are stored in integer minor units with a currency code. Floats appear only at the presentation edge, never in storage or arithmetic.

State only advances to `messaged` on a real send. A dry run, a suppr