Skip to main content

​
Overview

NetPOS terminals require proper configuration to communicate with the NIBSS (Nigeria Inter-Bank Settlement System) network and process transactions. This guide covers the complete terminal configuration process.

​
Configuration Parameters

The terminal configuration system manages critical connection and security parameters stored in the ConfigurationData model.

​
Core Configuration Fields

​
ip
string
required
NIBSS server IP address. Production default: 196.6.103.18
​
port
string
required
NIBSS server port. Production default: 4016
​
terminalId
string
required
Unique terminal identifier assigned by NIBSS. Default: 2057H63U
​
key1
string
required
First component of the host base key for encryption
​
key2
string
required
Second component of the host base key for encryption

​
Configuration Process

1

Initial Configuration

The terminal automatically initializes on first launch using the NetPosTerminalConfig.init() method.
NetPosTerminalConfig.init(
    context = context,
    configureSilently = false
)
The configuration process runs automatically when the app starts. Manual configuration is only needed for troubleshooting.
2

Download NIBSS Keys

The terminal connects to NIBSS to download cryptographic keys:
  • Session Keys: Temporary keys for secure communication
  • PIN Keys (TPK): Terminal PIN Key for card PIN encryption
  • Master Keys: Long-term encryption keys
Keys are downloaded via the downloadNibssKeys() method and stored securely.
3

Download Terminal Parameters

After key exchange, the terminal downloads operational parameters:
terminalConfigurator.downloadTerminalParameters(
    context,
    terminalId,
    sessionKey,
    deviceSerial
)
Parameters include transaction limits, supported card types, and merchant settings.
4

Configuration Validation

The system validates the configuration and stores it locally:
  • Configuration data is saved to SharedPreferences
  • TPK key is written to secure hardware storage
  • Configuration timestamp is recorded
  • Status broadcast is sent to the application

​
Configuration Modes

​
Silent Configuration

For background updates without UI feedback: 
NetPosTerminalConfig.init(
    context = context,
    configureSilently = true
)

​
Interactive Configuration

With UI status updates and user feedback: 
NetPosTerminalConfig.init(
    context = context,
    configureSilently = false
)

​
Call Home Protocol

Terminals perform a daily “call home” to verify configuration validity:
The call home process:
  1. Checks if configuration was done today using LAST_POS_CONFIGURATION_TIME
  2. If not today, performs full reconfiguration
  3. If today, sends lightweight validation request to NIBSS
  4. On success (responseCode = "00"), continues normal operation
  5. On failure, triggers full reconfiguration
terminalConfigurator.nibssCallHome(
    context,
    terminalId,
    clearSessionKey,
    deviceSerial
)

​
Configuration Status

The configuration process uses status codes to track progress:
StatusMeaning
-99Reset/Idle state
0Configuration started
1Configuration successful
-1Configuration failed

​
Monitoring Configuration Status

Listen for configuration broadcasts: 
LocalBroadcastManager.getInstance(context)
    .registerReceiver(object : BroadcastReceiver() {
        override fun onReceive(context: Context, intent: Intent) {
            val status = intent.getIntExtra(CONFIGURATION_STATUS, -99)
            when (status) {
                1 -> // Configuration successful
                -1 -> // Configuration failed
                0 -> // Configuration in progress
            }
        }
    }, IntentFilter(CONFIGURATION_ACTION))
The broadcast action is com.woleapp.netpos.TERMINAL_CONFIGURATION

​
Storage Locations

Configuration data is persisted in multiple locations:
  • PREF_KEYHOLDER: Encrypted key holder with session and PIN keys
  • PREF_CONFIG_DATA: Terminal configuration parameters
  • LAST_POS_CONFIGURATION_TIME: Timestamp of last successful configuration
  • CLEAR_PIN_KEY: Decrypted PIN key for hardware storage
  • PREF_USE_STORM_TERMINAL_ID: Flag to use Storm-assigned terminal ID
  • TPK Index: Secure storage index for Terminal PIN Key
  • Device Serial: Retrieved via NetPosSdk.getDeviceSerial()
  • Keys are written using NetPosSdk.writeTpkKey() to secure hardware

​
Terminal ID Management

Always use the terminal ID from your logged-in user account. The default terminal ID is for testing only.
The terminal ID is retrieved from the current user: 
val terminalId = Singletons.getCurrentlyLoggedInUser()?.terminal_id

​
Using Storm Terminal ID

NetPOS can switch between NIBSS and Storm-assigned terminal IDs: 
// Enable Storm terminal ID
Singletons.setUseStormTid(true)

// Check current setting
val usingStormId = useStormTerminalId()

​
Encryption Keys

NetPOS uses different key sets based on environment:

​
Production Keys (POSVAS)

key1 = "9BF76D3E13ADD67A51549B7C3EB0E3AD"
key2 = "A4BAEC5E31BFD913919262C7A7A76D52"

​
Test Keys

key1 = "5D25072F04832A2329D93E4F91BA23A2"
key2 = "86CBCDE3B0A22354853E04521686863D"
Never use test keys in production environments. Keys are set automatically based on build configuration.

​
Connection Settings

Connection to NIBSS uses SSL/TLS encryption: 
ConnectionData(
    ipAddress = "196.6.103.18",
    ipPort = 4016,
    isSSL = true
)

​
Network Requirements

  • Protocol: ISO 8583 over SSL/TLS
  • Timeout: Configurable per transaction type
  • Retry Logic: Automatic retry on network failures
  • Firewall: Allow outbound connections to NIBSS IP on specified port

​
Best Practices

Daily Configuration

Allow automatic daily call home to keep terminal updated

Secure Storage

Never log or expose encryption keys in production

Error Handling

Monitor configuration status and handle failures gracefully

Network Stability

Ensure stable network connection during configuration

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us