Docs / API reference

Wallets

Where your money sits. Assign shortcodes to a wallet and payments to them land there.

The Wallet object

A balance in KES that collections land in and payouts leave from. You can have as many as you need, for example one per shop or a separate payroll float.

Attributes

idstring
Unique identifier, starting wal_.
namestring
A name you choose.
balanceinteger
Available balance in the smallest unit.
pendinginteger
Pending in, not yet available.
heldinteger
Reserved for payouts that are waiting for approval or still being sent. Not available to spend.
statusstring
Locked and suspended wallets cannot send payouts. Dormant wallets have had no activity for 90 days.
One of active, suspended, locked, dormant
frozenboolean
A frozen wallet takes no payments and sends no payouts.
shortcode_idsstring[]
Shortcodes assigned to this wallet.
created_atstring
ISO 8601 timestamp.

Example object

{
  "id": "wal_main",
  "object": "wallet",
  "name": "Main collections",
  "currency": "KES",
  "balance": 128450000,
  "pending": 4230000,
  "held": 0,
  "status": "active",
  "frozen": false,
  "shortcode_ids": [
    "sc_4012345",
    "sc_5567890"
  ],
  "livemode": false,
  "created_at": "2026-06-12T09:00:00+03:00"
}

POST/v1/wallets

Create a wallet

Add a wallet.

Headers

Idempotency-Keystring
A unique value per logical request, up to 255 characters. Retrying with the same key returns the original result instead of creating a second one.

Body parameters

namestringrequired
A name you choose.
currencystring
Always KES.
One of KES

Errors

400 invalid_request
403 permission_denied

See Errors for what each means.

curl -X POST "$PITISHA_API/v1/wallets" \
  -H "Authorization: Bearer $PITISHA_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-attempt-1" \
  -d '{
    "name": "Online shop",
    "currency": "KES"
  }'

{
  "id": "wal_main",
  "object": "wallet",
  "name": "Online shop",
  "currency": "KES",
  "balance": 0,
  "pending": 0,
  "held": 0,
  "status": "active",
  "frozen": false,
  "shortcode_ids": [],
  "livemode": false,
  "created_at": "2026-06-12T09:00:00+03:00"
}

GET/v1/wallets

List wallets

All wallets in this mode.

Query parameters

limitinteger
How many items to return, from 1 to 100. Defaults to 20.
starting_afterstring
A cursor from a previous response's next_cursor. Returns the next page.

Errors

401 authentication_failed

See Errors for what each means.

curl -X GET "$PITISHA_API/v1/wallets" \
  -H "Authorization: Bearer $PITISHA_SECRET_KEY"

{
  "object": "list",
  "data": [
    {
      "id": "wal_main",
      "object": "wallet",
      "name": "Main collections",
      "currency": "KES",
      "balance": 128450000,
      "pending": 4230000,
      "held": 0,
      "status": "active",
      "frozen": false,
      "shortcode_ids": [
        "sc_4012345",
        "sc_5567890"
      ],
      "livemode": false,
      "created_at": "2026-06-12T09:00:00+03:00"
    }
  ],
  "has_more": true,
  "next_cursor": "cur_9fK2mQ"
}

GET/v1/wallets/{id}

Retrieve a wallet

Fetch one wallet and its balance.

Path parameters

idstringrequired
The wallet id.

Errors

404 not_found

See Errors for what each means.

curl -X GET "$PITISHA_API/v1/wallets/ID_FROM_RESPONSE" \
  -H "Authorization: Bearer $PITISHA_SECRET_KEY"

{
  "id": "wal_main",
  "object": "wallet",
  "name": "Main collections",
  "currency": "KES",
  "balance": 128450000,
  "pending": 4230000,
  "held": 0,
  "status": "active",
  "frozen": false,
  "shortcode_ids": [
    "sc_4012345",
    "sc_5567890"
  ],
  "livemode": false,
  "created_at": "2026-06-12T09:00:00+03:00"
}

PATCH/v1/wallets/{id}

Update a wallet

Rename or freeze a wallet.

Path parameters

idstringrequired
The wallet id.

Body parameters

namestring
A new name.
frozenboolean
Freeze or unfreeze.

Errors

404 not_found
403 permission_denied

See Errors for what each means.

curl -X PATCH "$PITISHA_API/v1/wallets/ID_FROM_RESPONSE" \
  -H "Authorization: Bearer $PITISHA_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "frozen": true
  }'

{
  "id": "wal_main",
  "object": "wallet",
  "name": "Main collections",
  "currency": "KES",
  "balance": 128450000,
  "pending": 4230000,
  "held": 0,
  "status": "active",
  "frozen": true,
  "shortcode_ids": [
    "sc_4012345",
    "sc_5567890"
  ],
  "livemode": false,
  "created_at": "2026-06-12T09:00:00+03:00"
}