API

Start / Quickstart

Quickstart

Create a sandbox key, place a test order that completes on its own, then point a webhook at your server. Nothing here moves real money.

Get a sandbox key

Sandbox keys are issued straight away. Use your business or project name so we can recognise you when you apply for production.

This form needs JavaScript. Without it, use the curl command below.

Or from a terminal:

curl https://sandbox.vukia.app/v1/sandbox/keys \
  -H "Content-Type: application/json" \
  -d '{"name": "Duka POS", "email": "[email protected]"}'
{
  "partner_id": "ptr_db39b165a1c7db993cf812f6",
  "environment": "sandbox",
  "api_key": "vk_test_HM8dJVc6gIs_ETc5_aQ-MUOhAJPbKPVt",
  "limits": {
    "max_order": 500000,
    "daily": 5000000
  },
  "note": "Store this key now. Vukia does not show it again."
}

The key is shown once. Save it as an environment variable for the rest of this page:

export VUKIA_API_KEY=vk_test_...

Check the key

curl https://sandbox.vukia.app/v1/account \
  -H "Authorization: Bearer $VUKIA_API_KEY"
{
  "id": "ptr_db39b165a1c7db993cf812f6",
  "object": "account",
  "environment": "sandbox",
  "name": "Duka POS",
  "limits": {
    "max_order": 500000,
    "daily": 5000000
  },
  "webhook": null
}

Limits are in cents. A sandbox account can create orders of up to KES 5,000 and up to KES 50,000 in any 24 hours, the same limits production accounts start with.

Create an order

This order is for KES 1,500. The phone number 0700000000 is a test number: the sandbox treats it as a customer who pays straight away, so the order completes about 8 seconds later.

curl https://sandbox.vukia.app/v1/orders \
  -H "Authorization: Bearer $VUKIA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: sale-3-000187" \
  -d '{
    "amount": 150000,
    "phone": "0700000000",
    "lightning_address": "[email protected]",
    "reference": "till-3-000187"
  }'
// Node.js 18 or later (built-in fetch)

const res = await fetch('https://sandbox.vukia.app/v1/orders', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.VUKIA_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'sale-3-000187',
  },
  body: JSON.stringify({
    amount: 150000,                  // KES 1,500.00 in cents
    phone: '0700000000',
    lightning_address: '[email protected]',
    reference: 'till-3-000187',
  }),
});
const order = await res.json();
if (!res.ok) throw new Error(`${order.error.code}: ${order.error.message}`);
console.log(order.id, order.status, order.sats);
# pip install requests

import os, requests

res = requests.post(
    "https://sandbox.vukia.app/v1/orders",
    headers={
        "Authorization": f"Bearer {os.environ['VUKIA_API_KEY']}",
        "Idempotency-Key": "sale-3-000187",
    },
    json={
        "amount": 150000,  # KES 1,500.00 in cents
        "phone": "0700000000",
        "lightning_address": "[email protected]",
        "reference": "till-3-000187",
    },
    timeout=40,
)
order = res.json()
if not res.ok:
    raise RuntimeError(f"{order['error']['code']}: {order['error']['message']}")
print(order["id"], order["status"], order["sats"])
<?php
$ch = curl_init('https://sandbox.vukia.app/v1/orders');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 40,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('VUKIA_API_KEY'),
        'Content-Type: application/json',
        'Idempotency-Key: sale-3-000187',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'amount' => 150000, // KES 1,500.00 in cents
        'phone' => '0700000000',
        'lightning_address' => '[email protected]',
        'reference' => 'till-3-000187',
    ]),
]);
$order = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
if ($status >= 400) {
    throw new RuntimeException($order['error']['code'] . ': ' . $order['error']['message']);
}
echo $order['id'], ' ', $order['status'], ' ', $order['sats'], PHP_EOL;
{
  "id": "test_80ef637b4dada3da1c2a5fb70c4f9038",
  "object": "order",
  "environment": "sandbox",
  "status": "awaiting_payment",
  "reference": "till-3-000187",
  "amount": 150000,
  "currency": "KES",
  "fee": 4500,
  "sats": 14550,
  "kes_per_btc": 10000000,
  "payment": {
    "method": "mpesa_prompt",
    "phone": "+254•••000",
    "instructions": "Sandbox: no prompt is sent. Use a magic number or the simulate endpoint.",
    "paybill": null
  },
  "destination": {
    "lightning_address": "sh•••@blink.sv"
  },
  "delivery": null,
  "failure": null,
  "metadata": {
    "till": "3",
    "cashier": "wanjiru"
  },
  "created_at": "2026-11-19T09:30:00.000Z",
  "updated_at": "2026-11-19T09:30:00.000Z"
}

Read the numbers in the response, not the ones you expected. Here KES 1,500 pays a 3% fee of KES 45 (fee: 4500). The remaining KES 1,455 buys 14,550 sats at the sandbox rate. Those 14,550 sats are what the Lightning address receives.

Idempotency-Key

Every order needs a unique key, usually your own sale or invoice ID. If the network fails and you send the same request again with the same key, you get the same order back and the customer is not charged twice. See Retries and idempotency.

Watch it complete

Wait about 10 seconds, then read the order again using the id from the response:

curl https://sandbox.vukia.app/v1/orders/test_80ef637b4dada3da1c2a5fb70c4f9038 \
  -H "Authorization: Bearer $VUKIA_API_KEY"
{
  "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"
}

The order went from awaiting_payment to processing after 5 seconds and to completed after 8. delivery.payment_hash identifies the Lightning payment. Print it on the receipt: the receiving wallet shows the same hash.

Receive webhooks

Polling works for a quick test, but production integrations should let Vukia call them. Register an HTTPS URL on your server:

curl https://sandbox.vukia.app/v1/webhook \
  -H "Authorization: Bearer $VUKIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://pos.example.com/hooks/vukia"}'
{
  "url": "https://pos.duka.example/hooks/vukia",
  "secret": "whsec_nyi_v_wRapSNWzHTGdDwgiJM7glriEUyQ6c8Y6Hf6pI",
  "created_at": "2026-11-19T09:30:00.000Z"
}

Store secret. You need it to check that each webhook really came from Vukia. Then send a test event:

curl -X POST https://sandbox.vukia.app/v1/webhook/test \
  -H "Authorization: Bearer $VUKIA_API_KEY"
{
  "event_id": "evt_999a94da1fe7ee87b46f7bee",
  "delivered": true,
  "status_code": 200,
  "error": null
}

If delivered is false, the error field says why, for example http_404 or timeout. No public server yet? Use a request inspector or a tunnel while you develop. The URL only has to be public HTTPS.

Now create another order with 0700000000. Within a few seconds your endpoint receives order.processing, then order.completed. Verify the signature before you trust either one.

Next