ReliefPay: Agentic Relief Finance

AI-assisted disaster relief on PayPal: donors fund campaigns with PayPal Checkout, an AI agent drafts payouts to verified families, and only a human with an authorization code can release the money.

Comment

Inspiration

After floods and landslides, relief organizations collect money quickly but struggle to pay families quickly and traceably. Spreadsheets, manual bank transfers and unclear approvals slow everything down, and donors rarely see where their money went. We wanted one place where donations come in, verified beneficiaries get paid, and every step is on record. We also wanted AI to do the tedious work without ever being able to move money on its own.

What it does

ReliefPay is a relief-finance platform with six roles: Admin, Reviewer, Beneficiary, Donor, Volunteer and Auditor.

  • Donate with PayPal. Donors give with PayPal Checkout built on the PayPal JavaScript SDK v6. The server creates and captures a PayPal order, and the campaign's progress bar updates from the captured amount.
  • Split one donation across several causes. A donor can split one PayPal payment across 2 to 10 campaigns in a single order. An AI "Suggest a split" button proposes percentages. The donor edits them and approves.
  • AI Command Centre. An admin asks questions such as "Which campaigns have the least funds available?" or "Draft a payout batch for approved applications in cmp-01". The agent calls tools that read live campaign, application, donation and payout data, answers with tables, and can draft a payout batch.
  • Human-authorized PayPal Payouts. On the Payment Agent page, the admin ticks which beneficiaries to pay and enters an authorization code that the server checks. Only the ticked people are paid through PayPal Payouts. Unticked people go back to the queue for a later batch. The AI has no tool that releases money, and this is enforced in code, not just in the prompt.
  • Webhooks keep everything in sync. PayPal webhooks are signature-verified, then update donations, payouts and refunds. Duplicate events are ignored.
  • Refunds. Admins can refund a donation through PayPal. Refunds and reversals lower the campaign total exactly once.
  • Analytics dashboard (AG Studio). An admin analytics page shows campaign progress, funded rate, net donations, donor and payout data, and a donations and refunds panel. A floating AI Assistant button opens an assistant that answers questions about the data.
  • Tax receipt PDFs. Donors download a PDF receipt for each donation from their dashboard.
  • Full audit trail. Every login, donation, AI conversation, tool call, payout draft, release, failed authorization and webhook is written to an audit log that the Auditor role can read.
  • Launch campaigns Admins create new relief campaigns from the dashboard. The server saves the campaign and records it in the audit log.
  • Every role has working tools Volunteers start tasks, upload evidence, add notes and mark tasks complete. Auditors view and export reports. Every button on every page does something.
  • In Full audit trail, add "refunds" and "campaign creation" to the list of logged events.
  • Every role works on real data. Beneficiaries register, apply to a campaign with a PayPal payout email, and see the reviewer's decision on their dashboard. Reviewers review AI findings and save their decisions. Volunteers record field checks with notes and evidence, and the server refuses to complete a task without evidence. A relief map shows each role only what it is allowed to see.

How we built it

  • Frontend: React 18, Vite, Tailwind CSS, React Router, the PayPal JavaScript SDK v6 (paypal-payments component, and one-time payment sessions, with v5 Buttons as a fallback) and jsPDF for receipts.
  • Backend: Node.js and Express 5 with SQLite. It has JWT authentication with hashed passwords, role checks on every route, and a small PayPal REST client built on fetch (OAuth client credentials, Orders v2, Payouts v1, refunds, webhook signature verification).
  • AI:
    • Groq with openai/gpt-oss-120b runs the AI Command Centre tool loop and the split suggestions.
    • Amazon Bedrock (Nova 2 Lite) runs the AG Studio assistant through a server-side proxy.
  • Hosting: Render, with a Blueprint (render.yaml) that builds the frontend and serves it from the API as one service.
  • AWS: a CloudFormation template creates a dedicated IAM user that can only call Nova 2 Lite.
  • Testing: 145 automated backend tests with PayPal, Groq and Bedrock faked, plus Playwright end-to-end runs against the live site and a local run with real sandbox calls.
  • Docs: a draw.io architecture diagram, an API reference, an end-to-end test report and a public Postman collection.
  • Developer tooling: we used Kiro as an AI coding assistant to plan, write, test and review the code and documentation.

