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
| Behaviour | Sandbox |
|---|---|
| M-Pesa prompt | Never sent. Any real phone number you use receives nothing. |
| Exchange rate | Always kes_per_btc: 10000000 (KES 10,000,000 per BTC). |
| Fee | 3% (fee_bps: 300), the same as production at launch, rounded up to the next cent. |
| Lightning address | Only the format is checked. Production also contacts the receiving wallet when the order is created and rejects addresses that do not answer. |
| Pay Bill details | Business number 600000 and a random account number. They cannot be paid. |
| Limits | KES 5,000 per order and KES 50,000 per 24 hours for each sandbox account, the same as a new production account. |
| Key | vk_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….
| Phone | Outcome | Timing after the order is created |
|---|---|---|
0700000000 | completed | processing at 5 s, completed at 8 s |
0700000001 | payment_failed | payment_failed at 5 s (customer cancelled or did not pay) |
0700000002 | needs_review | processing at 5 s, needs_review at 8 s (paid, delivery not confirmed) |
| Any other valid number | payment_failed | Waits 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.
/v1/sandbox/orders/{id}/simulateSandbox onlyoutcome | Result |
|---|---|
paid | processing now, completed 3 seconds later |
failed | payment_failed now |
needs_review | processing 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.
- A completed order with a webhook.
0700000000. Your system marks the sale paid only after a verifiedorder.completedwebhook, or after reading the order and seeingcompleted. - A failed payment.
0700000001. Your screen says no money was taken and offers to try again with a new order. - An order under review.
0700000002. Your screen does not offer a retry and shows the order ID for support. - A Pay Bill order.
mpesa_paybillwith any other number, thensimulatewithpaid. Your screen shows the business number, account number and exact amount. - A retried request. Send the same create request twice with the same
Idempotency-Key. You get one order and the second response hasIdempotent-Replayed: true. - 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.