Skip to main content

​
Overview

This guide helps you diagnose and resolve common issues with NetPOS terminals, including configuration errors, network problems, and transaction failures.

​
Configuration Issues

​
Terminal Configuration Failed

Error message: “Terminal configuration failed” or status code -1
  • No internet connection
  • NIBSS server unreachable
  • Invalid terminal ID
  • Incorrect encryption keys
  • Expired certificates
1

Verify Network Connectivity

  • Check internet connection is active
  • Test connection to NIBSS server: 
    ping 196.6.103.18
  • Ensure port 4016 is accessible
  • Switch between Wi-Fi and mobile data
2

Validate Terminal ID

  • Confirm terminal ID is correct
  • Check logged-in user has valid terminal_id
  • Verify terminal ID is registered with NIBSS
  • Default test ID: 2057H63U (for testing only)
3

Check Configuration Data

  • Verify NIBSS IP: 196.6.103.18
  • Verify NIBSS Port: 4016
  • Confirm SSL is enabled: isSSL = true
  • Check encryption keys are correct for environment
4

Force Reconfiguration

  • Clear configuration data from SharedPreferences
  • Clear LAST_POS_CONFIGURATION_TIME
  • Restart application
  • Configuration will run automatically

​
Call Home Failed

Error: “call home failed” - Terminal cannot validate existing configuration
  • Session key expired
  • Configuration data corrupted
  • NIBSS server rejected request (response != “00”)
  • Network timeout
1

Check Session Key

  • Verify clearSessionKey is stored correctly
  • Session keys expire periodically
  • Full reconfiguration will download new keys
2

Trigger Full Reconfiguration

The system automatically triggers full reconfiguration if call home fails:
callHome(context).onErrorResumeNext {
    // Automatically falls back to full configuration
    configureTerminal(context)
}
No manual intervention needed - just retry the operation.
3

Verify Device Serial

  • Device serial is retrieved via NetPosSdk.getDeviceSerial()
  • Must match registered device in NIBSS
  • Contact support if device serial mismatch

​
Terminal Not Configured

Message: “Terminal not configured” when attempting transactions
  • First-time setup not completed
  • Configuration cleared
  • Keys not downloaded
  • ConfigData or KeyHolder is null
1

Check Configuration Status

val keyHolder = NetPosTerminalConfig.getKeyHolder()
val configData = NetPosTerminalConfig.getConfigData()

if (keyHolder == null || configData == null) {
    // Terminal needs configuration
    NetPosTerminalConfig.init(context)
}
2

Monitor Configuration Broadcast

Listen for configuration completion:
LocalBroadcastManager.getInstance(context)
    .registerReceiver(object : BroadcastReceiver() {
        override fun onReceive(context: Context, intent: Intent) {
            val status = intent.getIntExtra(CONFIGURATION_STATUS, -99)
            when (status) {
                1 -> // Success - terminal ready
                -1 -> // Failed - show error
                0 -> // In progress - show loading
            }
        }
    }, IntentFilter(CONFIGURATION_ACTION))
3

Wait for Completion

  • Configuration takes 10-30 seconds
  • Ensure stable internet during process
  • Do not force-close the app
  • Status 1 indicates success

​
TPK Key Write Failed

Terminal PIN Key (TPK) not written to secure storage
  • Hardware security module error
  • Invalid TPK index
  • Insufficient permissions
  • Device compatibility issue
1

Verify Device Compatibility

  • Check device has hardware security support
  • Confirm device model is supported
  • Test on known-compatible device
2

Check TPK Parameters

writeTpkKey(
    DeviceConfig.TPKIndex,  // Correct index
    clearPinKey,            // Valid key
    context                 // Valid context
)
3

Fallback Storage

TPK is also stored in SharedPreferences:
Prefs.putString(CLEAR_PIN_KEY, clearPinKey)
val storedKey = Prefs.getString(CLEAR_PIN_KEY, "")
Use stored key if hardware write fails.

​
Network Issues

​
Connection Timeout

“Connection timed out, failed to receive response from remote server”
1

Check Network Speed

  • Test internet speed (minimum 2G/3G)
  • Switch to faster network if available
  • Use Wi-Fi for better stability
2

Increase Timeout

  • Default timeout may be too short for slow networks
  • Configure longer timeout for mobile data
  • Retry transaction
3

