Homeward

Homeward lets you buy medicine for family in Nigeria from abroad: pay a verified local pharmacy with PayPal, they collect with a one-time code, and you see the moment it's picked up.

Comment

Inspiration

If you grew up in Nigeria and now live abroad, you know the call: "Mummy's BP drugs have finished." What usually happens next is a bank transfer to a sibling, a cousin or a neighbour, and then you wait. Did the money reach them? Did it go on the medicine or on something more urgent? Was the pack real? Nobody is doing anything wrong. Cash just stops being traceable once it leaves your account.

We wanted the money to go straight to the pharmacy that hands over the medicine, and we wanted the person paying to see the moment it was collected. PayPal already handles the hard part: a payer abroad, a merchant account, and a payment you can trace from start to finish. An AI agent handles the other hard part, which is turning a worried "Mum needs her amlodipine, the 5mg one" into an exact order from a real catalog.

What it does

Homeward lets someone abroad pay for medicine for family in Nigeria and see proof that it was collected.

  1. Ask the agent. In chat, the payer says what's needed ("Order Mum's blood-pressure medicine in Enugu"), or uploads a photo of a prescription or medicine pack. The agent reads back only what is written on it and asks the payer to confirm. It never guesses a strength.
  2. The agent finds a verified pharmacy and drafts an order using that pharmacy's catalog prices. It never invents or changes a price.
  3. The payer approves with PayPal. The payment goes directly to the pharmacy's PayPal account as the payee, not to a person and not through Homeward.
  4. The family member collects at the counter with a 6-character pickup code. The pharmacist enters the code, takes a handover photo, and the payer's order page changes to picked up, with a receipt.
  5. If something goes wrong, the payer can cancel before pickup (the code stops working and the pharmacy refunds) or report a problem after pickup (the pharmacy replies with a replacement or a refund).

Beyond one-off orders: monthly refills are drafted automatically, monthly allowances per family member warn you when an order goes over, every order has a live 3D diorama that moves through each stage, and pharmacies get an order ledger built with AG Grid. There's also a map of all 22 WellaHealth partner pharmacies in Enugu State.

How we built it

  • Next.js (App Router) + TypeScript + Tailwind, hosted on Render from a render.yaml Blueprint, with Postgres on Neon through Drizzle.
  • The agent: Claude Sonnet 5.5 through the Vercel AI SDK, with three of our own tools (search_pharmacies, find_partner_pharmacies, draft_order) plus read-only tools from the PayPal Agent Toolkit (get_order, transaction lookup). The agent can draft an order but it can't move money. Only the payer's click on the PayPal button does that.
  • PayPal: Orders v2 with intent: CAPTURE and payee.email_address set to the pharmacy, so each order pays that merchant directly. Capture happens on return, and a verified webhook (CHECKOUT.ORDER.APPROVED, PAYMENT.CAPTURE.COMPLETED, …REFUNDED, …REVERSED) reconciles any order whose return redirect never arrived.
  • Pickup codes come from a 32-character alphabet without look-alike characters (no 0/O, 1/I), and are 6 characters long:

$$|\mathcal{C}| = 32^6 = 2^{30} \approx 1.07 \times 10^9$$

That's plenty for a code that a pharmacist checks by hand against one open order.

  • Allowances are a simple monthly budget per family member. For an order of amount $a$ in month $m$:

$$\text{remaining}m = A - \sum{o \,\in\, \text{paid}_m} a_o, \qquad \text{warn if } a > \text{remaining}_m$$

The payer can still approve. The agent only points it out.

  • 3D: every diorama tile (the order, the home, the pharmacy counter) was modelled and animated in Blender by script, exported to .glb, and rendered with three.js.
  • AG Grid powers the pharmacy ledger and the partner directory, with the chosen pharmacy pinned to the top row.
  • Notifications use a tool-agnostic outgoing webhook (order.paid, order.picked_up, problem.reported, …) that works with n8n, Activepieces or anything else that accepts a JSON POST. A Postman collection documents every PayPal and Homeward call in order.

Challenges we ran into

  • Refunds turned the design upside down. We planned for Homeward to refund cancelled orders. PayPal returned 403 PERMISSION_DENIED, and that's correct: a platform can't refund money it never received. So we redesigned the flow. Cancelling disables the pickup code right away, the pharmacy sends the refund from its own account, and Homeward confirms it by reading the capture status from PayPal instead of trusting a button press.
  • The Agent Toolkit's create_order can't set a payee. Paying the merchant directly was the whole point, so the agent uses the toolkit for reads and our own route creates the order once the payer approves. That limit also gave us a cleaner safety boundary.
  • Model and SDK mismatch. Our AI SDK version always sends temperature, which the model rejects. We wrapped fetch to remove it from the request body.
  • Hosting behind a proxy. On Render, request.url is localhost:10000, so PayPal return URLs pointed nowhere. We now build every redirect and outgoing link from the public origin. Env vars pasted with their quotes also broke the database connection string.
  • Lost redirects. Some payers approve in PayPal and never come back to the return page. The webhook was what fixed it, and its first real delivery recorded exactly that kind of order.
  • Being careful about medicine. The agent must never suggest a dose, a strength or a substitute. Getting it to ask instead of guess, especially when reading prescription photos, took more prompt work than any other feature.

Accomplishments that we're proud of

  • The full loop works on the live site in the PayPal sandbox: chat → PayPal approval → payment to the pharmacy → pickup code → counter confirmation → handover photo → receipt.
  • The money never passes through Homeward. We designed it that way from the start, and it held up even when refunds made it harder.
  • An agent that can read a prescription photo and still refuses to guess.
  • Hand-built Blender dioramas that make "where's my order?" something you can see.

What we learned

  • Put the agent in charge of words and the human in charge of money. Separating "draft" from "approve" made the agent more useful and much easier to trust.
  • PayPal's payee model maps cleanly onto "pay the merchant, not the middleman", but refunds, disputes and permissions follow from who the payee is, so you have to design around that from day one.
  • Webhooks aren't optional. Any flow that relies on the user coming back to a return URL will lose orders.
  • Read the capture status from the source of truth instead of trusting what someone clicked.

What's next for Homeward

  • Instant refunds using authorize-then-capture or PayPal's marketplace permissions, so a cancel refunds right away instead of waiting on the pharmacy.
  • Opening orders to the 22 WellaHealth partner pharmacies, which are listed today but can't take orders yet, and moving pharmacy search onto Elasticsearch with typo tolerance.
  • Pharmacy logins, photo evidence on problem reports, and escalation after the 48-hour window.
  • SMS or WhatsApp delivery of pickup codes to the family member through the notification webhook.
  • Moving beyond medicine to school fees and groceries, paid to verified merchants and never as cash.

Built With

Share this project:

Updates

Submission history