M-Pesa Daraja

M-Pesa Daraja

This is an advisory/reference skill. It does not call Safaricom APIs, initiate payments, or require external account access to install or use.

Operating Rules

• Treat this as payment-integration guidance, not permission to move money.
• Default to Daraja sandbox endpoints and placeholder configuration unless the user explicitly asks for production guidance.
• Never store sensitive Daraja values, 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 protected deployment settings 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:

• Daraja session setup and caching
• request authorization value 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 \references/stk-push.md\ for STK Push/Lipa na M-Pesa Online implementation details.

7. Use \references/api-endpoints.md\ when the user needs current Daraja endpoint names, versions, or flow coverage.

8. Use \references/production-readiness.md\ before production-readiness reviews, client handoff, or launch checklists.

9. Use \references/maintenance.md\ before updating or publishing this skill. Always check official Safaricom/Daraja sources for API changes, update the version, and run validation before pushing to ClawHub.

Implementation Guidance

• Keep Daraja client code small and injectable so app tests can mock HTTP calls.
• Follow Safaricom's current STK authorization formula with timestamp format \YYYYMMDDHHmmss\.
• Cache Daraja authorization sessions 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, and all sensitive Daraja values.
• 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 sensitive-data 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, configuration list, callback contract, test plan, and production checklist.
• For troubleshooting: exact failing step, expected Daraja response, likely causes, and the smallest safe verification step.