In today's digital landscape, most businesses have embraced mobile money for digital transactions. Most customers also find paying for goods and services convenient using mobile money. It is crucial for companies that engage in monetary transactions to integrate seamless payment features to enhance the overall user experience. Safaricom a leading telecom company has exposed a range of MPESA APIs, such as B2B, C2B, and Mpesa Express, enabling access to MPESA services.

In this guide, we will explore the process of integrating the MPesa Express API into a Node.js and Express application.

Before proceeding with the integration process, ensure you have the following:

Daraja API credentials. You can obtain the credentials from the 

Create your Nodejs and Typescript project

In this guide, we will create a Nodejs project with Typescript. Create a new directory for your project and initialize it with a package manager of your preference. We will use npm.

Install Typescript as a development dependency

Ensure the following configurations are set for the tsconfig.json file

express: A minimalist web framework for Node.js

cors: Allows you to enable CORS in your Node.js app

dotenv: Manages environment variables configuration

nodemon: Restarts your Nodejs application whenever it detects changes.

To compile your Typescript file to JavaScript. Run the following command.

Create an src directory and add the index.ts file, middleware, controller, and routes.

Automate the process of starting the server

  file to make running and building the server easier.

Sign up on the developer portal and create an app under my apps tab.

Once the application is created, the consumer secret and consumer key are generated. Copy the credentials and store them in the .env file.

Navigate to the APIs tab that has various endpoints exposed. Click the Mpesa Express simulate button.  

On the Mpesa Express simulator select the app that you have created. The business short code(Party B) and the passkey will be accessed here.

Save all the credentials in a .env file for security concerns.

 is our entry point for the application. We will set up an Express server with middleware for JSON parsing and CORS. Define route handlers for the  "/lipa" endpoint, and start the server listening on the specified port.

The route handler logic will be explained as we proceed.

generates tokens for authenticating your api calls.

By extending the request type, the token is added as an additional property, to the request object in a type-safety manner. The property will later be used to store the access token.

Once the API request is successful, the response will contain an access token in response.data.access_token.

req.token stores the access token generated in the req(request) object to be used later in the request lifecycle.

The next() function is used to pass control to the next middleware function in the stack.

, allowing the request to proceed to the next function, in our case it is the handleStkPush function.

TimeStamp ensures that each transaction request is time-specific and unique. This prevents resending a valid request to perform unauthorized transactions.

We will need a utility function that converts Date to a string formatted as, YYYYMMDDHHMMSS.

The timestamp is included in the payload when initiating the stk push and represents the exact time when the request is generated.

This function initiates the business logic to handle the Mpesa STK push (Sim Toolkit Push) request.

The payload construction includes all the required data for the STK push request. The password is generated by concatenating the M-Pesa pass key business short code, and the timestamp, then encoding the result in Base64.

: The type of transaction (CustomerPayBillOnline).

: A URL where M-Pesa will send transaction status updates.

 call must be authenticated by including an authorization header in the request, which contains the token generated earlier by the generateToken function.

If the request is successful, the user receives an STK push on their phone. This user is prompted to enter their PIN to authorize the transaction amount and the amount charged.

When a POST request to the 'stkpush/' endpoint is received the request first goes through the generateToken middleware, which handles the generation of an authentication token.

After the token has been verified the request is passed to the handleStkPush request handler function which requests the M-Pesa API.

Navigate to Postman and pass the amount and phone as part of the payload. 

We will make an api request using the endpoint below.

The phone number used will receive an STK push.

https://github.com/kodaschool/nodejs-mpesa-integration

Dive into our programming articles for insights and tips. Covering a range of topics, they're perfect for learners at any level eager to expand their knowledge.

Dive into our programming articles for insights and tips.

Articles

How to integrate Mpesa Daraja API  with Node.js

NestJs is an open-source, progressive Node.js framework for building robust, efficient, and scalable server-side applications. NestJS offers abstraction to a certain extent while directly exposing APIs to developers.NestJs architecture significantly draws inspiration from Angular. 

