Quickstart

Get from zero to a completed payment in three steps.

Create an API key

Sign in to your Fortpesa dashboard and open Settings → API keys. Create a key — it is shown once, so copy it immediately.

Keys are tied to your merchant account. Never embed keys in client-side code — call the Fortpesa API from your server.

Initiate an STK Push

Prompt the customer’s phone for a payment. This example charges KES 150 (15000 minor units):

Your merchant account needs an approved payment channel (request one under Channels in the dashboard) and prepaid wallet balance for platform fees — otherwise the request fails with 503 or 402 INSUFFICIENT_CREDIT.

curl -X POST "https://fortpesa.co.ke/api/v1/payments/stk" \
  -H "Authorization: Bearer pb_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 15000,
    "phone": "0712345678",
    "account_reference": "INV-2041"
  }'

const res = await fetch("https://fortpesa.co.ke/api/v1/payments/stk", {
  method: "POST",
  headers: {
    Authorization: "Bearer pb_live_YOUR_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    amount: 15000,
    phone: "0712345678",
    account_reference: "INV-2041",
  }),
});

const body = await res.json();
if (!res.ok) throw new Error(body.error?.message ?? "Request failed");
console.log(body.data.uuid, body.data.status); // e.g. "…", "pending"

import requests

res = requests.post(
    "https://fortpesa.co.ke/api/v1/payments/stk",
    headers={"Authorization": "Bearer pb_live_YOUR_KEY"},
    json={
        "amount": 15000,
        "phone": "0712345678",
        "account_reference": "INV-2041",
    },
    timeout=30,
)
body = res.json()
if res.status_code != 201:
    raise RuntimeError(body["error"]["message"])

print(body["data"]["uuid"], body["data"]["status"])  # "…", "pending"

use GuzzleHttp\Client;

$client = new Client();
$res = $client->post('https://fortpesa.co.ke/api/v1/payments/stk', [
    'headers' => ['Authorization' => 'Bearer pb_live_YOUR_KEY'],
    'json' => [
        'amount' => 15000,
        'phone' => '0712345678',
        'account_reference' => 'INV-2041',
    ],
]);

$tx = json_decode((string) $res->getBody(), true)['data'];
echo $tx['uuid'] . ' ' . $tx['status'];  // "… pending"

You get 201 Created with a transaction whose status is pending — the customer now sees an M-Pesa prompt on their phone.

Wait for the result

A payment reaches a final (terminal) state within a couple of minutes. Get notified in one of two ways:

Webhooks (recommended) — we POST a signed transaction.success / transaction.failed event to your endpoint. See Webhooks.

Polling — repeatedly read the transaction until its status is terminal:

curl "https://fortpesa.co.ke/api/v1/transactions/TRANSACTION_UUID" \
  -H "Authorization: Bearer pb_live_YOUR_KEY"

const res = await fetch(
  "https://fortpesa.co.ke/api/v1/transactions/TRANSACTION_UUID",
  { headers: { Authorization: "Bearer pb_live_YOUR_KEY" } }
);
const { data } = await res.json();
console.log(data.status); // pending → processing → success/failed/…

import requests, time

while True:
    tx = requests.get(
        "https://fortpesa.co.ke/api/v1/transactions/TRANSACTION_UUID",
        headers={"Authorization": "Bearer pb_live_YOUR_KEY"},
        timeout=30,
    ).json()["data"]
    if tx["status"] in ("success", "failed", "cancelled", "expired", "reversed"):
        break
    time.sleep(3)

Next steps

Authentication — keys, headers, rate limits
Create STK Push — full request and error reference
Webhooks — verify signatures and handle events

Get started

API reference

Guides

Next steps

​Next steps

Next steps