API

Guides / Point of sale

Point of sale

This guide covers adding Vukia to a till or POS system. The customer pays with M-Pesa at the counter, and the sats go to a Lightning address you choose for each sale.

Two ways to use it

Settle sales in bitcoinSell bitcoin over the counter
Customer paysFor goods, in shillings, with M-PesaShillings with M-Pesa, to buy bitcoin
lightning_addressThe shop's address, set once in your settingsThe customer's address, typed or scanned at the till
amountThe sale totalWhat the customer wants to spend
Receipt showsGoods, total paid, sats received by the shopShillings paid, fee, sats delivered, payment hash

The API calls are the same. Only the Lightning address changes.

Architecture

Till / tablet  ──►  Your POS server  ──►  api.vukia.app
     ▲                   │  ▲
     │  sale status      │  │  signed webhooks
     └───────────────────┘  └───── Vukia

The cashier flow

  1. Cashier enters the amount and picks "M-Pesa → bitcoin". For over-the-counter sales, the customer gives their Lightning address. Many wallets show it as a QR code, which the till can scan. Optionally call POST /v1/quotes to show "You will receive about 14,550 sats".
  2. Cashier enters the customer's M-Pesa number.
  3. Your server creates the order. If the response is an error, show the message and let the cashier correct the field named in param.
  4. The till shows the waiting screen. The customer approves the prompt on their phone, or pays by Pay Bill.
  5. Your server receives order.completed, checks the signature and marks the sale paid. The till shows the success screen and prints the receipt.

What the till shows

Suggested wording for each status. Keep the order ID visible on every screen after creation, in case the customer needs help.

StatusScreenCashier can
awaiting_payment
prompt
Check your phone. Enter your M-Pesa PIN to pay KES 1,500.
Small: Prompt not showing? Wait for this request to time out, then choose Pay Bill.
Cancel on the till only. The order cannot be cancelled, but an unpaid prompt simply fails.
awaiting_payment
Pay Bill
Pay with M-Pesa Pay Bill
Business number {business_number}
Account number {account_number}
Amount KES 1,500 exactly
Read the numbers aloud. Show them in large type.
processingPayment received. Sending bitcoin…Wait. Usually a few seconds.
completedDone. 14,550 sats delivered.Print the receipt and hand over the goods.
payment_failedPayment not completed. No money was taken.Try again (new order and new key), or switch to Pay Bill.
needs_reviewPayment received. The bitcoin delivery is being checked. Keep this receipt. Order live_…Print a receipt with the order ID. Do not retry. Contact Vukia with the order ID.
Never charge twice for one sale

Create a second order for the same sale only after the first is payment_failed. If a customer says they paid but the till still shows awaiting_payment, wait. M-Pesa confirmations can lag. Check the order with GET /v1/orders/{id} before trying anything else.

Waiting for the result

Use both of these:

If the till loses its connection mid-sale, nothing is lost. When it reconnects, it asks your server for the sale, and your server asks Vukia for the order using the ID it saved.

Receipt

Print values from the completed order, not from the quote:

DUKA POS · TILL 3 Receipt 000187 2026-11-19 12:30 EAT -------------------------------- Paid via M-Pesa KES 1,500.00 Vukia fee (3%) KES 45.00 Bitcoin delivered 14,550 sats Rate KES 10,000,000 / BTC To sh•••@blink.sv -------------------------------- Order test_6271197401f5f99b… Payment hash 2d3f3dc52e889e5781fa0385f9b2… -------------------------------- Bitcoin service by Vukia

The payment hash lets the customer, or the shop, find the same payment in their Lightning wallet.

End of day

  1. List the day's orders with GET /v1/orders?limit=100, paging with starting_after until you pass the start of the day.
  2. Match on reference, which you set to the receipt number. Every sale you marked paid must be completed. Every completed order must match a sale.
  3. Check open orders. Anything still awaiting_payment after an hour is abandoned and will fail. Anything in needs_review should already be with Vukia. If it is not, email us the order IDs.
  4. Check webhook health with GET /v1/events?limit=100. Any failed deliveries point to a problem on your endpoint.

Staff notes