Check Server Status

  • Verify NIBSS server is operational
  • Check for scheduled maintenance
  • Contact support if server down

​
Port Unreachable

“Could not connect with remote server, port is unreachable”
1

Verify Firewall Rules

Ensure outbound connections allowed:
TCP 196.6.103.18:4016 (Outbound, SSL)
2

Check Network Restrictions

  • Corporate networks may block non-standard ports
  • Contact network administrator
  • Try alternate network (mobile data)
3

Test Port Connectivity

telnet 196.6.103.18 4016
Should connect successfully.

​
DNS Resolution Failed

“Host address could not be recognized”
1

Check DNS Settings

  • Verify device DNS configuration
  • Try Google DNS: 8.8.8.8 / 8.8.4.4
  • Restart network connection
2

Use IP Address

  • NIBSS uses IP address (196.6.103.18) not hostname
  • No DNS lookup required for NIBSS
  • Check MQTT broker hostname resolves

​
SSL/TLS Errors

SSL handshake failed or certificate validation error
1

Check Device Time

  • Incorrect device time causes certificate validation failures
  • Set automatic date and time
  • Sync with network time
2

Update System Certificates

  • Update device to latest OS version
  • Install system security updates
  • Verify TLS 1.2+ support
3

Verify SSL Enabled

ConnectionData(
    ipAddress = "196.6.103.18",
    ipPort = 4016,
    isSSL = true  // Must be true
)

​
Transaction Issues

​
Terminal Validation Failed

Error: “Terminal validation failed” during transaction
  • Terminal not properly configured
  • Invalid terminal parameters
  • Expired configuration
  • Session keys expired
1

Reconfigure Terminal

  • Force reconfiguration by clearing LAST_POS_CONFIGURATION_TIME
  • Restart app to trigger auto-configuration
  • Wait for configuration to complete successfully
2

Verify Terminal Parameters

Check ConfigData contains:
  • Valid terminal capabilities
  • Correct merchant ID
  • Proper transaction limits
  • Supported card types

​
Payment Failed

  • Insufficient funds
  • Invalid PIN
  • Card declined by issuer
  • Network timeout
  • Terminal configuration issue
1

Check Response Code

  • 00: Approved (success)
  • 51: Insufficient funds
  • 55: Incorrect PIN
  • 91: Issuer not available
  • 96: System error
See NIBSS response codes documentation for complete list.
2

Verify Card Status

  • Card not expired
  • Card not blocked
  • Card type supported (Verve, Visa, MasterCard)
  • Chip functional (for chip cards)
3

Check Transaction Log

  • Review transaction details in database
  • Check for error messages
  • Verify request reached NIBSS
  • Confirm response received

​
Transaction Timeout

Transaction takes too long and times out
1

Check Network Quality

  • Ensure stable internet connection
  • Avoid network switching during transaction
  • Use Wi-Fi for better performance
2

Reversal Handling

  • System automatically reverses timeout transactions
  • Check if reversal completed successfully
  • Verify funds returned to customer
3

Retry Transaction

  • Wait for timeout period to complete
  • Ensure previous transaction reversed
  • Retry with same or different card

​
MQTT Issues

​
MQTT Connection Failed

“Connection failed because: [error message]”
1

Verify Broker Configuration

  • Production: storm-mqtt.netpluspay.com
  • Staging: storm-mqtt.test.netpluspay.com
  • Check correct environment is configured
2

Check Network Access

ping storm-mqtt.netpluspay.com
Verify hostname resolves and is reachable.
3

Verify Port Access

  • SSL port: 8883
  • Non-SSL port: 1883 (if SSL disabled)
  • Ensure firewall allows connection
4

Check Authentication

  • Verify MQTT credentials are correct
  • Check client ID is unique
  • Ensure user has permission to connect

​
Events Not Received

MQTT connected but not receiving notifications
1

Verify Subscriptions

Check subscribed to correct topics:
  • mqtt.pos.terminal_config.event
  • mqtt.pos.transaction.event
  • mqtt.pos.system.event
2

Check Topic Filters

  • Ensure topic names match exactly
  • Verify wildcard subscriptions if used
  • Check QoS level (0, 1, or 2)
3

Monitor Connection State

  • Connection may disconnect silently
  • Implement automatic reconnection
  • Log connection state changes

​
App-Specific Issues

​
Wrong Branding Displayed

App shows incorrect bank logo or name
1

