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 bitcoin | Sell bitcoin over the counter | |
|---|---|---|
| Customer pays | For goods, in shillings, with M-Pesa | Shillings with M-Pesa, to buy bitcoin |
lightning_address | The shop's address, set once in your settings | The customer's address, typed or scanned at the till |
amount | The sale total | What the customer wants to spend |
| Receipt shows | Goods, total paid, sats received by the shop | Shillings 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 API key lives on your POS server only. Tills authenticate to your server the way they already do. A key on a till can be copied off the device.
- Your server owns each sale's state. It creates the order, receives webhooks and tells the till what to show. The till can poll your server, or you can push to it.
- One sale, one
Idempotency-Key. Use the sale or receipt number, for examplesale-{branch}-{till}-{receipt}. Save it with the sale before calling Vukia.
The cashier flow
- 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/quotesto show "You will receive about 14,550 sats". - Cashier enters the customer's M-Pesa number.
- Your server creates the order. If the response is an error, show the message and let the cashier correct the field named in
param. - The till shows the waiting screen. The customer approves the prompt on their phone, or pays by Pay Bill.
- 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.
| Status | Screen | Cashier can |
|---|---|---|
awaiting_paymentprompt | 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_paymentPay 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. |
processing | Payment received. Sending bitcoin… | Wait. Usually a few seconds. |
completed | Done. 14,550 sats delivered. | Print the receipt and hand over the goods. |
payment_failed | Payment not completed. No money was taken. | Try again (new order and new key), or switch to Pay Bill. |
needs_review | Payment 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. |
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:
- Webhooks as the main signal. Your server marks the sale and notifies the till.
- Polling while a screen is open as a backup. Every 3 to 5 seconds, ask your server, which calls
GET /v1/orders/{id}if it has not heard a webhook. Stop polling when the status is final or the cashier leaves the screen.
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:
The payment hash lets the customer, or the shop, find the same payment in their Lightning wallet.
End of day
- List the day's orders with
GET /v1/orders?limit=100, paging withstarting_afteruntil you pass the start of the day. - Match on
reference, which you set to the receipt number. Every sale you marked paid must becompleted. Everycompletedorder must match a sale. - Check open orders. Anything still
awaiting_paymentafter an hour is abandoned and will fail. Anything inneeds_reviewshould already be with Vukia. If it is not, email us the order IDs. - Check webhook health with
GET /v1/events?limit=100. Anyfaileddeliveries point to a problem on your endpoint.
Staff notes
- The customer's phone must be on and have signal for the prompt. If it does not appear within about 30 seconds, the customer can open M-Pesa and pay by Pay Bill on the next attempt.
- Bitcoin sent to a Lightning address cannot be reversed. Before sending over the counter, confirm the address with the customer. Read the first few characters aloud, or let them scan it.
- After three failed attempts on one number, the system will block that number for 10 minutes. This is deliberate.
- Vukia never asks a cashier or customer for an M-Pesa PIN, and no one at Vukia will phone to ask for one.