Circlepay AI

Inspiration

Family and community savings circles—often called esusu, susu, or rotating savings groups—help people save and support one another. But they often depend on memory, chat messages, and manual records. Members can forget contributions, misunderstand due dates, or lose confidence in who is next to receive a payout.

CirclePay AI was inspired by the need to make these circles clearer, more accountable, and easier to coordinate.

What it does

CirclePay AI is a savings-circle coordination prototype with an AI-powered Treasurer.

An organizer can create a contribution cycle, and the application creates one pending contribution obligation for each active member. The system prevents duplicate cycles and duplicate contribution records. The organizer can filter the ledger by cycle, view pending and paid contribution records, and ask the AI Treasurer questions about the current ledger.

The AI Treasurer is read-only. It uses real data loaded from the server-side PostgreSQL database and explains the group’s current status in plain language. It cannot move money, mark contributions paid by itself, or invent financial facts.

For payments, CirclePay AI demonstrates a PayPal Sandbox checkout flow. The server creates a PayPal order, redirects the member to PayPal for approval, and captures the approved order server-side. Only then is the matching contribution reconciled as PAID in the ledger.

How we built it

CirclePay AI is built with Next.js, React, TypeScript, Tailwind CSS, Drizzle ORM, and PostgreSQL.

The backend uses Next.js API routes to handle circle creation, member management, cycle generation, ledger retrieval, authentication, AI explanations, and PayPal Sandbox payments. Contribution records are stored in PostgreSQL with amounts retained as decimal strings to avoid floating-point financial calculations.

The AI Treasurer uses Google Gemini through the Google AI Studio API. The server loads a limited, read-only ledger snapshot from PostgreSQL and sends it to Gemini with strict instructions. Common questions, such as pending or paid record counts, are answered directly from verified server data to keep the experience fast.

The PayPal integration uses PayPal’s Orders v2 REST API in the Sandbox environment. The browser sends only a contribution identifier. The server loads the authoritative amount and currency from PostgreSQL, creates the PayPal order, redirects the member to PayPal for approval, and captures the approved order before updating the ledger.

Challenges we ran into

• Designing duplicate-safe cycle generation so repeated requests could not create duplicate contribution obligations.
• Handling existing cycles correctly: the same cycle number and due date should return existing records, while a changed due date should return a conflict.
• Keeping financial data trustworthy by loading amounts and currencies from the database rather than accepting them from the browser.
• Making the AI useful without allowing it to invent financial facts or move money.
• Reducing AI response time for a short demo by using a focused ledger snapshot, shorter outputs, and instant server-calculated answers for common questions.
• Handling PostgreSQL connection stability in a serverless-style Next.js environment by using connection pooling and reusable database clients.
• Learning that NGN is not currently supported as a PayPal payment currency, so the PayPal Sandbox demonstration uses a separate USD test circle while the Nigerian family circle remains an NGN ledger example.
• Understanding that pooled-funds collection and redistribution would require PayPal approval, account eligibility, and compliance review before production use.

What we learned

• A payment status shown in an app is not the same as an independently verified settlement.
• AI is most valuable in financial products when it is grounded in server-loaded data and has no ability to perform unsafe actions.
• Idempotency, authorization, and clear status labels are essential for financial workflows.
• PayPal Sandbox is useful for demonstrating integration, but Sandbox success does not automatically mean a product is approved for real-money pooled-funds operations.
• A smaller, reliable, transparent product is more compelling than a large demo with unverified claims.
• Next-Js gives you frontend and backend in one project, Typescript reduces bugs, Drizzle and the Gemini SDK handles the core future. -Drizzle configuration requires the dialect, schema path and database correction details -It is necessary to differentiate between env.local and env.example, for env.local you will insert your real secrets, but you are not to push it to github, while for the env.example you won't insert your secrets. -Reusing one connection prevents too many open database connections. -Drizzle supports conflict-aware and composite unique constraints. -Smaller context windows can reduce latency and MaxOutputTokens limit generated response length -I learnt about ctrl + F, is to find a code or some line of codes, for instance if you want to debug. -Lastly, i learnt when you add this line "channel_binding=require" to your connection string beside your Database_URL, can sometimes increase the latency of the web/app.

What’s next

With more time, we would add full role-based authorization, verified PayPal webhooks, payout planning controls, rotation visualization, and clearer member-facing payment status explanations. Production money movement would remain subject to PayPal approval and applicable compliance requirements.

Built With

• ai
• drizzle-orm
• google-ai-studio
• google-gemini
• nextjs
• node.js
• paypal
• paypal-orders-api
• paypal-sandbox
• postgresql
• react
• tailwindcss
• typescript
• vercel