Inspiration

Nigerian freelancers are often paid in dollars, euros, or pounds through PayPal, then have to guess what will actually land after fees, and what that is worth in Naira. PayPal does not settle in NGN, official receiving fees are easy to misread, and invoices still arrive as messy WhatsApp messages. I wanted a small agent, named Kudi (Hausa for money), that turns that chat into a checkout link and a plain-English take-home figure, built for someone working from Nigeria.

What it does

A freelancer pastes an invoice or a short chat message, for example "Logo design for Sarah, 150 USD, due Friday". The agent reads the client, the work, the amount and currency, and the due date. After a quick review step, it creates a PayPal sandbox checkout link with the Orders v2 API.

It then explains, in plain English:

  • what the client is asked to pay
  • PayPal's official fee for a Nigerian account receiving an international payment
  • what the freelancer would receive in PayPal
  • a mid-market Naira estimate, with the rate time shown in WAT (Africa/Lagos)

If the invoice is in Naira, the checkout is created in USD at the mid-market rate, because PayPal does not settle in NGN. The app says that clearly. Conversion and partner withdrawal fees that may apply later are explained separately, not silently subtracted from the main "you receive" figure.

The hosted demo runs in PayPal sandbox only. No live payments are taken.

How we built it

The app is a FastAPI service with a single-page front end, hosted on Render.

Invoice reading uses an AI model, gpt-oss-120b hosted on Groq. It reads messy chat messages, pulls out the client, work, amount, currency and due date, and handles day-first Nigerian dates like "due Friday" in WAT (Africa/Lagos). If the model is ever unavailable, a rule-based parser takes over, so the app never breaks.

Checkout links come from the PayPal Orders v2 sandbox API. If sandbox keys are missing, the app runs in mock mode so the UI and tests still work. Live or production mode is refused.

Receiving fees are copied from PayPal's official Nigeria seller fee page (https://www.paypal.com/ng/business/paypal-business-fees, last updated 28 October 2026). For a Nigerian account receiving an international commercial payment the official rate is 4.90% plus a fixed fee in the currency received ($0.30 for USD). Mid-market FX uses open.er-api.com, with Frankfurter as a fallback.

Tools used

  • PayPal Orders v2 API (sandbox) for the shareable checkout link
  • Groq (gpt-oss-120b) AI model for reading invoices, with a rule-based backup- FastAPI, Python, and a static front end
  • open.er-api.com and Frankfurter for mid-market FX
  • Render, for hosting the public demo
  • pytest for parser, fee math, FX fallback, mock checkout, and API tests

Challenges we ran into

Official fees had to be taken from the Nigeria seller fee page, not guessed. PayPal does not settle in NGN, so a Naira invoice needs a clear USD conversion path and a disclaimer. Mid-market Naira figures must not be mistaken for a bank credit. The parser also had to work on messy, unlabelled chat text without requiring a paid model, so the demo stays reliable for judges.

Accomplishments

We shipped a working end-to-end prototype: paste an invoice, review the fields, create a real PayPal sandbox checkout, and read a cited fee breakdown plus a Naira estimate. The $150 USD example is charged the official $7.65 receiving fee, so the freelancer would receive $142.35 in PayPal. The project is public, MIT licensed, tested, and hosted on Render.

What's next

A production version would add a freelancer's own PayPal payout settings, a saved client list, and a clearer cash-out path that still keeps official PayPal fees separate from bank or partner charges. I would also like to support more invoice formats and a short history of links sent.

Built With

Share this project:

Updates

Submission history