Integrations
Use the Daraja SDK from server routes, loaders, actions, and Node.js services.
The SDK is a server-side TypeScript client for Safaricom's Daraja API. It uses
standard fetch, AbortController, timers, Base64 encoding, and
Intl.DateTimeFormat for the East Africa timestamp required by STK Push.
There is one package and one client shape: create it once, then call it from
your framework's server boundary.
Keep credentials on the server
Never import the SDK into a browser component or expose consumerKey,
consumerSecret, passkeys, or security credentials to the client. Use a route
handler, loader, action, server endpoint, or backend service instead.
Supported guides
These guides match the framework examples currently maintained in this repository. Each one covers client construction, an STK Push route, and Daraja callbacks where the framework supports them.
Next.js
App Router route handlers for STK Push, C2B callbacks, and B2C top-ups.
Astro
Server endpoints via Astro API routes.
Remix
Action and loader functions for requests and callbacks.
Express
A Node server with routers for STK Push and callbacks.
Runtime fit
The package declares Node.js >=20.19.0 and is tested as a Node-first SDK.
Its HTTP layer uses Web APIs, so it can also fit other server runtimes that
provide compatible fetch, AbortController, Base64, timers, and
Intl.DateTimeFormat support.
Node.js
Primary runtime for APIs and workers.
Deno
Compatible through npm package imports.
Bun
Compatible with Bun.serve() and Bun servers.
Edge runtime note
Edge deployments are not the primary tested target. The SDK uses btoa when
available and falls back to Buffer for Base64 encoding, so verify the target
platform's globals before deploying to an edge isolate. In Next.js, use the
default Node.js runtime unless you have verified the specific edge deployment
yourself.
SDK surface
The same client exposes the implemented Daraja products below. Callback handlers are application code: the SDK sends outbound requests, while your server receives and persists Safaricom's asynchronous payloads.
M-Pesa Express
Send an STK Push and query its CheckoutRequestID.
C2B
Register callback URLs and simulate sandbox payments.
B2C Account Top Up
Submit top-ups and handle the asynchronous result callback.
Dynamic QR and Offers
Generate payment QR codes and work with data offers.
Verification services
Use SIM swap, IMSI, mobile-number, and B2B Hakikisha clients.
Shared setup
Construct the client at module scope so its in-memory OAuth token cache can be reused between requests.
import { Daraja } from "@lumierelabs/daraja";
export const daraja = new Daraja({
environment:
process.env.DARAJA_ENVIRONMENT === "production" ? "production" : "sandbox",
consumerKey: process.env.DARAJA_CONSUMER_KEY!,
consumerSecret: process.env.DARAJA_CONSUMER_SECRET!,
passkey: process.env.DARAJA_PASSKEY!,
shortcode: process.env.DARAJA_SHORTCODE!,
callbackUrl: process.env.DARAJA_CALLBACK_URL!,
});Call methods such as daraja.stkPush(), daraja.stkPushQuery(),
daraja.c2b.registerUrl(), or daraja.b2cTopUp.topUp() from the server
boundary. Catch DarajaError to return a stable error code and HTTP status to
your application.
Scaffold with the CLI
create-daraja currently generates complete Next.js and Express projects,
including only the selected service routes.
npx create-daraja@latestChoose Next.js or Express, select sandbox or production, then select STK Push, STK query, C2B, or B2C Account Top Up.
Copy .env.example to .env, add your credentials, install dependencies, and
start the generated dev server. The CLI never creates a real .env file.
Adding another framework
The SDK has no Express, Next.js, Astro, or Remix dependency. A new adapter only needs to construct the client once and call its methods from the framework's server boundary.