Mit Zoi ID entwickeln

1. 1

   Sitzung erstellen

   Ihr Backend ruft POST /v1/partner/sessions mit Ihrem Partnerschlüssel auf.

2. 2

   Ablauf ausführen

   Geben Sie das Client-Token an das SDK oder öffnen Sie verificationUrl in einem Browser.

3. 3

   Ergebnis empfangen

   Prüfen Sie die Webhook-Signatur und speichern Sie dann die Identitäts-ID und ihren Status.

curl https://kyc.zoi.network/v1/partner/sessions \
  -H "Authorization: Bearer $ZOI_ID_PARTNER_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: signup-user_42" \
  -d '{ "externalUserId": "user_42", "level": "standard", "appId": "com.example.app" }'

Konventionen

• Zeiten sind Epoch-Millisekunden, in Feldern, deren Name auf At endet.
• Daten haben das Format YYYY-MM-DD. Unbekannte Teile sind XX, zum Beispiel 1990-XX-XX.
• POST-Anfragen, die etwas anlegen oder entscheiden, akzeptieren einen Idempotency-Key-Header. Schlüssel werden 24 Stunden gespeichert.
• Änderungen an einer Sitzung senden die erwartete Revision. Hat sie sich geändert, bekommen Sie revision_conflict.

1. Sitzung im Backend erstellen

Ein erneuter Aufruf für denselben Nutzer setzt die offene Sitzung fort und gibt ein neues Client-Token.

POST /v1/partner/sessions
Authorization: Bearer <partner key>
Content-Type: application/json
Idempotency-Key: 6f1c2a9e-signup-42

{
  "externalUserId": "user_42",
  "level": "standard",
  "locale": "en",
  "appId": "com.example.app"
}

200 OK
{
  "sessionId": "ses_...",
  "clientToken": "...",
  "clientTokenExpiresAt": 1767225600000,
  "status": "created",
  "apiBaseUrl": "https://kyc.zoi.network",
  "resumed": false
}

2. Schritte, die das SDK ausführt

1. 01

   Sitzung und die noch nötigen Schritte lesen.

   GET /v1/client/session

2. 02

   Einwilligung speichern, mit der eigenen, freiwilligen Wahl zum Gesichtsvergleich.

   POST /v1/client/consent

3. 03

   App und Gerät prüfen. Das Ergebnis fließt in die Entscheidung ein.

   POST /v1/client/attestation/challenge, POST /v1/client/attestation

4. 04

   Dokument senden: Chip nach einem MRZ-Scan lesen oder Fotos senden.

   POST /v1/client/document/mrz-scan, POST /v1/client/document/chip/challenge, POST /v1/client/document/chip or POST /v1/client/document/photos

5. 05

   Ein kurzes Video mit der Frontkamera aufnehmen, während die App die Kopfbewegungen zeigt.

   POST /v1/client/liveness/challenge, POST /v1/client/liveness

6. 06

   Wohnsitzland senden, auf der erweiterten Stufe auch die Adresse.

   POST /v1/client/profile

7. 07

   Nur mit der Anforderung Adresse: ein Dokument hochladen, dann die Adresse bestätigen. Entfällt, wenn das Ausweisdokument sie schon geliefert hat.

   POST /v1/client/address/document, POST /v1/client/address/confirm

8. 08

   Nur mit einer Anforderung zur Mittelherkunft: Antworten speichern, Dokumente hinzufügen, wenn die Policy sie verlangt, dann den Schritt abschließen.

   POST /v1/client/funds/answers, POST /v1/client/funds/document, POST /v1/client/funds/remove, POST /v1/client/funds/complete

9. 09

   Zwei Fragen beantworten: politisch exponierte Person und Handeln im eigenen Namen.

   POST /v1/client/declarations

10. 10

    Mit der aktuellen Revision absenden.

    POST /v1/client/submit

Der Nutzer kann auch eine menschliche Prüfung eines automatischen Ergebnisses verlangen (POST /review-request) oder die Einwilligung widerrufen; das bricht die Sitzung ab und löscht ihre Dateien sofort (POST /withdraw).

POST /v1/partner/sessions
Authorization: Bearer <partner key>
Content-Type: application/json

