How to Integrate Digital KYC: API and SDK Walkthrough

Building digital KYC from scratch — NFC SDKs for iOS and Android, a liveness model, biometric matching, video session infrastructure, audit logging, regulatory compliance across multiple jurisdictions — quickly turns into a 12-18 month engineering effort. Most fintechs, banks, and crypto exchanges therefore integrate a vendor's SDK and API. But integration done poorly produces flow friction, low success rates, and broken audit trails. This guide walks through the 8 technical steps to integrate a digital KYC vendor's SDK and API into your mobile app, web flow, and backend.

Prerequisites

Before starting integration, the following decisions should be settled:

• Vendor selection — a provider offering NFC + liveness + biometric matching + video sessions under a single SDK; aligned with your regulatory regime (EU AMLD/EBA, UK MLR 2017, Turkey BDDK/SPK); NIST PAD Level 2+ certified.
• Flow design — risk-based tier structure (at least two levels) with clear pass criteria for each tier.
• Mobile platform support — iOS 13+ and Android API 21+ minimum targets.
• Backend environment — REST-capable application server, webhook receiver, durable job queue, long-term log storage infrastructure.
• Legal prep — GDPR/KVKK privacy notice updated for biometric special-category data, explicit consent flow designed, Data Processing Agreement with vendor signed.

General digital KYC architecture in our complete digital KYC guide.

Step 1: API Key and Environment Setup

First step is getting API credentials (key + secret) from the vendor's developer console, and isolating sandbox vs production environments.

Practical guidance:

• Sandbox for development + integration testing.
• Production for live customer data only; deploy pipelines should fail-safe to sandbox credentials in non-production environments.
• API keys never embedded in mobile applications — backend only. Mobile clients receive short-lived session tokens from your backend.

Typical backend → vendor API call:

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

Returns session_id and session_token; the token is passed to the mobile client.

Step 2: Bind the Mobile SDK (iOS)

iOS SDKs typically distribute via CocoaPods, Swift Package Manager (SPM), or as an XCFramework.

Add to Info.plist:

• NSCameraUsageDescription — camera usage for selfie and video session.
• NSMicrophoneUsageDescription — microphone for video session.
• NFCReaderUsageDescription — for NFC chip reading.

Entitlement:

• com.apple.developer.nfc.readersession.formats — set to TAG.

Initialization: Pass the session_token and flow configuration (NFC required, active liveness on, etc.) when initializing the SDK.

Step 3: Bind the Mobile SDK (Android)

Android SDKs ship as Gradle dependencies.

Add to AndroidManifest.xml:

• android.permission.CAMERA
• android.permission.RECORD_AUDIO
• android.permission.NFC
• <uses-feature android:name="android.hardware.nfc" android:required="false" /> — allows fallback for non-NFC devices.

Initialization: Request runtime permissions (camera, microphone) before starting the flow. NFC doesn't need runtime permission but device capability should be checked.

Practical note: Android device fragmentation is high — lower-tier device NFC driver quality varies substantially. Review the vendor's device compatibility matrix before launch.

Step 4: Web Channel Integration

For web onboarding, vendors typically offer either a JavaScript SDK + iframe approach or a redirect-based flow.

With JavaScript SDK:

• An iframe is embedded in your page.
• Initialized with session_token.
• Posts results back to the parent window via postMessage when complete.

Redirect-based:

• Backend generates a redirect URL.
• User is redirected to the vendor's hosted page.
• Vendor calls back to your URL when complete.

NFC reading on web is limited (Web NFC API only fully supported in Chrome on Android). Typical web flow is OCR + MRZ + liveness + video session; NFC is steered to the mobile channel.

Step 5: Backend API Architecture

Backend exposes three endpoint categories:

Session Management

• POST /sessions — start a new KYC session.
• GET /sessions/:id — query session status.
• POST /sessions/:id/cancel — user abandoned.

Result Retrieval

• GET /sessions/:id/result — fetch outcome (NFC data, biometric score, liveness score, AML hits).
• GET /sessions/:id/audit — full audit trail for inspection.

Webhook

• POST /webhooks/kyc (your endpoint) — vendor calls you when KYC completes, fails, or escalates to video.

Practical guidance: Make webhooks idempotent — vendors typically retry on transient failures, so the same event can arrive multiple times. Use session_id + event_type as the idempotency key.

Step 6: Webhook Flow

Webhooks require an event-driven architecture. Typical flow:

1. Webhook arrives → verify HMAC signature (replay/spoofing prevention).
2. Write the event to a durable queue (Kafka, RabbitMQ, SQS).
3. A worker consumes the event and:
   • Fetches the session result.
   • Updates the customer's risk score.
   • Triggers account activation or tier escalation.
   • Writes to the audit log.
4. Return 200 OK to the webhook sender (within 5 seconds).

Critical: Don't do heavy work synchronously in the webhook handler — just write to a queue and return. The rest happens asynchronously.

Step 7: Audit Log and Retention

Every step of the KYC flow must be logged. Minimum log fields for EU AMLD, UK MLR, and Turkey BDDK/MASAK inspection:

