NORTHFAST.
Talk to team →
docs.northfast.co.ke · v1

Developer documentation

Everything you need to build with our open-source tools: the M-Pesa Box SDK for M-Pesa payments and the VerenaJS data-driven framework. MIT-licensed and community-driven.

Introduction

M-Pesa Box is a reliable, MIT-licensed SDK that wraps the Safaricom Daraja APIs — STK Push, C2B, B2C and reconciliation — so you can accept M-Pesa in any Node.js app. It powers Cashly under the hood and is free to self-host.

Installation

Install from npm. It works in any Node.js environment.

bash 
npm install @northfast/mpesa-box

Quickstart

Initialise the client with your Daraja credentials and send your first STK push.

quickstart.ts 
import { MpesaBox } from '@northfast/mpesa-box' const box = new MpesaBox({ env: 'sandbox', /* credentials */ })
await box.stkPush({ phone: '2547XXXXXXXX', amount: 2500, ref: 'ORDER_8821' })

Configuration

Get your Consumer Key, Consumer Secret, Shortcode and Passkey from the Safaricom Daraja portal. Keep these on your server — never ship them to the browser.

config.ts 
const box = new MpesaBox({
  env: 'production', 
consumerKey: process.env.MPESA_KEY,
  consumerSecret: process.env.MPESA_SECRET,
  shortcode: '174379',
  passkey: process.env.MPESA_PASSKEY,
  callbackUrl: 'https://yoursite.com/mpesa/callback',
})
!

Store credentials in environment variables. The SDK fetches and caches the OAuth token for you and refreshes it before expiry.

STK Push

Prompt a customer's phone for their M-Pesa PIN (Lipa na M-Pesa Online). The result is delivered to your callbackUrl.

FieldTypeDescription
phonestringCustomer MSISDN in 2547XXXXXXXX format.
amountnumberAmount in KES (whole shillings).
refstringAccount reference shown to the customer.
stk.ts 
const res = await box.stkPush({
  phone: '2547XXXXXXXX',
  amount: 2500,
  ref: 'ORDER_8821',
})

C2B & callbacks

Handle the callback M-Pesa posts after a transaction. The SDK parses and validates the payload so you can fulfil idempotently.

express · callback 
app.post('/mpesa/callback', (req, res) => {
const event = box.callbacks.parse(req.body)
if (event.success) {

}
  res.json({ ResultCode: 0, ResultDesc: 'Accepted' })
})

Methods

MethodDescription
stkPush()Trigger a customer STK prompt (Lipa na M-Pesa Online).
c2b()Register URLs and handle customer-to-business payments.
b2c()Send business-to-customer disbursements.
query()Query STK / transaction status for reconciliation.
Ready to build?
All of our tools are open source on GitHub.
Explore projects →