daraja-mock

A small local test double for the Safaricom M-Pesa Daraja API, built on Flask. It lets you exercise OAuth and STK Push flows (and the request shapes of B2C v3, transaction status and account balance; there is no C2B, B2B or reversal endpoint, and those paths return 404) without a Safaricom account, credentials or internet access.

What this is, and is not. A test double, not a simulator of Safaricom's behaviour, and not affiliated with Safaricom. Only the STK Push query result is configurable. B2C, Account Balance and Transaction Status always return an "accepted" response, and no asynchronous result callbacks are sent. See Limits.

Install

pip install daraja-mock    # installs Flask

Quickstart

import requests
from daraja_mock import DarajaMock

mock = DarajaMock()
base_url = mock.run_thread(port=18080)      # non-blocking; returns "http://127.0.0.1:18080"

token = requests.get(f"{base_url}/oauth/v1/generate").json()["access_token"]
headers = {"Authorization": f"Bearer {token}"}

push = requests.post(
    f"{base_url}/mpesa/stkpush/v1/processrequest", headers=headers,
    json={"BusinessShortCode": "174379", "Amount": 100, "PhoneNumber": "254712345678",
          "CallBackURL": "https://example.com/callback", "AccountReference": "Order001", "TransactionDesc": "Payment"},
).json()
assert push["ResponseCode"] == "0"

mock.set_stk_result(1032)                   # STK queries now report "cancelled by user"
status = requests.post(f"{base_url}/mpesa/stkpushquery/v1/query", headers=headers,
                       json={"CheckoutRequestID": push["CheckoutRequestID"]}).json()
assert status["ResultCode"] == "1032"

Configuration

The STK query endpoint returns the configured ResultCode for any CheckoutRequestID; it does not look the id up, and it returns a fresh random CheckoutRequestID of its own.

Endpoints

Standalone server

python -m daraja_mock                 # http://127.0.0.1:8765
python -m daraja_mock --port 9000
daraja-mock --port 9000               # the same, as an installed command

Use with pesa-cli

pesa-cli 1.0.1 and later reads PESA_BASE_URL, so its commands can run against this server:

python -m daraja_mock --port 8765 &
export PESA_BASE_URL=http://127.0.0.1:8765
pesa auth && pesa stk push 0712345678 100

daraja-v3 (the mpesa-python SDK) 0.1.2 and later accept MpesaClient(..., base_url="http://localhost:8765"), so the SDK can be pointed at this server; its own test suite does exactly that. base_url must be https://, or http:// for localhost only.

Limits

• Credentials, shortcodes, passkeys and callback URLs are not validated.
• No asynchronous result or callback delivery: STK, B2C and balance results that real Daraja posts to your URLs are not sent.
• STK query is stateless (see above). No C2B URL registration endpoint.
• It runs on Flask's development server, in a daemon thread for run_thread, in one process.

Tests

pip install -e ".[dev]" && python -m pytest

The tests also fail if this README names a class, method or endpoint that does not exist, and they run the Quickstart above.

Part of the nairobi-stack East Africa engineering ecosystem. Maintained by Gabriel Mahia. Kenya × USA.