• session_id, user_id, timestamp
• KYC step (nfc_read, liveness_check, face_match, video_session)
• Raw vendor response (score, model version, threshold)
• Operator decision (if applicable) — who, when, reasoning
• For NFC: SOD signature validation detail, PKD certificate version
• All records retained 5-10 years depending on jurisdiction; integrity ensured via hash chains or WORM storage.

Practical guidance: Keep audit logs separate from operational database — compliance logs in immutable storage, operational data in regular DB. Mixing them creates inspection issues later.

Step 8: Tier Transitions and Ongoing Monitoring

The final piece — KYC isn't done once, then forgotten.

Tier escalation triggers:

• Customer approaching limit → automated upgrade suggestion.
• High-risk transaction requested → mandatory tier upgrade.
• Regulatory change requiring re-verification → retroactive tier update.

Ongoing monitoring:

• Behavior anomaly detection → re-KYC trigger.
• Periodic AML re-screening (typically daily) → risk score update on new hits.
• Inactive customer (6+ months) → automated tier downgrade or re-verification.

Common Integration Mistakes

Mistake 1: API key in the mobile app. Reversibly broken — mobile binaries can be reverse-engineered and keys extracted. Always proxy through your backend.

Mistake 2: Synchronous webhook handling. Vendor expects 200 within 5 seconds; if you're doing heavy work synchronously, you'll timeout, retries will fire, and idempotency issues compound.

Mistake 3: Writing audit logs to the operational DB. A plain PostgreSQL table won't survive the "how do you guarantee record integrity" inspection question.

Mistake 4: Testing sandbox with production data. Using real customer ID numbers in sandbox is a GDPR/KVKK violation. Use fabricated test data.

Mistake 5: Delegating retry to the vendor. Vendor SDKs typically include 1-2 retries; if the customer fails the third attempt, your flow needs a fallback (video session escalation, customer service channel) — ready from launch.

Typical Integration Timeline

For a team starting from zero:

A single-tier sandbox MVP is achievable in 4-6 weeks; the full tier stack + ongoing monitoring + audit infrastructure takes longer.

Frequently Asked Questions

How much does the mobile SDK add to app binary size?

A full digital KYC SDK (NFC + liveness + biometrics + video) typically adds 8-15 MB on iOS and 12-20 MB on Android. This is meaningful overhead — particularly in markets with constrained mobile data. Some vendors offer dynamic loading (downloading modules on-demand); this is a useful selection criterion.

What should I do if the vendor API is slow?

Typical p50 should be 200-500ms; p99 1-2 seconds. p99 above 3 seconds degrades user experience. First mitigation: use the vendor's regional endpoint near your customers. Second: cache cacheable queries (PKD certificates, sanctions list checksums) at your backend. Third: move non-blocking steps off the critical path — asynchronous processing reduces user wait.

What SLAs should I evaluate vendors against?

• Uptime: 99.9% minimum; 99.95% preferred.
• API response time: p99 below 2 seconds.
• Video session operator queue: 5-minute average wait.
• Webhook delivery time: under 30 seconds from event.
• Data retention guarantee: 10 years with immutable audit log.
• Breach notification: within 24 hours.

Beyond SLAs, the vendor's regulatory inspection track record (which institutions have deployed, how they performed in inspection) is critical.

Which backend languages/frameworks make webhook handling easy?

Webhooks are essentially simple HTTP endpoint + queue write — implementable in under 50 lines in any modern language. Practical guidance: HMAC verification, idempotency key check, queue write — these three steps in any well-tested HTTP framework (Express, FastAPI, Spring Boot, Gin). The real work happens in the processor worker.

How do I update my privacy notice for digital KYC?

Digital KYC involves biometric data — special-category personal data under GDPR Article 9 (and KVKK in Turkey). The privacy notice should specify: what data is processed (facial image, biometric template, NFC chip data), processing purpose (regulatory obligation, fraud prevention), retention period (5-10 years per AML retention), data transfers (to vendor, under DPA), data subject rights. Explicit consent must be obtained before biometric capture; users who decline should be offered an alternative (branch visit).

How Legichain helps

Legichain Digital KYC SDK provides iOS, Android, and Web SDKs in a single package, covering NFC + liveness + biometric matching + video session capabilities; typical integration takes 4-6 weeks to production. Backend integration uses standard REST API + webhooks; HMAC-signed webhooks, idempotency keys, OpenAPI spec, and EN/TR documentation are ready out of the box. For high-risk flows, Legichain Video KYC operator console activates from the same API. Audit log infrastructure provides default 10-year WORM retention and hash-chain integrity; EBA, FCA, BDDK, and MASAK inspection reports can be exported in minutes. GDPR/KVKK-compliant biometric data handling and a DPA template accelerate your compliance team's work. Typical European, UK, or Turkish fintech, bank, or crypto exchange teams complete an integration that would take 14-22 weeks of in-house effort in 4-6 weeks with Legichain.

Next Steps

• The complete digital KYC guide
• How NFC ID verification works
• Video KYC and SPK compliance
• Turkey's remote customer onboarding regulation