Dijital KYC Entegrasyonu Nasıl Yapılır: API ve SDK Adımları

Dijital KYC altyapısını sıfırdan kurmak — NFC SDK, canlılık modeli, biyometrik eşleştirme, görüntülü oturum platformu, audit log, regülasyon uyumu — 12-18 aylık bir mühendislik işine kolayca dönüşür. Bu sebeple çoğu fintech, banka ve kripto borsa hazır bir dijital KYC sağlayıcısının SDK + API'sini entegre etmeyi tercih ediyor. Ancak entegrasyon da iyi yapılmadığında akış sürtünmesi, başarı oranı düşüklüğü ve denetim hattı kopukluğu sorun çıkarır. Bu rehber, bir dijital KYC sağlayıcısının SDK + API katmanını mobil uygulamanıza, web onboarding'inize ve backend'inize entegre etmenin 8 adımını anlatıyor.

Önkoşullar

Entegrasyona başlamadan önce şunlara karar vermiş olmanız gerek:

• Sağlayıcı seçimi — NFC + canlılık + biyometrik + görüntülü tespit katmanlarını tek SDK altında sunan; BDDK ve SPK uyumlu; NIST PAD Level 2+ sertifikalı.
• Akış tasarımı — risk-bazlı tier yapısı (en az 2 seviye), her tier'ın kabul kriterleri belirli.
• Mobil platform desteği — iOS 13+ ve Android API 21+ minimum hedef.
• Backend ortamı — REST API çağrısı yapabilen bir uygulama sunucusu, webhook alıcı, dayanıklı job queue, uzun süreli log saklama altyapısı.
• Hukuki hazırlık — KVKK aydınlatma metni biyometrik veri rejimine uyumlu, açık rıza akışı tasarlanmış, DPA sağlayıcı ile imzalanmış.

Genel dijital KYC mimarisi için dijital KYC rehberimize bakın.

1. Adım: API Anahtarı ve Ortam Kurulumu

İlk adım sağlayıcının developer dashboard'undan API anahtarı (key + secret) ve sandbox/production ortamlarını ayırmak.

Pratik öneri:

• Sandbox ortamı geliştirme + entegrasyon test için.
• Production ortamı sadece canlı müşteri verisi için; deploy pipeline'da farklı secret'larla kontrol edilir.
• API anahtarları asla mobil uygulamada gömülü olmamalı — sadece backend tutulur. Mobil uygulama backend üzerinden geçici oturum token'ı alır.

Tipik backend → sağlayıcı API çağrısı:

POST /api/v1/sessions
Authorization: Bearer <SERVICE_API_KEY>
{
  "user_id": "user_12345",
  "tier": "tier2",
  "callback_url": "https://your-backend/webhooks/kyc"
}

Yanıt olarak session_id ve session_token döner; bu token mobil uygulamaya iletilir.

2. Adım: Mobil SDK'yı Bağla (iOS)

iOS için SDK genelde CocoaPods, SPM (Swift Package Manager) veya doğrudan XCFramework olarak gelir.

Info.plist'e ekle:

• NSCameraUsageDescription — selfie ve görüntülü oturum için kamera izni açıklaması.
• NSMicrophoneUsageDescription — görüntülü oturum için mikrofon.
• NFCReaderUsageDescription — TCKK NFC okuma için.

Entitlement:

• com.apple.developer.nfc.readersession.formats — TAG değeri.

Initialization: SDK initialize edilirken session_token geçirilir, akış konfigürasyonu (NFC zorunlu mu, aktif canlılık var mı) verilir.

3. Adım: Mobil SDK'yı Bağla (Android)

Android için SDK Gradle dependency olarak entegre edilir.

AndroidManifest.xml'e ekle:

• android.permission.CAMERA
• android.permission.RECORD_AUDIO
• android.permission.NFC
• <uses-feature android:name="android.hardware.nfc" android:required="false" /> — NFC olmayan cihazlarda fallback için.

Initialization: İlk akıştan önce runtime permission istenir (kamera, mikrofon). NFC için ek API izni gerekmez ama cihaz desteği kontrol edilir.

Pratik öneri: Android cihaz fragmentasyonu yüksek — düşük segment cihazlarda NFC sürücü kalitesi değişken. SDK'nın cihaz uyumluluk matrisini önceden inceleyin.

4. Adım: Web Kanalı Entegrasyonu

Web tarayıcı tabanlı akış için sağlayıcı genelde JavaScript SDK + iframe yaklaşımı veya redirect tabanlı akış sunar.

JavaScript SDK ile:

• Sayfa içine iframe gömülür.
• session_token ile başlatılır.
• Akış tamamlandığında parent window'a postMessage gönderir.

Redirect tabanlı:

• Backend redirect URL üretir.
• Kullanıcı sağlayıcının sayfasına yönlendirilir.
• Akış sonunda callback URL'e dönüş.

