Introduction

@lumierelabs/daraja wraps the Safaricom Daraja API in a TypeScript client that handles the parts everyone reimplements badly on their own project: 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!,
  environment: "sandbox",
});

const result = await daraja.stkPush({
  businessShortCode: "174379",
  passkey: process.env.MPESA_PASSKEY!,
  transactionType: "CustomerPayBillOnline",
  amount: 1,
  partyA: "254708374149",
  partyB: "174379",
  phoneNumber: "254708374149",
  callBackURL: "https://example.com/callbacks/stk",
  accountReference: "INV-1042",
});

console.log(result.CheckoutRequestID);

What's actually in the box

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.