Wallet and Billing

Summary

Sautikit uses a prepaid wallet model denominated in Kenyan shillings (KES). Every charge (call cost, number rental, or storage) creates an immutable ledger entry. The wallet balance is a cached sum of all ledger entries. When the balance reaches zero, outbound calls are blocked and number rentals will not renew until you top up.

Wallet currency

Each workspace has exactly one wallet, locked to a single currency at creation. For workspaces registered in Kenya the currency is KES. The currency cannot be changed after the workspace is created.

All amounts in the API use minor units (lowest denomination). For KES: 1 KES = 100 minor units. An amount of 50000 minor units = KES 500.00.

Topping up

Top up via:

• M-Pesa STK push (API-initiated): POST /v1/topups with provider: "mpesa" and a phone_e164. An STK push prompt arrives on that phone within seconds; the wallet credits as soon as M-Pesa confirms.
• M-Pesa Paybill (manual): pay via the Paybill menu using your workspace's account reference (TS-XXXXXXXX). No API call needed. The platform reconciles the payment automatically from the M-Pesa callback.

# M-Pesa STK push: the most common path for in-Kenya teams.
curl -X POST "https://api.sautikit.com/v1/topups" \
  -H "Authorization: Bearer $SAUTIKIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "mpesa",
    "amount_minor": 500000,
    "currency": "KES",
    "phone_e164": "+254722000001"
  }'

Why phone_e164 is required for M-Pesa: the STK push is Safaricom's "send a confirmation prompt to a specific SIM" protocol. Without a phone number there's no way to deliver the prompt. The number does NOT have to belong to a Sautikit user; one finance person can fund many workspaces from their own M-Pesa-registered phone.

The response includes a topup_id and mpesa_account_ref so your UI can also display the manual Paybill instructions as a fallback. The wallet balance updates automatically when M-Pesa confirms.

Ledger semantics

The wallet ledger is append-only. Every balance change (debit or credit) creates a new wallet_ledger entry with:

Ledger entry kinds:

You can list your ledger via GET /v1/wallet/statements for a full audit trail.

Balance check

curl "https://api.sautikit.com/v1/wallet/balance" \
  -H "Authorization: Bearer $SAUTIKIT_API_KEY"

{
  "workspace_id": "01900000-0000-7000-8000-000000000001",
  "balance_minor": 250000,
  "currency": "KES",
  "low_balance_threshold_minor": 100000
}

balance_minor is the cached value from the wallets table, updated atomically on each ledger write. It reflects the true balance within the consistency guarantees of a single PostgreSQL database.

Low-balance alerts

Set a threshold below which you want to receive a wallet.low_balance webhook event:

curl -X PATCH "https://api.sautikit.com/v1/wallet/threshold" \
  -H "Authorization: Bearer $SAUTIKIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"threshold_minor": 100000}'

When the balance drops at or below the threshold during a call charge or rental, the platform emits a wallet.low_balance webhook event to any active subscriptions. The notification is rate-limited to once per 24 hours per workspace to avoid alert fatigue.

Suggested threshold for a workspace running 5 numbers: KES 500 (50000 minor units), enough for roughly 166 minutes of outbound calls at the standard rate (KES 3/min). Inbound calls are free and do not draw down the balance.

Alert subscribers

Beyond the wallet.low_balance webhook, you can configure email recipients who receive a notification when the wallet crosses your low-balance threshold. Useful when finance and engineering are different people.

Manage subscribers via the API:

# List current subscribers
curl https://api.sautikit.com/v1/wallet/alert/subscribers \
  -H "Authorization: Bearer $SAUTIKIT_API_KEY"
 
# Add a recipient
curl -X POST https://api.sautikit.com/v1/wallet/alert/subscribers \
  -H "Authorization: Bearer $SAUTIKIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "finance@your-company.co.ke"}'
 
# Remove a recipient
curl -X DELETE https://api.sautikit.com/v1/wallet/alert/subscribers/{subscriber_id} \
  -H "Authorization: Bearer $SAUTIKIT_API_KEY"

Add up to 20 recipients per workspace. Each receives a single email when the balance drops below the threshold (debounced, so you won't get spammed during a sustained low-balance period). Emails are sent to verified addresses only; the first POST triggers an opt-in confirmation that the recipient must accept before they receive alerts.

You can also manage subscribers via the console at Settings → Wallet → Alert recipients.

Low-balance behaviour

The balance can briefly go below zero by at most one call's cost, because the debit is applied at hangup rather than at call initiation.

Trial credit

New workspaces may receive a one-time trial credit provisioned by Sautikit support. The credit appears as a trial_credit ledger entry. Trial numbers provisioned alongside the credit have a trial_until expiry timestamp. When the trial ends, numbers auto-release and the remaining credit is not refunded.

Check whether your workspace has received trial credit:

curl "https://api.sautikit.com/v1/wallet/statements?kind=trial_credit" \
  -H "Authorization: Bearer $SAUTIKIT_API_KEY"

Next steps

• Wallet API reference
• Place your first call
• Numbers and rental billing