paypal-retrofit lets an AI agent wire PayPal into the system a business already runs on: its own database, its own invoice numbers, its own customers. Then it keeps both sides reconciled, and every action that moves money follows a rule the owner set.
A booking tool, an old invoicing app, a spreadsheet, a homegrown ERP. PayPal's Agent Toolkit lets an AI agent call PayPal, but nothing helps an agent connect PayPal to a system that was never built for it. So invoices get re-typed, payments get marked by hand, and the two sets of books drift apart.
Someone has to learn the PayPal API and write glue code against a schema they didn't design.
Without webhooks wired to the old system, staff reconcile by eye and mark invoices paid manually.
An AI that can call payment APIs directly is one bad prompt away from a refund nobody approved.
The Mapper agent reads the schema and a few masked sample rows, then proposes how customers, services, invoices, line items and recurring agreements become PayPal objects. Every choice comes with a reason. Nothing touches PayPal until you accept.
$ npx paypal-retrofit init --source sqlite:./fernhill.db ◇ Found 5 tables table rows foreign keys customers 12 invoice_items 66 service_id→services, invoice_id→invoices invoices 40 customer_id→customers retainers 4 customer_id→customers services 8 ◇ Claude is mapping your schema to PayPal objects object from detail Customer customers name=full_name, email=email Catalog product services name=name, price=unit_price Invoice invoices number=invoice_no, total=total Invoice items invoice_items via invoice_id Status meaning status open=[overdue,sent,draft] paid=[paid] Send to PayPal status when status in [overdue,sent] Write back invoices paypalId→paypal_invoice_id, … Subscription retainers monthly_fee/month, when [pending] ? Use this mapping? Yes └ Wrote retrofit.config.yaml and retrofit.map.json
sync plans every change, then creates PayPal invoices that keep the business's invoice numbers, emails each customer a pay link, and writes the PayPal id and link back into the columns the mapping allows. Voided invoices are cancelled; invoices paid outside PayPal are recorded so customers aren't asked twice.
When a customer pays, PayPal's webhook is checked with PayPal's own signature verification, stored once, and applied to the legacy record (status, paid date and amount) before PayPal is told it arrived. If a webhook is ever lost, the reconciler finds the payment and repairs it, and flags anything that needs a person.
verify-webhook-signature
Every PayPal write is an action with an idempotency key, a reason a person can read, and the policy that decided it. The agents only ever see read tools and one write tool: propose_action.
PayPal request ids derive from the record and its content hash; one link per legacy record; one application per webhook event.
On every invoice event, retrofit re-reads the invoice from PayPal before writing anything back.
Webhook failures return 500 so PayPal retries; the reconciler is the backstop for anything still missed.
Built with Claude through the official Anthropic SDK. The default model is claude-opus-5-5.
Turns an unfamiliar schema into a typed PayPal mapping with structured outputs.
Works the receivables in plain language, using the SDK tool runner.
Drafts a response when a buyer opens a dispute.
Every side effect, whether it comes from sync, an agent or a button, is an action decided by a policy. The defaults are conservative and can be changed per action in the console.
| Action | Default policy |
|---|---|
| Create, send, update invoices | auto |
| Send reminders | confirm |
| Record a payment made outside PayPal | confirm |
| Cancel an invoice | confirm |
| Refund | confirm |
| Create or cancel a subscription | confirm |
| Accept a dispute claim | never |
Every table is built on AG Grid Community: filters, quick search, bulk selection, custom status cells, CSV export and editable mapping grids. Click any image to enlarge it.
| Area | Used for |
|---|---|
| Invoicing v2 | Create, get, update, send, remind, cancel, record payment, record refund, search |
| Payments v2 | Refunding captured invoice payments |
| Catalog Products, Billing Plans, Subscriptions | Turning recurring agreements such as retainers into PayPal subscriptions |
| Webhooks v1 | Registering the endpoint, signature verification, 15 event types across invoices, captures, subscriptions, sales and disputes |
| Disputes v1 | Listing and reading disputes for the Support agent; accepting claims only if the owner allows it |
| Transaction Search | Fees and transaction history for the Ops agent |
| PayPal Agent Toolkit | The Ops agent's read-only PayPal tools in sandbox and production; writes are deliberately not exposed |
The demo runs Fernhill Studio's legacy app, a local stand-in for the PayPal endpoints and the console in one process.
# Node 20+ with corepack $ git clone https://github.com/Thinkelution/paypal-retrofit.git $ cd paypal-retrofit $ corepack enable && pnpm install && pnpm build $ pnpm retrofit demo --fresh paypal-retrofit demo (mock PayPal, no account needed) Dashboard http://localhost:8787/ Legacy app http://localhost:8787/fernhill # your own system, against the PayPal sandbox $ cp .env.example .env # PayPal sandbox app + ANTHROPIC_API_KEY $ pnpm retrofit init --source postgres://… # or sqlite:… / csv:… $ pnpm retrofit sync --dry-run $ pnpm retrofit serve
paid.Add ANTHROPIC_API_KEY to .env. Without it, mapping uses the deterministic mapper and the agent panel stays off.
A new, open-source project that makes PayPal integration practical for businesses that already have a system, with AI doing the integration work and a deterministic engine doing the money work.
No schema changes, ever. Retrofit reads your tables and writes only to the columns your mapping names, such as a PayPal invoice id or a paid date. If you have no such columns, it keeps the links in its own state store. For CSV sources it writes to sidecar files and leaves the originals untouched.
No. The demo ships with a local stand-in for the PayPal endpoints retrofit uses, with signed webhooks and customer pay pages. To use the real PayPal sandbox, create a free developer app and run the demo with --sandbox.
Only if you let it. Agents can only propose actions; each kind of action has a policy (auto, confirm or never). Refunds, cancellations and reminders wait for your approval by default, and accepting disputes is refused.
Claude through the official Anthropic SDK, defaulting to claude-opus-5-5. You can choose another model with RETROFIT_MODEL.
Not yet. It is built and tested against PayPal's sandbox APIs and refuses production mode unless explicitly enabled. Treat it as a strong starting point, not a finished payments product.
No. paypal-retrofit is an independent open-source project built on PayPal's public APIs and Agent Toolkit. It is not affiliated with or endorsed by PayPal.