M-Pesa Daraja

Dev Tools

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.

Install

openclaw skills install mpesa-daraja

M-Pesa Daraja

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.