API

Start / Sandbox

Testing in the sandbox

The sandbox behaves like production but has no M-Pesa and no bitcoin. Each order's outcome depends on the phone number you send, or on a call you make to the simulate endpoint.

What is different from production

BehaviourSandbox
M-Pesa promptNever sent. Any real phone number you use receives nothing.
Exchange rateAlways kes_per_btc: 10000000 (KES 10,000,000 per BTC).
Fee3% (fee_bps: 300), the same as production at launch, rounded up to the next cent.
Lightning addressOnly the format is checked. Production also contacts the receiving wallet when the order is created and rejects addresses that do not answer.
Pay Bill detailsBusiness number 600000 and a random account number. They cannot be paid.
LimitsKES 5,000 per order and KES 50,000 per 24 hours for each sandbox account, the same as a new production account.
Keyvk_test_… works only on sandbox.vukia.app. Sending it to api.vukia.app returns wrong_environment.

Everything else is the same as production: validation, idempotency, limits on how often one phone can be charged, error codes, webhook signing and retries.

Magic phone numbers

These numbers decide the outcome. They work with both mpesa_prompt and mpesa_paybill. You may write them as 07… or +2547….

PhoneOutcomeTiming after the order is created
0700000000completedprocessing at 5 s, completed at 8 s
0700000001payment_failedpayment_failed at 5 s (customer cancelled or did not pay)
0700000002needs_reviewprocessing at 5 s, needs_review at 8 s (paid, delivery not confirmed)
Any other valid numberpayment_failedWaits for simulate. With no simulate call, it becomes payment_failed at 180 s, like a customer who never paid.

Webhooks are sent within about 2 seconds of each change. The sandbox enforces the same per-phone limit as production: 3 orders per number every 10 minutes. If your tests create many orders, spread them across numbers such as 0711000001, 0711000002 and so on, and drive them with simulate.

Simulate an outcome

Use this to drive a specific order, for example to step through your Pay Bill screen at your own pace. It only works while the order is awaiting_payment.

POST/v1/sandbox/orders/{id}/simulateSandbox only
outcomeResult
paidprocessing now, completed 3 seconds later
failedpayment_failed now
needs_reviewprocessing now, needs_review 3 seconds later
curl -X POST https://sandbox.vukia.app/v1/sandbox/orders/test_64305051b9385934a2db49411f3e17c1/simulate \
  -H "Authorization: Bearer $VUKIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"outcome": "paid"}'
{
  "id": "test_64305051b9385934a2db49411f3e17c1",
  "object": "order",
  "environment": "sandbox",
  "status": "processing",
  "reference": "till-3-000188",
  "amount": 50000,
  "currency": "KES",
  "fee": 1500,
  "sats": 4850,
  "kes_per_btc": 10000000,
  "payment": {
    "method": "mpesa_paybill",
    "phone": "+254•••678",
    "instructions": null,
    "paybill": null
  },
  "destination": {
    "lightning_address": "sh•••@blink.sv"
  },
  "delivery": null,
  "failure": null,
  "metadata": {},
  "created_at": "2026-11-19T09:30:00.000Z",
  "updated_at": "2026-11-19T09:30:21.000Z"
}

Calling it again on the same order returns 409 order_not_awaiting_payment.

A Pay Bill order

Send "payment_method": "mpesa_paybill" and the order carries the details your screen must show:

{
  "id": "test_64305051b9385934a2db49411f3e17c1",
  "object": "order",
  "environment": "sandbox",
  "status": "awaiting_payment",
  "reference": "till-3-000188",
  "amount": 50000,
  "currency": "KES",
  "fee": 1500,
  "sats": 4850,
  "kes_per_btc": 10000000,
  "payment": {
    "method": "mpesa_paybill",
    "phone": "+254•••678",
    "instructions": "Sandbox: pay KES 500.00 to Pay Bill 600000, account 9093645. No real payment is possible; use the simulate endpoint.",
    "paybill": {
      "business_number": "600000",
      "account_number": "9093645"
    }
  },
  "destination": {
    "lightning_address": "sh•••@blink.sv"
  },
  "delivery": null,
  "failure": null,
  "metadata": {},
  "created_at": "2026-11-19T09:30:00.000Z",
  "updated_at": "2026-11-19T09:30:00.000Z"
}

In production, instructions holds the real text and paybill holds the real business and account numbers. Always display the values from the response. Never hard-code a business number.

Test plan before you go live

Run each of these against your own code, not just with curl. We ask for the order IDs when you apply for production.

  1. A completed order with a webhook. 0700000000. Your system marks the sale paid only after a verified order.completed webhook, or after reading the order and seeing completed.
  2. A failed payment. 0700000001. Your screen says no money was taken and offers to try again with a new order.
  3. An order under review. 0700000002. Your screen does not offer a retry and shows the order ID for support.
  4. A Pay Bill order. mpesa_paybill with any other number, then simulate with paid. Your screen shows the business number, account number and exact amount.
  5. A retried request. Send the same create request twice with the same Idempotency-Key. You get one order and the second response has Idempotent-Replayed: true.
  6. A rejected signature. Change one byte of a webhook body, or use the wrong secret. Your endpoint rejects it with a 400 response and does not change the sale.

Data in the sandbox

Do not send real customer data to the sandbox. Use the test numbers above and test Lightning addresses. Sandbox data may be deleted at any time, and sandbox keys may be revoked if they are abused.