Challenges we ran into

  • Moving to SDK v6. v6 loads a core script, creates an SDK instance, and starts a payment session when the button is clicked. The session must start in the same click, before any await, or the browser blocks the PayPal popup. We pass it the server's order promise instead of awaiting it, and we kept v5 Buttons as a fallback so donations never break.
  • Payouts and sandbox account setup. Our first sandbox business account returned PAYOUT_NOT_AVAILABLE because of its country, so we created a US sandbox business account. We then hit SELF_PAY_NOT_ALLOWED, from paying the sender's own account, and RECEIVER_UNREGISTERED, from using a non-sandbox email. After those fixes, a payout reached a sandbox personal account with SUCCESS.
  • Webhooks need a public URL. Webhooks only worked after deploying to Render and registering that URL with PayPal. For local runs we added a "Refresh status from PayPal" action.
  • A double-payout risk. Code review found that after a failed release, the same beneficiaries could be drafted into a second batch and paid twice. A failed batch now keeps holding its applications, and a retry reuses the same PayPal sender_batch_id.
  • A duplicate batch ID after a database reset. Render's free plan re-seeds the database, so a re-seeded batch reused an ID PayPal had already processed. Each first release now gets a unique PayPal batch ID.
  • AI rate limits. Every chat model on our free Groq account is capped at 8,000 tokens per minute, and one AG Studio assistant turn sends about 7,000 tokens. We moved only that assistant to Amazon Bedrock and kept Groq for everything else.
  • Keeping the AI safe around money. The agent can read data and draft batches. Releasing money requires a separate, human-only, server-checked step.
  • The AG Studio assistant sent invalid queries. Nova 2 Lite kept failing with "Could not run the query: Expected an object" because our proxy dropped the type information from nested parts of the tool schema. We fixed the proxy so it keeps those types, and the assistant now answers with no query errors.

Accomplishments that we're proud of

  • An end-to-end PayPal sandbox flow on the live deployment: a donation captured, and the PAYMENT.CAPTURE.COMPLETED webhook verified and recorded in the audit log about 18 seconds later.
  • Choosing who gets paid: an admin unticked one of two beneficiaries, and PayPal paid only the ticked person with SUCCESS. The other application stayed available for a later batch.
  • Split donations: one PayPal order with one purchase unit per campaign.
  • An AI agent that is useful but structurally unable to move money.
  • Two AI providers, each used where it fits.
  • 145 passing backend tests, a full audit log, and a public Postman collection judges can run.
  • Single and split donations run on PayPal JavaScript SDK v6, with PayPal checkout opening on orders our server creates.
  • A 49-check end-to-end browser test across all six roles, with every check passing.

What we learned

  • PayPal sandbox setup details matter as much as code: account country, separate sender and receiver accounts, and webhook IDs tied to a specific app.
  • PayPal's v6 SDK separates loading, eligibility and the payment session, which gave us clearer control over when the PayPal window opens and what happens on approve, cancel or error.
  • Signature-verified, idempotent webhooks are the reliable way to keep payment state correct.
  • For agentic finance, safety has to live in code, as tools the model simply doesn't have, rather than in prompt instructions.
  • Picking the AI provider per feature (Groq for fast chat, Bedrock for long-context dashboard turns) works better than forcing one provider everywhere.

What's next for ReliefPay

  • A persistent database. On Render's free plan, the SQLite data resets on redeploy.
  • Recurring monthly donations with PayPal Subscriptions.
  • Pay Later through the v6 SDK.
  • Real file uploads for evidence and documents.
  • Accessibility improvements and multi-language support, such as Hindi.
  • Read-only PayPal transaction reconciliation for auditors.

Built With

  • ag-grid
  • ag-studio
  • agentic-ai
  • ai-agents
  • amazon-bedrock
  • amazon-nova
  • express.js
  • fintech
  • gpt-oss
  • groq
  • node.js
  • paypal
  • paypal-checkout
  • paypal-js-sdk
  • paypal-orders-api
  • paypal-payouts
  • paypal-sandbox
  • paypal-webhooks
  • postman
  • react
  • render
  • social-impact
  • sqlite
  • tailwindcss
  • vite
Share this project:

Updates

Submission history