Gina da Zoi ID

1. 1

   Ƙirƙiri zama

   Backend ɗinku yana kiran POST /v1/partner/sessions da makullin abokin hulɗa.

2. 2

   Gudanar da tafiya

   Miƙa alamar abokin ciniki ga SDK, ko buɗe verificationUrl a burauza.

3. 3

   Karɓi sakamako

   Duba sa hannun webhook, sannan ajiye lambar shaida da matsayinta.

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" }'

Ƙa'idoji

• Lokaci yana cikin milisakan epoch, a filayen da sunansu ya ƙare da At.
• Kwanan wata yana cikin tsarin YYYY-MM-DD. Sassan da ba a sani ba su ne XX, misali 1990-XX-XX.
• Buƙatun POST da ke ƙirƙira ko yanke hukunci suna karɓar kan saƙo Idempotency-Key. Ana ajiye makullan na awa 24.
• Canje-canje a zama suna aika bugun da ake tsammani. Idan ya canza, kuna samun revision_conflict.

1. Ƙirƙiri zama daga sabar ku

Idan aka sake kira don mai amfani ɗaya, zaman da ke buɗe yana ci gaba kuma ana ba da sabuwar alamar abokin ciniki.

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. Matakan da SDK ke gudanarwa

1. 01

   Karanta zama da matakan da har yanzu ake buƙata.

   GET /v1/client/session

2. 02

   Rubuta amincewa, tare da zaɓi daban na son rai game da kwatanta fuska.

   POST /v1/client/consent

3. 03

   Duba manhaja da na'ura. Sakamakon yana cikin hukuncin.

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

4. 04

   Aika takarda: karanta chip bayan an ɗauki hoton MRZ, ko aika hotuna.

   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

   Ɗauki gajeren bidiyo ɗaya da kyamarar gaba yayin da manhaja ke nuna motsin kai.

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

6. 06

   Aika ƙasar zama, da adireshi a mataki ingantacce.

   POST /v1/client/profile

7. 07

   Sai da buƙatar adireshi kawai: ɗora takarda, sannan ku tabbatar da adireshin. Ana tsallake shi idan takardar shaida ta riga ta ba da shi.

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

8. 08

   Sai da buƙatar kuɗi kawai: ajiye amsoshi, ƙara takardu idan manufar ta buƙace su, sannan ku kammala matakin.

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

9. 09

   Amsa tambayoyi biyu: ko mutum ne mai muƙamin siyasa, da ko yana aiki a madadin kansa.

   POST /v1/client/declarations

10. 10

    Miƙa da bugun yanzu.

    POST /v1/client/submit

Mai amfani kuma zai iya neman mutum ya sake duba sakamakon atomatik (POST /review-request) ko ya janye amincewa, wanda ke soke zaman kuma ya goge fayilolinsa nan take (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" }
}

Manufofi na son rai

Idan babu manufa, saitin tsoho naku na abokin hulɗa ne ke aiki, in ba haka ba namu. Ana kwafa manufar a kan zaman lokacin da aka ƙirƙira shi.

• addressPolicy: maxAgeDays (tsoho 90, 1 zuwa 366), acceptedTypes (tsoho: takardun ayyuka, waya da banki, takardun haraji, wasiƙun gwamnati da takaddun shaidar zama) da signedOnly (tsoho false).
• fundsPolicy: questions, evidence (none, optional ko required, tsoho none), acceptedTypes, maxAgeDays (tsoho 180), currency (ISO 4217, tsoho USD) da brackets don rukunan kuɗi.
• Zama a buɗe mai wasu buƙatu da ba a miƙa ba tukuna ana soke shi kuma sabo ya fara, kamar canjin mataki.
• Gwada kowane sakamako da yanayin gwaji na sandbox kamar address_signed_pdf, address_document_review, funds_signed_documents da funds_review.

• Mai amfani yana ba da amincewa kuma yana kammala sababbin matakai kawai. Ba a sake neman takarda, selfie ko bayanan kai ba.
• Idan aka amince, shaidar tana riƙe lambarta, ranar tabbatarwa da wa'adin aiki, kuma tana samun sabon sakamakon. Kuna karɓar session.approved da identity.updated.
• Idan babu shaida mai aiki, kiran yana amsawa da 409 step_not_allowed.
• Ku fara shi daga ƙa'idodin haɗarinku, kamar babban ajiya, alamar PEP ko ƙasa mai haɗari. Ƙa'idodinku suna zama a backend ɗinku, a wuri ɗaya.

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", ... } }

• Izini address: layukan adireshi. Ba tare da shi ba kuna samun verified, method, evidenceLevel, documentType, documentDate, verifiedAt da country.
• Izini financial_data: answers, documents da findings. Ba tare da shi ba kuna samun kinds, evidenceLevel, reviewed, documentCount da verifiedAt. Ba ya taɓa zama ɓangare na eligibility.
• evidenceLevel shi ne high, medium, low ko none. Hanyoyin adireshi, daga mafi ƙarfi: wallet, id_document, signed_pdf, official_code, document_review da declared.
• Ba a aika takardu ta API. Membobi masu matsayin bin ƙa'idoji za su iya ganin shafukan takardun tushen kuɗi a dashboard idan muhallin yana da izinin financial_data. Ana rubuta kowane kallo.

