Build / Orders
Orders
An order is one customer payment: a set amount of shillings collected from one M-Pesa number, then a set amount of sats delivered to one Lightning address.
Create an order
/v1/ordersSend an Idempotency-Key header with every create request (8 to 100 characters: letters, digits, _ . : -). Use your own sale or invoice ID, so a retry can never charge the customer twice. See Retries and idempotency.
| Field | Description |
|---|---|
amountRequired | Shillings the customer pays, in cents. Must be a multiple of 100 (whole shillings) and at least 1000 (KES 10). The maximum is your account's per-order limit. |
phoneRequired | The customer's M-Pesa number: 0712345678, +254712345678 or 254712345678. Numbers starting 01 work the same way. Spaces, brackets and dashes are ignored. |
lightning_addressRequired | Where the sats go, in the form name@domain. In production Vukia contacts the wallet when the order is created. If the wallet cannot give an invoice for this amount, the order is refused before the customer is asked to pay. |
payment_method | mpesa_prompt (default) or mpesa_paybill. See Prompt or Pay Bill. |
reference | Your own reference, returned on the order and in webhooks. 1 to 64 characters: letters, digits, _ . : -. It does not have to be unique. |
customer_email | Optional. Passed to the payment processor with the M-Pesa collection. If you leave it out, Vukia uses its own address. |
metadata | Up to 10 keys of your own. Keys are 1 to 40 characters (letters, digits, _ . -). Values are strings of up to 200 characters. Returned unchanged. |
currency | Optional. Must be KES if sent. |
Any other field is rejected with 400 unknown_parameter, and param names the field. This catches spelling mistakes such as amout.
A successful create returns 201 with the order in awaiting_payment. In production the M-Pesa prompt has already been sent by the time you receive the response.
The order object
{
"id": "test_80ef637b4dada3da1c2a5fb70c4f9038",
"object": "order",
"environment": "sandbox",
"status": "completed",
"reference": "till-3-000187",
"amount": 150000,
"currency": "KES",
"fee": 4500,
"sats": 14550,
"kes_per_btc": 10000000,
"payment": {
"method": "mpesa_prompt",
"phone": "+254•••000",
"instructions": null,
"paybill": null
},
"destination": {
"lightning_address": "sh•••@blink.sv"
},
"delivery": {
"payment_hash": "ce478fbc0a2df281a8ebd57c4154a5f9e8a9fac5a0030e595a0720ca66e7150b",
"routing_fee_sats": 0
},
"failure": null,
"metadata": {
"till": "3",
"cashier": "wanjiru"
},
"created_at": "2026-11-19T09:30:00.000Z",
"updated_at": "2026-11-19T09:30:08.000Z"
}
| Field | Description |
|---|---|
id | live_ or test_ followed by 32 hex characters. |
status | See Statuses. |
amount | Cents the customer pays. This is the full M-Pesa amount and includes the fee. |
fee | Vukia's fee in cents. It is part of amount, not added on top. |
sats | Sats the Lightning address receives. This is fixed when the order is created and does not change if the rate moves. |
kes_per_btc | Shillings per bitcoin used to price this order. |
payment.method | mpesa_prompt or mpesa_paybill. |
payment.phone | Masked phone number. |
payment.instructions | Text to show the customer while the order is awaiting_payment. null at other times. |
payment.paybill | For Pay Bill orders that are awaiting_payment: business_number and account_number. null otherwise. |
destination.lightning_address | Masked Lightning address. |
delivery | On completed orders: payment_hash (64 hex characters, identifies the Lightning payment) and routing_fee_sats (what Vukia paid the network; not taken from sats). null otherwise. |
failure | On payment_failed and needs_review: code and message. null otherwise. |
reference, metadata | What you sent. |
created_at, updated_at | ISO 8601, UTC. |
How the price is worked out
The fee comes out of the amount the customer pays. The rest is converted to sats at the current rate and rounded down to a whole sat:
fee = ceil(amount × fee_bps ÷ 10,000)
sats = floor((amount − fee) × 1,000,000 ÷ kes_per_btc)
Both amount and fee are in cents. × 1,000,000 converts cents to sats: 100 cents per shilling and 100,000,000 sats per bitcoin.
| Worked example | |
|---|---|
| Customer pays | KES 1,500.00 (amount: 150000) |
Fee at 3% (fee_bps: 300) | KES 45.00 (fee: 4500) |
| Converted | KES 1,455.00 |
| Rate | KES 10,000,000 per BTC |
| Delivered | 14,550 sats |
The Lightning routing fee is paid by Vukia. The address always receives exactly sats.
Showing a price before the customer commits
POST /v1/quotes with {"amount": 150000} returns the same calculation without creating anything. A quote is a preview only: it does not hold the rate. The price that counts is the one in the create response. Show the customer sats from the order once it exists.
{
"object": "quote",
"environment": "sandbox",
"amount": 150000,
"fee": 4500,
"sats": 14550,
"kes_per_btc": 10000000,
"expires_at": "2026-11-19T09:31:00.000Z"
}
GET /v1/rates returns the current rate, the fee and your current minimum and maximum order amount.
Prompt or Pay Bill
mpesa_prompt (default) | mpesa_paybill | |
|---|---|---|
| Customer does | Sees a prompt on their phone and enters their M-Pesa PIN. | Opens M-Pesa, chooses Lipa na M-Pesa → Pay Bill, and enters the business number, account number and exact amount from the order. |
| Your screen shows | "Check your phone and enter your M-Pesa PIN", the amount, and payment.instructions. | payment.paybill.business_number, payment.paybill.account_number and the exact amount, in large text. |
| Use when | Normally. It is quicker and leaves less room for mistakes. | The prompt does not appear on the customer's phone. This happens with some handsets, SIM toolkit problems or poor signal. |
Each Pay Bill order has its own account number. The customer must pay the exact amount to that account number, or the payment cannot be matched to the order. The instructions ask the customer to pay within 3 minutes.
To switch a sale from prompt to Pay Bill, wait until the prompt order is payment_failed, then create a new order with a new Idempotency-Key. If both orders are open at once and the customer completes both, both are charged and both deliver sats.
Statuses
| Status | Final | Meaning and what to show |
|---|---|---|
awaiting_payment | No | Waiting for M-Pesa. Show the amount and the payment instructions. Do not hand over goods. |
processing | No | M-Pesa payment confirmed. Sats are being delivered, usually within seconds. Show "Payment received, sending bitcoin". |
completed | Yes | Sats delivered to the Lightning address. The sale is done. Print id, sats and delivery.payment_hash on the receipt. |
payment_failed | Yes | The customer did not pay: they cancelled, entered the wrong PIN, had too little balance, or the request expired. No money was taken. To try again, create a new order with a new Idempotency-Key. |
needs_review | No | The customer paid, but Vukia could not confirm that the sats were delivered. Do not create a replacement order. Show the order ID and tell the customer it is being checked. Vukia's team looks at every such order and contacts you with the outcome. |
The paths an order can take:
awaiting_payment → processing → completed
awaiting_payment → payment_failed
awaiting_payment → processing → needs_review
Statuses only move forward. A completed or payment_failed order never changes again.
How long each step takes in production
- Prompt: the customer approves on their phone. An ignored prompt expires. Vukia marks the order
payment_failedonce M-Pesa reports the payment as failed or expired, usually within a few minutes. - Pay Bill: depends on the customer. Vukia checks for the payment every few seconds.
- Delivery: once the payment is confirmed, Lightning delivery usually completes within a few seconds.
Treat these times as typical, not guaranteed. Let the order status, not a timer, decide what happens to the sale.
Read and list orders
/v1/orders/{id}Returns the current order. Orders created by other accounts return 404 not_found.
/v1/ordersYour orders, newest first. Parameters: limit (1 to 100, default 20) and starting_after (the id of the last order on the previous page). Keep requesting while has_more is true.
curl "https://api.vukia.app/v1/orders?limit=100&starting_after=live_9a1f..." \
-H "Authorization: Bearer $VUKIA_API_KEY"
Use the list to reconcile at the end of the day. Every order you have marked as paid should be completed here, and every completed order here should match a sale on your side through reference.