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
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.
Confirm runtime context: language/framework, sandbox vs production, callback URL availability, persistence layer, and compliance constraints.
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
Use \references/examples.md\ when the user asks for sample OpenClaw prompts, implementation examples, or architecture snippets.
Use \references/test-cases.md\ when the user asks for QA scenarios, unit tests, integration tests, sandbox tests, or production-readiness checks.
Use \references/stk-push.md\ for STK Push/Lipa na M-Pesa Online implementation details.
Use \references/api-endpoints.md\ when the user needs current Daraja endpoint names, versions, or flow coverage.
Use \references/production-readiness.md\ before production-readiness reviews, client handoff, or launch checklists.
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.