Configuration

Overview

The SDK requires M-Pesa API credentials from Safaricom's Developer Portal. Configuration is framework-agnostic and works the same across all packages.

Basic Configuration

All M-Pesa integrations require these core credentials for STK Push:

MPESA_CONSUMER_KEY=your_consumer_key
MPESA_CONSUMER_SECRET=your_consumer_secret
MPESA_SHORTCODE=174379
MPESA_PASSKEY=bfb279f9aa9bdbcf158e97dd71a467cd2e0c893059b10f78e6b72ada1ed2c919
MPESA_ENVIRONMENT=sandbox
MPESA_CALLBACK_URL=https://yourdomain.com/api/mpesa/callback

SDK Initialization

import { MpesaClient } from "@singularity-payments/nextjs";

const client = new MpesaClient({
  consumerKey: process.env.MPESA_CONSUMER_KEY,
  consumerSecret: process.env.MPESA_CONSUMER_SECRET,
  passkey: process.env.MPESA_PASSKEY,
  shortcode: process.env.MPESA_SHORTCODE,
  environment: "sandbox",
  callbackUrl: process.env.MPESA_CALLBACK_URL,
});

Getting M-Pesa Credentials

Step 1: Create a Safaricom Developer Account

Go to Safaricom Developer Portal
Click Sign Up and create an account
Verify your email address
Log in to your account

Step 2: Create an App

Navigate to My Apps
Click Create Sandbox App
Fill in the app details:
- App Name: Your application name
- Description: Brief description of your app
Select Lipa Na M-Pesa (STK Push)
Click Create App

Step 3: Get Your Credentials

After creating your app, you'll receive:

Consumer Key: Found on your app's page
Consumer Secret: Found on your app's page (click to reveal)

Sandbox Test Credentials

MPESA_CONSUMER_KEY=your_sandbox_consumer_key
MPESA_CONSUMER_SECRET=your_sandbox_consumer_secret
MPESA_PASSKEY=bfb279f9aa9bdbcf158e97dd71a467cd2e0c893059b10f78e6b72ada1ed2c919
MPESA_SHORTCODE=174379
MPESA_ENVIRONMENT=sandbox
MPESA_CALLBACK_URL=https://your-ngrok-url.ngrok.io/api/mpesa/callback

Setting Up Tunneling for Development

Your callback URL must be publicly accessible. For local development, use a tunneling service:

Using ngrok

Install ngrok:

npm install -g ngrok

Start your development server:

npm run dev

In a new terminal, start ngrok:

ngrok http 3000

Copy the HTTPS URL (e.g., https://abc123.ngrok.io)
Update your .env:

MPESA_CALLBACK_URL=https://abc123.ngrok.io/api/mpesa/callback

Alternative Tunneling Services

Environment Variables

Create a .env file in your project root:

MPESA_CONSUMER_KEY=your_consumer_key
MPESA_CONSUMER_SECRET=your_consumer_secret
MPESA_PASSKEY=bfb279f9aa9bdbcf158e97dd71a467cd2e0c893059b10f78e6b72ada1ed2c919
MPESA_SHORTCODE=174379
MPESA_ENVIRONMENT=sandbox
MPESA_CALLBACK_URL=https://yourdomain.com/api/mpesa/callback