For agent-assisted Daraja builders

Officially reviewed Daraja context for every coding agent.

Install a Daraja/M-Pesa engineering kit with 24 page-by-page Safaricom API reviews, endpoint indexes, backend templates, callback fixtures, reconciliation rules, credential helpers, doctor checks, and runnable STK, C2B, and B2C samples.

npx daraja-skills install

Codex Cursor Gemini CLI Antigravity Claude Code AGENTS.md

What ships

The pieces developers actually need after the first API call.

Daraja Skills gives coding agents the workflow and files they usually miss: reviewed endpoint references, secure backend scaffolds, callback evidence, reconciliation, go-live checks, and runnable examples.

Reviewed official pages

Each Safaricom API page is reviewed as its own source: endpoint facts, request and response shape, callbacks, security needs, implementation obligations, and gaps.

Backend templates

Copy-paste Next.js Route Handlers, Express, FastAPI, and Laravel templates that keep secrets server-side and persist intents before Daraja calls.

Callbacks and reconciliation

Illustrative fixtures, parser expectations, Postgres starter tables, duplicate handling, ambiguous-state handling, and callback-before-fulfillment rules.

Credential and go-live tooling

Security credential generation from Safaricom certificates plus a sandbox-to-production checklist for HTTPS callbacks, env separation, approvals, and audit.

Runnable sample apps

Node sample apps for STK, C2B, and B2C with local intent storage, callback endpoints, status routes, and safe offline defaults.

Error handling catalog

Result-code categories, acknowledgement boundaries, timeout handling, duplicate detection, and product-specific cautions where the reviewed page exposes them.

Official review coverage

Page-by-page coverage, not a generic M-Pesa cheat sheet.

The package keeps product pages, multi-endpoint pages, missing production URLs, and official-page discrepancies visible. Agents can load the exact reviewed page before generating code for that flow.

Getting Started Authorization Dynamic QR M-Pesa Express STK Push C2B B2C Transaction Status Account Balance Reversal Tax Remittance Business Pay Bill Business Buy Goods Bill Manager B2B Express Checkout Pull Transactions Business To Pochi Swap IMSI Lipa na Bonga Query Org Info B2C Account Top Up M-Pesa Ratiba IoT SIM Management

Adapter matrix

One installer, native files for each tool.

The wizard asks what you use and whether the install should be project-local or global. Non-interactive commands are explicit, so CI and setup docs do not guess where your agent reads context.

Interactive wizard npx daraja-skills install

Codex npx daraja-skills install --target codex --scope project --yes

Cursor npx daraja-skills install --target cursor --scope project --yes

Gemini CLI npx daraja-skills install --target gemini --scope project --yes

Antigravity npx daraja-skills install --target antigravity --scope project --yes

Claude Code npx daraja-skills install --target claude --scope project --yes

All project targets npx daraja-skills install --target all --scope project --yes

Inspect paths npx daraja-skills where --target all --scope project

Project installs go to the nearest Git root. Global installs are supported for Codex, Gemini CLI, Antigravity, Claude Code, Codex plugin packaging, and the Gemini extension; Cursor and AGENTS.md stay project-local.

Codex

Skill or plugin

Writes `.agents/skills/daraja-api` for direct use, or installs a Codex plugin with marketplace metadata when you target `codex-plugin`.

Cursor

Project rule

Adds `.cursor/rules/daraja-skills.mdc`, the project-native place Cursor expects repository rules.

Gemini CLI

Skill or extension

Writes `.gemini/skills/daraja-api` or `~/.gemini/skills/daraja-api`; the optional extension target installs `~/.gemini/extensions/daraja-skills`.

Antigravity

Agent skill

Writes the Daraja skill to `.agents/skills/daraja-api` for a workspace, or `~/.gemini/antigravity/skills/daraja-api` globally.

Claude Code

Claude skill

Copies the same `SKILL.md` package into `.claude/skills/daraja-api` for a repo or `~/.claude/skills/daraja-api` for personal use.

Generic agents

AGENTS.md

Optional root `AGENTS.md` for tools that read plain repository instructions instead of a dedicated skill registry.

Preflight

Catch broken Daraja setups before money moves.

The doctor checks flow-specific env vars, browser-exposed secrets, callback URL shape, production HTTPS rules, endpoint URL shape, and route reachability for the reviewed flow names.

Sandbox STK npx daraja-skills doctor --flow stk --env sandbox

Production B2C npx daraja-skills doctor --flow b2c --env production --probe

Security credential npx daraja-skills security-credential --cert ProductionCertificate.cer --password-env DARAJA_INITIATOR_PASSWORD

Why it matters

Most generated Daraja code fails after the first HTTP response.

Daraja integrations are payment systems, not endpoint snippets. The skill pushes agents to load the reviewed official page, keep credentials out of browser code, persist payment state, and wait for callbacks or reconciliation before declaring success.

Official page review firstEach API page has a reviewed source record, with category pages, multi-endpoint pages, and gaps kept visible.

Backend-only credentialsTemplates and doctor checks keep consumer secrets, passkeys, tokens, initiator passwords, and security credentials out of browser code.

Callback-first settlementSTK acknowledgements, C2B validation, and B2C request acceptance are not final success until callbacks or reconciliation confirm them.