Skip to main content
GET
/
wallets
/
service
/
balance
Get service wallet balance
curl --request GET \
  --url https://api.palpluss.com/v1/wallets/service/balance \
  --header 'Authorization: Basic <encoded-value>'
{
  "success": true,
  "data": {
    "walletId": "e3f2a1b0-0000-0000-0000-000000000001",
    "tenantId": "b6fbe75f-ce87-4d44-b318-6cfdb8b7de4d",
    "currency": "KES",
    "availableBalance": 4250,
    "ledgerBalance": 4250,
    "updatedAt": "2026-03-01T10:00:00.000Z"
  },
  "requestId": "e3d4c5b6-0000-0000-0000-000000000000"
}

​
Service wallet overview

The service wallet holds pre-funded tokens used to pay PalPluss transaction fees. A fee is deducted from this balance each time you initiate an STK Push or B2C payout. If the balance reaches zero, payment requests return 402 INSUFFICIENT_SERVICE_BALANCE and no payments can be processed until you top up.

​
Monitoring balance

Poll this endpoint regularly to avoid running out of funds. A recommended approach:
  1. Check balance before each batch of payments.
  2. Set a minimum threshold alert in your application (e.g. alert when balance drops below KES 500).
  3. Trigger an automated top-up or notify your team when the threshold is breached.
curl https://api.palpluss.com/v1/wallets/service/balance \
  -u "$PALPLUSS_API_KEY:"

​
availableBalance vs ledgerBalance

FieldDescription
availableBalanceSpendable balance after pending deductions. Use this for fee sufficiency checks.
ledgerBalanceTotal balance including pending items.
In most cases these values are identical. They may differ briefly during high-throughput periods when multiple fee deductions are being processed simultaneously.

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>

Response

Service wallet balance.

​
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"