Start / Overview
Vukia API
Take a payment in Kenyan shillings over M-Pesa and deliver the bitcoin to a Lightning address. One HTTPS request starts the payment. Vukia tells your server when the sats have arrived.
QuickstartGet a sandbox key and complete a test order with curl in about five minutes.
Point of sale guideWhat the cashier screen shows at each step, receipts and end-of-day checks.
WebhooksSigned status updates, with verification code for Node.js, Python and PHP.
API referenceEvery endpoint, field and error code, with real responses.
How a payment works
- Your server creates an order. It sends the amount in shillings, the customer's M-Pesa number and the Lightning address that should receive the bitcoin. The response tells you exactly how many sats will be delivered and what Vukia's fee is.
- The customer pays with M-Pesa. By default their phone shows an M-Pesa prompt and they enter their PIN. If the prompt does not reach their phone, use Pay Bill instead: the order then carries a business number and account number for the customer to pay manually.
- Vukia confirms the payment and pays the Lightning invoice. The order moves to
processing, then tocompleted, and gets a Lightning payment hash. - Your server hears about each change. Vukia sends a signed webhook for every status change. You can also read the order at any time.
The customer is never redirected and never needs a Vukia account. The bitcoin goes straight to the Lightning address in the order, which can belong to the customer or to your business.
Environments
The sandbox and production have the same endpoints, fields and statuses. Only the host, the key and the money differ.
| Sandbox | Production | |
|---|---|---|
| Base URL | https://sandbox.vukia.app/v1 | https://api.vukia.app/v1 |
| Key prefix | vk_test_ | vk_live_ |
| Order IDs | test_… | live_… |
| Money | None. No M-Pesa prompt is sent and no bitcoin moves. Outcomes come from test phone numbers. | Real M-Pesa collections and real Lightning payments. |
| Exchange rate | Fixed at KES 10,000,000 per BTC so your tests give the same numbers every time. | Live market rate, refreshed every few minutes. |
| Getting a key | Instant, from the quickstart. | Email us after your sandbox integration works. See Going live. |
What is available
| Flow | Status |
|---|---|
| Buy: M-Pesa shillings in, sats out to a Lightning address | Available in the sandbox and to approved production accounts. |
| Sell: sats in, M-Pesa shillings out | Not available through the API. |
Conventions
- Amounts are integers in cents. KES 1,500 is
150000. M-Pesa only moves whole shillings, so amounts must be multiples of 100. - Bitcoin amounts are in sats (1 BTC = 100,000,000 sats).
- Requests and responses are JSON. Send
Content-Type: application/jsonwith a body. - Times are ISO 8601 in UTC, for example
2026-11-19T09:30:08.000Z. - Every response has a
Vukia-Request-Idheader. Include it when you write to us about a specific request. - Phone numbers and Lightning addresses come back masked, for example
+254•••678andsh•••@blink.sv. Keep the full values on your side if you need them.
What you need
- A server that can make HTTPS requests and keep a secret. API keys must never be placed in a mobile app, a browser or a POS terminal. The terminal talks to your server, and your server talks to Vukia.
- An HTTPS endpoint for webhooks, reachable from the internet on port 443. Without one you can poll, but webhooks are better.
- For production: an approved account. Start in the sandbox. When your integration passes the checks on Going live, email [email protected].