02 - Mock Mode

Mock mode is the reason you can run the entire 16-stage eKYC journey on your laptop without real SMS, NSDL calls, or bank verification. Understanding it is critical for local development.

Backend Setup

Mock mode is controlled by a single flag in the backend's Development settings file.

{
  "Logging": {
    "LogLevel": {
      "Default": "Debug",
      "Microsoft.AspNetCore": "Information",
      "Microsoft.EntityFrameworkCore.Database.Command": "Information"
    }
  },
  "ConnectionStrings": {
    "EkycDb": "Host=127.0.0.1;Port=5432;Database=ekyc3;Username=postgres;Password=root123;..."
  },
  "MockMode": {
    "GlobalMockEnabled": true
  },
  "Payment": {
    "Razorpay": {
      "ClientApiKey": "rzp_test_placeholder"
    }
  },
  "Sms": {
    "Mode": "FIXED_OTP",
    "FixedOtp": "1234"
  },
  "Email": {
    "Mode": "FIXED_OTP",
    "FixedOtp": "1234"
  }
}

Where the Backend Reads This Flag

At least 13 backend services check GlobalMockEnabled and change behavior accordingly.

Per-Provider Mock Mode

Beyond the global switch, each external provider has its own mock_mode flag in the provider_configurations database table. This lets you force one provider live while keeping others mocked.

-- See current provider mock settings
SELECT provider_name, category, mock_mode
FROM ekyc.provider_configurations
ORDER BY category, priority;

-- Turn off mock for HyperVerge liveness (go live for this one provider)
UPDATE ekyc.provider_configurations
SET mock_mode = false
WHERE provider_name = 'HypervergeLiveness';

The backend's ProviderChainExecutor reads this per request - no restart needed.

Flutter Side: Mock URL Detection

When the backend is in mock mode, it returns fake redirect URLs containing strings like example.com, mock-digilocker, or hyperverge.co. The Flutter app detects these URLs and skips opening the WebView or UPI app, calling the success callback directly instead.

Critically, this detection is only active in dev builds. In prod builds, ApiConfig.isDev is a compile-time constant false, so the mock-bypass code is dead and tree-shaken out of the binary.

if (_redirectUrl != null && _redirectUrl!.isNotEmpty) {
  // Dev only: skip WebView for mock URLs from backend
  if (ApiConfig.isDev &&
      (_redirectUrl!.contains('mock-digilocker') ||
       _redirectUrl!.contains('example.com'))) {
    await _handleMockDigilocker();
    return;
  }
  _initWebView(_redirectUrl!);
  setState(() {
    _screenState = _ScreenState.webview;
    _isLoading = false;
  });
}

// Dev only: skip external UPI launch for mock URLs from backend
if (ApiConfig.isDev &&
    (redirectUrl.contains('mock') ||
     redirectUrl.contains('example.com') ||
     redirectUrl.contains('hyperverge.co') ||
     redirectUrl.isEmpty)) {
  // Mock: skip UPI app but still show verified state for income selection
  final mockResult = await api.completeReversePenny(
    transactionRef: transactionId,
    accountNumber: '',
    ifscCode: '',
  );
  ...
}

What Behaves Differently in Mock Mode

To see the full stage-by-stage flow for both modes, open the Old vs New UI Comparison or check the Journey Flow Bar on the WarRoom dashboard.

Testing Journey Variations

Test a specific provider live

Keep GlobalMockEnabled: true, but update the DB for the one provider you want live:

UPDATE ekyc.provider_configurations
SET mock_mode = false
WHERE provider_name = 'HypervergeLiveness';

Test full live mode locally

Set GlobalMockEnabled: false and provide real API keys in appsettings.Development.json. This is risky - you'll hit real SMS, real NSDL, real providers. Only do this if you have non-production credentials.

Test Decentro auto-verify

Decentro mobile-to-bank is triggered at Stage 2 (OTP verified). In mock mode, it stores a fake HDFC savings account for the lead. When the user reaches Stage 6, the backend auto-promotes this to a verified bank account and the user lands directly on the Bank Verified screen. Clicking "Change bank" takes them to manual entry.

Troubleshooting

OTP 1234 is rejected

• Check appsettings.Development.json: Sms.Mode must be "FIXED_OTP" (not "REAL")
• Restart the backend after changing appsettings
• Make sure you are running in Development environment: dotnet run uses Development by default

Real DigiLocker WebView opens in mock mode

• Backend returning a real URL means GlobalMockEnabled is false - check the file
• Or the backend never set AadhaarVerificationService._globalMockEnabled - verify the service reads config.GetValue<bool>("MockMode:GlobalMockEnabled")

Stage 6 shows hardcoded test bank in prod

Backend started but app still says "No internet"

• Check CORS in backend/src/MO.Ekyc.Api/appsettings.json - AllowedOrigins must include http://localhost:8080
• Check the browser Network tab (F12) to see the actual failed request and status code