Web kanalında NFC okuma sınırlı (Web NFC API sadece Chrome Android'de tam destekli). Tipik web akışı OCR + MRZ + canlılık + görüntülü oturum üzerine kurulur; NFC mobile kanalına yönlendirilir.

5. Adım: Backend API Mimarisi

Backend tarafında üç ana endpoint kategorisi:

Oturum Yönetimi

• POST /sessions — yeni KYC oturumu başlat.
• GET /sessions/:id — oturum durumunu sorgu.
• POST /sessions/:id/cancel — kullanıcı vazgeçti.

Sonuç Sorgulama

• GET /sessions/:id/result — KYC sonucunu (NFC veri, biyometrik skor, canlılık skoru, MASAK hit'leri) çek.
• GET /sessions/:id/audit — denetim için tam log.

Webhook

• POST /webhooks/kyc (siz alacaksınız) — sağlayıcı KYC tamamlandığında, başarısız olduğunda veya operatör görüntülü oturum kararı verildiğinde size çağrı yapar.

Pratik öneri: Webhook'ları idempotent yapın — sağlayıcı aynı eventi 2-3 kez gönderebilir (retry mantığı). Idempotency key olarak session_id + event_type kullanın.

6. Adım: Webhook Akışı

Webhook bir event-driven mimari gerektirir. Tipik akış:

1. Sağlayıcıdan webhook gelir → siz HMAC signature doğrulaması yapın (replay/spoofing önleme).
2. Event'i dayanıklı bir queue'ya (örn. Kafka, RabbitMQ, SQS) yazın.
3. Worker queue'dan event'i alıp:
   • Oturum sonucunu çekin.
   • Müşteri risk skorunu güncelleyin.
   • Hesap aktivasyonu/limit yükseltmesi tetikleyin.
   • Audit log'a yazın.
4. Webhook sender'a 200 OK döndürün (5 saniye içinde).

Önemli: Webhook handler'da uzun süren işlem yapmayın; sadece event'i queue'ya yazıp dönün. İşin geri kalanı asenkron.

7. Adım: Audit Log ve Saklama

KYC akışının her adımı audit log'a yazılmak zorunda. BDDK ve MASAK denetimi için minimum log alanları:

• session_id, user_id, timestamp
• KYC adımı (nfc_read, liveness_check, face_match, video_session)
• Sağlayıcıdan dönen ham sonuç (skor, model versiyonu, eşik)
• Operatör kararı (varsa) — kim, ne zaman, hangi gerekçeyle
• NFC için: SOD imza doğrulama detayı, PKD sertifika versiyonu
• Tüm kayıt 10 yıl saklanmalı; hash zinciri veya WORM depolama ile bütünlük garanti.

Pratik öneri: Audit log'u operasyonel database'den ayrı tutun — compliance log'u immutable depolamada, operasyonel veri normal DB'de. Karışıklık ileride denetimde sorun çıkarır.

8. Adım: Tier Geçişleri ve Sürekli İzleme

Entegrasyonun son parçası — KYC bir kez tamamlanır, sonra bittik düşüncesi yanlış.

Tier yükseltme tetikleyici:

• Müşteri limitine yaklaştığında otomatik öneri.
• Yüksek riskli işlem talebinde zorunlu tier yükseltme.
• BDDK/SPK düzenleme değişikliği — yeni gereklilik ortaya çıkarsa retroaktif tier güncelleme.

Sürekli izleme:

• Davranış anomali tespiti → re-KYC tetikleyici.
• Periyodik MASAK tarama (genelde günlük) → yeni hit varsa müşteri risk skorunu güncelle.
• Müşteri 6 ay+ inaktif → otomatik tier düşürme veya yeniden doğrulama.

Yaygın Entegrasyon Hataları

Hata 1: API anahtarını mobil uygulamada tutmak. Geri çevrilebilir tasarım hatası — mobil binary reverse-engineer edilebilir, anahtar sızar. Mutlaka backend üzerinden geçici token ile.

Hata 2: Webhook'u synchronous handle etmek. Sağlayıcı 5 saniye içinde 200 yanıt bekler; siz uzun süren iş yapıyorsanız timeout olur, retry başlar, idempotency sorunları çıkar.

Hata 3: Audit log'u operasyonel DB'ye yazmak. Sıradan PostgreSQL tablosuna log atmak, denetimde "veri bütünlüğünü nasıl garanti ediyorsunuz" sorusuna yanıt veremezsiniz.

Hata 4: Sandbox'ta production verisiyle test. Gerçek müşteri TC No'sunu sandbox'ta denemek KVKK ihlali. Test datasını dummy üretip kullanın.

Hata 5: Retry akışını sağlayıcıya bırakmak. Sağlayıcı SDK genelde 1-2 retry sunar; kullanıcı 3. kez başarısız olunca akış kopabilir. Sizin akışınızda fallback (görüntülü oturum kuyruğu, müşteri hizmetleri kanalı) hazır olmalı.

Tipik Entegrasyon Süresi

Sıfırdan başlayan bir ekip için süre tahmini:

Sandbox'ta tek bir tier ile MVP'yi 4-6 haftada canlıya almak mümkün; tam tier yapısı + sürekli izleme + audit altyapısı için zaman daha uzun.

Sıkça Sorulan Sorular

Mobil SDK uygulama boyutunu ne kadar artırır?

Tipik bir tam dijital KYC SDK (NFC + canlılık + biyometrik + görüntülü) iOS'ta 8-15 MB, Android'de 12-20 MB ekler. Bu büyük bir overhead — özellikle düşük internet bağlantılı pazarlarda. Bazı sağlayıcılar dynamic loading (ihtiyaca göre modül indirme) sunuyor; SDK seçiminde bu önemli kriter.

Sağlayıcı API'si yavaş ise neye yapmalıyım?

Tipik p50 yanıt süresi 200-500ms, p99 1-2 saniye olmalı. p99 3 saniyeyi geçiyorsa kullanıcı deneyimi bozulur. İlk önlem: sağlayıcının regional endpoint'ini kullanın (Türkiye için Frankfurt veya İstanbul). İkinci önlem: cache'lenebilir sorguları (PKD sertifikası, sanctions list checksum) backend'inizde cache'leyin. Üçüncü önlem: kritik path'ten ayırarak asenkron yapın — kullanıcı bekleme süresi kısalır.

Hangi sağlayıcı SLA'ları üzerinde durmalıyım?

• Uptime: %99.9 minimum; %99.95 tercih.
• API yanıt süresi: p99 2 saniye altı.
• Görüntülü oturum operatör kuyruk süresi: ortalama 5 dakika altı.
• Webhook teslim süresi: event'ten sonra <30 saniye.
• Veri saklama garantisi: 10 yıl + audit log immutable.
• Veri ihlali bildirim süresi: 24 saat içinde.

SLA dışında sağlayıcının BDDK/SPK denetim deneyimi (geçmişte hangi kuruluşlarda kullanıldı, denetimde nasıl performans gösterdi) de kritik kriter.

Backend webhook handler'da hangi diller/framework'ler en kolay?

Webhook çoğunlukla basit HTTP endpoint + queue write — herhangi bir dilde 50 satırın altında yazılır. Pratik öneri: HMAC doğrulama, idempotency key kontrolü ve queue write — bu üç adımı standard library + iyi test'li bir HTTP framework ile (Express, FastAPI, Spring Boot, Gin) yapın. Asıl iş processor worker'da gerçekleşir.

KVKK aydınlatma metnini nasıl güncellemeliyim?

Dijital KYC kullanımı, KVKK'da biyometrik veri (özel nitelikli kişisel veri) işleme kategorisine girer. Aydınlatma metninde şunlar netleştirilmeli: hangi verinin işlendiği (yüz görüntüsü, biyometrik şablon, NFC çip verisi), işleme amacı (regülasyon yükümlülüğü, dolandırıcılık önleme), saklama süresi (10 yıl regülasyon gereği), aktarım (sağlayıcıya aktarım + DPA), ilgili kişi hakları. Açık rıza akışı KYC başlamadan önce gösterilmeli; kullanıcı reddederse alternatif (şube ziyareti) sunulmalı.

Legichain ile dijital KYC entegrasyonu

Legichain Dijital KYC SDK iOS, Android ve Web için tek bir SDK paketinde NFC + canlılık + biyometrik eşleştirme + görüntülü oturum katmanlarının tümünü sunuyor; entegrasyon tipik olarak 4-6 hafta içinde canlıya alınabiliyor. Backend tarafında REST API + webhook altyapısı standart; HMAC imzalı webhook, idempotency key, OpenAPI spec ve TR/EN dokümantasyon hazır. Yüksek riskli akışlar için Legichain Görüntülü KYC operatör paneli aynı API üzerinden devreye giriyor. Audit log altyapısı default 10 yıllık WORM saklama ve hash zinciri ile bütünlük garanti ediyor; BDDK ve MASAK denetim raporları tek tıkla çıkarılıyor. KVKK uyumlu biyometrik veri rejimi ve DPA template'i compliance ekibinizin işini hızlandırıyor. Tipik bir Türk fintech, banka veya kripto borsa ekibi kendi geliştirmeyle 14-22 hafta sürecek entegrasyonu Legichain ile 4-6 haftada tamamlıyor.

Sonraki Adımlar

• Dijital KYC rehberi: NFC, görüntülü tespit ve canlılık testi
• NFC çipli kimlik doğrulama nasıl çalışır?
• Görüntülü kimlik tespiti ve SPK uyumluluğu
• Uzaktan müşteri edinimi yönetmeliği — banka ve e-para için pratik rehber