API

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

HeaderDescription
Vukia-Request-IdUnique per request. Quote it when you contact us.
Vukia-Environmentlive or sandbox.
Idempotent-Replayedtrue when a create returned an existing order.

Health

GET/healthzNo key

Returns {"status": "ok", "environment": "live"} when the API is answering. Use it for uptime checks.

Create a sandbox key

POST/v1/sandbox/keysSandbox only · No key
FieldDescription
nameRequiredBusiness or project name, 2 to 80 characters.
emailRequiredContact 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

GET/v1/account
{
  "id": "ptr_db39b165a1c7db993cf812f6",
  "object": "account",
  "environment": "sandbox",
  "name": "Duka POS",
  "limits": {
    "max_order": 500000,
    "daily": 5000000
  },
  "webhook": null
}

Current rate

GET/v1/rates

The 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

POST/v1/quotes
FieldDescription
amountRequiredCents, 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

POST/v1/orders

Header 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

GET/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

GET/v1/orders
QueryDescription
limit1 to 100. Default 20.
starting_afterAn order ID. Returns orders created before it.
{
  "object": "list",
  "data": [ { "id": "test_…", "object": "order", … }, … ],
  "has_more": true
}

Set the webhook endpoint

POST/v1/webhook
FieldDescription
urlRequiredPublic 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

GET/v1/webhook
{
  "url": "https://pos.duka.example/hooks/vukia",
  "created_at": "2026-11-19T09:30:00.000Z"
}

Remove the webhook endpoint

DELETE/v1/webhook

Returns {"url": null}. Events that happen afterwards are logged with the state no_endpoint.

Send a test event

POST/v1/webhook/test

Sends 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

GET/v1/events
QueryDescription
limit1 to 100. Default 20.
starting_afterAn event ID. Returns events created before it.
typeOnly 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

POST/v1/sandbox/orders/{id}/simulateSandbox only
FieldDescription
outcomeRequiredpaid, 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"
}