API

Build / Limits and fees

Limits and fees

Limits protect your customers and Vukia's reserves. Each one returns a distinct error code, so your system can explain to the cashier what happened.

Fee

Vukia charges 3% of the amount the customer pays (fee_bps: 300), rounded up to the next cent. The fee comes out of the amount, so the customer pays exactly amount and nothing more. There is no monthly charge and no setup fee. Lightning routing fees are paid by Vukia.

Always read the fee from the order or from GET /v1/rates. Do not hard-code it. If the fee ever changes, we will email every production account before the change.

M-Pesa may charge the customer its own transaction fee, depending on how they pay. That is between the customer and Safaricom, and Vukia does not receive it.

Order amounts

LimitSandboxProduction
Minimum per orderKES 10KES 10
Maximum per orderKES 5,000KES 5,000
Per account, any 24 hoursKES 50,000Set when your account is approved, up to KES 50,000

The 24-hour limit is a rolling window. It counts every order created in the last 24 hours except those that ended payment_failed, because no money moved on those. GET /v1/account shows your limits. GET /v1/rates shows the maximum you can use right now as max_amount.

Vukia also has an overall daily volume across all accounts. When it is reached, new orders return daily_limit_reached with a message that says so, even if your own account has room.

Above the limit, the create request returns 422 amount_too_large or 429 daily_limit_reached. Nothing is charged.

Per-phone limit

One M-Pesa number can receive at most 3 payment requests in any 10 minutes, across all orders from your account, whatever their outcome. The 4th returns 429 phone_rate_limited with param: "phone".

This stops a mistake or a bad actor from flooding someone's phone with M-Pesa prompts. In practice it means: if a customer has failed to pay three times, stop and ask them to try again later, or to pay from another number.

Request rate

ScopeLimit
Per API key120 requests per minute
Per IP address300 requests per minute
Sandbox key creation, per IP address5 per minute

Over the limit returns 429 rate_limited. Polling one order every 3 seconds uses 20 requests a minute. If you poll many open orders at once, switch to webhooks instead.

Requests

Higher limits

KES 5,000 per order and KES 50,000 per account per 24 hours are the current ceilings. New production accounts may start lower and are raised towards the ceiling as their history builds. To ask for an increase, email [email protected] with the limits you need and your recent volume.