"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. Samo mahaɗin

POST /v1/partner/sessions yana dawo da verificationUrl. Ku aika redirectUrl don mayar da mai amfani gare ku idan ya gama. Dole ne ya fara da ɗaya daga cikin asalin juyawa da kuka yi rajista.

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",
  ...
}

• Tokin abokin ciniki yana cikin ɓangaren fragment na URL, bayan #. Burauzoji ba sa taɓa aika fragment zuwa sabar, don haka tokin ba ya cikin bayanan log ko kan Referer. Shafin yana karanta shi, yana cire shi daga sandar adireshi kuma yana ajiye shi a ƙwaƙwalwa kawai.
• Ku ƙara lang a fragment don zaɓar ɗaya daga cikin harsuna 19. Idan babu, shafin yana amfani da harshen burauza.
• Sake loda shafi yana rasa tokin. Ku ƙirƙiri sabon mahaɗi don zama ɗaya daga backend ɗinku.
• Shafin yana aika channel: "web" tare da izini. Burauzoji ba za su iya karanta chip na takardun shaida ba, don haka zaman yanar gizo yana amfani da hotunan takarda ko wallet na shaidar dijital. Suna tsallake binciken na'ura, kuma mai bita da aka horar ne koyaushe ke yanke hukunci kan hotunan takarda daga yanar gizo.
• A kwamfuta, shafin yana nuna lambar QR don mai amfani ya ci gaba a waya.

2. Idan mai amfani ya gama

Idan tsarin ya ƙare (an aika, an soke ko matsayi na ƙarshe), shafin yana aika wannan saƙon ga kowanne daga cikin waɗannan da ke akwai: window.ReactNativeWebView, window.webkit.messageHandlers.zoiId, window.ZoiIdAndroid da window.opener. Sannan yana buɗe redirectUrl tare da zoiIdSession da zoiIdStatus.

Kada ku taɓa amincewa da saƙon ko sigogin juyawa. Ku amince da webhook ɗinku ko GET /v1/partner/sessions/:id kawai.

// 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. Saitunan webview

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.
    }
  }}
/>

Ba a goyon bayan iframe, saboda izinin kyamara da clickjacking. Ku yi amfani da shafin burauza, taga mai tashi ko webview.

• Kowane webhook yana da kan saƙo Zoi-Id-Signature: t=unix seconds,v1=hex.
• v1 shi ne HMAC-SHA256 na rubutun t.raw body da sirrin webhook ɗinku. Yi amfani da jikin saƙo kamar yadda yake, kafin karanta JSON.
• Yayin da ake canza sirri, kan saƙon yana da v1 ɗaya ga kowane sirri mai aiki. Karɓi webhook idan ɗaya daga cikinsu ya dace.
• Ƙi shi idan t ya yi nisa da yanzu fiye da daƙiƙa 300.
• Ana sake gwada isarwar da ta kasa har na awa 72. Kowane sake gwadawa ana sake sa masa hannu da sabon t.
• Shaidu suna da revision. Yi amfani da abin da ya faru ne kawai idan bugunsa ya fi wanda kuka ajiye sabo.

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"
  }
}

Nau'ukan abubuwan da suka faru

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

Duba sa hannu a TypeScript

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 });
}

Duba sa hannu a Go

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
}

• Izini sessions:write. Ga zaman da aka yanke hukunci kawai (an amince ko an ƙi). Kafin hukunci, kiran yana amsawa da 409.
• Jikin saƙo maras komai yana ba da rahoton confirmed_fraud da rukuni other. status kuma zai iya zama suspected_fraud, ko cleared don janye rahotonku.
• Rukunai: forged_document, impostor, deepfake_or_replay, synthetic_identity, account_takeover da other. Babu rukuni tare da cleared.
• note rubutu ne na kyauta ga manazartanmu, haruffa 1000 a mafi yawa. Kada ku taɓa saka sunaye, lambobin takardu ko wasu bayanan sirri a ciki.
• Sabon rahoto yana amsawa da 201. Idan aka sake aika rahoto iri ɗaya, yana dawo da wanda aka ajiye da 200. Aika Idempotency-Key don sake gwadawa lafiya. Rahotanni 20 a mafi yawa a kowane zama.
• Rahoto iri ɗaya yana nan da danna ɗaya a shafin zama na dashboard.

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_..."
  }
}

Lambobin dalili

Zama suna ɗauke da reasonCodes idan suna buƙatar sake miƙawa ko an ƙi su. Nuna saƙonku da aka fassara ga kowace lamba. Kada ku taɓa nuna wa masu amfani lambar kamar yadda take.

• 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