M-Pesa Daraja

Build, review, test, or explain Safaricom M-Pesa Daraja API integrations for STK Push/Lipa na M-Pesa Online, C2B validation and confirmation, B2C payouts, transaction status, reversals, callbacks, credential setup, sandbox testing, and production-readiness. Use when Codex needs to create implementation plans, code, examples, mocks, test cases, troubleshooting steps, or security checks for M-Pesa payments in OpenClaw or client applications.

Operating Rules

• Treat this as a payment-integration skill, not permission to move money.
• Default to Daraja sandbox endpoints and test credentials unless the user explicitly asks for production guidance.
• Never store consumer secrets, passkeys, initiator passwords, security credentials, access tokens, callback payloads with phone numbers, or transaction IDs in committed files.
• Ask before calling any live/production endpoint or sending any request that could trigger a payment prompt, payout, reversal, or customer-facing callback.
• Prefer environment variables and secret managers over `.env` files in shared repos. If `.env.example` is needed, use placeholder values only.
• Make callbacks idempotent: verify request shape, persist raw event safely, deduplicate by CheckoutRequestID/ConversationID/TransactionID, then process business state transitions.

Workflow

1. Identify the payment flow:
   • STK Push / Lipa na M-Pesa Online for customer-initiated checkout.
   • C2B for paybill/till customer payments with validation and confirmation callbacks.
   • B2C for business payouts to customers or agents.
   • Transaction Status / Reversal for reconciliation and recovery.
2. Confirm runtime context: language/framework, sandbox vs production, callback URL availability, persistence layer, and compliance constraints.
3. Design the integration around these boundaries:
   • token generation and caching
   • request signing/password generation
   • outbound Daraja client
   • callback receiver
   • idempotency/reconciliation
   • observability without leaking personal or payment data
4. Use `references/examples.md` when the user asks for sample OpenClaw prompts, implementation examples, or architecture snippets.
5. Use `references/test-cases.md` when the user asks for QA scenarios, unit tests, integration tests, sandbox tests, or production-readiness checks.
6. Use `scripts/validate_daraja_fixture.py` to sanity-check example STK Push request and callback JSON fixtures before writing tests around them.

Implementation Guidance

• Keep Daraja client code small and injectable so app tests can mock HTTP calls.
• Generate the STK password as `base64(shortcode + passkey + timestamp)` with timestamp format `YYYYMMDDHHmmss`.
• Use OAuth access tokens from Daraja and cache them until shortly before expiry.
• Expose public HTTPS callback URLs in sandbox using a stable tunnel or deployed test environment; avoid local-only callback URLs.
• Return fast from callbacks after durable persistence; do heavier fulfillment asynchronously when possible.
• Log correlation IDs, response codes, and internal order IDs. Mask phone numbers, names, access tokens, credentials, and raw security credentials.
• Model payment state explicitly, for example: `pending`, `prompt_sent`, `paid`, `failed`, `cancelled`, `expired`, `reversed`, `manual_review`.

Common OpenClaw Requests

• "Use $mpesa-daraja to add STK Push checkout to this Django app."
• "Use $mpesa-daraja to write sandbox test cases for our M-Pesa checkout."
• "Use $mpesa-daraja to review this Daraja callback handler for idempotency and secret leakage."
• "Use $mpesa-daraja to create an OpenClaw automation that drafts M-Pesa reconciliation reports without touching production APIs."

Deliverables To Prefer

• For implementation: client module, callback route, typed request/response models, masked logging, tests, and `.env.example`.
• For review: findings ordered by payment risk, security risk, idempotency/reconciliation risk, then code quality.
• For planning: flow diagram in text, endpoint list, secret list, callback contract, test plan, and production checklist.
• For troubleshooting: exact failing step, expected Daraja response, likely causes, and the smallest safe verification step.