Flutter SDK - OTPLESS

This page covers the SNA-only integration of the OTPless Headless SDK in Flutter. The SDK accepts the requestId generated by the Create API, performs the silent network handshake, and reports progress through callbacks. Your backend confirms the final result via the Status Check API.

Requirements

Requirement	Version
Android Minimum SDK	21
iOS	13.0+

Step 1: Add SDK dependency

Add the dependency to your pubspec.yaml:

pubspec.yaml

dependencies:
  otpless_headless_flutter: ^<latest_version>

Then fetch it:

flutter pub get

Check the latest version of the SDK on pub.dev.

Step 2: Smart Authentication (SNA) setup

Make sure Silent Network Authentication is enabled on the OTPLESS dashboard. For an SNA-only configuration, SNA must be the only channel enabled.

Android
iOS

Add the network security config inside android/app/src/main/AndroidManifest.xml, in your <application> tag:

AndroidManifest.xml

android:networkSecurityConfig="@xml/otpless_network_security_config"

If your MainActivity extends FlutterActivity, change it to extend FlutterFragmentActivity for lifecycle awareness:

MainActivity.kt

import io.flutter.embedding.android.FlutterFragmentActivity

class MainActivity : FlutterFragmentActivity() {
}

Add the following block to your ios/Runner/Info.plist.

If the NSAppTransportSecurity key is not already present, add the entire block below.
If it is already present, add the listed domains one by one under NSExceptionDomains.

Info.plist

<key>NSAppTransportSecurity</key>
<dict>
    <key>NSExceptionDomains</key>
    <dict>
        <key>api-csp.airtel.in</key>
        <dict>
            <key>NSExceptionAllowsInsecureHTTPLoads</key>
            <true/>
            <key>NSIncludesSubdomains</key>
            <true/>
        </dict>
        <key>v4-api-csp.airtel.in</key>
        <dict>
            <key>NSExceptionAllowsInsecureHTTPLoads</key>
            <true/>
            <key>NSIncludesSubdomains</key>
            <true/>
        </dict>
        <key>in-vil.ipification.com</key>
        <dict>
            <key>NSExceptionAllowsInsecureHTTPLoads</key>
            <true/>
            <key>NSIncludesSubdomains</key>
            <true/>
        </dict>
        <key>partnerapi.jio.com</key>
        <dict>
            <key>NSExceptionAllowsInsecureHTTPLoads</key>
            <true/>
            <key>NSIncludesSubdomains</key>
            <true/>
        </dict>
    </dict>
</dict>

Step 3: Initialize the SDK

Create an Otpless instance, initialize it with your App ID, and register the response callback:

import 'package:otpless_headless_flutter/otpless_flutter.dart';

final _otplessHeadlessPlugin = Otpless();

@override
void initState() {
    super.initState();
    _otplessHeadlessPlugin.initialize("YOUR_APP_ID");
    _otplessHeadlessPlugin.setResponseCallback(onOtplessResponse);
}

Replace YOUR_APP_ID with your actual App ID from the OTPLESS dashboard.

Step 4: Start SNA with the requestId

Pass the requestId returned by the Create API to start():

final Map<String, dynamic> args = {
    "requestId": "REQUEST_ID_FROM_API"
};

_otplessHeadlessPlugin.start(onOtplessResponse, args);

Start polling the Status Check API from your backend immediately after calling start(). The SDK callback and the server status run in parallel.

Step 5: Handle callbacks

void onOtplessResponse(dynamic response) {
    _otplessHeadlessPlugin.commitResponse(response);

    final responseType = response["responseType"];
    switch (responseType) {
        case "SDK_READY":
            // SDK initialized successfully — enable your continue button
            // or proceed with user authentication.
            break;
        case "FAILED":
            // SDK initialization failed
            if (response["statusCode"] == 5003) {
                // Please try to initialize the SDK again.
            }
            break;
        case "INITIATE":
            // Authentication has been initiated
            if (response["statusCode"] != 200) {
                handleInitiateError(response);
            } else if (response["response"]?["authType"] == "SILENT_AUTH") {
                // SNA is being attempted — show a loading state.
            }
            break;
        case "VERIFY":
            // Verification failed for the attempted authType.
            if (response["response"]?["authType"] == "SILENT_AUTH" && response["statusCode"] == 9106) {
                // SNA verification failed — treated as AUTH_TERMINATED.
            }
            break;
        case "ONETAP":
            // Final success response — returns token / idToken
            break;
        case "AUTH_TERMINATED":
            // SNA-only configuration: auth could not complete.
            // Emitted when pre-checks fail, or when SNA was attempted
            // and then failed. Treat as a terminal failure and rely on
            // the Status Check API for the exact error.
            break;
    }
}

Callback reference

The SDK works in two steps — initialization and start() — and each step has its own set of callbacks.

Step 1: Initialization callbacks

Emitted when you initialize the SDK (Step 3).

Callback	Meaning
`SDK_READY`	SDK initialization completed.
`FAILED`	SDK failed to initialize (e.g. `statusCode 5003`).

Step 2: Start callbacks

Emitted after you invoke start() (Step 4).

Callback	State	Meaning
`INITIATE`	Non-terminal	SNA is being attempted after pre-checks pass. `authType` is `SILENT_AUTH`.
`VERIFY`	Non-terminal	Verification failed for the attempted `authType` (e.g. `statusCode 9106` for `SILENT_AUTH`).
`ONETAP`	Success — terminal	SNA completed successfully (Silent Mobile Verification). Returns `token` / `idToken`.
`AUTH_TERMINATED`	Failed — terminal	Emitted in two cases: (1) pre-checks failed → terminated directly; (2) SNA was initiated and then failed.

In the SNA-only configuration AUTH_TERMINATED is a terminal failure with no fallback. Always treat the Status Check API result as authoritative. See Handling the AUTH_TERMINATED callback.

For the errorCode / statusCode values surfaced in SDK callbacks, see SDK Error Codes.

Next step

Status Check API

Confirm the authoritative auth status from your server.

​Requirements

​Step 1: Add SDK dependency

​Step 2: Smart Authentication (SNA) setup

​Step 3: Initialize the SDK

​Step 4: Start SNA with the requestId

​Step 5: Handle callbacks

​Callback reference

​Step 1: Initialization callbacks

​Step 2: Start callbacks

​Next step

Status Check API

Requirements

Step 1: Add SDK dependency

Step 2: Smart Authentication (SNA) setup

Step 3: Initialize the SDK

Step 4: Start SNA with the requestId

Step 5: Handle callbacks

Callback reference

Step 1: Initialization callbacks

Step 2: Start callbacks

Next step