Read balances
GET /balance: check funds and payout availability for your merchant.
Endpoint
GET /api/v1/balance
Required scope: balances:read. No request body or merchant identifier.
Request
curl --fail-with-body "$DERIPAY_API_BASE_URL/balance" \
-H "X-API-Key: $DERIPAY_API_KEY"Response
{
"data": {
"currency": "KES",
"available_minor": 500000,
"reserved_minor": 10000,
"funding_pending_minor": 0,
"payout_available_minor": 500000
}
}| Field | Meaning |
|---|---|
currency | KES |
available_minor | Merchant funds not reserved for in-progress payouts |
reserved_minor | Merchant funds committed to in-progress payouts |
funding_pending_minor | Legacy confirmed collection holds awaiting reconciliation; zero for new confirmed STK deposits |
payout_available_minor | The smaller of unreserved merchant funds and available merchant-owned B2C funds |
All values are integer cents. Divide by 100 for KES display.
Verified STK deposits increase available_minor and payout_available_minor immediately. funding_pending_minor is retained for legacy holds awaiting reconciliation. Unconfirmed STK requests do not increase any balance.
Use the right balance
Use payout_available_minor for payout availability and allow for applicable charges. Confirmed STK funds are immediately spendable, subject to payout amounts, fees, merchant limits and existing reservations.
The response is a snapshot. Concurrent requests can change it before a payout is accepted; the creation endpoint performs the authoritative reservation check.