Ship identity verification, faster.

curl -X POST https://kalutakyc.com/v1/sessions \
  -H "X-API-Key: klt_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "external_id": "user_42" }'

# → { "session_id": "abc123",
#     "verification_url": "https://kalutakyc.com/verify/abc123",
#     "expires_at": "2026-06-02T00:00:00Z" }

<script src="https://kalutakyc.com/embed.js"></script>
<button onclick="open()">Verify my identity</button>
<script>
  function open() {
    KalutaKYC.open({
      url: "https://kalutakyc.com/verify/abc123",
      onComplete: (r) => console.log(r.status, r.score),
    });
  }
</script>

app.post("/hooks/kaluta", (req, res) => {
  if (!isSignatureValid(req)) return res.status(401).end();
  if (req.body.event === "session.approved") {
    // unlock the user account
  }
  res.sendStatus(200);
});

X-API-Key: klt_live_xxxxxxxxxxxxxxxxxxxxxxxx

POST /v1/sessions
X-API-Key: klt_live_xxx

{
  "external_id":   "user_42",
  "redirect_url":  "https://yourapp.com/kyc/done",
  "webhook_url":   "https://yourapp.com/hooks/kyc",
  "metadata":      { "plan": "premium" },

  "first_name":    "Jean Baptiste",
  "last_name":     "Kouame",
  "date_of_birth": "1992-03-15",
  "country":       "CI"
}

{
  "session_id":       "abc123",
  "verification_url": "https://kalutakyc.com/verify/abc123",
  "expires_at":       "2026-06-02T00:00:00Z"
}

POST /v1/sessions/{rejected_session_id}/retry
# → { "session_id": "def456", "verification_url": "...", "retry_index": 1 }

GET /v1/sessions/{id}
Authorization: Bearer <jwt>

<script src="https://kalutakyc.com/embed.js"></script>

<button id="verify-btn">Verify my identity</button>
<script>
  document.getElementById("verify-btn").addEventListener("click", () => {
    KalutaKYC.open({
      url: "https://kalutakyc.com/verify/abc123",
      onReady:    ()  => console.log("widget loaded"),
      onStep:     (s) => console.log("step:", s),
      onComplete: (r) => console.log(r.status, r.score),
      onClose:    ()  => console.log("widget closed"),
    });
  });
</script>

window.location.href = verificationUrl;
// or
KalutaKYC.redirect(verificationUrl);

https://yourapp.com/kyc/done
  ?kyc_session_id=abc123
  &kyc_status=approved        // approved | rejected
  &kyc_external_id=user_42    // your own reference, if you set one

PUT /v1/auth/me
Authorization: Bearer <jwt>

{ "require_document_video": true }

POST /v1/sessions/{id}/document-video
Content-Type: multipart/form-data

files=@frame_01.jpg
files=@frame_02.jpg
files=@frame_03.jpg
...
# or a single clip: files=@tilt.mp4

POST /v1/kyb/sessions
X-API-Key: klt_live_xxx

{
  "external_id":  "company_42",
  "redirect_url": "https://yourapp.com/kyb/done",
  "webhook_url":  "https://yourapp.com/hooks/kyb",
  "metadata":     { "tier": "enterprise" },

  "legal_name":          "ACME TRADING SARL",
  "registration_number": "CI-ABJ-2019-B-12345",
  "country":             "CI",

  "representative_session_id": "abc123"
}

{
  "session_id":       "kyb_abc123",
  "verification_url": "https://kalutakyc.com/kyb/kyb_abc123",
  "expires_at":       "2026-08-11T00:00:00Z"
}

POST /v1/kyb/sessions/{id}/documents
Content-Type: multipart/form-data

doc_type=registration_extract
file=@extract.pdf

# then, when the representative is done:
POST /v1/kyb/sessions/{id}/submit

{
  "event": "kyb.verified",
  "timestamp": "2026-08-05T10:14:02Z",
  "session": {
    "id": "kyb_abc123",
    "external_id": "company_42",
    "status": "approved",
    "company": {
      "legal_name": "ACME TRADING SARL",
      "trading_name": "Acme",
      "registration_number": "CI-ABJ-2019-B-12345",
      "tax_number": "1943827K",
      "incorporation_date": "2019-06-14",
      "company_type": "SARL",
      "country": "CIV",
      "registered_address": "Rue du Commerce, Plateau, Abidjan",
      "company_status": "active",
      "directors": [{ "name": "Jean Baptiste Kouame", "role": "Gerant" }]
    },
    "overall_score": 84,
    "risk_level": "low",
    "scores": { "document": 88, "data_match": 100 },
    "representative_session_id": "abc123",
    "ai_extraction": { }
  }
}

