API

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.

How a payment works

  1. 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.
  2. 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.
  3. Vukia confirms the payment and pays the Lightning invoice. The order moves to processing, then to completed, and gets a Lightning payment hash.
  4. 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.

SandboxProduction
Base URLhttps://sandbox.vukia.app/v1https://api.vukia.app/v1
Key prefixvk_test_vk_live_
Order IDstest_…live_…
MoneyNone. 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 rateFixed 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 keyInstant, from the quickstart.Email us after your sandbox integration works. See Going live.

What is available

FlowStatus
Buy: M-Pesa shillings in, sats out to a Lightning addressAvailable in the sandbox and to approved production accounts.
Sell: sats in, M-Pesa shillings outNot available through the API.

Conventions

What you need