Flutter SDK

The Flutter SDK opens the full verification flow as a modal sheet via MyazaKYC.show(), with on-device native liveness (Apple Vision on iOS, Google ML Kit on Android). It uses a publishable (pk_) key and detects the environment automatically from the key prefix (pk_test_* → sandbox, pk_live_* → production). For shared concepts (supported countries, branding, results, and errors), see Client SDKs.

Feature availability. This SDK is at full parity with the web and React Native SDKs: workflow embedding (workflowId, ≥ 2.2.0; earlier versions need a placeholder country to compile a workflow mount), the capture add-ons (contact OTP, proof of address, questionnaire), business (KYB) verification, any Global Documents country, plus NFC chip reading, which the web SDK can't do at all (browsers can't talk to a passport chip). See Feature availability.

Install

Add the dependency to your pubspec.yaml, then run flutter pub get:

dependencies:
  myaza_kyc_sdk_flutter: ^2.2.0

Requirements

Face detection runs on-device (Apple Vision on iOS, Google ML Kit on Android: an Android-only Gradle dependency, so there's no cross-platform ML Kit iOS pod and the SDK still builds on Apple-Silicon iOS simulators). Add the camera permission on both platforms (there is no microphone permission: voice guidance is text-to-speech output only):

<!-- iOS: ios/Runner/Info.plist -->
<key>NSCameraUsageDescription</key>
<string>We use the camera to photograph your ID and capture a live selfie.</string>

<!-- Android: android/app/src/main/AndroidManifest.xml -->
<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.INTERNET" />

If your workflows use the Address Intelligence step, also add the location strings. Both are best-effort (they power the "Use my current location" shortcut and the attest fix; the pin always works by dragging alone), but iOS crashes on the permission request if the usage string is missing:

<!-- iOS: ios/Runner/Info.plist -->
<key>NSLocationWhenInUseUsageDescription</key>
<string>Your location helps place the map pin on your address.</string>

<!-- Android: android/app/src/main/AndroidManifest.xml -->
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

The SDK bundles webview_flutter, which renders the Google map and the Street View entrance framer on the address step inside your app; when that page cannot load, the built-in map and the entrance photo remain. Address fields the workflow marks required are enforced in the app (Continue opens the details sheet naming what is still needed), so a submission is never refused for a missing field at the end of the flow.

Presence reporting (Address Intelligence)

When a workflow enables presence verification, the SDK stores the confirmed pin on-device at capture. Call the reporter from your app on a natural moment (app open works well):

final result = await MyazaAddressPresence.report(
  apiKey: 'pk_live_…',
  externalUserId: 'user_42', // the same userId the KYC flow ran with
);
// result.reason: reported | noPin | servicesOff | noFix | outsideFence | noWatch | networkError

You can also call it from onSubmit, the moment the flow finishes: the watch is created a few seconds after a submission is accepted, so when the pin was captured within the last 15 minutes the reporter waits for it (up to 90 seconds) before posting. noWatch means nothing is monitoring this user right now, so there was nothing to report to.

It never throws and never blocks startup. The geofence is evaluated on-device: only the derived day + night flag is transmitted, never a coordinate. A fix outside the fence sends nothing; a mock-location fix is reported flagged. clearPresencePin(externalUserId) drops the stored pin. Stored pins self-expire after 45 days for bounded checks; a pin captured under always-on monitoring never expires until revoked.

Background monitoring (native geofencing)

The stronger tier: the OS wakes the plugin's native side on fence crossings, app closed or not — on Android the fence survives reboots, and iOS relaunches the app for crossings by itself. Entries stamp; exits fold the dwell into per-day aggregates natively and flush them.

Declare the background-location entries in your own manifest and Info.plist first (the plugin never adds them for you, because the declaration changes your store review posture — the Background Location Declarations page carries the ready-to-paste texts). Then:

final result = await MyazaBackgroundPresence.enable(
  apiKey: 'pk_live_…',
  externalUserId: 'user_42',
);
// result.reason: started | noPin | permissionDenied | backgroundDenied | unavailable

enable() walks the two-step permission escalation (while-in-use, then "allow all the time"); MyazaBackgroundPresence.disable() disarms and forgets. A refusal leaves the foreground tier working exactly as before.

The Android foreground service

On phones whose battery managers drop geofence transitions (Tecno, Infinix, Xiaomi and friends), a persistent notification is what keeps the check alive. Opt-in and Android only. The plugin ships the service class; you declare it, with its two permissions, in your own manifest (the block is on the Background Location Declarations page), then:

final result = await MyazaPresenceService.enable(
  apiKey: 'pk_live_…',
  externalUserId: 'user_42',
  notification: const PresenceNotification(
    title: 'Address verification in progress',
    body: 'Open the app to see your progress',
  ),
);
// result.reason: started | unsupportedPlatform | noPin | permissionDenied | backgroundDenied | notDeclared | unavailable

enable() walks the same permission escalation and arms the fence too. A low-power fix every ten minutes becomes the same enter/exit spans the geofence folds, natively, on the same stored state; the queue flushes while the process is alive; a dropped fence is re-armed; a reboot restarts it. MyazaPresenceService.disable() stops it. See Address Intelligence for the reasoning.

Which tier is running?

final status = await presenceStatus('user_42');
// status.tier: PresenceTier.background | foreground | none, plus pinStored, alwaysOn,
// locationServicesEnabled, both permission states, geofenceArmed, foregroundServiceRunning
if (!status.locationServicesEnabled) {
  await openLocationSettings(target: PresenceSettingsTarget.services); // the toggle is off
} else if (status.tier == PresenceTier.none && status.pinStored) {
  await openLocationSettings(); // the only road back after a denial
}

To show the person where the check stands, poll GET /api/kyc/address/presence/:externalUserId with the publishable key; see Address Intelligence.

Usage

MyazaKYC.show() opens the full flow as a modal bottom sheet (a full-screen page on Android). Note that context is a named parameter, and the callbacks are passed to show() alongside config, not inside it.

Recommended: mount a workflow

Build the flow once in the dashboard as a workflow, then mount it by id. The country, ID types, capture steps, branding and copy all come from the workflow, so changing the flow is a re-publish rather than an app release, which matters more on mobile, where a redeploy means an app-store round trip.

import 'package:flutter/material.dart';
import 'package:myaza_kyc_sdk_flutter/myaza_kyc_sdk_flutter.dart';

void startKYC(BuildContext context) {
  MyazaKYC.show(
    context: context,
    config: const MyazaKYCConfig(
      apiKey: 'pk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
      workflowId: 'wf_AbC123dEf456',
      // Runtime data — a workflow is a shared template and cannot carry any of it.
      userId: 'user_42',
      userData: UserData(firstName: 'Jane', lastName: 'Doe'),
      metadata: {'requestId': 'order_1001'},
    ),
    onSubmit: (submission) => debugPrint('Submitted: ${submission.verificationId}'),
    onError: (error) => debugPrint('Error: ${error.code} — ${error.message}'),
    onClose: () => debugPrint('KYC closed'),
  );
}

userData is worth passing. It is the name you believe the user has, and it is compared against the name read off their document, and that comparison is what produces dataMatch on the verification. Leave it out and the check simply never runs: there is nothing to compare the document against, and dataMatch comes back null.

It cannot live on the workflow. userId, userData and metadata are per-user runtime values, and a workflow is a template shared by every visitor, so these stay in code even when everything else moves to the dashboard.

country is optional here: the resolved workflow carries it, exactly as in the React SDK. Pass one only when you are not using a workflow.

Or configure everything in code

Skip the workflow and pass the flow's shape in MyazaKYCConfig. Useful for a quick start or a single fixed flow; anything you'd change later means an app release.

import 'package:flutter/material.dart';
import 'package:myaza_kyc_sdk_flutter/myaza_kyc_sdk_flutter.dart';

void startKYC(BuildContext context) {
  MyazaKYC.show(
    context: context,
    config: MyazaKYCConfig(
      apiKey: 'pk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
      country: 'NG',
      idTypes: const ['bvn', 'drivers-license', 'passport'],
      userData: const UserData(firstName: 'Jane', lastName: 'Doe'),
      enableSelfie: true,
      enableDocumentCapture: true,
      enableLiveness: true,
      appearance: const MyazaKYCAppearance(
        primaryColor: Color(0xFF5645F5),
        companyName: 'Myaza',
        logo: 'default',
        theme: MyazaThemeMode.light,
      ),
      consent: const KYCConsentContent(
        title: 'Welcome, {firstName}',
        description: "A quick check to confirm it's really you.",
      ),
      success: const KYCSuccessContent(
        title: "You're all set, {firstName}!",
        description: "We'll email you once your verification is reviewed.",
      ),
      metadata: const {'requestId': 'order_1001', 'userId': 'user_42'},
    ),
    onSubmit: (submission) {
      // The verification was created; submission.status is always 'pending'.
      // The final result arrives via webhook to your backend (or fetch it with a
      // secret-key GET /verifications/:id call, never from the client).
      debugPrint('Submitted: ${submission.verificationId}');
    },
    onError: (error) {
      // Technical errors only (network / 401 / 402 / upload).
      debugPrint('Error: ${error.code} — ${error.message}');
    },
    onClose: () => debugPrint('KYC closed'),
  );
}

Config (MyazaKYCConfig)

UserData accepts firstName, lastName, dateOfBirth, gender, address, phoneNumber and email (all optional). email is never asked for in the flow: it is the address your organisation can have the applicant emailed at about a decision.

Callbacks

Passed to MyazaKYC.show() alongside config:

Biometric re-authentication

A workflow on the biometric-authentication scope confirms it is really your user, matching a live selfie against the face you enrolled. Three options on the workflow, plus your own words for its screens, shape how the Flutter flow behaves, exactly as on the web and React Native SDKs. All three live on the workflow's Presence Intelligence panel in the builder, under Flow, so they need no code change; a config can pass the same biometric block.

• Where the verdict lands: In the app and on your webhook (the default) keeps the person on one loading screen from the moment the selfie is taken until the check settles, polling the status endpoint for up to a minute, then shows whether it was them; your app hears the verdict in onResult and your webhook receives it as on every other flow. In the app only is the same wait, but the server sends no webhook for that check at all, so the verdict is your app's alone. Webhook only shows the ordinary submitted screen and leaves the verdict to your webhook. Enrolment workflows never wait.
• Selfie review: whether the captured selfie is shown back with Retake and Continue before it is sent. Off by default on the biometric scopes.
• Done button: whether the final screen carries a Done button. On by default. Turn it off when your app pops the sheet itself from onResult; the screen then stays until your app dismisses the SDK.
• Screen copy: your own title and description for the screens the person sees, on the workflow's Presence Intelligence panel under Face check screens: the loading screen while the check runs ("Checking it's you") and, on a verdict delivered in the app, the verified screen ("You're verified") and the not-verified screen ("We couldn't confirm it's you"). Leave a field empty to keep the default; {firstName} and {lastName} fill from the userData you pass, as on the welcome and success screens. A not-verified description replaces the reason the server sends. Enrolment offers the loading screen only. In code the same block is biometric.copy (waiting, verified, declined, each with title and description).

await MyazaKYC.show(
  context: context,
  config: const MyazaKYCConfig(
    apiKey: 'pk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
    workflowId: 'wf_AbC123dEf456', // a biometric-authentication workflow
    userId: 'user_42',               // required: the enrolled user being re-authenticated
  ),
  onSubmit: (s) => debugPrint('submitted ${s.verificationId}'),
  onResult: (r) {
    // r.status is the same vocabulary GET /api/kyc/status/:id serves.
    if (r.status == 'approved') unlockSensitiveAction();
  },
);

onSubmit still fires the moment the check is submitted. onResult fires once when the wait settles, never when it times out, and carries the state and reason pair only (verificationId, status, reason, reasonCode); scores and other result data stay behind your secret key. The webhook (where the flow sends one) and GET /api/kyc/verifications/:id remain the record.

Countries & ID types are plain strings

country takes any ISO-2 code ('NG', 'GH', 'FR', …) and idTypes takes the same kebab-case keys as the React SDKs ('bvn', 'drivers-license', 'ghana-card', …). See the ID types catalogue. There is no Country/IdType enum to import. The one enum you'll meet is MyazaThemeMode (light / dark) on appearance.theme.

Liveness configuration

LivenessConfig tunes the active-liveness step. Defaults match the web SDK.

The default pool covers four LivenessChallenge gestures: nod, turn, blink, and smile.