IKYC Flutter SDK #

Merchant integration guide #

For the complete server, Flutter, Android, iOS, testing, troubleshooting, and security walkthrough, read Merchant integration guide. It uses the current public SDK API and describes the native-session contract; it does not require merchants to put an IKYC secret key or QoreID credential in their app.

This is a native-only Flutter SDK for Flutter 3.41.0+ (Dart 3.4.3+) on Android and iOS; it does not support Flutter Web. A merchant backend must issue a short-lived native bearer session token and provide it to the mobile app; never put long-lived credentials in the app. The SDK sends that token only as Authorization: Bearer ... and deliberately does not set an Origin header.

IkycVerificationFlow provides an accessible, host-themeable start → consent → checks → liveness → verify UI. It delegates all liveness to LivenessAdapter; it never treats a still photo as production liveness and it requests the optional sensitive-media cleanup hook when cancelled or unmounted.

The native payload contract is camelCase: liveness results use { livenessReference, resultPayload }, where resultPayload is limited to { status?, passed?, score?, liveness: { passed?, score? } }. Verification requires the stored consentId. The client sends only Authorization: Bearer ..., never Origin, a browser public key, a customer reference, subjectRef, or externalUserId. Every POST has an idempotency key that is stable for the named logical operation so a transport retry does not create a duplicate effect. Do not automatically retry IDEMPOTENCY_EFFECT_UNRESOLVED; reconcile with the merchant backend first.

For enabled liveness, the merchant backend supplies a trimmed pseudonymous subjectRef only when it mints the short-lived native bearer session. IKYC validates and binds it there. The Flutter host receives no subject reference, and /liveness/reference is intentionally an empty request body: the client cannot choose, resend, or override that binding.

Configure Native mobile consent in IKYC Dashboard. By default, IkycVerificationFlow loads the active/effective nativeConsent policy from IKYC's native /config response and renders and records its exact server text/version. The SDK has no generic/default consent wording and fails closed before consent, liveness, or verification when that policy is unavailable, inactive, malformed, or not yet effective.

Existing integrations may continue to pass consentDocument: NativeConsentDocument(text: ..., version: ...). This is for controlled/custom host rendering only: the supplied text and version must exactly match IKYC's active policy or the flow fails closed before consent is recorded. New integrations should omit consentDocument and let IKYC provide the policy.

IkycVerificationFlow(
  controller: controller,
  // Omit consentDocument: the server-approved policy is rendered by default.
)

For deterministic development and tests, explicitly inject DeterministicMockLivenessAdapter. It neither opens a camera nor contacts any provider. In normal integration, NativeFlowController defaults to the real QoreIdLivenessAdapter: after consent, it asks IKYC for a liveness session and uses the server response to choose the capture path. stubbed: false launches QoreID; stubbed: true uses the server-selected sandbox path and never opens QoreID. Flutter never receives or chooses a provider API key or environment.

QoreID liveness installation #

The package pins qoreidsdk: 2.1.0 exactly. A QoreID liveness integration must run in a native Flutter app. Keep DeterministicMockLivenessAdapter as the default in local tests and demos; it cannot open a camera or create provider traffic.

iOS compatibility fix in 0.1.4 #

When version 0.1.4 is available to your approved package source, upgrade to it if your iOS app uses qoreidsdk 2.1.0. It prevents that dependency's NSNull launch crash by supplying an empty OCR-documents value for the token-authorized liveness launch. This is an internal compatibility value: do not add applicant data, references, credentials, or provider tokens to it.

QoreID status compatibility in 0.1.5 #

When version 0.1.5 is available to your approved package source, upgrade to it. The SDK normalizes QoreID's Android and iOS terminal-status variants before submitting the bounded liveness evidence to IKYC. No merchant configuration, applicant data, reference, token, or provider data is needed for this update.

The adapter launches QoreID with only IKYC's private issued sdkSessionToken and an empty provider-required applicant-data map. It never forwards subjectRef, externalUserId, a merchant customer reference, or IKYC's livenessReference to QoreID. A QoreID UI customer-reference display is not required for liveness. IKYC derives the subject binding server-side when the merchant backend mints the native session; IKYC's issued sessionId and livenessReference remain authoritative for submission and verification.

sdkSessionToken is private adapter state for one launch. It is absent from public session/result objects, callbacks, errors, logs, and serialized IKYC requests. Provider event details are likewise never used as public errors or logs.

Android host setup #

Set compile/target SDK 36, min SDK 23, Java 17, AGP 8.13.2, and Kotlin 2.0.0. Add QoreID's Maven releases repository and JitPack. Because qoreidsdk 2.1.0 omits application of its Kotlin plugin, apply org.jetbrains.kotlin.android to its subproject before it is evaluated. Initialize QoreidsdkPlugin in the host MainActivity and retain the com.qoreid.sdk release rule. Add only android.permission.CAMERA for liveness.

Android release reproducibility

qoreidsdk 2.1.0 declares its Android native artifact as com.qoreid:qoreid-sdk:+. Pin the resolved artifact in the consuming app so a release build cannot silently pick up a newer vendor binary. Add this to the app's Android Gradle build file (use the syntax that matches the file):

configurations.configureEach {
    resolutionStrategy.force 'com.qoreid:qoreid-sdk:2.0.1'
}

configurations.configureEach {
    resolutionStrategy.force("com.qoreid:qoreid-sdk:2.0.1")
}

Keep the existing consumer ProGuard/R8 rule in the host app's release rules:

-keep class com.qoreid.sdk.** { *; }

After changing either rule, build and install a release APK on a real Android device before distribution. This pin makes the native dependency reproducible; it does not bypass or convert a direct QoreID capture/upload failure into a successful verification. Those failures must remain safe, actionable provider failures and be investigated with the provider's diagnostics.

iOS host setup #

Set iOS 13.0, use framework linkage in the Podfile, and retain the Flutter UIScene setup with a UINavigationController root: qoreidsdk pushes native screens onto that navigation stack. Add only NSCameraUsageDescription for liveness; do not add gallery, motion, location, or background permissions.

Use Flutter 3.41 or later and Xcode 15 or later for an iOS host. The QoreID native iOS SDK is declared by qoreidsdk's Package.swift; enable Flutter's Swift Package Manager integration so Xcode resolves that package. It is not supplied by the plugin's CocoaPods specification.

From the consuming Flutter app directory, run:

flutter config --enable-swift-package-manager
flutter clean
flutter pub get
flutter run -d <ios-device-id>

Use flutter devices to find <ios-device-id>. After upgrading Flutter or changing the SDK dependency, run the same clean and dependency steps before building again. If Xcode reports Unable to find module dependency: 'QoreIDSDK', first confirm the Flutter version with flutter --version, then repeat the commands above and open ios/Runner.xcworkspace to let Xcode finish resolving packages. Do not add a manual QoreID pod or copy native frameworks into the app.

The qoreidsdk 2.1.0 artifact itself references QoreID's iOS SDK from an upstream main branch and Android uses an unversioned native artifact. Those transitive references remain vendor reproducibility/release blockers. Validate native Android release and iOS builds in host CI before release.