Small note while I am deep in mcp-african-markets: do not trust Daraja's sandbox to tell you the truth about idempotency.
In production, sending the same STK push request twice with the same reference is supposed to be rejected or deduplicated. In the sandbox, I have sent the same request three times in a row and had all three succeed as if they were new. The documentation describes the production behaviour. The sandbox just does not enforce it.
This matters because the whole point of giving an agent a payment tool is that it might retry. A network blip, a timeout, an agent that is not sure the first call went through: retries happen, and if your idempotency key is only theoretical, a sandbox test suite that is green tells you nothing about what happens the first time it matters.
What I am doing about it: keeping my own idempotency ledger client-side, independent of whatever Daraja does or does not enforce, and writing the test that deliberately sends a duplicate request before I trust any tool with real money. Sandbox green is not evidence. A duplicate request that gets caught by my own code is.