API

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

POST/v1/orders

Send 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.

FieldDescription
amountRequiredShillings 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.
phoneRequiredThe customer's M-Pesa number: 0712345678, +254712345678 or 254712345678. Numbers starting 01 work the same way. Spaces, brackets and dashes are ignored.
lightning_addressRequiredWhere 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_methodmpesa_prompt (default) or mpesa_paybill. See Prompt or Pay Bill.
referenceYour own reference, returned on the order and in webhooks. 1 to 64 characters: letters, digits, _ . : -. It does not have to be unique.
customer_emailOptional. Passed to the payment processor with the M-Pesa collection. If you leave it out, Vukia uses its own address.
metadataUp to 10 keys of your own. Keys are 1 to 40 characters (letters, digits, _ . -). Values are strings of up to 200 characters. Returned unchanged.
currencyOptional. 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"
}
FieldDescription
idlive_ or test_ followed by 32 hex characters.
statusSee Statuses.
amountCents the customer pays. This is the full M-Pesa amount and includes the fee.
feeVukia's fee in cents. It is part of amount, not added on top.
satsSats the Lightning address receives. This is fixed when the order is created and does not change if the rate moves.
kes_per_btcShillings per bitcoin used to price this order.
payment.methodmpesa_prompt or mpesa_paybill.
payment.phoneMasked phone number.
payment.instructionsText to show the customer while the order is awaiting_payment. null at other times.
payment.paybillFor Pay Bill orders that are awaiting_payment: business_number and account_number. null otherwise.
destination.lightning_addressMasked Lightning address.
deliveryOn 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.
failureOn payment_failed and needs_review: code and message. null otherwise.
reference, metadataWhat you sent.
created_at, updated_atISO 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 paysKES 1,500.00 (amount: 150000)
Fee at 3% (fee_bps: 300)KES 45.00 (fee: 4500)
ConvertedKES 1,455.00
RateKES 10,000,000 per BTC
Delivered14,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 doesSees 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 whenNormally. 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.

One open order per sale

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

awaiting_paymentCreated. Waiting for the customer to pay with M-Pesa.
processingPayment confirmed. Vukia is paying the Lightning invoice.
completedSats delivered. Final.
StatusFinalMeaning and what to show
awaiting_paymentNoWaiting for M-Pesa. Show the amount and the payment instructions. Do not hand over goods.
processingNoM-Pesa payment confirmed. Sats are being delivered, usually within seconds. Show "Payment received, sending bitcoin".
completedYesSats delivered to the Lightning address. The sale is done. Print id, sats and delivery.payment_hash on the receipt.
payment_failedYesThe 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_reviewNoThe 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

Treat these times as typical, not guaranteed. Let the order status, not a timer, decide what happens to the sale.

Read and list orders

GET/v1/orders/{id}

Returns the current order. Orders created by other accounts return 404 not_found.

GET/v1/orders

Your 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.