Skip to main content

TopUp initiates a wallet top-up via M-Pesa STK push.

POST 
/api/v1/billing/wallet/topup

Sends an STK push prompt to the specified phone number. User enters PIN on their phone to complete payment. Wallet is credited upon successful payment confirmation.

Authorization​

Requires billing:manage permission.

Behavior​

  • Initiates M-Pesa STK push to provided phone number
  • Returns immediately with checkout request ID
  • Wallet credited asynchronously on payment confirmation
  • Use PaymentService to check payment status

Validation​

  • Minimum amount: KES 10 (1000 cents)
  • Phone format: 254XXXXXXXXX (Kenyan format)

Errors​

  • INVALID_ARGUMENT: Amount below minimum or invalid phone
  • UNAVAILABLE: M-Pesa service temporarily unavailable

Request​

Responses​

A successful response.