AI coding agents (ChatGPT, Claude Code, opencode, Cursor, and others) can integrate Fortpesa payments into your app for you. This page gives them everything they need: a machine-readable skill file and a copy-paste starter prompt.

​
How it works

  1. Your agent fetches the skill file (a dense, self-contained integration guide).
  2. You tell it your stack and what you need (STK checkout, payment links, webhooks).
  3. It writes the code, reads FORTPESA_API_KEY from your environment, and walks you through a test payment.
The skill file is the single source of truth for agents. It covers authentication, required fields, whole-shilling amounts, idempotency, webhook HMAC verification, and the error codes you will actually see.

​
Starter prompt

Copy this into any AI agent that can fetch a URL:
That is the whole prompt — the skill file is self-contained and tells the agent the rest (STK Push, payment links, webhooks, whole-shilling amounts, 254… phones, error handling). The agent reads FORTPESA_API_KEY (and FORTPESA_WEBHOOK_SECRET if you want webhooks) from your environment; channel_id comes from your Fortpesa Channels page. If your agent can’t fetch URLs, open the link and paste the file into chat instead.

​
Per-agent setup

ChatGPT / Claude (web)

Paste the starter prompt above. The agent fetches the skill URL over HTTP — no local install needed.

Claude Code

Save the skill as .claude/skills/fortpesa/SKILL.md in your project (or ~/.claude/skills/fortpesa/SKILL.md globally). Fetch it with curl, or copy from the raw link.

opencode

Save as .opencode/skills/fortpesa/SKILL.md in your project, or ~/.agents/skills/fortpesa/SKILL.md for all projects. The agent discovers it on the next session.

Cursor / Windsurf / Codex

Paste the starter prompt into chat, or drop the skill content into your project rules / AGENTS.md so the agent always has it.

​
The skill file

The full, machine-readable integration guide lives at one stable URL: https://fortpesa.co.ke/skill It is plain Markdown, versioned with the rest of the docs, and updated whenever the API changes. Agents should treat it as authoritative over any older training data.

​
What the agent will build

A minimal, production-safe integration:
  • STK Push checkout — customer enters their phone, agent’s backend calls POST /payments/stk with an idempotency key, customer sees the M-Pesa prompt.
  • Status polling — the app polls GET /transactions/{uuid} (or uses webhooks) and shows success / failure to the customer.
  • Webhook receiver (optional but recommended) — verifies the HMAC signature against the raw body, then re-fetches the transaction before fulfilling the order.
For a no-code path, the agent can instead guide the user to create a payment link in the Fortpesa dashboard and embed https://fortpesa.co.ke/pay/{uuid} — no API key in the browser.

​
Full documentation

Prefer to read the human docs yourself, or need detail beyond the skill?
  • Quickstart — first STK Push in five minutes
  • STK Push API — full request / response reference
  • Webhooks — signed event delivery and verification
  • PHP SDK — official client library
  • Errors — every error code and what it means