Gam'eya: AI-run savings circles on PayPal

Gam'eya runs the savings circle (gam'eya, tanda, susu) on PayPal: AI advises, deterministic code moves the money.
Organiser view: a $600 monthly pot, the payout ring and a schedule set by the fair order.
A fair payout order from members' own needs, explained in their language. Everyone approves before it applies.
10,000-run stress test: completion rises from 27.7% with no reserve to 92.2% with the recommended 9% reserve.
Organiser-only reliability: each member's chance of paying late, with the top 3 reasons. Members never see it.
The Circle Agent sets up a circle from plain words; every AI decision is logged in the audit trail.
A member's view: when the pot comes to them and their own PayPal invoices. No risk data shown.

Inspiration

In Egypt it's called a gam'eya. In Mexico, a tanda; in West Africa, a susu; in India, a chit fund. Hundreds of millions of people save this way: a group of friends each pays a fixed amount every month, and each month one of them takes the whole pot. It's interest-free credit built on trust.

But it runs on WhatsApp and memory. Nobody keeps a ledger, the order is argued over ("who needs it first?"), and when one member pays late or disappears, everyone else pays the price. We wanted to keep what makes a gam'eya work (community, trust, no interest) and give it the tools a bank would have: a fair order, real payment records, follow-up, and safe payouts.

What it does

Gam'eya runs a savings circle end to end on PayPal, with AI helping and humans in control.

Set up by chat. The organiser describes the circle in plain words ("6 friends, $100 a month, starting 1 December"). The Circle Agent fills in a card; when the organiser confirms, it creates a real PayPal catalog product and billing plan. An optional safety reserve becomes the plan's setup fee.
A fair payout order. Each member says what they need the pot for, in English or Egyptian Arabic ("school fees in December", "فرح في مارس"). The Needs Extractor turns that into a category and a date. An optimiser (the Hungarian algorithm) gives each member the slot that best fits their need, and keeps members with a higher chance of paying late out of the earliest slots. The tie-break seed is derived from the circle, so nobody can steer it. Every member approves the order before it applies, and it is locked once money starts moving.
Collection with real invoices. Each cycle, every member gets a real PayPal invoice and pays on PayPal's own payment page. The engine reads the status back from PayPal; only money PayPal actually received counts.
Smart Chase. For anyone still unpaid after a one-day grace period, Smart Chase sends a reminder in the member's language. It can only use allow-listed invoice tools and can never ask for more than the contribution.
One safe payout. When the pot is complete, the engine pays it to that cycle's recipient with PayPal Payouts, exactly once.
Explainable risk, for the organiser only. A reliability model estimates each member's chance of paying late, with the top three reasons. A Monte Carlo stress test (10,000 simulated circles) recommends a safety reserve. For our demo circle, which includes one high-risk member, it shows completion rising from 27% with no reserve to 91% with a 9% reserve. Members never see anyone's score.
A ledger and an audit log. The organiser sees every contribution and payout with its real PayPal id, and every AI decision with the PayPal calls it made.

How we built it

Our golden rule: "AI understands and advises. Deterministic code moves the money. Humans approve anything that changes who gets paid."

Backend: Python 3.11, FastAPI, SQLAlchemy 2, Pydantic 2 and Postgres. Money is always Decimal, rounded to the cent and sent as strings, never floats.
PayPal (sandbox):
- OAuth (a cached, auto-refreshing token);
- Catalog Products and Billing Plans;
- Invoicing v2 (create, send, read status, reminders, QR codes);
- Payouts v1.

Every POST carries a deterministic PayPal-Request-Id, so a retry can never create a second invoice or payout.

Payout safety: before any HTTP call, the engine checks four invariants:
1. the pot is complete;
2. this cycle has not been paid;
3. the recipient has never been paid in this circle;
4. the recipient has an email.

The payout row is written first, with a deterministic sender_batch_id, so even a crash mid-request cannot pay twice.

AI: Google Gemini with a fallback chain across models, plus a deterministic fallback for every feature (rules, regex, templates), so the app works within free-tier quotas and even with no API key. AI text is checked before use: invented numbers or dates, links and contact details are rejected, and member text is wrapped as untrusted input. No AI code can reach Payouts, and a test enforces it.
ML: a logistic-regression reliability model trained on simulated payment histories, with no demographic features, shipped as JSON coefficients. A vectorised NumPy Monte Carlo runs the stress test.
Frontend: React 18, TypeScript, Vite and AG Grid, with plain-text rendering everywhere.
Quality: 864 backend tests (unit, integration and property-based with Hypothesis) and 28 frontend tests. CI runs a secrets scan, ruff, strict mypy, pytest and tsc. Two independent whole-branch code reviews were run before launch, and every finding was fixed with a test that failed first.
Hosting: Docker on Render's free tier (API, static web app and Postgres).

Challenges we ran into

Making money paths impossible to get wrong. Our reviews found real cases where a failed payout could look "sent", where a demo reset made PayPal replay old requests, and where re-approving the order could pay someone twice. We fixed each with deterministic ids, stored recipients and invariants checked before any HTTP call.
PayPal details:
- Invoice numbers are limited to 25 characters and must never repeat.
- Reminder text has to go into the invoice note when it's created.
- A duplicate payout can be reported in more than one error format.
Fairness that people accept. The order has to be optimal and explainable, without revealing anyone's private risk score to other members.
Arabic and English needs, including Egyptian dialect and Arabic-Indic digits.

Accomplishments that we're proud of

A complete circle running on real PayPal sandbox APIs: product, plan, invoices, reminders and payout, with every id visible in the ledger.
No AI path can move money; humans approve the order; every AI decision is audited.
A fair order that is mathematically optimal and seeded so nobody can steer it.
890+ automated tests and two independent reviews before launch.

What we learned

Idempotency and invariants matter more than features when real money is involved.
Deterministic fallbacks make AI features dependable, and keep a demo alive within free-tier quotas.
Explaining a decision ("you get December because your school fees are due then") matters as much as making it.

What's next for Gam'eya

Members subscribe to the billing plan so contributions are collected automatically, with verified webhooks for real-time status. Today members pay by invoice.
Use the safety reserve to cover a missed payment automatically.
Wire up the features that still use demo data: joining a circle, swaps between members, and the Copilot.
Before going to production: a licensed money-transmission partner or PayPal's multiparty flows, KYC, and more currencies.