API

Build / Errors

Errors

Errors use standard HTTP status codes and a JSON body with a stable code. Write your logic against code. The message is plain English and may be reworded.

Error shape

{
  "error": {
    "code": "invalid_amount",
    "message": "M-Pesa only collects whole shillings. Use a multiple of 100.",
    "param": "amount",
    "request_id": "req_166084a8410d136c57f2e5cb"
  }
}
FieldDescription
codeStable, machine-readable. Listed below.
messageWhat went wrong and how to fix it. Fine to log. Many messages are also fine to show a cashier.
paramThe request field at fault, when there is one. Use it to highlight the field on your form.
request_idThe same value as the Vukia-Request-Id header. Quote it when you contact us.

Request problems

Fix the request before sending it again.

StatusCodeCause
400invalid_jsonThe body is not valid JSON, or is not a JSON object.
400unknown_parameterA field the endpoint does not accept. param names it.
400idempotency_key_requiredPOST /v1/orders was sent without a valid Idempotency-Key (8 to 100 characters: letters, digits, _ . : -).
400invalid_amountNot an integer, or not a multiple of 100 cents.
400invalid_currencycurrency was sent and is not KES.
400invalid_phoneNot a Kenyan mobile number in a recognised format.
400invalid_lightning_addressNot in the form name@domain.
400invalid_payment_methodNot mpesa_prompt or mpesa_paybill.
400invalid_referenceLonger than 64 characters, or uses other characters.
400invalid_emailcustomer_email is not a valid address.
400invalid_metadataMore than 10 keys, a key that is too long, or a value that is not a string of up to 200 characters.
400invalid_cursorstarting_after is not an ID from your own list.
400invalid_urlThe webhook URL breaks a URL rule.
400invalid_outcomeSandbox simulate: not paid, failed or needs_review.
404not_foundNo such endpoint, or no such order in your account.
413body_too_largeThe body is over 16 KB.

Keys and accounts

StatusCodeCause
401missing_api_keyNo Authorization: Bearer header.
401wrong_environmentA vk_test_ key sent to production, or a vk_live_ key sent to the sandbox.
401invalid_api_keyUnknown or replaced key.
403account_disabledThe account is suspended.

The order cannot be filled as asked

These come back when you create an order. Show the customer the reason and let them change something.

StatusCodeCause and what to do
422amount_too_smallBelow KES 10, or too small to buy a single sat after the fee.
422amount_too_largeAbove your per-order limit (see max_amount in GET /v1/rates). Split the sale or ask for a higher limit.
422invalid_lightning_addressProduction only: the receiving wallet did not accept this as a Lightning address. Ask the customer to check it.
422destination_unreachableProduction only: the wallet did not return a usable invoice. Ask the customer to check the address.
422destination_rejected_amountProduction only: the wallet will not accept this many sats. Try a different amount or a different wallet.
422destination_unsupportedProduction only: this wallet cannot be paid by Vukia. Use a different Lightning address.

Conflicts

StatusCodeCause and what to do
409idempotency_conflictThe key was already used with different order details. For a new sale, use a new key.
409request_in_progressThe first request with this key has not finished. Retry in a few seconds.
409no_webhookWebhook test with no URL set.
409order_not_awaiting_paymentSandbox simulate on an order that has already moved on.

Limits

StatusCodeCause and what to do
429rate_limitedToo many requests in the last minute. Wait a minute.
429phone_rate_limitedThis phone number already received 3 payment requests in the last 10 minutes. Ask the customer to wait, or to pay from another number.
429daily_limit_reachedYour account's 24-hour volume limit, or Vukia's overall daily volume, is used up. The message says which. Space frees up as orders fall out of the 24-hour window.

Temporary problems on our side

Nothing is wrong with your request. Retry later with the same Idempotency-Key, which is always safe.

StatusCodeCause
502upstream_unavailableA payment provider did not respond.
503liquidity_unavailableVukia does not have enough bitcoin available right now for this amount. A smaller amount may work.
503rate_unavailableNo fresh exchange rate. Usually clears within a minute.
503service_pausedNew orders are paused, for example during maintenance. Existing orders keep settling.
503service_unavailableAnything else unexpected. If it persists, write to us with the request_id.

Order failure codes

These are not HTTP errors. They appear in an order's failure field.

Statusfailure.codeMeaning
payment_failedpayment_not_completedThe M-Pesa payment was not completed. No money was taken.
needs_reviewdelivery_under_reviewThe customer paid. Delivery is not confirmed and Vukia is checking it. Do not create a replacement order.