Transaction status

Retrieve a transaction

GET /api/v1/transactions/{uuid}

Read the current state of one transaction. This is the endpoint to poll (or call from your webhook handler) before you fulfil an order.

Non-terminal transactions are live-reconfirmed with M-Pesa while you poll — at most once every 10 seconds per transaction — so a success shows up here within seconds of the payment settling, with no callback or background job required. list responses come straight from our database and may lag; poll this endpoint for freshness.

curl "https://fortpesa.co.ke/api/v1/transactions/9f1c4a5e-2f77-4a0e-9c3b-1d5f6a7b8c9d" \
  -H "Authorization: Bearer pb_live_YOUR_KEY"

const res = await fetch(
  "https://fortpesa.co.ke/api/v1/transactions/" + uuid,
  { headers: { Authorization: "Bearer pb_live_YOUR_KEY" } }
);
const body = await res.json();
if (res.status === 404) { /* not found (or not yours) */ }
console.log(body.data.status, body.data.failure_code);

import requests

res = requests.get(
    f"https://fortpesa.co.ke/api/v1/transactions/{uuid}",
    headers={"Authorization": "Bearer pb_live_YOUR_KEY"},
    timeout=30,
)
tx = res.json()["data"]
print(tx["status"], tx["failure_code"])

use GuzzleHttp\Client;

$client = new Client();
$res = $client->get(
    'https://fortpesa.co.ke/api/v1/transactions/'.$uuid,
    ['headers' => ['Authorization' => 'Bearer pb_live_YOUR_KEY']]
);
$tx = json_decode((string) $res->getBody(), true)['data'];

Response

200 OK — same transaction object shape as Create STK Push:

{
  "data": {
    "uuid": "9f1c4a5e-2f77-4a0e-9c3b-1d5f6a7b8c9d",
    "amount": 150,
    "currency": "KES",
    "platform_fee": 6,
    "phone": "0712345678",
    "account_reference": "INV-2041",
    "status": "success",
    "failure_code": null,
    "channel_id": 42,
    "provider_transaction_id": "ptx_8a3f9c21",
    "created_at": "2026-09-25T14:03:22+00:00",
    "settled_at": "2026-09-25T14:03:51+00:00"
  }
}

404 NOT_FOUND is returned when the UUID does not exist or belongs to another merchant — the API never leaks cross-tenant data.

Status lifecycle

Status	Terminal?	Meaning
`initiating`	no	Transaction recorded; provider call in flight.
`pending`	no	Provider accepted — customer sees the M-Pesa prompt.
`processing`	no	Customer acted; we are confirming the result.
`success`	yes	Payment collected.
`failed`	yes	Customer declined / provider rejected. `failure_code` explains why.
`cancelled`	yes	Payment was cancelled.
`expired`	yes	No result within the confirmation window. `failure_code`: `POLL_TIMEOUT`.
`reversed`	yes	A collected payment was reversed.

Pending transactions are confirmed from three directions: your polls (live, deduped to once per 10s), the signed STK callback from M-Pesa, and a background poll chain — and if no result ever arrives the chain gives up after 30 checks and marks the transaction expired. So every transaction reaches a terminal state, and your webhook always fires exactly once per terminal transition.

Treat any non-terminal status as “keep waiting”: continue polling or wait for the webhook.

List transactions

GET /api/v1/transactions

Your most recent transactions, newest first.

string

Optional filter — one of initiating, pending, processing, success, failed, cancelled, expired, reversed.

integer

default:50

How many transactions to return (newest first).

curl "https://fortpesa.co.ke/api/v1/transactions?status=success&per_page=25" \
  -H "Authorization: Bearer pb_live_YOUR_KEY"

const res = await fetch(
  "https://fortpesa.co.ke/api/v1/transactions?status=success&per_page=25",
  { headers: { Authorization: "Bearer pb_live_YOUR_KEY" } }
);
const { data } = await res.json();

import requests

txs = requests.get(
    "https://fortpesa.co.ke/api/v1/transactions",
    headers={"Authorization": "Bearer pb_live_YOUR_KEY"},
    params={"status": "success", "per_page": 25},
    timeout=30,
).json()["data"]

use GuzzleHttp\Client;

$client = new Client();
$txs = json_decode((string) $client->get(
    'https://fortpesa.co.ke/api/v1/transactions',
    [
        'headers' => ['Authorization' => 'Bearer pb_live_YOUR_KEY'],
        'query' => ['status' => 'success', 'per_page' => 25],
    ]
)->getBody(), true)['data'];

Response

200 OK

{
  "data": [
    {
      "uuid": "9f1c4a5e-2f77-4a0e-9c3b-1d5f6a7b8c9d",
      "amount": 150,
      "status": "success",
      "created_at": "2026-09-25T14:03:22+00:00",
      "...": "same fields as a single transaction"
    }
  ]
}

Get started

API reference

Guides

Libraries & SDKs

AI agents

Transaction status

Retrieve a transaction

Response

Status lifecycle

List transactions

Response

​Retrieve a transaction

​Response

​Status lifecycle

​List transactions

​Response

Retrieve a transaction

Response

Status lifecycle

List transactions

Response