Skip to content
API reference Get API keys

SDKs and plugins · Chapter 11

Flutter SDK

Run the verification flow inside your Android or iOS app with the kyc_flutter package. It opens the flow with camera access and can add the electronic document check for passports and ID cards.

4 min read

Install

Requirements: Dart 3.5+, Flutter 3.24+, Android minSdk 24, iOS 13.

  1. Download kyc_flutter.zip and unzip it into your project, for example into packages/kyc_flutter.
  2. Add a path dependency to pubspec.yaml:
dependencies:
  kyc_flutter:
    path: packages/kyc_flutter
  1. Run flutter pub get.

The package is not on pub.dev yet. The zip contains an example/ app with the full setup below.

Permissions

The SDK asks for the camera natively, then gives it to the flow. If the user refuses, the flow shows its own message.

Android — android/app/src/main/AndroidManifest.xml:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.CAMERA" />

iOS — ios/Runner/Info.plist:

<key>NSCameraUsageDescription</key>
<string>The camera is used to photograph your document and take a selfie for identity verification.</string>

and turn on the camera permission in ios/Podfile (inside post_install):

target.build_configurations.each do |config|
  config.build_settings['GCC_PREPROCESSOR_DEFINITIONS'] ||= ['$(inherited)', 'PERMISSION_CAMERA=1']
end

with platform :ios, '13.0' at the top of the Podfile.

Start the flow

Your backend creates the session (POST /applicants/{id}/sessions) and sends only its token to the app. Pass the token, not the url.

Important

Never put the API secret key into the app. Anyone can extract it from the app package.

import 'package:kyc_flutter/kyc_flutter.dart';

Future<void> verify(BuildContext context) async {
  final token = await myBackend.createKycSession(); // session token

  final result = await KycFlow.start(
    context,
    token: token,
    locale: 'uz', // uz | ru | en, optional
  );

  if (result.isCancelled) {
    // Closed before a decision. result.errorCode: link_invalid, session_expired, network, …
    return;
  }

  switch (result.decision!) {
    case KycDecision.green:
      showMessage('Thank you! We are confirming your verification.');
    case KycDecision.onHold:
      showMessage('Your documents are under review.');
    case KycDecision.red:
      // decisionType: 'retry' — can try again with a new session; 'final' — cannot
      showMessage('Verification failed: ${result.rejectLabels.join(', ')}');
  }

  // Unlock features only after your backend confirms the decision.
  await myBackend.refreshKycStatus();
}

KycFlow.start opens a full-screen route and returns Future<KycResult>. It is never null: if the user closes the screen, you get a cancelled result. The route closes by itself 3 seconds after the result screen.

Parameter Default Description
token required Session token
baseUrl https://kyc.goxost.net Must be HTTPS
locale applicant's locale uz, ru or en
title "Identity verification" in locale (English when not set) App bar title
closeDelay 3 seconds How long the result screen stays before closing
onEvent — Called for every event (see below)
readChip true Run the electronic document check when the flow asks for it

KycResult:

Field Type Description
decision KycDecision? green, red, onHold; null when cancelled. .code gives GREEN, RED, ON_HOLD
decisionType String? final or retry for RED, otherwise usually null
rejectLabels List<String> Reason codes, see Errors and labels
errorCode String? Last error when the flow was closed without a decision
isCancelled bool true when there is no decision
Note

The result in the app is for the interface only. Take the final decision on your backend from the webhook or GET /verifications/{id}.

Embed in your own screen

Use KycView to put the flow inside your own layout:

SizedBox(
  height: 640,
  child: KycView(
    key: ValueKey(token),       // a new key restarts the flow with a new token
    token: token,
    locale: 'ru',
    onStep: (step) {},          // KycStep.consent, document, liveness, processing, handoff
    onComplete: (result) {},    // KycResult
    onError: (code) {},         // link_invalid, session_expired, network, http_<status>, …
    onCancel: () {},            // system back before a result
    onEvent: (event) {},        // every event, including ready and resize
  ),
)

KycView needs a bounded size — for example inside Expanded, a SizedBox or a Scaffold body. It does not run the electronic document check; use KycFlow.start for that.

Events (onEvent): KycReadyEvent, KycStepEvent, KycCompleteEvent, KycErrorEvent, KycResizeEvent — the same events as kyc.js.

Electronic document check

When the flow has the electronic document check set to optional or required (panel → Settings), KycFlow.start runs it after the photos: an instruction screen, progress, retry, and a skip button when the flow allows it. Phones that do not support it skip the step automatically. Pass readChip: false to turn it off. Nothing from this step is stored on the device.

Android — add to the manifest. required="false" keeps the app installable on phones that do not support this step:

<uses-permission android:name="android.permission.NFC" />
<uses-feature android:name="android.hardware.nfc" android:required="false" />

iOS (iPhone 7 or newer) — add to ios/Runner/Info.plist:

<key>NFCReaderUsageDescription</key>
<string>Used to check your identity document electronically.</string>
<key>com.apple.developer.nfc.readersession.iso7816.select-identifiers</key>
<array>
  <string>A0000002471001</string>
</array>

Then in Xcode → Signing & Capabilities add Near Field Communication Tag Reading. It writes ios/Runner/Runner.entitlements:

<key>com.apple.developer.nfc.readersession.formats</key>
<array>
  <string>TAG</string>
</array>

The App ID must have this capability enabled. The step works only on a real device, not in the simulator.

Important

The web flow and kyc.js cannot run the electronic document check. If a flow has it required and does not allow a fallback, submitting from the web fails with 409 nfc_required — use a separate flow for web users.

Troubleshooting

Problem Fix
ArgumentError on start Pass the session token (starts with eyJ), not the url; baseUrl must be HTTPS
Black camera on iOS Check NSCameraUsageDescription and PERMISSION_CAMERA=1 in the Podfile, then pod install
Camera does not open on Android Check the CAMERA permission in the manifest and that the user allowed it in system settings
errorCode: link_invalid or session_expired The session was used, replaced or expired — create a new session for each attempt
KycView is empty or throws a layout error Give it a bounded height
No electronic document check step The flow has it off, the phone does not support it, readChip is false, or you used KycView
The step fails on iOS Check the select-identifiers entry, the capability and that the App ID has it enabled