Top Up Service Wallet

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"
}
'

import requests

url = "https://api.palpluss.com/v1/wallets/service/topups"

payload = {
    "amount": 500,
    "phone": "0712345678",
    "accountReference": "TOPUP-2024-001",
    "transactionDesc": "Service wallet top-up"
}
headers = {
    "Authorization": "Basic <encoded-value>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    amount: 500,
    phone: '0712345678',
    accountReference: 'TOPUP-2024-001',
    transactionDesc: 'Service wallet top-up'
  })
};

fetch('https://api.palpluss.com/v1/wallets/service/topups', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.palpluss.com/v1/wallets/service/topups",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'amount' => 500,
    'phone' => '0712345678',
    'accountReference' => 'TOPUP-2024-001',
    'transactionDesc' => 'Service wallet top-up'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Basic <encoded-value>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.palpluss.com/v1/wallets/service/topups"

	payload := strings.NewReader("{\n  \"amount\": 500,\n  \"phone\": \"0712345678\",\n  \"accountReference\": \"TOPUP-2024-001\",\n  \"transactionDesc\": \"Service wallet top-up\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Basic <encoded-value>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.palpluss.com/v1/wallets/service/topups")
  .header("Authorization", "Basic <encoded-value>")
  .header("Content-Type", "application/json")
  .body("{\n  \"amount\": 500,\n  \"phone\": \"0712345678\",\n  \"accountReference\": \"TOPUP-2024-001\",\n  \"transactionDesc\": \"Service wallet top-up\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.palpluss.com/v1/wallets/service/topups")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Basic <encoded-value>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"amount\": 500,\n  \"phone\": \"0712345678\",\n  \"accountReference\": \"TOPUP-2024-001\",\n  \"transactionDesc\": \"Service wallet top-up\"\n}"

response = http.request(request)
puts response.read_body

{
  "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"
}

{
  "success": false,
  "error": {
    "message": "Invalid phone number format.",
    "code": "INVALID_PHONE",
    "details": {}
  },
  "requestId": "a1b2c3d4-0000-0000-0000-000000000000"
}

{
  "success": false,
  "error": {
    "message": "Invalid or revoked API key.",
    "code": "INVALID_API_KEY",
    "details": {}
  },
  "requestId": "a1b2c3d4-0000-0000-0000-000000000000"
}

{
  "success": false,
  "error": {
    "message": "Rate limit exceeded. Try again in 12 seconds.",
    "code": "RATE_LIMIT_EXCEEDED",
    "details": {
      "limit": 60,
      "remaining": 0,
      "resetInSeconds": 12
    }
  },
  "requestId": "a1b2c3d4-0000-0000-0000-000000000000"
}

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"
}
'

import requests

url = "https://api.palpluss.com/v1/wallets/service/topups"

payload = {
    "amount": 500,
    "phone": "0712345678",
    "accountReference": "TOPUP-2024-001",
    "transactionDesc": "Service wallet top-up"
}
headers = {
    "Authorization": "Basic <encoded-value>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    amount: 500,
    phone: '0712345678',
    accountReference: 'TOPUP-2024-001',
    transactionDesc: 'Service wallet top-up'
  })
};

fetch('https://api.palpluss.com/v1/wallets/service/topups', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.palpluss.com/v1/wallets/service/topups",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'amount' => 500,
    'phone' => '0712345678',
    'accountReference' => 'TOPUP-2024-001',
    'transactionDesc' => 'Service wallet top-up'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Basic <encoded-value>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.palpluss.com/v1/wallets/service/topups"

	payload := strings.NewReader("{\n  \"amount\": 500,\n  \"phone\": \"0712345678\",\n  \"accountReference\": \"TOPUP-2024-001\",\n  \"transactionDesc\": \"Service wallet top-up\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Basic <encoded-value>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.palpluss.com/v1/wallets/service/topups")
  .header("Authorization", "Basic <encoded-value>")
  .header("Content-Type", "application/json")
  .body("{\n  \"amount\": 500,\n  \"phone\": \"0712345678\",\n  \"accountReference\": \"TOPUP-2024-001\",\n  \"transactionDesc\": \"Service wallet top-up\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.palpluss.com/v1/wallets/service/topups")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Basic <encoded-value>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"amount\": 500,\n  \"phone\": \"0712345678\",\n  \"accountReference\": \"TOPUP-2024-001\",\n  \"transactionDesc\": \"Service wallet top-up\"\n}"

response = http.request(request)
puts response.read_body

{
  "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"
}

{
  "success": false,
  "error": {
    "message": "Invalid phone number format.",
    "code": "INVALID_PHONE",
    "details": {}
  },
  "requestId": "a1b2c3d4-0000-0000-0000-000000000000"
}

{
  "success": false,
  "error": {
    "message": "Invalid or revoked API key.",
    "code": "INVALID_API_KEY",
    "details": {}
  },
  "requestId": "a1b2c3d4-0000-0000-0000-000000000000"
}

{
  "success": false,
  "error": {
    "message": "Rate limit exceeded. Try again in 12 seconds.",
    "code": "RATE_LIMIT_EXCEEDED",
    "details": {
      "limit": 60,
      "remaining": 0,
      "resetInSeconds": 12
    }
  },
  "requestId": "a1b2c3d4-0000-0000-0000-000000000000"
}

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

Paste your PalPluss API key in the username field and leave the password field empty — it is ignored.

Get your key from console → Settings → API Keys (starts with pk_live_ or pk_test_).

In your own code, send the key directly: Authorization: Basic YOUR_API_KEY

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.

Show child attributes

requestId

string<uuid>

required

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

Example:

"c1b2a3d4-e5f6-7890-abcd-ef1234567890"

Get Service Wallet Balance Create Payment Channel

Get Started

Guides

SDKs

STK Push

Transactions

B2C Payouts

Service Wallet

Payment Channels

Top Up Service Wallet

How it works

Idempotent retries

When to top up

Authorizations

Headers

Body

Response

​How it works

​Idempotent retries

​When to top up

Authorizations

Headers

Body

Response

How it works

Idempotent retries

When to top up