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",
  "callbackUrl": "https://yourserver.com/webhooks/topup"
}
'
{
  "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>",
    "resultCode": "<string>",
    "resultDescription": "<string>",
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z"
  },
  "requestId": "c1b2a3d4-e5f6-7890-abcd-ef1234567890"
}

​
How top-ups work

A top-up sends an STK Push to the phone number you specify. When the customer (typically you or your account administrator) enters their M-Pesa PIN, the amount is deposited into your service wallet. Top-up transactions appear in your transaction list with a WALLET_TOPUP type. The balance update happens after the STK callback is received from M-Pesa — usually within 1–2 minutes.

​
Idempotent retries

Use the Idempotency-Key header to safely retry a top-up request without creating duplicates: 
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",
    "callbackUrl": "https://yourserver.com/webhooks/topup"
  }'
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 (e.g. 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.
  • Set up a webhook handler for top-up results to update your balance display in real time.

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 to send the STK Push to.

Example:

"0712345678"

​
accountReference
string
required
Maximum string length: 12
Example:

"TOPUP-001"

​
transactionDesc
string
required

Description shown on the STK prompt.

Maximum string length: 13
Example:

"Wallet Top-Up"

​
callbackUrl
string<uri>
required

HTTPS URL for the top-up result notification.

Example:

"https://yourserver.com/webhooks/topup"

​
credentialId
string<uuid> | null

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"