Introducing the Ultimate Go Daraja (M‑Pesa) Client

go-daraja is a lightweight, idiomatic Go client for Safaricom's Daraja (M‑Pesa) APIs. It emphasizes a clean developer experience, easy configuration across environments, and safe defaults for production.

Why Would I use this?

• Easy to set up and install
• Have a clean, consistent API surface
• Context-aware calls for timeouts/cancellation
• Pluggable http.Client for custom transports/retries
• 12‑factor configuration via OS env, optional .env
• Embedded X.509 certs and typed error model
• Covers core Daraja flows (STK Push, B2C, C2B, B2B, Business Express)

Table of Contents

• Install
• APIs Covered
• Advanced Features
• Configuration
• Usage Examples
• Project Structure
• Development
• GitHub Stats
• Contributing
• Security
• License

Install

Go Get

go get github.com/silaselisha/go-daraja

Then import and construct a client:

import (
  "log"
  daraja "github.com/silaselisha/go-daraja/pkg/handler"
)

func main() {
  client, err := daraja.NewClient()
  if err != nil { log.Fatal(err) }
  // ...
}

APIs Covered

• STK Push (NI)
• Business to Customer (B2C)
• Customer to Business (C2B)
• Business to Business (B2B)
• Business Express Checkout
• OAuth access token generation

Advanced Features

Use functional options with NewClient(...) to tailor behavior:

• HTMX-style context support via *_Ctx methods for cancellation/timeouts
• Inject your own http.Client (retries, proxies, tracing)
• Load configuration from .env with WithEnvFile("path")
• Embedded sandbox/production X.509 certs via go:embed
• Consistent, typed errors; backward compatible responses

Configuration

Set required envs (12‑factor friendly). .env is optional and supported.

export MPESA_ENVIRONMENT=sandbox
export DARAJA_CONSUMER_KEY=your_key
export DARAJA_CONSUMER_SECRET=your_secret
export DARAJA_BUSINESS_SHORT_CODE=174379
export DARAJA_PASS_KEY=your_pass_key
export DARAJA_CALL_BACK_URL=https://your.app/callback
export DARAJA_ACCOUNT_REF=YourApp
# Required for B2C/B2B:
export DARAJA_INITIATOR_NAME=your_initiator
export DARAJA_INITIATOR_PASSWORD=your_password

Usage Examples

Quickstart:

client, err := daraja.NewClient()
if err != nil { log.Fatal(err) }

STK Push (NI):

res, err := client.NIPush("payment for order #123", "0712345678", 100)

B2C:

res, err := client.BusinessToConsumer(
  100, 0, "0712345678", "salary",
  "https://example.com/timeout",
  "https://example.com/result",
)

C2B register URLs:

res, err := client.CustomerToBusiness(
  "https://example.com/confirm",
  "https://example.com/validate",
  1,
)

Business Express Checkout:

res, err := client.BusinessExpressCheckout(
  "PAY-123",
  "https://example.com/callback",
  "YourBiz",
  "600000",
  100,
)

Backward compatible constructor:

client, err := daraja.NewDarajaClient(".")

Project Structure

pkg/
  handler/          # Public client and operations
  internal/
    auth/           # Basic auth token creation
    builder/        # Helpers (base URLs, phone formatting, timestamp)
    config/         # Viper-based configuration loader
    x509/           # go:embed certs + security credential generation
example/            # Example .env and sample usage

Development

Prereqs: Go >= 1.22

• Run tests:

go test ./...

• Lint/inspect locally:

go vet ./...

GitHub Stats

Contributing

Contributions are welcome! Please read CONTRIBUTING.md and open an issue or PR.

Security

If you discover a security vulnerability, please follow the process in SECURITY.md.

License

This project is licensed under the MIT License. See LICENSE for details.