Instant international payments for Nigerian freelancers — powered by Stellar and stablecoins.
AfriPay enables freelancers to receive payments from global clients in minutes, not days, with fees under 1%. Blockchain complexity is completely abstracted — users see invoices, balances, and bank withdrawals, nothing else.
- Traditional payment methods (PayPal, Wise) charge 5–10% fees and take 3–7 days to settle
- Nigerian freelancers lose significant portions of their earnings to fees and exchange rate markups
- Crypto solutions are too complex for non-technical users
- Create invoice → Get a shareable payment link
- Client pays → Card payment converts to USDC on Stellar
- Instant settlement → Funds arrive in 3–5 seconds
- Withdraw to bank → Convert to NGN via Yellow Card, instant bank transfer
- Keep 99%+ → Fees under 1%, zero crypto knowledge required
| Layer | Technology |
|---|---|
| Frontend | Next.js 15 (App Router), React 19, Tailwind CSS v4 |
| Backend | Next.js API Routes, Prisma ORM, PostgreSQL (Neon) |
| Auth | Privy — OAuth + embedded Stellar wallets |
| Blockchain | Stellar Network — USDC stablecoin |
| On-ramp | MoonPay — card → USDC |
| Off-ramp | Yellow Card — USDC → NGN bank transfer |
| Resend | |
| Deployment | Vercel |
- ⚡ 3–5 second settlement with fees < $0.01
- 🏦 Yellow Card integration — direct off-ramp to Nigerian banks in 20+ African countries
- 🌍 475,000+ on/off-ramp access points worldwide
- 🔒 Battle-tested — used by MoneyGram, Onafriq, and major African payment providers
- 💰 Low cost — ~$0.75 per wallet (XLM reserves) vs building custom infrastructure
Client Card Payment
↓
MoonPay (Fiat → USDC on Stellar)
↓
Freelancer's Stellar Wallet (Privy embedded)
↓
Yellow Card API (USDC → NGN)
↓
Nigerian Bank Account
afripay/
├── app/
│ ├── (auth)/ # Login, register, onboarding
│ ├── (dashboard)/ # Authenticated app pages
│ │ ├── dashboard/ # Overview with stats
│ │ ├── invoices/ # Invoice list + create + detail
│ │ ├── withdrawals/ # Withdrawal history + initiate
│ │ └── settings/ # Profile & wallet settings
│ ├── api/
│ │ ├── invoices/ # CRUD
│ │ ├── moonpay/sign/ # Signed widget URL
│ │ ├── webhooks/ # MoonPay + Yellow Card
│ │ ├── withdrawals/ # Initiate + list
│ │ ├── wallet/balance/ # USDC balance
│ │ ├── users/onboard/ # Onboarding
│ │ └── cron/ # Scheduled jobs
│ ├── pay/[token]/ # Public payment page (no auth)
│ └── page.tsx # Landing page
├── components/
│ ├── ui/ # Badge, CopyButton, Toaster
│ ├── dashboard/ # Stats, RecentInvoices
│ ├── sidebar.tsx
│ ├── navbar.tsx
│ ├── payment-widget.tsx
│ └── providers.tsx
├── hooks/
│ ├── use-invoices.ts
│ ├── use-wallet.ts
│ └── use-withdrawals.ts
├── lib/
│ ├── stellar.ts # Stellar SDK helpers
│ ├── moonpay.ts # MoonPay URL signing + webhook verify
│ ├── yellowcard.ts # Yellow Card API client
│ ├── resend.ts # Email templates
│ ├── auth.ts # Privy server-side auth
│ ├── prisma.ts # Prisma singleton
│ └── utils.ts # cn(), formatDate(), formatCurrency()
├── prisma/
│ ├── schema.prisma # Database schema
│ └── seed.ts # Demo data
└── docs/
├── architecture.md # System design
└── api.md # API reference
- Node.js ≥ 20
- PostgreSQL database (Neon free tier works)
- Privy app (free tier)
- MoonPay sandbox account
- Yellow Card sandbox account
- Resend account
# Clone the repo
git clone https://github.com/devUnixx/afripay.git
cd afripay
# Install dependencies
npm install
# Set up environment variables
cp .env.example .env.local
# Edit .env.local with your credentials
# Push database schema
npx prisma db push
# (Optional) Seed demo data
npm run db:seed
# Start development server
npm run devOpen http://localhost:3000.
See .env.example for all required variables. Key ones:
| Variable | Description |
|---|---|
DATABASE_URL |
PostgreSQL connection string |
NEXT_PUBLIC_PRIVY_APP_ID |
Privy app ID |
PRIVY_APP_SECRET |
Privy app secret |
NEXT_PUBLIC_MOONPAY_API_KEY |
MoonPay publishable key |
MOONPAY_SECRET_KEY |
MoonPay secret key |
MOONPAY_WEBHOOK_SECRET |
MoonPay webhook signing secret |
YELLOW_CARD_API_KEY |
Yellow Card API key |
YELLOW_CARD_API_SECRET |
Yellow Card API secret |
RESEND_API_KEY |
Resend API key |
CRON_SECRET |
Secret for cron job authorization |
npm test # Run all tests
npm run test:ci # CI mode with coverage
npm run type-check # TypeScript check
npm run lint # ESLintConfigured in vercel.json and protected by CRON_SECRET.
| Job | Schedule | Description |
|---|---|---|
cancel-overdue-invoices |
0 2 * * * (daily 2AM UTC) |
Cancels PENDING invoices with dueDate > 90 days ago. Skips invoices with active escrow, active dispute, or doNotAutoCancel: true. |
Test locally:
curl -H "Authorization: Bearer YOUR_CRON_SECRET" \
http://localhost:3000/api/cron/cancel-overdue-invoices- Push to GitHub
- Import project in Vercel
- Add all environment variables from
.env.example - Deploy — cron jobs are configured automatically via
vercel.json
After deploying, configure these webhook URLs in your provider dashboards:
| Provider | Webhook URL |
|---|---|
| MoonPay | https://afripay.io/api/webhooks/moonpay |
| Yellow Card | https://afripay.io/api/webhooks/yellowcard |
Contributions are welcome! Please read CONTRIBUTING.md first.
- Fork the repo
- Create a branch:
git checkout -b feat/your-feature - Commit with conventional commits:
feat: add invoice PDF export - Open a pull request
- Architecture — system design and payment flow
- API Reference — all API endpoints
- Contributing — how to contribute
- Security — reporting vulnerabilities
Licensed under the Apache License 2.0.
Built with ❤️ for Nigerian freelancers. Powered by Stellar.