{
  "externalUserId": "user_42",
  "level": "standard",
  "appId": "com.example.app",
  "requirements": ["address", "source_of_funds"],
  // Optional. Without them your partner default applies, else ours.
  "addressPolicy": { "maxAgeDays": 90, "signedOnly": false },
  "fundsPolicy": { "evidence": "optional", "currency": "EUR" }
}

Optionale Policies

Ohne Policy gilt Ihr Partner-Standard, sonst unserer. Die Policy wird beim Erstellen in die Sitzung kopiert.

• addressPolicy: maxAgeDays (Standard 90, 1 bis 366), acceptedTypes (Standard: Versorger-, Telekom- und Bankdokumente, Steuerdokumente, Behördenschreiben und Wohnsitzbescheinigungen) und signedOnly (Standard false).
• fundsPolicy: questions, evidence (none, optional oder required, Standard none), acceptedTypes, maxAgeDays (Standard 180), currency (ISO 4217, Standard USD) und brackets für die Spannen.
• Eine offene, noch nicht abgesendete Sitzung mit anderen Anforderungen wird abgebrochen, und eine neue startet, wie bei einem Stufenwechsel.
• Testen Sie jedes Ergebnis mit Sandbox-Szenarien wie address_signed_pdf, address_document_review, funds_signed_documents und funds_review.

• Der Nutzer willigt ein und erledigt nur die neuen Schritte. Dokument, Selfie und Erklärungen werden nicht erneut abgefragt.
• Bei Genehmigung behält die Identität ihre ID, ihr Verifizierungsdatum und ihre Gültigkeit und erhält das neue Ergebnis. Sie bekommen session.approved und identity.updated.
• Ohne aktive Identität antwortet der Aufruf mit 409 step_not_allowed.
• Starten Sie sie aus Ihren eigenen Risikoregeln heraus, etwa bei einer hohen Einzahlung, einem PEP-Treffer oder einem Risikoland. Ihre Regeln bleiben in Ihrem Backend, an einem Ort.

POST /v1/partner/sessions
Authorization: Bearer <partner key>
Content-Type: application/json
Idempotency-Key: edd-user_42-2026-11

{
  "externalUserId": "user_42",
  "appId": "com.example.app",
  "requirements": ["source_of_funds", "source_of_wealth"],
  "reuseIdentity": true,
  "fundsPolicy": { "evidence": "required" }
}

// No active identity for user_42:
409 { "error": { "code": "step_not_allowed", ... } }

• Scope address: die Adresszeilen. Ohne ihn erhalten Sie verified, method, evidenceLevel, documentType, documentDate, verifiedAt und country.
• Scope financial_data: answers, documents und findings. Ohne ihn erhalten Sie kinds, evidenceLevel, reviewed, documentCount und verifiedAt. Er ist nie Teil von eligibility.
• evidenceLevel ist high, medium, low oder none. Adressmethoden, die stärkste zuerst: wallet, id_document, signed_pdf, official_code, document_review und declared.
• Dokumente werden nicht über die API gesendet. Mitglieder mit der Compliance-Rolle können Dokumentseiten zur Mittelherkunft im Dashboard ansehen, wenn die Umgebung den Scope financial_data hat. Jede Ansicht wird protokolliert.

"session": {
  "id": "ses_...",
  "status": "approved",
  "requirements": ["address", "source_of_funds"],
  "reusesIdentity": false,
  "address": {
    "verified": true,
    "method": "signed_pdf",
    "evidenceLevel": "high",
    "documentType": "bank_statement",
    "documentDate": "2026-10-14",
    "verifiedAt": 1767225600000,
    "country": "DE",
    // scope "address"
    "address": { "line1": "Musterstrasse 12", "city": "Berlin", "postalCode": "10115", "country": "DE" }
  },
  "funds": {
    "kinds": ["source_of_funds"],
    "evidenceLevel": "medium",
    "reviewed": true,
    "documentCount": 2,
    "verifiedAt": 1767225600000,
    // scope "financial_data"
    "answers": {
      "employmentStatus": "employed",
      "income": { "min": 50000, "max": 100000, "currency": "EUR" },
      "sources": ["salary", "savings"],
      ...
    },
    "documents": [
      { "documentType": "payslip", "documentDate": "2026-10-31", "amount": 5200, "currency": "EUR",
        "signature": "valid", "signedByKnownIssuer": true, "nameMatch": "match", "findings": [], ... },
      ...
    ],
    "findings": []
  }
}