Check Build Flavor

Log.d("BuildFlavor", BuildConfig.FLAVOR)
// Should show: netpos, zenith, wema, etc.
2

Clean and Rebuild

./gradlew clean
./gradlew assembleZenithRelease  # or correct flavor
3

Verify Installation

  • Uninstall old version completely
  • Install correct flavor APK
  • Check package name matches expected flavor

​
Reprint Password Not Working

Cannot set or use reprint password (Wema/Zenith only)
1

Verify Flavor Support

Feature only available for Wema and Zenith:
if (BuildConfig.FLAVOR != "wema" && BuildConfig.FLAVOR != "zenith") {
    // Feature not available
}
2

Set Password

  • Go to Settings
  • Tap “Reprint Password”
  • Enter password twice
  • Tap Save
3

Reset Password

Password stored in SharedPreferences as PREF_REPRINT_PASSWORD:
Prefs.remove(PREF_REPRINT_PASSWORD)
// Password cleared - can set new one

​
Features Not Available

Expected payment method or feature not visible
1

Check Flavor-Specific Features

Some features are flavor-specific:
  • Zenith: Pay by Transfer, Custom QR
  • Wema: Agent Banking, MPGS
  • Providus: Merchant accounts
Verify correct flavor is installed.
2

Verify User Permissions

  • Check user role and permissions
  • Some features require specific account types
  • Contact support to enable features
3

Check Configuration

  • Features may require additional configuration
  • Verify merchant is registered for service
  • Ensure terminal parameters include feature flags

​
Diagnostic Tools

​
Enable Debug Logging

1

Timber Logging

NetPOS uses Timber for logging:
Timber.d("Debug message")
Timber.e("Error message")
Timber.e(exception, "Exception occurred")
View logs in Logcat when device connected via ADB.
2

Configuration Status

Monitor configuration process:
NetPosTerminalConfig.liveData.observe(owner) { event ->
    event.getContentIfNotHandled()?.let { status ->
        Timber.d("Configuration status: $status")
    }
}
3

Network Request Logging

Enable OkHttp logging for API requests:
val loggingInterceptor = HttpLoggingInterceptor().apply {
    level = HttpLoggingInterceptor.Level.BODY
}

​
Check Stored Configuration

1

View SharedPreferences

// Check configuration data
val configData = Prefs.getString(PREF_CONFIG_DATA, null)
val keyHolder = Prefs.getString(PREF_KEYHOLDER, null)
val lastConfigTime = Prefs.getLong(LAST_POS_CONFIGURATION_TIME, 0)

Timber.d("ConfigData: $configData")
Timber.d("KeyHolder: $keyHolder")
Timber.d("Last configured: ${Date(lastConfigTime)}")
2

Validate Configuration

val keyHolder = NetPosTerminalConfig.getKeyHolder()
val configData = NetPosTerminalConfig.getConfigData()
val terminalId = NetPosTerminalConfig.getTerminalId()

if (keyHolder == null || configData == null || terminalId.isEmpty()) {
    Timber.e("Configuration incomplete!")
    // Trigger reconfiguration
}

​
Getting Help

Check Logs

  • Review Logcat output
  • Check Timber logs
  • Look for exception stack traces
  • Note error codes and messages

Test Connectivity

  • Ping NIBSS server
  • Test port connectivity
  • Verify DNS resolution
  • Check firewall rules

Verify Configuration

  • Check terminal ID
  • Validate encryption keys
  • Confirm environment settings
  • Review build flavor

Contact Support

  • Provide device model
  • Include error messages
  • Share configuration details
  • Describe steps to reproduce

​
Common Solutions Summary

  1. Check internet connection
  2. Verify NIBSS server reachable (196.6.103.18:4016)
  3. Validate terminal ID
  4. Clear configuration cache
  5. Restart app
  1. Ensure terminal configured (status = 1)
  2. Check network connectivity
  3. Verify card is valid and active
  4. Review transaction response code
  5. Check for reversals if timeout occurred
  1. Test internet connection
  2. Switch networks (Wi-Fi ↔ Mobile)
  3. Check firewall and port access
  4. Verify SSL/TLS certificate validity
  5. Retry with stable connection
  1. Confirm correct build flavor installed
  2. Check user permissions and account type
  3. Verify merchant registered for feature
  4. Review terminal parameters
  5. Contact support to enable feature

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us