But first, let's use an Analogy to understand the concepts of NestJS

Let us imagine we are building a house. In traditional construction, you will be required to manually handle pouring concrete, framing walls, installing plumbing and wiring, and so on. This particular approach is not efficient since it requires a lot of manual labor and changes can be difficult to implement.

Now, let us look at building a modern house that reflects a modular building system. Each house component (floors, walls, electrical wiring, water system, etc.) comes pre-built with such a system. This setup abstracts away common tasks allowing you to connect the components rather than building from scratch.

In this analogy, NestJS works similarly to the modular building system. It provides pre-built components and patterns like modules, controllers, services, and middleware that you can easily connect to build your application. These components are abstracted away allowing developers to to build and maintain complex applications easily.

How Nest borrows inspiration from Angular:

: Nest has a modular structure for building applications, similar to Angular's modules. Modules in Nest provide separation of concerns making it possible to build high-performance applications.

: Nest middleware functions are similar to Angular interceptors, in that incoming requests and outgoing responses can be intercepted before or after interacting with the controller. This enables operations such as authentication and error handling.

: Dependency Injection is a design pattern used to manage the services required by different components and modules of an application to perform tasks. Both Nest and Angular use dependency injection by allowing components to be loosely coupled.

: Nest makes extensive use of decorators and metadata, similar to Angular. Decorators are used to annotate classes, methods, and properties to provide additional functionality or metadata, such as defining routes, middleware, or providers. This declarative approach enhances readability and reduces boilerplate code.

: Nest provides lifecycle hooks that are conceptually similar to Angular's lifecycle hooks. These hooks allow developers to execute code at specific points during the lifecycle of a component, controller, or module.

: Providers  are classes annotated with the 

 decorator which are responsible for interacting with external services, handling business logic,  and managing data. Providers can be injected into other components, such as controllers or other providers, to facilitate modular and reusable code. 

: Each NestJS application typically consists of multiple modules, each serving a specific purpose or feature set. Modules encapsulate related functionality and provide a clear structure for organizing code. The 

 decorator provides metadata that Nest makes use of to organize the application structure.

: Controllers are responsible for handling incoming HTTP requests and generating appropriate responses. They are classes annotated with the 

 decorator and contain handler methods  annotated with specific HTTP request method decorators (such as 

, etc.). To create a basic controller, we use classes and 

. Decorators associate classes with required metadata and enable Nest to create a routing map

: The middleware sits between a client and the controller allowing logic to be executed before or after the controller handles invoked methods. Custom Nest middleware is either implemented as a function or in a class with an 

To get started ensure you have NestCLI installed. If not use the following command to install it.

You will be prompted to pick the name of your project and select a package manager. For this project will be using npm. Below is our project structure.

: This is the starting point of our application, where Nest will begin building the dependency graph

: This is the root module of our application. In the module, we can define controllers and providers, and we can import and export providers.

 : A controller serves as a route handler, providing the context for one or more related routes.

 : Encapsulates business logic and functionality shared across multiple parts of the application

We shall create a folder called tasks and create a controller, module, and service following nest architecture. Use the CLI to execute the following commands.

This is how our updated folder structure will look:

 class as a provider, this means it can be injected as a dependency into other components like controllers. 

This task service class manages a list of tasks with operations to add a new task and retrieve all tasks.

 serves as the interface for HTTP clients to interact with the task management functionality provided by 

. It defines routes to create new tasks and retrieve existing tasks.

 is designed to encapsulate all the functionalities related to task management. It uses the 

 to handle business logic of task creation.  The module connects these components using the @Module() decorator enabling the separation of concerns.

 method will handle HTTP POST requests to the 

