---
title: "Top up service wallet"
method: POST
path: "/wallets/service/topups"
tags: ["Service Wallet"]
---

# Top up service wallet

`POST /wallets/service/topups`

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`.

## Headers

- `Idempotency-Key` string

## Request body

- ServiceTopupRequest
  - `amount` number, required — Top-up amount in KES.
  - `phone` string, required — Phone number to send the STK Push prompt to.
  - `accountReference` string — Optional reference label for this top-up. Appears in the M-Pesa statement.
  - `transactionDesc` string — Optional description shown in your transaction history.

## Response `200`

Top-up STK Push accepted.

- object
  - `success` boolean, required
  - `data` object, required — Response payload. Shape varies by endpoint.
    - `transactionId` string, uuid
    - `tenantId` string, uuid
    - `channelId` string, uuid, nullable
    - `type` string
    - `status` string
    - `amount` number
    - `currency` string
    - `phone` string
    - `accountReference` string
    - `transactionDesc` string
    - `providerRequestId` string, nullable
    - `providerCheckoutId` string, nullable
    - `transactionFee` number — Service wallet fee charged for this request in KES. `0` when no pricing rule is configured or the transaction did not succeed.
    - `resultCode` string, nullable
    - `resultDescription` string, nullable
    - `createdAt` string, date-time
    - `updatedAt` string, date-time
  - `requestId` string, uuid, required — Unique identifier for this API request. Include in support tickets.

## Other responses

- `400` — Validation error — check the request body or parameters.
- `401` — Missing, invalid, or revoked API key.
- `429` — Rate limit exceeded — 60 requests per minute per API key.

---

[API](https://skmtc.dev/palpluss/apis/palpluss-api.md) · [All operations](https://skmtc.dev/palpluss/apis/palpluss-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/palpluss/palpluss-api/revisions/33fd40a3b314/schema)