// app/actions/verify.ts
"use server";
export async function createVerificationSession(externalId: string) {
  const res = await fetch("https://kalutakyc.com/v1/sessions", {
    method: "POST",
    headers: {
      "X-API-Key": process.env.KALUTA_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      external_id: externalId,
      redirect_url: `${process.env.NEXT_PUBLIC_APP_URL}/kyc/done`,
    }),
    cache: "no-store",
  });
  if (!res.ok) throw new Error("Failed to create session");
  return res.json() as Promise<{ session_id: string; verification_url: string }>;
}

// app/kyc/page.tsx
"use client";
import Script from "next/script";
import { useState } from "react";
import { createVerificationSession } from "@/app/actions/verify";
declare global { interface Window { KalutaKYC: any } }

export default function KycPage() {
  const [status, setStatus] = useState("");
  const start = async () => {
    const { verification_url } = await createVerificationSession("user_42");
    window.KalutaKYC.open({
      url: verification_url,
      onComplete: (r: any) => setStatus(`${r.status} (score ${r.score})`),
    });
  };
  return (<>
    <Script src="https://kalutakyc.com/embed.js" strategy="afterInteractive" />
    <button onClick={start} className="bg-blue-600 text-white px-5 py-3 rounded-lg">
      Verify my identity
    </button>
    <p>{status}</p>
  </>);
}

<?php // create-session.php
header("Content-Type: application/json");
$ch = curl_init("https://kalutakyc.com/v1/sessions");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST           => true,
  CURLOPT_HTTPHEADER     => [
    "X-API-Key: " . getenv("KALUTA_API_KEY"),
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "external_id"  => $_POST["user_id"] ?? "anon",
    "redirect_url" => "https://example.com/kyc/done",
  ]),
]);
$resp = curl_exec($ch);
http_response_code(curl_getinfo($ch, CURLINFO_HTTP_CODE));
echo $resp;

<!-- verify.html -->
<button id="go">Verify my identity</button>
<script src="https://kalutakyc.com/embed.js"></script>
<script>
  document.getElementById("go").addEventListener("click", async () => {
    const r = await fetch("/create-session.php", { method: "POST" });
    const { verification_url } = await r.json();
    KalutaKYC.open({
      url: verification_url,
      onComplete: (result) => alert("Status: " + result.status),
    });
  });
</script>

import express from "express";
import crypto from "node:crypto";
const app = express();

app.post("/api/create-session", express.json(), async (req, res) => {
  const r = await fetch("https://kalutakyc.com/v1/sessions", {
    method: "POST",
    headers: {
      "X-API-Key": process.env.KALUTA_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ external_id: req.body.userId }),
  });
  res.status(r.status).json(await r.json());
});

app.post("/hooks/kaluta", express.raw({ type: "application/json" }), (req, res) => {
  const raw = req.body;
  const sig = req.get("x-kaluta-signature") || "";
  const [ts, v1] = sig.split(",").map(p => p.split("=")[1]);
  const expected = crypto
    .createHmac("sha256", process.env.KALUTA_WEBHOOK_SECRET)
    .update(`${ts}.${raw}`).digest("hex");
  if (!crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected))) {
    return res.sendStatus(401);
  }
  const { event } = JSON.parse(raw.toString());
  if (event === "session.approved") { /* unlock account */ }
  res.sendStatus(200);
});

import os, hmac, hashlib, httpx
from fastapi import FastAPI, Request, HTTPException
app = FastAPI()
API_KEY = os.environ["KALUTA_API_KEY"]
SECRET  = os.environ["KALUTA_WEBHOOK_SECRET"].encode()

@app.post("/api/create-session")
async def create_session(payload: dict):
    async with httpx.AsyncClient() as client:
        r = await client.post(
            "https://kalutakyc.com/v1/sessions",
            headers={"X-API-Key": API_KEY},
            json={"external_id": payload["user_id"]},
        )
    return r.json()

