> ## Documentation Index
> Fetch the complete documentation index at: https://docs.palpluss.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Service Wallet Balance

> Check the current balance of your service wallet.

Know your balance before payments fail. Monitor this proactively.

## Service wallet

The service wallet holds pre-funded tokens used to pay PalPluss transaction fees. A fee is deducted each time you initiate an STK Push or B2C payout.

**If balance reaches zero**, payment requests return `402 INSUFFICIENT_SERVICE_BALANCE` — no payments process until you top up.

## `availableBalance` vs `ledgerBalance`

| Field              | Description                                                                      |
| ------------------ | -------------------------------------------------------------------------------- |
| `availableBalance` | Spendable balance after pending deductions. Use this for fee sufficiency checks. |
| `ledgerBalance`    | Total balance including pending items.                                           |

These values are identical in most cases. They may differ briefly during high-throughput periods when multiple fee deductions are processing simultaneously.

## Monitoring

```bash theme={null}
curl https://api.palpluss.com/v1/wallets/service/balance \
  -u "$PALPLUSS_API_KEY:"
```

**Recommended approach:**

* Check balance before each batch of payments
* Alert when balance drops below your minimum threshold (e.g. KES 500)
* Trigger an automated top-up or notify your team when the threshold is breached


## OpenAPI

````yaml GET /wallets/service/balance
openapi: 3.1.0
info:
  title: PalPluss API
  version: '1.0'
  summary: >-
    Payment infrastructure for Kenya — STK Push, B2C payouts, and wallet
    management.
  description: >
    The PalPluss API gives developers programmatic access to M-Pesa STK Push
    collections,

    B2C payouts, service wallet top-ups, and payment channel management.


    **Base URL:** `https://api.palpluss.com/v1`


    All requests must be authenticated with an API key using HTTP Basic Auth.

    All responses are wrapped in a standard envelope. See [Errors](#tag/errors)
    for error codes.


    Amounts are in **KES (Kenyan Shillings)** unless stated otherwise. Phone
    numbers

    are normalized to the `254XXXXXXXXX` format internally.
  contact:
    name: PalPluss Developer Support
    email: developer@palpluss.com
    url: https://palpluss.com/developers
servers:
  - url: https://api.palpluss.com/v1
    description: Production
  - url: https://sandbox.palpluss.com/v1
    description: Sandbox
security:
  - BasicAuth: []
tags:
  - name: STK Push
    description: >
      Initiate M-Pesa STK Push payment prompts. The customer receives a PIN
      prompt on their

      phone and confirms payment. PalPluss delivers the result asynchronously to
      your webhook URL.
  - name: Transactions
    description: >-
      Query the status of any transaction by ID, or list all transactions with
      filters.
  - name: B2C Payouts
    description: >
      Send money directly to a customer's M-Pesa number. Requires KYC approval
      and sufficient

      B2C wallet balance. Payouts are processed asynchronously.
  - name: Service Wallet
    description: >
      The service wallet holds pre-funded tokens used to pay PalPluss
      transaction fees.

      Top up via STK Push. Balance is deducted with each API call.
  - name: Payment Channels
    description: >
      Payment channels represent the M-Pesa shortcodes (Paybill / Till)
      associated with your

      account. Channels are used to route STK Push requests to a specific
      shortcode.
paths:
  /wallets/service/balance:
    get:
      tags:
        - Service Wallet
      summary: Get service wallet balance
      description: >
        Returns the current balance of your service wallet. The service wallet
        holds

        pre-funded tokens used to pay PalPluss transaction fees.


        Monitor this balance and top up before it reaches zero to avoid `402`
        errors

        on payment requests.
      operationId: getServiceWalletBalance
      responses:
        '200':
          description: Service wallet balance.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SuccessEnvelope'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/WalletBalance'
              examples:
                success:
                  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
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    SuccessEnvelope:
      type: object
      required:
        - success
        - data
        - requestId
      properties:
        success:
          type: boolean
          example: true
        data:
          type: object
          description: Response payload. Shape varies by endpoint.
        requestId:
          type: string
          format: uuid
          description: Unique identifier for this API request. Include in support tickets.
          example: c1b2a3d4-e5f6-7890-abcd-ef1234567890
    WalletBalance:
      type: object
      properties:
        walletId:
          type: string
          format: uuid
        tenantId:
          type: string
          format: uuid
        currency:
          type: string
          example: KES
        availableBalance:
          type: number
          format: decimal
          description: Spendable balance after pending holds.
          example: 4250
        ledgerBalance:
          type: number
          format: decimal
          description: Total credited balance including pending items.
          example: 4250
        updatedAt:
          type: string
          format: date-time
    ErrorEnvelope:
      type: object
      required:
        - success
        - error
        - requestId
      properties:
        success:
          type: boolean
          example: false
        error:
          type: object
          required:
            - message
            - code
          properties:
            message:
              type: string
              description: Human-readable error description.
              example: Invalid API key
            code:
              type: string
              description: Machine-readable error code.
              example: INVALID_API_KEY
            details:
              type: object
              description: Optional structured details about the error.
        requestId:
          type: string
          format: uuid
          example: c1b2a3d4-e5f6-7890-abcd-ef1234567890
  responses:
    Unauthorized:
      description: Missing, invalid, or revoked API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          examples:
            invalid_key:
              value:
                success: false
                error:
                  message: Invalid or revoked API key.
                  code: INVALID_API_KEY
                  details: {}
                requestId: a1b2c3d4-0000-0000-0000-000000000000
    RateLimited:
      description: Rate limit exceeded — 60 requests per minute per API key.
      headers:
        x-ratelimit-limit:
          schema:
            type: integer
          description: Maximum requests per minute.
        x-ratelimit-remaining:
          schema:
            type: integer
          description: Remaining requests in the current window.
        x-ratelimit-reset:
          schema:
            type: integer
          description: Unix timestamp when the window resets.
        Retry-After:
          schema:
            type: integer
          description: Seconds to wait before retrying.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          examples:
            rate_limited:
              value:
                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
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
      description: >
        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`

````