Jenga kwa Zoi ID

1. 1

   Unda kipindi

   Backend yako huita POST /v1/partner/sessions kwa ufunguo wako wa mshirika.

2. 2

   Endesha mtiririko

   Pitisha tokeni ya mteja kwa SDK, au fungua verificationUrl kwenye kivinjari.

3. 3

   Pokea matokeo

   Kagua sahihi ya webhook, kisha hifadhi kitambulisho cha utambulisho na hali yake.

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

Kanuni

• Muda ni milisekunde za epoch, kwenye sehemu ambazo majina yake huishia na At.
• Tarehe ziko kwa muundo YYYY-MM-DD. Sehemu zisizojulikana ni XX, kwa mfano 1990-XX-XX.
• Maombi ya POST yanayounda au kuamua kitu hukubali kichwa Idempotency-Key. Funguo huhifadhiwa kwa saa 24.
• Mabadiliko ya kipindi hutuma toleo linalotarajiwa. Likiwa limebadilika, unapata revision_conflict.

1. Unda kipindi kutoka seva yako

Ukiita tena kwa mtumiaji yuleyule, kipindi kilicho wazi kinaendelea na tokeni mpya ya mteja inatolewa.

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. Hatua ambazo SDK huendesha

1. 01

   Soma kipindi na hatua ambazo bado zinahitajika.

   GET /v1/client/session

2. 02

   Rekodi idhini, pamoja na chaguo tofauti la hiari la kulinganisha uso.

   POST /v1/client/consent

3. 03

   Kagua programu na kifaa. Matokeo ni sehemu ya uamuzi.

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

4. 04

   Tuma hati: soma chipu baada ya kuchanganua MRZ, au tuma picha.

   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

   Rekodi video fupi moja kwa kamera ya mbele wakati programu inaonyesha mijongeo ya kichwa.

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

6. 06

   Tuma nchi ya ukaazi, na anwani kwenye kiwango cha ziada.

   POST /v1/client/profile

7. 07

   Pale tu kuna sharti la anwani: pakia hati, kisha thibitisha anwani. Huachwa pale hati ya utambulisho tayari imeitoa.

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

8. 08

   Pale tu kuna sharti la fedha: hifadhi majibu, ongeza hati sera inapozihitaji, kisha kamilisha hatua.

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

9. 09

   Jibu maswali mawili: je, ni mtu mwenye wadhifa wa kisiasa, na je, anafanya kwa niaba yake mwenyewe.

   POST /v1/client/declarations

10. 10

    Wasilisha kwa toleo la sasa.

    POST /v1/client/submit

Mtumiaji pia anaweza kuomba mtu akague tena matokeo ya kiotomatiki (POST /review-request) au kuondoa idhini, jambo linalositisha kipindi na kufuta faili zake mara moja (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" }
}

Sera za hiari

Bila sera, chaguo-msingi lako la mshirika hutumika, la sivyo letu. Sera hunakiliwa kwenye kipindi kinapoundwa.

• addressPolicy: maxAgeDays (chaguo-msingi 90, 1 hadi 366), acceptedTypes (chaguo-msingi: hati za huduma, simu na benki, hati za kodi, barua za serikali na vyeti vya makazi) na signedOnly (chaguo-msingi false).
• fundsPolicy: questions, evidence (none, optional au required, chaguo-msingi none), acceptedTypes, maxAgeDays (chaguo-msingi 180), currency (ISO 4217, chaguo-msingi USD) na brackets kwa viwango.
• Kipindi kilicho wazi chenye masharti mengine ambacho bado hakijawasilishwa hughairiwa na kipya huanza, kama ilivyo kwa kubadilisha kiwango.
• Jaribu kila matokeo kwa hali za majaribio za sandbox kama address_signed_pdf, address_document_review, funds_signed_documents na funds_review.

• Mtumiaji hutoa idhini na hukamilisha hatua mpya tu. Hati, selfie au matamko haviombwi tena.
• Ikikubaliwa, utambulisho hubaki na kitambulisho chake, tarehe ya uthibitisho na muda wa uhalali, na hupata matokeo mapya. Unapokea session.approved na identity.updated.
• Bila utambulisho ulio hai, mwito hujibu 409 step_not_allowed.
• Kianzishe kutokana na kanuni zako za hatari, kama amana kubwa, alama ya PEP au nchi ya hatari. Kanuni zako hubaki kwenye backend yako, mahali pamoja.

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

• Ruhusa address: mistari ya anwani. Bila hiyo unapata verified, method, evidenceLevel, documentType, documentDate, verifiedAt na country.
• Ruhusa financial_data: answers, documents na findings. Bila hiyo unapata kinds, evidenceLevel, reviewed, documentCount na verifiedAt. Kamwe si sehemu ya eligibility.
• evidenceLevel ni high, medium, low au none. Njia za anwani, kuanzia iliyo imara zaidi: wallet, id_document, signed_pdf, official_code, document_review na declared.
• Hati hazitumwi kupitia API. Wanachama wenye jukumu la uzingatiaji wanaweza kuona kurasa za hati za chanzo cha fedha kwenye dashibodi pale mazingira yana ruhusa financial_data. Kila mtazamo hurekodiwa.