1. Den Link holen

POST /v1/partner/sessions gibt verificationUrl zurück. Geben Sie redirectUrl mit, um den Nutzer am Ende zurückzuschicken. Die URL muss mit einem Ihrer registrierten Redirect-Origins beginnen.

POST /v1/partner/sessions
Authorization: Bearer <partner key>
Content-Type: application/json

{
  "externalUserId": "user_42",
  "level": "standard",
  "locale": "en",
  "appId": "com.example.app",
  "redirectUrl": "https://example.com/kyc/done"
}

200 OK
{
  "sessionId": "ses_...",
  "clientToken": "...",
  "verificationUrl": "https://kyc.zoi.network/verify/#token=...&lang=en",
  ...
}

• Das Client-Token steht im Fragment der URL, nach #. Browser senden das Fragment nie an einen Server, daher steht das Token nicht in Logs oder im Referer-Header. Die Seite liest es, entfernt es aus der Adressleiste und hält es nur im Speicher.
• Fügen Sie lang zum Fragment hinzu, um eine der 19 Sprachen zu wählen. Ohne den Wert nutzt die Seite die Sprache des Browsers.
• Beim Neuladen geht das Token verloren. Erstellen Sie in Ihrem Backend einen neuen Link für dieselbe Sitzung.
• Die Seite sendet channel: "web" mit der Einwilligung. Browser können keine Ausweischips lesen, daher nutzen Web-Sitzungen Dokumentfotos oder eine digitale Ausweis-Wallet. Sie überspringen die Geräteprüfung, und über Dokumentfotos aus dem Web entscheidet immer ein geschulter Prüfer.
• Auf einem Computer zeigt die Seite einen QR-Code, damit der Nutzer auf dem Handy weitermachen kann.

2. Wenn der Nutzer fertig ist

Wenn der Ablauf endet (gesendet, abgebrochen oder ein Endstatus), sendet die Seite diese Nachricht an jedes dieser Objekte, das existiert: window.ReactNativeWebView, window.webkit.messageHandlers.zoiId, window.ZoiIdAndroid und window.opener. Danach öffnet sie redirectUrl mit den Parametern zoiIdSession und zoiIdStatus.

Vertrauen Sie nie der Nachricht oder den Redirect-Parametern. Vertrauen Sie nur Ihrem Webhook oder GET /v1/partner/sessions/:id.

// Sent to each bridge that exists:
//   window.ReactNativeWebView.postMessage(JSON string)
//   window.webkit.messageHandlers.zoiId.postMessage(object)
//   window.ZoiIdAndroid.postMessage(JSON string)
//   window.opener.postMessage(object, "<origin of your redirectUrl>")
//     (popups only, and only when the session has a redirectUrl)
{
  "source": "zoi-id",
  "type": "finished",        // or "cancelled"
  "sessionId": "ses_...",
  "status": "processing"     // the session status at that moment
}

// Then, if redirectUrl was set (the page uses the one stored with the
// session, never one from the address bar):
https://example.com/kyc/done?zoiIdSession=ses_...&zoiIdStatus=processing

3. Webview-Einstellungen

webView.settings.javaScriptEnabled = true
webView.settings.domStorageEnabled = true
webView.settings.mediaPlaybackRequiresUserGesture = false
webView.webChromeClient = object : WebChromeClient() {
  override fun onPermissionRequest(request: PermissionRequest) {
    // Only after your app holds Manifest.permission.CAMERA.
    if (request.resources.contains(PermissionRequest.RESOURCE_VIDEO_CAPTURE)) {
      request.grant(arrayOf(PermissionRequest.RESOURCE_VIDEO_CAPTURE))
    } else {
      request.deny()
    }
  }
  override fun onShowFileChooser(
    view: WebView, callback: ValueCallback<Array<Uri>>, params: FileChooserParams,
  ): Boolean {
    // Open a picker and pass the result to callback (photo fallback).
    return true
  }
}

