# Mpesa Stk Helper

> Send M-pesa payment prompts and track their results from a small FastAPI service, built for python developers integrating Safaricom's Daraja for the first time.

- Documentation: https://mpesa-stk-helper.thally.app
- GitHub: https://github.com/willen-gitonga/mpesa-stk-service
- Full docs for LLMs: https://mpesa-stk-helper.thally.app/llms-full.txt
- Agent discovery (ai.txt): https://mpesa-stk-helper.thally.app/ai.txt
- Structured docs index (JSON): https://mpesa-stk-helper.thally.app/api/docs-index
- OpenAPI spec: https://mpesa-stk-helper.thally.app/openapi.yaml

## For AI agents

Every page supports content negotiation on its human URL:
- JSON API: append `?format=json` or send `Accept: application/json`
- JSON-LD: append `?format=ldjson` or send `Accept: application/ld+json`
- Markdown: append `?format=md` or send `Accept: text/markdown`
- Per-page API: https://mpesa-stk-helper.thally.app/api/docs/{page-id}
- Search API: https://mpesa-stk-helper.thally.app/api/search?q={query}
- Capability manifest (skill): https://mpesa-stk-helper.thally.app/skill.md
- Agent guidance (editing these docs): https://mpesa-stk-helper.thally.app/AGENTS.md
- MCP server (attach docs as native tools): https://mpesa-stk-helper.thally.app/api/mcp
- Agent readiness: https://mpesa-stk-helper.thally.app/api/agent-readiness

### Recommended workflow

1. Use this index, the search API, or `search_sections` / `search_docs` before choosing a page.
2. Read the smallest set of relevant pages and follow their prerequisite links.
3. Treat the published docs as the source of truth. Label inferences and say when evidence is missing.
4. Cite the canonical human page URLs, not only API endpoints.
5. Use `/AGENTS.md` before editing a repository. The public MCP server is read-only.

## Documentation

### Getting Started

- [Introduction](https://mpesa-stk-helper.thally.app/): A small FastAPI service that sends M-Pesa STK Push payment prompts through Safaricom's Daraja sandbox and records the result when Safaricom calls back.
- [Quickstart](https://mpesa-stk-helper.thally.app/quickstart): Run the helper in mock mode, send a payment prompt, and simulate Safaricom's callback in about five minutes.

### Guides

- [Receive payment callbacks from the Daraja sandbox](https://mpesa-stk-helper.thally.app/guides/sandbox-callbacks): Connect the helper to Safaricom's Daraja sandbox, receive real payment callbacks on your local machine, and handle successful and failed payments.

### API Reference

- [POST /stk-push](https://mpesa-stk-helper.thally.app/api/stk-push): Send an M-Pesa STK push prompt to a phone number and receive a pending payment record.
- [GET /payments/{checkout_request_id}](https://mpesa-stk-helper.thally.app/api/payment-status): Poll for the current status of an STK push payment.
- [POST /callback/{secret}](https://mpesa-stk-helper.thally.app/api/callbacks): Receive Safaricom STK Push result notifications and update payment records.

### Reference

- [Configuration](https://mpesa-stk-helper.thally.app/configuration): Environment variables that control M-Pesa STK Push Helper, with types, defaults, and startup validation rules.