The whole thing, before you sign up

Sandbox transaction codes are prefixed SBX-. You do not need an OTP — but if you choose to send one, it is always 123456.

# One call. No OTP — your key already identifies you.
# In the sandbox nothing is charged, no SMS is sent, no sats move.
curl -X POST https://bitikaserver.up.railway.app/api/v1/xwift/collect \
  -H 'Authorization: Bearer bk_test_xxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "amount": "100",
    "phone": "254712345678",
    "lightningAddress": "name@blink.sv"
  }'
# → { "transaction_code": "SBX-1A2B3C4D", "status": "processing" }

# Your webhook then receives, for real:
#   transaction.updated  (~1.5s)  → processing_payment
#   payment.completed    (~4s)    → fulfilled

Force a failure (like a test card)

Test your unhappy paths by choosing the phone number:

You do not OTP your users

Your key identifies you — an approved, email-verified developer. You already own the relationship with your customer, and you are the accountable party for the charges you initiate. So we do not ask you to SMS a one-time code to your own user. Just call /xwift/collect.
(verificationCode is still accepted if you want that extra step. Bitika's own anonymous web checkout still uses one, because there the payer is a stranger to us.)

Scopes

Self-serve keys carry payments:initiate, payments:read and otp:send. A call outside your scopes returns 403.

IP allowlist — optional, and usually skip it

You can lock a key to specific source IPs. It is off by default and we recommend leaving it off unless you genuinely have a fixed egress IP. It protects against one narrow thing — a stolen key being replayed from somewhere else — and it breaks loudly (403) the moment your egress IP changes.

Your key is protected by more than an IP anyway: it is hashed at rest, scoped, rate-limited, rotatable, and revocable the moment you suspect a leak. If a key leaks, rotate it — that is the real fix.

1. 1

   Initiate the collection

   POST /api/v1/xwift/collect with the amount, phone and Lightning destination. No OTP — your key already identifies you. You get back a transaction_code and status: "processing".

2. 2

   The user approves the STK push

   They enter their M-Pesa PIN on their phone. Nothing for you to do here.

3. 3

   Listen for the result

   Bitika charges M-Pesa, pays Lightning, and tells you — via webhook or WebSocket — as it moves through the state machine.

processing ──▶ processing_payment ──▶ fulfilled        ✅ sats delivered
    │                   │
    │                   └──────────────▶ payment_failed  ⚠️ M-Pesa took payment,
    │                                                       Lightning payout failed
    └───────────────────────────────────▶ failed          ❌ M-Pesa declined

Events

Payload

{
  "id": "evt_9f2c...",
  "event": "payment.completed",
  "created": "2026-07-14T09:31:02.114Z",
  "data": {
    "transaction_code": "SBX-1A2B3C4D",
    "status": "fulfilled",
    "amount_kes": 100,
    "sats": 1212,
    "lightning_address": "you@blink.sv",
    "payment_hash": "b3f1...",
    "mpesa_receipt": "SBX8A2F19",
    "decline_reason": null,
    "created_at": "2026-07-14T09:30:58.001Z",
    "updated_at": "2026-07-14T09:31:02.100Z"
  }
}

Verify the signature

Every delivery carries X-Bitika-Event and X-Bitika-Signature: t=<ts>,v1=<hmac>. We sign "<timestamp>.<raw body>" with HMAC-SHA256 so signatures can't be replayed. Verify against the raw body, before any JSON parsing.

import crypto from "crypto";

// Bitika signs "<timestamp>.<raw body>" with your webhook secret (HMAC-SHA256).
// Header: X-Bitika-Signature: t=1783625207,v1=9f86d081...
export function verifyBitika(rawBody: string, header: string, secret: string) {
  const parts = Object.fromEntries(
    header.split(",").map((kv) => kv.split("=") as [string, string]),
  );
  const { t, v1 } = parts;

  // Reject replays (5-minute window).
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;

  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${t}.${rawBody}`)
    .digest("hex");

  // Constant-time compare — never use ===
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}

Managing webhooks

These use your developer session JWT (from POST /api/v1/developers/login), not the API key.

Deliveries retry with backoff and are deduplicated per (webhook, transaction, event) — so you get each event exactly once, even though it can be emitted from several code paths. Return a 2xx quickly; do your work asynchronously.