"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. Pata kiungo

POST /v1/partner/sessions hurudisha verificationUrl. Tuma redirectUrl ili kumrudisha mtumiaji kwako akimaliza. Lazima ianze na mojawapo ya asili za kuelekeza ulizosajili.

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

• Tokeni ya mteja iko kwenye fragment ya URL, baada ya #. Vivinjari havitumi fragment kwa seva kamwe, kwa hiyo tokeni haiko kwenye kumbukumbu za seva wala kwenye kichwa cha Referer. Ukurasa huisoma, huiondoa kwenye upau wa anwani na huiweka kwenye kumbukumbu ya kifaa tu.
• Ongeza lang kwenye fragment ili kuchagua mojawapo ya lugha 19. Bila hiyo, ukurasa hutumia lugha ya kivinjari.
• Kupakia upya kunapoteza tokeni. Tengeneza kiungo kipya cha kipindi kile kile kutoka kwenye backend yako.
• Ukurasa hutuma channel: "web" pamoja na idhini. Vivinjari haviwezi kusoma chipu za vitambulisho, kwa hiyo vipindi vya wavuti hutumia picha za hati au pochi ya utambulisho wa kidijitali. Huruka ukaguzi wa kifaa, na picha za hati kutoka kwenye wavuti daima huamuliwa na mkaguzi aliyefunzwa.
• Kwenye kompyuta, ukurasa huonyesha msimbo wa QR ili mtumiaji aendelee kwenye simu.

2. Mtumiaji akimaliza

Mtiririko ukiisha (umetumwa, umeghairiwa au hali ya mwisho), ukurasa hutuma ujumbe huu kwa kila kimoja kilichopo kati ya hivi: window.ReactNativeWebView, window.webkit.messageHandlers.zoiId, window.ZoiIdAndroid na window.opener. Kisha hufungua redirectUrl pamoja na zoiIdSession na zoiIdStatus.

Usiamini kamwe ujumbe huo au vigezo vya kuelekeza. Amini tu webhook yako au 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. Mipangilio ya 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.
    }
  }}
/>

iframe hazitumiki, kwa sababu ya ruhusa za kamera na clickjacking. Tumia kichupo cha kivinjari, dirisha ibukizi au webview.

• Kila webhook ina kichwa Zoi-Id-Signature: t=unix seconds,v1=hex.
• v1 ni HMAC-SHA256 ya maandishi t.raw body kwa siri yako ya webhook. Tumia mwili ghafi, kabla ya kuchanganua JSON.
• Siri inapobadilishwa, kichwa kina v1 moja kwa kila siri hai. Kubali webhook ikiwa yoyote kati yake inalingana.
• Ikatae ikiwa t iko mbali na sasa kwa zaidi ya sekunde 300.
• Utumaji ulioshindwa hujaribiwa tena kwa saa 72. Kila jaribio husainiwa upya kwa t mpya.
• Utambulisho una revision. Tumia tukio tu ikiwa toleo lake ni jipya kuliko ulilohifadhi.

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

Aina za matukio

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

Kagua sahihi kwa 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 });
}

Kagua sahihi kwa 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
}

• Ruhusa sessions:write. Kwa vipindi vilivyoamuliwa tu (vilivyokubaliwa au kukataliwa). Kabla ya uamuzi, mwito hujibu 409.
• Mwili mtupu huripoti confirmed_fraud yenye aina other. status inaweza pia kuwa suspected_fraud, au cleared ili kufuta ripoti yako mwenyewe.
• Aina: forged_document, impostor, deepfake_or_replay, synthetic_identity, account_takeover na other. Hakuna aina pamoja na cleared.
• note ni maandishi huru kwa wachambuzi wetu, yasiyozidi herufi 1000. Usiweke kamwe majina, namba za hati au data nyingine binafsi ndani yake.
• Ripoti mpya hujibu 201. Ripoti ileile ikitumwa tena hurudisha iliyohifadhiwa pamoja na 200. Tuma Idempotency-Key ili kujaribu tena kwa usalama. Hadi ripoti 20 kwa kila kipindi.
• Ripoti hiyohiyo iko mbofyo mmoja tu kwenye ukurasa wa kipindi kwenye dashibodi.

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

Misimbo ya sababu

Vipindi vina reasonCodes vinapohitaji kuwasilishwa tena au vimekataliwa. Onyesha ujumbe wako uliotafsiriwa kwa kila msimbo. Usimwonyeshe mtumiaji msimbo ghafi kamwe.

• 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