Skip to main content
POST
/
wallets
/
service
/
topups
Top up service wallet
curl --request POST \
  --url https://api.palpluss.com/v1/wallets/service/topups \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount": 500,
  "phone": "0712345678",
  "accountReference": "TOPUP-2024-001",
  "transactionDesc": "Service wallet top-up"
}
'
{
  "success": true,
  "data": {
    "transactionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "tenantId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "channelId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "type": "STK",
    "status": "PENDING",
    "amount": 1000,
    "currency": "KES",
    "phone": "254712345678",
    "accountReference": "INV-2024-001",
    "transactionDesc": "Payment",
    "providerRequestId": "<string>",
    "providerCheckoutId": "<string>",
    "transactionFee": 2.5,
    "resultCode": "<string>",
    "resultDescription": "<string>",
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z"
  },
  "requestId": "c1b2a3d4-e5f6-7890-abcd-ef1234567890"
}
Fund your service wallet to keep payments running without interruption.

​
How it works

A top-up sends an STK Push to the phone number you specify. When the M-Pesa PIN is entered, the amount is deposited into your service wallet.
  • Top-ups appear in your transaction list with type WALLET_TOPUP
  • Balance updates after the STK callback is received from M-Pesa — usually within 1–2 minutes

​
Idempotent retries

Use Idempotency-Key to safely retry without creating duplicate top-ups. 
curl -X POST https://api.palpluss.com/v1/wallets/service/topups \
  -u "$PALPLUSS_API_KEY:" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: topup-2026-03-01-001" \
  -d '{
    "amount": 1000,
    "phone": "0712345678",
    "accountReference": "TOPUP-001",
    "transactionDesc": "Wallet Top-Up"
  }'
If a top-up with the same Idempotency-Key was already accepted, the original response is returned without initiating a new STK Push. Use a unique key per top-up attempt (include a date or sequence number).

​
When to top up

  • Top up before your balance drops below your minimum operating threshold
  • For high-volume operations, maintain a buffer of 2–5× your expected daily fee spend
  • The result is delivered asynchronously — poll GET /transactions/{id} to confirm the balance update

Authorizations

​
Authorization
string
header
required

Use your API key as the username. Leave the password field empty.

Authorization: Basic <base64(apikey:)>

You can also pass the raw API key:

Authorization: Basic <apikey>

Headers

​
Idempotency-Key
string

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

Body

application/json
​
amount
number
required

Top-up amount in KES.

Required range: x >= 1
Example:

500

​
phone
string
required

Phone number to send the STK Push prompt to.

Example:

"0712345678"

​
accountReference
string

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

Maximum string length: 120
Example:

"TOPUP-001"

​
transactionDesc
string

Optional description shown in your transaction history.

Maximum string length: 255
Example:

"Service wallet top-up"

Response

Top-up STK Push accepted.

​
success
boolean
required
Example:

true

​
data
object
required

Response payload. Shape varies by endpoint.

​
requestId
string<uuid>
required

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

Example:

"c1b2a3d4-e5f6-7890-abcd-ef1234567890"