Introduction
A typed, zero-nonsense TypeScript SDK for Safaricom's Daraja (M-Pesa) API.
@lumierelabs/daraja wraps the Safaricom Daraja API in a TypeScript client that handles OAuth token caching, STK Push password generation, callback URL validation, and Daraja's inconsistent PascalCase/camelCase payload shapes.
You give it a Consumer Key and Consumer Secret. It gives you back a client with typed methods, readable error messages, and no Buffer.from(...).toString('base64') scattered across your codebase.
import { Daraja } from "@lumierelabs/daraja";
const daraja = Daraja({
consumerKey: process.env.DARAJA_CONSUMER_KEY!,
consumerSecret: process.env.DARAJA_CONSUMER_SECRET!,
shortcode: process.env.DARAJA_SHORTCODE!,
passkey: process.env.DARAJA_PASSKEY!,
callbackUrl: process.env.DARAJA_CALLBACK_URL!,
environment: "sandbox",
});
const result = await daraja.stkPush({
transactionType: "CustomerPayBillOnline",
amount: 1,
partyA: "254708374149",
phoneNumber: "254708374149",
accountReference: "INV-1042",
});
console.log(result.CheckoutRequestID);A note on scope
This documentation covers exactly what @lumierelabs/daraja implements today
nothing more. If you came here looking for Account Balance, Transaction
Status, or a generic Reversal/B2B Payment Request client, they
aren't in the package yet. See Roadmap & what's not
here for the honest list of what's missing and why,
instead of documentation for endpoints that would throw a 404 the moment you
called them.
What's actually in the box
Authentication
Auto-caching OAuth 2.0 token management, handled for you.
M-Pesa Express (STK Push)
Push a payment prompt to a customer's phone and query its outcome.
C2B
Register callback URLs and simulate customer payments in sandbox.
B2C Account Top Up
Move funds from your MMF/Working account into a B2C shortcode's utility account.
B2B Hakikisha
Verify an organization's name and tariff before you pay it.
Dynamic QR
Generate a scannable M-Pesa payment QR code.
Mobile Data Bundles
Browse, purchase, and check the status of data bundle offers.
SIM Swap & IMSI
Fraud checks: last SIM swap date, hashed IMSI, network registration age.
Mobile Number Validation
Confirm an msisdn is registered against a given National ID, Military ID, or Passport.
Understanding Endpoint Badges
- Working: The SDK implementation is available and the repository has passing tests for its local behavior. - Upstream Issue: The SDK method and payload types are implemented, but the repository has observed errors or inconsistent responses from the corresponding sandbox endpoint. These badges are not a live availability check.
Why this exists
Daraja's own documentation is functional but thin: field names change case between endpoints (OriginatorCoversationID is a real, misspelled field Safaricom ships), the STK Push password has to be hand-built as Base64(ShortCode + Passkey + Timestamp) in the exact East African timezone, and half the "gotchas" you'll hit are only discoverable by hitting them. This SDK bakes those lessons in so you don't have to relearn them from a failed sandbox call at 11pm.
Start with Installation, or jump straight to Quickstart if you already have sandbox credentials.