Install
Requirements: Dart 3.5+, Flutter 3.24+, Android minSdk 24, iOS 13.
- Download kyc_flutter.zip and unzip it into your project, for example into
packages/kyc_flutter. - Add a path dependency to
pubspec.yaml:
dependencies:
kyc_flutter:
path: packages/kyc_flutter
- 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.
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 |
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.
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 |