Sign in

v1

latestOpenAPI 3.1.02026-07-2691531.2 KB
Service Wallet

Top up service wallet

Initiates an M-Pesa STK Push to top up your service wallet. The customer (typically yourself or your account admin) receives a PIN prompt and the credited amount is added to your service wallet balance on success.

Top-up transactions appear in your transaction list with type WALLET_TOPUP. The result is delivered asynchronously to your callbackUrl.

post/wallets/service/topups

Headers

Idempotency-Keystring

Optional unique key for idempotent retries. If a top-up with the same key was already processed, the original response is returned.

Request body

amountnumber required

Top-up amount in KES.

phonestring required

Phone number to send the STK Push prompt to.

accountReferencestring

Optional reference label for this top-up. Appears in the M-Pesa statement.

transactionDescstring

Optional description shown in your transaction history.

Example request

{
  "amount": 500,
  "phone": "0712345678",
  "accountReference": "TOPUP-001",
  "transactionDesc": "Service wallet top-up"
}

Response

Top-up STK Push accepted.

successboolean required
requestIdstring uuid required

Unique identifier for this API request. Include in support tickets.

Example response

{
  "success": true,
  "data": {
    "type": "STK",
    "status": "PENDING",
    "amount": 1000,
    "currency": "KES",
    "phone": "254712345678",
    "accountReference": "INV-2024-001",
    "transactionDesc": "Payment",
    "transactionFee": 2.5
  },
  "requestId": "c1b2a3d4-e5f6-7890-abcd-ef1234567890"
}