FAQ

What is Daraja Local?

Daraja Local is an unofficial local sandbox for M-Pesa Daraja API integrations. It helps you build, test, and debug request flows, callbacks, and transaction state changes without sending requests to Safaricom or moving real money.

Is Daraja Local an official Safaricom product?

No. It is an emulator, not an official Safaricom service. Safaricom’s active Daraja portal remains the authority for public API behavior.

Which flows are supported?

The current docs cover:

• OAuth token generation
• STK Push
• STK Query
• C2B register URL and simulation
• B2C payments
• B2B payments
• experimental B2C account top-up
• callback replay and transaction inspection

See the compatibility contract for verified behavior, deliberate differences, and version-sensitive areas.

Does Daraja Local send real M-Pesa requests?

No. It stores transactions locally and simulates outcomes such as success, failure, and timeout. It is designed for development and testing rather than live payment processing.

Do I still need OAuth tokens?

Yes. Daraja Local exposes a local OAuth endpoint and expects a bearer token on supported /mpesa routes. The request and response shape mirrors Daraja, but the token is generated and validated locally.

Are transactions persisted?

Not in the current MVP. Transactions, tokens, registrations, and callback attempts are stored in memory and are lost when the emulator restarts.

Can I treat the immediate STK Push response as payment success?

No. The immediate response is only an acknowledgement. Your application should save the identifiers, mark the payment as pending, and wait for the callback or query the transaction state before finalizing it.

How do I simulate final outcomes?

Use the CLI or simulator endpoints to approve, fail, timeout, or replay callbacks for a transaction. The guides in Simulate Outcomes and Callbacks walk through that flow.

Does ResponseType disable C2B validation?

No. ResponseType controls the fallback when the validation endpoint cannot provide a valid decision. It does not enable or disable validation itself.

Is B2C Account Top-Up fully supported?

No. It is explicitly marked experimental. Product support, route naming, and field expectations are version-sensitive, so verify them in the active Safaricom Daraja portal before relying on parity.

Can I use this in production?

You can use it to prepare and test your integration locally, but it is not a live payment gateway and should not be treated as a substitute for real Daraja infrastructure in production.

Where should I report bugs, feature requests, or security issues?

• Bugs and feature ideas should go through the project’s issue and pull-request workflow.
• Security problems or exposed credentials should not be reported publicly; use the repository’s private security advisory process instead.

See Contributing for the full contribution process.