@app.post("/hooks/kaluta")
async def webhook(request: Request):
    raw = await request.body()
    sig = request.headers.get("x-kaluta-signature", "")
    ts, v1 = (p.split("=")[1] for p in sig.split(","))
    expected = hmac.new(SECRET, f"{ts}.".encode() + raw, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(v1, expected):
        raise HTTPException(status_code=401)
    return {"ok": True}

# views.py
import os, json, hmac, hashlib, requests
from django.http import JsonResponse, HttpResponse
from django.views.decorators.csrf import csrf_exempt
from django.views.decorators.http import require_POST

API_KEY = os.environ["KALUTA_API_KEY"]
SECRET  = os.environ["KALUTA_WEBHOOK_SECRET"].encode()

@require_POST
def create_session(request):
    body = json.loads(request.body)
    r = requests.post(
        "https://kalutakyc.com/v1/sessions",
        headers={"X-API-Key": API_KEY},
        json={"external_id": body["user_id"]},
        timeout=10,
    )
    return JsonResponse(r.json(), status=r.status_code)

@csrf_exempt
@require_POST
def kaluta_webhook(request):
    raw = request.body
    sig = request.headers.get("X-Kaluta-Signature", "")
    ts, v1 = (p.split("=")[1] for p in sig.split(","))
    expected = hmac.new(SECRET, f"{ts}.".encode() + raw, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(v1, expected):
        return HttpResponse(status=401)
    return HttpResponse("ok")

// routes/api.php
use Illuminate\Http\Request;
use Illuminate\Support\Facades\{Http, Route};

Route::post("/create-session", function (Request $r) {
    $resp = Http::withHeaders(["X-API-Key" => config("services.kaluta.key")])
        ->post("https://kalutakyc.com/v1/sessions", [
            "external_id" => $r->input("user_id"),
        ]);
    return response()->json($resp->json(), $resp->status());
});

Route::post("/hooks/kaluta", function (Request $r) {
    $raw = $r->getContent();
    $sig = $r->header("X-Kaluta-Signature", "");
    [$ts, $v1] = array_map(fn($p) => explode("=", $p)[1], explode(",", $sig));
    $expected = hash_hmac("sha256", "$ts.$raw", config("services.kaluta.webhook_secret"));
    abort_unless(hash_equals($expected, $v1), 401);
    return response("ok");
})->withoutMiddleware([\App\Http\Middleware\VerifyCsrfToken::class]);

<button id="go">Verify my identity</button>
<p id="result"></p>
<script src="https://kalutakyc.com/embed.js"></script>
<script>
  document.getElementById("go").onclick = async () => {
    const res = await fetch("/api/create-session", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ user_id: "user_42" }),
    });
    const { verification_url } = await res.json();
    KalutaKYC.open({
      url: verification_url,
      onComplete: (r) => {
        document.getElementById("result").textContent =
          "Final status: " + r.status + " (score " + r.score + ")";
      },
    });
  };
</script>

X-Kaluta-Signature: t=1722070800,v1=8f4b3a...

{
  "event": "session.verified",
  "timestamp": "2026-08-03T14:23:11Z",
  "session": {
    "id": "abc123",
    "external_id": "user_42",
    "status": "approved",
    "identity": {
      "first_name": "Jean Baptiste",
      "last_name": "Kouame",
      "date_of_birth": "1992-03-15",
      "gender": "M",
      "nationality": "CIV",
      "document_type": "national_id",
      "document_number": "CI004587219",
      "document_expiry": "2030-08-22"
    },
    "overall_score": 87,
    "risk_level": "low",
    "rejection_reason": null,
    "scores": { "document": 92, "face": 88, "liveness": null, "poa": null },
    "checks_required": { "liveness": false, "proof_of_address": false },
    "ai_extraction": { /* raw model output: MRZ, confidence, tampering_signs, ... */ },
    "proof_of_address": null,
    "attempt_count": 1,
    "created_at": "2026-08-03T14:20:05Z",
    "completed_at": "2026-08-03T14:23:11Z"
  }
}

{
  "id":            "abc123",
  "external_id":   "user_42",
  "status":        "approved",
  "document_type": "passport",
  "first_name":    "Ada",
  "last_name":     "Lovelace",
  "date_of_birth": "1815-12-10",
  "nationality":   "GBR",
  "document_number":  "P12345678",
  "document_expiry":  "2030-01-01",
  "document_score":   92,
  "face_score":       96,
  "liveness_score":   90,
  "overall_score":    93,
  "risk_level":       "low",
  "extracted_data":   { /* full OCR/MRZ payload */ },
  "checks":           { "mrz_detected": true, "face_match": true, "liveness": true },
  "metadata":         { "plan": "premium" },
  "created_at":       "2026-06-01T12:00:00Z",
  "completed_at":     "2026-06-01T12:01:42Z"
}

{ "detail": "Invalid API key" }