A fintech backend API powering payments, wallets, transfers, and bill services.
Kobovault is a production-grade fintech backend built with NestJS. It provides a comprehensive suite of financial services including digital wallets, peer-to-peer transfers, airtime & data purchases, utility bill payments, and TV subscription management — all backed by integrations with leading African payment providers.
- Digital Wallets — Multi-currency wallet creation and balance management
- P2P Transfers — Send money to other users, request transfers, and approve/decline requests
- Deposits & Withdrawals — Fund wallets and withdraw to bank accounts via Paystack and Flutterwave
- Airtime — Purchase airtime for any Nigerian mobile network
- Mobile Data — Buy data bundles across all networks
- Electricity — Pay electricity bills (prepaid & postpaid)
- TV Subscriptions — Subscribe to DStv, GOtv, Startimes, and Showmax
- Education — Purchase WAEC result checker PINs
- Bank Account Linking — Add and verify bank accounts
- Virtual Accounts — Auto-generated Monnify virtual accounts for deposits
- Bank Directory — Fetch the full list of Nigerian banks and verify account details
- Registration & Authentication — JWT-based auth with separate user and admin login flows
- Transaction PIN — Secure transfers with a 4-digit transaction PIN
- KYC Verification — Customer KYC levels for tiered account limits
- Referral System — Unique referral codes and referral tracking
- Role-Based Access Control — Fine-grained permissions via CASL
- Admin Dashboard API — Separate admin endpoints for platform management
- Announcements — In-app announcements for users
- Activity Logging — Per-service activity tracking (airtime, data, electricity, TV)
- Email Notifications — Transactional emails via Nodemailer
- SMS Notifications — OTP and alerts via Twilio
- Health Checks — Built-in health endpoint via
@nestjs/terminus - API Documentation — Auto-generated docs via Compodoc
| Layer | Technology |
|---|---|
| Framework | NestJS 8 (Node.js) |
| Language | TypeScript 4 |
| Database | PostgreSQL (via TypeORM) |
| Cache | Redis (cache-manager-redis-store) |
| Auth | Passport.js + JWT + CASL |
| Validation | class-validator + Joi |
| Containerization | Docker + Docker Compose |
| Linting | ESLint + Prettier + Husky |
| Testing | Jest + Supertest |
| Provider | Purpose |
|---|---|
| Paystack | Deposits, withdrawals, bank verification, transfer recipients |
| Flutterwave | Wallet balance, deposits, card payments |
| Monnify | Virtual account generation for receiving payments |
| VTPass | Airtime, data, electricity, TV subscriptions, WAEC PINs |
| Twilio | SMS OTP and notifications |
| Nodemailer | Transactional email delivery |
src/
├── ability/ # CASL permission definitions & guards
├── account/ # Bank account linking & Monnify virtual accounts
├── activities/ # Per-service activity logs (airtime, data, bills, TV)
├── admin/ # Admin management & admin-specific endpoints
├── airtime/ # Airtime purchase module
├── announcement/ # In-app announcements
├── auth/ # Authentication (login, JWT, transaction PIN)
├── bank/ # Bank directory & account verification
├── common/ # Shared guards, decorators, types, DTOs
├── database/ # Database connection configuration
├── electricitybill/ # Electricity bill payments
├── email/ # Email entity & module
├── flutterwave/ # Flutterwave integration service
├── health/ # Health check endpoint
├── log/ # Custom logger implementation
├── mobiledata/ # Mobile data purchase module
├── monnify/ # Monnify integration (virtual accounts)
├── nodemailer/ # Nodemailer email service
├── paystack/ # Paystack integration (payments, transfers)
├── referral/ # Referral code system
├── role/ # User roles management
├── settings/ # App settings
├── sms/ # SMS service
├── transactions/ # Deposits, withdrawals, transaction records
├── transfers/ # P2P transfers & transfer requests
├── tvsubscription/ # TV subscription management
├── twillio/ # Twilio SMS integration
├── user/ # User registration, profiles, KYC
├── utils/ # Shared utilities
├── vtpass/ # VTPass integration (bills & services)
├── wallet/ # Digital wallet management
├── app.module.ts # Root application module
├── main.ts # Application bootstrap
└── ormconfig.ts # TypeORM configuration
- Docker & Docker Compose
- Node.js (v14+)
- npm
-
Clone the repository
git clone https://github.com/Preshy-Jones/kobovault-server.git cd kobovault-server -
Install dependencies
npm install
-
Configure environment variables
cp env.example .env
Fill in the required values in
.env:Variable Description POSTGRES_*PostgreSQL connection credentials PGADMIN_*pgAdmin web interface credentials JWT_SECRET/JWT_EXPIRATIONJWT signing secret and token TTL PAYSTACK_*Paystack API keys FLUTTERWAVE_*Flutterwave API keys MONNIFY_*Monnify API keys & contract code VTPASS_*VTPass API credentials TWILLIO_*Twilio account SID, auth token, and phone number REDIS_*Redis connection details -
Start the services
docker compose up -d
This spins up five containers:
Service Port Description api3000NestJS application postgres5432PostgreSQL database pgadmin8080pgAdmin web UI redis6379Redis cache redis-commander8081Redis web UI -
Create the database
Open pgAdmin in your browser and create the database matching your
POSTGRES_DBenv variable.
# With Docker (recommended)
docker compose up -d
# Without Docker
npm run start:devRebuild the containers to pick up new dependencies:
docker compose up -d -V --build| Command | Description |
|---|---|
npm run start:dev |
Start in watch mode |
npm run start:debug |
Start in debug mode with inspector |
npm run start:prod |
Start production build |
npm run build |
Compile TypeScript to dist/ |
npm run lint |
Run ESLint with auto-fix |
npm run format |
Format code with Prettier |
npm test |
Run unit tests |
npm run test:watch |
Run tests in watch mode |
npm run test:cov |
Run tests with coverage |
npm run test:e2e |
Run end-to-end tests |
npm run documentation:serve |
Serve Compodoc API docs on port 9000 |
npm run typeorm:migrate |
Generate a TypeORM migration |
npm run typeorm:run |
Run pending migrations |
kobovault uses PostgreSQL with TypeORM as the ORM. Key entities include:
Customer— User profile, referral code, KYC level, walletsAdministrator— Admin user with elevated privilegesWallet— Balance, currency, linked activities & transfersTransaction(abstract) →Deposit/WithdrawalSendTransfer/ReceiveTransfer/TransferRequestAirtimeActivity,MobileDataActivity,ElectricityBillActivity,TvSubscriptionActivityMonnifyAccount,Referral,Announcement,Role
- Authentication: Passport.js with Local + JWT strategies
POST /auth/login/user— Customer loginPOST /auth/login/admin— Admin loginPOST /auth/pin— Set transaction PIN
- Authorization: CASL ability-based guards applied globally
- Fine-grained permissions like
ReadUserPermission,EditUserPermission,ReadWithdrawalPermission - Public routes opted out via
@Public()decorator
- Fine-grained permissions like
GET /health
Powered by @nestjs/terminus for container orchestration readiness probes.
Generate and browse interactive API documentation:
npm run documentation:serveThen open http://localhost:9000 in your browser.
Pre-built documentation is also available in the documentation/ directory.
- Create a branch based on the issue title
- Make your changes following the existing code style
- Ensure linting passes:
npm run lint - Ensure tests pass:
npm test - Submit a pull request
This project is UNLICENSED — proprietary and private.