: This method signature uses decorators from NestJS to specify how to handle the incoming request data.

 decorator instructs nest to destructure the description from the request body and pass it to the createTask method.

 takes an argument (the method being decorated, in this case, getTasks and returns an array of tasks.

 decorator accepts a pathname that is used to make an api request. For example, a request to 

 NestJS architecture step by step guide.

Email sending has become a popular business feature in modern business operations. With the adoption of digital communication, most businesses use email as a primary channel to share important business information such as promotional offers, newsletters, service updates, and transactional notifications.

In this post, we will explore how to send emails with Nodejs and Express using SendGrid. We’ll walk through configuring your Node.js application, integrating SendGrid’s API, and crafting personalized email messages to be dispatched seamlessly through your Express web server.

SendGrid is an STMP service provider that offers robust APIs for sending emails without maintaining email servers. SMTP is a standard protocol used for sending email messages between the sender's and the recipient’s email server. SendGrid provides features like email templates, analytics, and scalability, enabling businesses to integrate email functionality into their applications.

SendGrid provides real-time tracking of emails, such as email delivery status, spam reports, unique opens and clicks, bounce rates, and email unsubscribers.

SendGrid provides high email delivery in large-scale marketing with unique features such as email validation, integrated email tests, and dedicated IP addresses.

SendGrid provides built-in email templates for quickly drafting and personalizing promotional emails. It also has a rich HTML editor and drag-and-drop editor for users who prefer to customize emails from scratch.

SendGrid’s SMTP service streamlines the automation of transactional emails leveraging on the percentage of recipients who open or view an email out of the total number of emails delivered.

SendGrid SMTP relay and Web API provide easy SendGrid integration with tools such as Twilio, Google Cloud Platform, and Airtable. This feature addresses business needs and enhances the email marketing experience.

The first step in using SendGrid services is setting up a SendGrid account. Go to the

 and create a free account if you haven’t already created one. After signing in you should see a default SendGrid dashboard view.

Set up your email or domain with SendGrid

 section and choose “Sender Authentication” from the dropdown menu. In this section, you define which email accounts are authorized to send emails via SendGrid.

Domain Authentication: This option allows you to authenticate your domain with SendGrid, authorizing it to send emails on your behalf. This is the recommended approach: 

https://docs.sendgrid.com/ui/sending-email/dmarc

Single Sender Authentication: This method allows you to authenticate a single email address for sending emails through SendGrid.

After verifying the sender, navigate to the

 tab, proceed to “API Keys”, and click on the "Create API Key” button. This action will generate an API Key, used to grant permission to send emails. Add the API key name and choose the permission level according to your business needs. I gave my API key full permission.

Setting up our Nodejs project involves the following steps

Install Node.js: Ensure that Node.js is installed on your machine. You can download the installer from the official Node.js website (

) and follow the installation instructions.

Initialize the Project: Open your terminal or cmd and navigate to the directory where you want to create the project. Use the following command to initialize a Nodejs project with the default settings.

3.  Install dependencies: Once the project is initialized install all the dependencies you need for your project. In our case, we shall install Typescript Express, dotenv, and SendGrid.

4. Configure project settings: Configure a.env file to store our sensitive information such as the SendGrid API key. The environment variable file gets loaded into the project using the dotenv package.

5. Create project files: Create the necessary folders and files for your project. In our case, we shall create a src folder with the main entry file of our application and a utility folder that will contain a file that will handle the 'send email' logic

Importing the SendGrid module allows us to use methods for sending emails. The API key verifies the identity of the sender when making requests to the SendGrid API key. This code encapsulates the logic for sending emails using SendGrid.

The components of the email message which is returned by the getMessage function

:  It specifies the recipient of the email.

: It specifies the email address of the person or domain sending the email. 

:  It specifies the title of the email content, providing recipients with an idea of what the email is about.

: This key represents the plain text content of the email. 

:  It specifies the main body of the email in HTML format. This content is typically displayed to recipients who prefer to view emails with HTML rendering enabled.

The index.ts file sets up an express server that listens for POST request on the 'api/test-email' endpoint. When a request is received, it sends a test email using SendGrid by calling the 

https://github.com/kodaschool/nodejs-sendgrid-integration

Articles

How to integrate Mpesa Daraja API with Node.js

NestJS architecture step by step guide.

A complete walkthrough: Sending Emails with Nodejs Using SendGrid

Practice Frontend, Android and iOS by building real world projects.