Service wallet balance

GET /api/v1/wallet/balance

Platform fees are prepaid from your service wallet: every STK Push reserves its fee from this balance. Read the balance to decide when to top up.

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

const res = await fetch("https://fortpesa.co.ke/api/v1/wallet/balance", {
  headers: { Authorization: "Bearer pb_live_YOUR_KEY" },
});
const { data } = await res.json();
console.log(data.balance, data.currency); // 482 "KES"

import requests

data = requests.get(
    "https://fortpesa.co.ke/api/v1/wallet/balance",
    headers={"Authorization": "Bearer pb_live_YOUR_KEY"},
    timeout=30,
).json()["data"]

use GuzzleHttp\Client;

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

Response

200 OK

{
  "data": {
    "merchant_id": 12,
    "balance": 482,
    "currency": "KES"
  }
}

integer

Available prepaid balance in whole KES — 482 = KES 482.

If the balance cannot cover an STK fee, Create STK Push fails with 402 INSUFFICIENT_CREDIT — so top up whenever this number gets low.

Top up your service wallet

Top-ups are requested from the Fortpesa dashboard (there is no top-up API endpoint) and are free — no platform fee applies to topping up:

Sign in to your dashboard and open Wallet & top-ups in the sidebar.
Enter the amount in whole KES and the M-Pesa phone that should receive the prompt.
Press Send STK push and approve the prompt on your phone. The payment settles on Fortpesa’s M-Pesa collection account.
The service wallet balance updates automatically once M-Pesa confirms — usually within seconds. Read it again with the endpoint above to confirm.

A prompt that is never completed does not credit anything.

Get started

API reference

Guides

Libraries & SDKs

AI agents

Service wallet balance

Response

Top up your service wallet

​Response

​Top up your service wallet

Response

Top up your service wallet