Building a Production-Grade Payroll System with Express, TypeScript, and Monnify API

In this article, we'll walk through creating a robust payroll system using Express.js, TypeScript, and Monnify's payment API. This system will handle bulk disbursements, employee records, and real-time status updates, providing a scalable solution for HR and fintech applications.

Why this matters

A well-designed payroll system is crucial for businesses of all sizes. It ensures accurate and timely payment of employees, maintaining employee satisfaction and trust. Moreover, a production-ready payroll system can serve as a foundation for building more complex financial applications, such as HR systems or fintech platforms.

Key components

Express API

Express.js is a minimal and flexible Node.js web framework, ideal for building RESTful APIs. It provides routing, middleware support, and makes it easy to manage employee records and payrolls.

Bull Queue

Bull is a Redis-based queue library for Node.js, enabling asynchronous processing of long-running tasks such as payroll disbursements. It handles job retries, scheduling, and provides a reliable way to process tasks without blocking the main application thread.

Redis

Redis serves as the backend for Bull queues, storing job data, managing job states (pending, active, completed, failed), and enabling distributed job processing across multiple workers.

PostgreSQL

PostgreSQL is a relational database that persists employee records, payrolls, and payment items. Its ACID compliance ensures data integrity, and its support for complex queries makes it ideal for financial applications.

Monnify API

Monnify API is a payment gateway service that handles actual money transfers to employee bank accounts. It provides bulk disbursement capabilities, allowing you to process multiple payments in a single API call, which is essential for payroll systems.

Webhooks

Webhooks are HTTP callbacks that receive real-time payment status updates from Monnify. When a payment completes or fails, Monnify sends a webhook to your server, allowing you to update your database immediately without polling.

Setting up the project

Before diving into the code, ensure you have the following prerequisites:

• Node.js (v18 or higher)
• Docker and Docker Compose installed
• Basic knowledge of TypeScript and Express.js
• Familiarity with REST APIs
• Monnify merchant account with API credentials

Project architecture overview

Here's a high-level overview of the payroll system's architecture:

Creating the API controllers

Controller responsibilities include:

• Creating an employee
• Fetching all employees
• Fetching a single employee
• Updating an employee
• Deleting an employee

Creating the payroll system

The payroll system includes:

• Creating payroll batches
• Processing payroll batches
• Reconciling payroll payments
• Payroll statistics update

Setting up webhook handlers

Webhook handlers wire up routes and handle real-time payment status updates from Monnify.

Conclusion

Building a production-grade payroll system with Express, TypeScript, and Monnify API equips you with valuable skills for building HR and fintech applications. The combination of asynchronous processing, real-time status updates, and database persistence ensures a robust, scalable, and reliable solution for managing employee payments.

By following this tutorial, you've learned how to:

• Handle bulk disbursements efficiently using Bull and Redis
• Manage employee records with bank account details
• Create and process payroll batches
• Handle payment status updates via webhooks
• Reconcile transactions to ensure data consistency

This tutorial represents a common stack in modern backend development, preparing you for more complex financial applications.