Reference / API reference
API reference
Base URLs: https://api.vukia.app (production) and https://sandbox.vukia.app (sandbox). All endpoints except the first two need Authorization: Bearer <key>. A machine-readable description is at /openapi.json. You can import it into Postman, Insomnia or a code generator.
Response headers
| Header | Description |
|---|---|
Vukia-Request-Id | Unique per request. Quote it when you contact us. |
Vukia-Environment | live or sandbox. |
Idempotent-Replayed | true when a create returned an existing order. |
Health
/healthzNo keyReturns {"status": "ok", "environment": "live"} when the API is answering. Use it for uptime checks.
Create a sandbox key
/v1/sandbox/keysSandbox only · No key| Field | Description |
|---|---|
nameRequired | Business or project name, 2 to 80 characters. |
emailRequired | Contact email. |
{
"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."
}
Retrieve your account
/v1/account{
"id": "ptr_db39b165a1c7db993cf812f6",
"object": "account",
"environment": "sandbox",
"name": "Duka POS",
"limits": {
"max_order": 500000,
"daily": 5000000
},
"webhook": null
}
Current rate
/v1/ratesThe rate and fee that a new order would use now, and the amount range you may order. max_amount is the lower of your account limit and Vukia's current per-order limit. expires_at is when Vukia will next refresh the rate.
{
"object": "rate",
"environment": "sandbox",
"kes_per_btc": 10000000,
"fee_bps": 300,
"min_amount": 1000,
"max_amount": 500000,
"updated_at": "2026-11-19T09:30:00.000Z",
"expires_at": "2026-11-19T09:35:00.000Z"
}
Preview a price
/v1/quotes| Field | Description |
|---|---|
amountRequired | Cents, a multiple of 100, at least 1000. |
Creates nothing and does not hold the rate. Use it to show an estimate before the customer commits.
{
"object": "quote",
"environment": "sandbox",
"amount": 150000,
"fee": 4500,
"sats": 14550,
"kes_per_btc": 10000000,
"expires_at": "2026-11-19T09:31:00.000Z"
}
Create an order
/v1/ordersHeader Idempotency-Key is required. Body fields are described in Orders.
curl https://api.vukia.app/v1/orders \
-H "Authorization: Bearer $VUKIA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: sale-3-000188" \
-d '{
"amount": 50000,
"phone": "0712345678",
"lightning_address": "[email protected]",
"payment_method": "mpesa_paybill",
"reference": "till-3-000188"
}'
Returns 201 with the new order, or 200 with Idempotent-Replayed: true if the key already created one.
{
"id": "test_64305051b9385934a2db49411f3e17c1",
"object": "order",
"environment": "sandbox",
"status": "awaiting_payment",
"reference": "till-3-000188",
"amount": 50000,
"currency": "KES",
"fee": 1500,
"sats": 4850,
"kes_per_btc": 10000000,
"payment": {
"method": "mpesa_paybill",
"phone": "+254•••678",
"instructions": "Sandbox: pay KES 500.00 to Pay Bill 600000, account 9093645. No real payment is possible; use the simulate endpoint.",
"paybill": {
"business_number": "600000",
"account_number": "9093645"
}
},
"destination": {
"lightning_address": "sh•••@blink.sv"
},
"delivery": null,
"failure": null,
"metadata": {},
"created_at": "2026-11-19T09:30:00.000Z",
"updated_at": "2026-11-19T09:30:00.000Z"
}
Retrieve an order
/v1/orders/{id}{
"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"
}
List orders
/v1/orders| Query | Description |
|---|---|
limit | 1 to 100. Default 20. |
starting_after | An order ID. Returns orders created before it. |
{
"object": "list",
"data": [ { "id": "test_…", "object": "order", … }, … ],
"has_more": true
}
Set the webhook endpoint
/v1/webhook| Field | Description |
|---|---|
urlRequired | Public HTTPS URL on port 443. See URL rules. |
Replaces any existing endpoint and returns a new signing secret. The secret is only shown in this response.
{
"url": "https://pos.duka.example/hooks/vukia",
"secret": "whsec_nyi_v_wRapSNWzHTGdDwgiJM7glriEUyQ6c8Y6Hf6pI",
"created_at": "2026-11-19T09:30:00.000Z"
}
Retrieve the webhook endpoint
/v1/webhook{
"url": "https://pos.duka.example/hooks/vukia",
"created_at": "2026-11-19T09:30:00.000Z"
}
Remove the webhook endpoint
/v1/webhookReturns {"url": null}. Events that happen afterwards are logged with the state no_endpoint.
Send a test event
/v1/webhook/testSends a ping event straight away and reports what your endpoint answered. If it fails, it is retried on the normal schedule, like any other event.
{
"event_id": "evt_999a94da1fe7ee87b46f7bee",
"delivered": true,
"status_code": 200,
"error": null
}
List events
/v1/events| Query | Description |
|---|---|
limit | 1 to 100. Default 20. |
starting_after | An event ID. Returns events created before it. |
type | Only events of this type, for example order.completed. |
{
"id": "evt_b55d7d5a8b1eda08afc6bba0",
"object": "event",
"type": "order.needs_review",
"environment": "sandbox",
"created_at": "2026-11-19T09:30:21.000Z",
"data": {
"object": {
"id": "test_ded96b6842482ab2b7b1710e4ae49ffa",
"object": "order",
"environment": "sandbox",
"status": "needs_review",
"reference": null,
"amount": 20000,
"currency": "KES",
"fee": 600,
"sats": 1940,
"kes_per_btc": 10000000,
"payment": {
"method": "mpesa_prompt",
"phone": "+254•••002",
"instructions": null,
"paybill": null
},
"destination": {
"lightning_address": "sh•••@blink.sv"
},
"delivery": null,
"failure": {
"code": "delivery_under_review",
"message": "The customer paid but the bitcoin delivery could not be confirmed. Vukia is reviewing it; do not create a replacement order."
},
"metadata": {},
"created_at": "2026-11-19T09:30:13.000Z",
"updated_at": "2026-11-19T09:30:21.000Z"
}
},
"delivery": {
"state": "delivered",
"attempts": 1,
"last_status": 200,
"last_error": null
}
}
Simulate an outcome
/v1/sandbox/orders/{id}/simulateSandbox only| Field | Description |
|---|---|
outcomeRequired | paid, failed or needs_review. |
Only for orders in awaiting_payment. See Testing in the sandbox.
{
"id": "test_64305051b9385934a2db49411f3e17c1",
"object": "order",
"environment": "sandbox",
"status": "processing",
"reference": "till-3-000188",
"amount": 50000,
"currency": "KES",
"fee": 1500,
"sats": 4850,
"kes_per_btc": 10000000,
"payment": {
"method": "mpesa_paybill",
"phone": "+254•••678",
"instructions": null,
"paybill": null
},
"destination": {
"lightning_address": "sh•••@blink.sv"
},
"delivery": null,
"failure": null,
"metadata": {},
"created_at": "2026-11-19T09:30:00.000Z",
"updated_at": "2026-11-19T09:30:21.000Z"
}