let config = WKWebViewConfiguration()
config.allowsInlineMediaPlayback = true
let webView = WKWebView(frame: .zero, configuration: config)
webView.uiDelegate = self // iOS 15+: decide camera access below

func webView(_ webView: WKWebView,
             requestMediaCapturePermissionFor origin: WKSecurityOrigin,
             initiatedByFrame frame: WKFrameInfo,
             type: WKMediaCaptureType,
             decisionHandler: @escaping (WKPermissionDecision) -> Void) {
  decisionHandler(origin.host == "kyc.zoi.network" ? .grant : .deny)
}
// Info.plist: NSCameraUsageDescription

<WebView
  source={{ uri: verificationUrl }}
  javaScriptEnabled
  allowsInlineMediaPlayback
  mediaCapturePermissionGrantType="grant"
  onMessage={(event) => {
    const message = JSON.parse(event.nativeEvent.data);
    if (message.source === "zoi-id") {
      // Close the webview, then ask your backend for the real status.
    }
  }}
/>

iframes werden nicht unterstützt, wegen der Kamera-Berechtigungen und wegen Clickjacking. Nutzen Sie einen Browser-Tab, ein Popup oder eine Webview.

• Jeder Webhook hat einen Zoi-Id-Signature-Header: t=unix seconds,v1=hex.
• v1 ist der HMAC-SHA256 des Textes t.raw body mit Ihrem Webhook-Secret. Nutzen Sie den rohen Body, vor jedem JSON-Parsing.
• Während ein Secret gewechselt wird, enthält der Header ein v1 pro aktivem Secret. Akzeptieren Sie den Webhook, wenn eines davon passt.
• Lehnen Sie ihn ab, wenn t mehr als 300 Sekunden von jetzt abweicht.
• Fehlgeschlagene Zustellungen werden 72 Stunden lang wiederholt. Jeder Versuch wird mit einem neuen t neu signiert.
• Identitäten haben eine revision. Wenden Sie ein Event nur an, wenn seine Revision neuer ist als die gespeicherte.

POST <your webhook URL>
Zoi-Id-Signature: t=1767225600,v1=5f2b...e9

{
  "v": 1,
  "eventId": "evt_...",
  "type": "identity.suspended",
  "createdAt": 1767225600000,
  "object": "identity",
  "externalUserId": "user_42",
  "identity": {
    "identityId": "idn_...",
    "revision": 7,
    "status": "suspended",
    "level": "standard",
    "verifiedAt": 1764547200000,
    "validUntil": 1859155200000,
    "ageOver18": true,
    "captureMethod": "nfc"
  }
}

Event-Typen

• session.processing
• session.review
• session.approved
• session.rejected
• session.resubmit
• session.expired
• session.cancelled
• identity.updated
• identity.suspended
• identity.reinstated
• identity.expired
• identity.revoked

Signatur in TypeScript prüfen

import { createHmac, timingSafeEqual } from "node:crypto";

const TOLERANCE_SECONDS = 300;

export function verifyZoiIdSignature(
  rawBody: string,
  header: string | null,
  secret: string,
  nowSeconds = Math.floor(Date.now() / 1000),
): boolean {
  if (!header) return false;

  let t: string | undefined;
  const signatures: Buffer[] = [];
  for (const part of header.split(",")) {
    const [key, value] = part.trim().split("=");
    if (!value) continue;
    if (key === "t") t = value;
    if (key === "v1" && /^[0-9a-f]+$/i.test(value)) signatures.push(Buffer.from(value, "hex"));
  }
  if (!t || !/^\d+$/.test(t) || signatures.length === 0) return false;
  if (Math.abs(nowSeconds - Number(t)) > TOLERANCE_SECONDS) return false;

  const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest();
  return signatures.some((sig) => sig.length === expected.length && timingSafeEqual(sig, expected));
}

// Example handler: read the raw body first, parse JSON only after the check.
export async function POST(request: Request) {
  const rawBody = await request.text();
  const ok = verifyZoiIdSignature(rawBody, request.headers.get("Zoi-Id-Signature"), process.env.ZOI_ID_WEBHOOK_SECRET!);
  if (!ok) return new Response("bad signature", { status: 400 });

  const event = JSON.parse(rawBody);
  // Store event.eventId to skip duplicates, then apply it if the revision is newer.
  return new Response(null, { status: 204 });
}

Signatur in Go prüfen

package zoiid

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"strconv"
	"strings"
	"time"
)

const toleranceSeconds = 300

// VerifySignature checks the Zoi-Id-Signature header against the raw body.
func VerifySignature(rawBody []byte, header, secret string, now time.Time) bool {
	var t string
	var sigs [][]byte
	for _, part := range strings.Split(header, ",") {
		key, value, ok := strings.Cut(strings.TrimSpace(part), "=")
		if !ok || value == "" {
			continue
		}
		switch key {
		case "t":
			t = value
		case "v1":
			if b, err := hex.DecodeString(value); err == nil {
				sigs = append(sigs, b)
			}
		}
	}
	ts, err := strconv.ParseInt(t, 10, 64)
	if err != nil || len(sigs) == 0 {
		return false
	}
	if d := now.Unix() - ts; d > toleranceSeconds || d < -toleranceSeconds {
		return false
	}

	mac := hmac.New(sha256.New, []byte(secret))
	mac.Write([]byte(t + "."))
	mac.Write(rawBody)
	expected := mac.Sum(nil)
	for _, sig := range sigs {
		if hmac.Equal(sig, expected) {
			return true
		}
	}
	return false
}

• Scope sessions:write. Nur für entschiedene Sitzungen (genehmigt oder abgelehnt). Vor einer Entscheidung antwortet der Aufruf mit 409.
• Ein leerer Body meldet confirmed_fraud mit der Kategorie other. status kann auch suspected_fraud sein, oder cleared, um Ihre eigene Meldung zurückzunehmen.
• Kategorien: forged_document, impostor, deepfake_or_replay, synthetic_identity, account_takeover und other. Keine Kategorie bei cleared.
• note ist Freitext für unsere Analysten, höchstens 1000 Zeichen. Tragen Sie dort nie Namen, Dokumentnummern oder andere personenbezogene Daten ein.
• Eine neue Meldung antwortet mit 201. Dieselbe Meldung erneut liefert die gespeicherte mit 200. Senden Sie einen Idempotency-Key, um gefahrlos zu wiederholen. Höchstens 20 Meldungen pro Sitzung.
• Dieselbe Meldung ist auf der Sitzungsseite im Dashboard nur einen Klick entfernt.

POST /v1/partner/sessions/ses_.../fraud-reports
Authorization: Bearer <partner key>
Content-Type: application/json
Idempotency-Key: chargeback-8812

{
  "status": "confirmed_fraud",
  "category": "impostor",
  "note": "Chargeback on the first deposit"
}

201 Created
{
  "id": "flb_...",
  "sessionId": "ses_...",
  "status": "confirmed_fraud",
  "category": "impostor",
  "noteKept": true,
  "createdAt": 1767225600000
}

{
  "error": {
    "code": "step_not_allowed",
    "message": "This step is not allowed now.",
    "requestId": "req_..."
  }
}

Grundcodes

Sitzungen enthalten reasonCodes, wenn sie erneut eingereicht werden müssen oder abgelehnt sind. Zeigen Sie für jeden Code Ihre eigene übersetzte Meldung. Zeigen Sie Nutzern nie den rohen Code.

• consent_missing
• consent_withdrawn
• attestation_failed
• document_expired
• document_unreadable
• document_not_supported
• document_suspected_tampering
• document_number_visible
• chip_verification_failed
• chip_proof_missing
• chip_data_mismatch
• mrz_invalid
• photo_quality
• face_not_found
• face_mismatch
• liveness_failed
• underage
• location_not_supported
• residence_not_supported
• sanctions_match
• pep_review
• duplicate_identity
• possible_duplicate
• declaration_requires_review
• user_requested_review
• reviewer_other
• address_unreadable
• address_document_too_old
• address_document_not_accepted
• address_name_mismatch
• address_signature_required
• funds_document_unreadable
• funds_document_too_old
• funds_document_not_accepted
• funds_more_evidence
• funds_evidence_rejected