Network Setup - NetPOS

Overview

NetPOS requires reliable network connectivity to communicate with NIBSS (Nigeria Inter-Bank Settlement System), backend APIs, and MQTT services. This guide covers network configuration, requirements, and troubleshooting.

Network Requirements

Internet Connection

Type: Wi-Fi or Mobile Data
Speed: Minimum 2G/3G (4G recommended)
Stability: Stable connection during transactions

Firewall Rules

NIBSS: Allow outbound to 196.6.103.18:4016
MQTT: Allow storm-mqtt.netpluspay.com
API: Allow *.netpluspay.com

SSL/TLS

Protocol: TLS 1.2 or higher
Certificates: Valid SSL certificates required
Encryption: End-to-end encryption enabled

Ports

NIBSS: Port 4016 (SSL)
MQTT: Port 8883 (SSL) or 1883
HTTPS: Port 443

NIBSS Connection

NetPOS connects to NIBSS using the ISO 8583 protocol over SSL/TLS.

Connection Parameters

ipAddress

string

required

NIBSS server IP addressProduction: 196.6.103.18

ipPort

number

required

NIBSS server portProduction: 4016

isSSL

boolean

required

Enable SSL/TLS encryptionValue: true (always required)

Connection Configuration

The connection is established using:

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

Connection parameters are automatically loaded from ConfigurationData during terminal initialization.

MQTT Integration

NetPOS uses MQTT for real-time notifications and remote terminal management.

MQTT Broker Configuration

Production
Staging

base.url.netpos.mqtt=storm-mqtt.netpluspay.com

Host: storm-mqtt.netpluspay.com
Port: 8883 (SSL) or 1883 (non-SSL)
Protocol: MQTT 3.1.1 or 5.0

base.url.netpos.mqtt=storm-mqtt.test.netpluspay.com

Host: storm-mqtt.test.netpluspay.com
Port: 8883 (SSL) or 1883 (non-SSL)
Protocol: MQTT 3.1.1 or 5.0

MQTT Topics

NetPOS subscribes to specific topics for different events:

Terminal Configuration

Topic: mqtt.pos.terminal_config.eventUsed for:

Remote configuration updates
Terminal parameter changes
Key rotation notifications

Transaction Notifications

Topic: mqtt.pos.transaction.eventUsed for:

Real-time transaction updates
Payment confirmations
Status notifications

System Events

Topic: mqtt.pos.system.eventUsed for:

App updates
System maintenance notifications
Emergency broadcasts

MQTT Connection Handling

// Connection established
onConnected() {
    Timber.d("MQTT Connected")
    // Subscribe to topics
}

// Connection failed
onFailure(exception: Throwable) {
    Timber.e("Connection failed: ${exception.localizedMessage}")
    // Retry connection
}

// Message received
onMessageReceived(topic: String, message: String) {
    // Process event based on topic
}

API Endpoints

NetPOS communicates with multiple backend services:

Storm API

base.url.storm.utilities

string

Production: https://storm-utilities.netpluspay.com/Staging: http://storm-utilities.test.netpluspay.com/

Services:

Transaction management
End-of-day reports
User authentication
Bills payment

NetPOS Gateway

STRING_DEFAULT_BASE_URL

string

Main NetPOS API endpoint (configured in local.properties)

Services:

Card transactions
Transaction history
Merchant operations

Zenith API

STRING_ZENITH_BASE_URL

string

Zenith Bank-specific API endpoint

Services:

Pay by transfer
Account verification
QR payments

QR Payment API

STRING_CONTACTLESS_PAYMENT_WITH_QR_BASE_URL

string

Contactless and QR payment services

Services:

NIBSS QR
MasterPass QR
BlueCode
Zenith QR

Network Error Handling

NetPOS implements comprehensive error handling for network issues:

Common Network Errors

Connection Timeout

Error: “Connection timed out, failed to receive response from remote server”Causes:

Slow network connection
Server not responding
Network congestion

Resolution:

Check internet connectivity
Retry transaction
Switch to alternate network (Wi-Fi ↔ Mobile Data)

No Internet Connection

Error: “Could not connect to the internet, check your connection settings and try again”Causes:

No active network connection
Airplane mode enabled
Network disabled

Resolution:

Enable Wi-Fi or Mobile Data
Disable airplane mode
Check device network settings

Server Unreachable

Error: “Could not connect with remote server, check your connection settings and try again”Causes:

Firewall blocking connection
Incorrect server address
Server maintenance

Resolution:

Verify firewall rules
Check server IP and port
Contact support if server is down

Port Unreachable

Error: “Could not connect with remote server, port is unreachable”Causes:

Port blocked by firewall
Wrong port configuration
Network policy restrictions

Resolution:

Check firewall allows port 4016
Verify port configuration
Contact network administrator

Malformed URL

Error: “Malformed url, check your connection settings and try again”Causes:

Invalid URL format
Configuration error
Incorrect endpoint

Resolution:

Verify API endpoints in configuration
Check local.properties URLs
Reconfigure terminal

Socket Errors

Errors:

“Could not bind socket to local address or port”
“Could not create socket”

Causes:

Port already in use
Network interface error
System resource limitation

Resolution:

Restart application
Restart device
Check for conflicting apps

Host Resolution

Error: “Host address could not be recognized”Causes:

DNS resolution failure
Invalid hostname
DNS server not responding

Resolution:

Check DNS settings
Use IP address instead of hostname
Try alternate DNS (8.8.8.8)

Error Detection

Check if an error is network-related:

if (ConnectionErrorConstants.isConnectionError(responseMessage)) {
    // Handle network error
    // Prompt user to check connection
    // Offer retry option
}

Network Monitoring

NetPOS monitors network status to ensure transaction reliability:

Connection State

// Check network availability
val isConnected = context.isNetworkAvailable()

if (!isConnected) {
    // Show offline message
    // Queue transactions for later
    // Disable payment options
}

Network Type Detection

when (networkType) {
    ConnectivityManager.TYPE_WIFI -> {
        // Optimal connection
    }
    ConnectivityManager.TYPE_MOBILE -> {
        // Mobile data - may be slower
    }
    else -> {
        // Unknown or no connection
    }
}

SSL/TLS Configuration

Certificate Validation

NetPOS validates SSL certificates for all secure connections:

NIBSS connections require valid SSL certificates
MQTT broker must have valid TLS certificate
API endpoints must use HTTPS with valid certificates

Do not disable certificate validation in production builds. This creates serious security vulnerabilities.

Supported TLS Versions

Minimum: TLS 1.2
Recommended: TLS 1.3
Cipher Suites: Strong encryption required

Firewall Configuration

Ensure your network allows these connections:

Outbound Rules Required

Service	Protocol	Destination	Port
NIBSS	TCP/SSL	196.6.103.18	4016
Storm MQTT (Prod)	TCP/SSL	storm-mqtt.netpluspay.com	8883
Storm MQTT (Test)	TCP/SSL	storm-mqtt.test.netpluspay.com	8883
Storm API (Prod)	HTTPS	storm-utilities.netpluspay.com	443
Storm API (Test)	HTTP/HTTPS	storm-utilities.test.netpluspay.com	80/443
NetPOS API	HTTPS	api.netpluspay.com	443

Network Security

Allow NIBSS Connection

Configure firewall to allow outbound connections to NIBSS:

Allow: TCP 196.6.103.18:4016 (Outbound)
Protocol: SSL/TLS

Allow MQTT Broker

Enable MQTT communication:

Allow: TCP storm-mqtt.netpluspay.com:8883 (Outbound)
Protocol: MQTT over SSL

Allow API Endpoints

Enable backend API access:

Allow: HTTPS *.netpluspay.com:443 (Outbound)
Protocol: HTTPS

Best Practices

Connection Stability

Use Wi-Fi for bulk operations
Ensure stable connection during transactions
Monitor network quality

Retry Logic

Implement automatic retry for network failures
Use exponential backoff
Limit retry attempts

Offline Handling

Queue transactions when offline
Inform users of connection status
Sync when connection restored

Security

Always use SSL/TLS
Validate certificates
Never expose credentials

Testing Network Connectivity

Manual Tests

Ping NIBSS Server

ping 196.6.103.18

Should receive responses confirming connectivity.

Test Port Connectivity

telnet 196.6.103.18 4016
# or
nc -zv 196.6.103.18 4016

Should connect successfully.

Verify MQTT Broker

ping storm-mqtt.netpluspay.com

Should resolve and respond.

Test API Endpoints

curl -I https://storm-utilities.netpluspay.com/

Should return HTTP 200 or valid response.

Get Started

User Guide

Payment Methods

Terminal Management

​Overview

​Network Requirements

Internet Connection

Firewall Rules

SSL/TLS

Ports

​NIBSS Connection

​Connection Parameters

​Connection Configuration

​MQTT Integration

​MQTT Broker Configuration

​MQTT Topics

​MQTT Connection Handling

​API Endpoints

​Storm API

​NetPOS Gateway

​Zenith API

​QR Payment API

​Network Error Handling

​Common Network Errors

​Error Detection

​Network Monitoring

​Connection State

​Network Type Detection

​SSL/TLS Configuration

​Certificate Validation

​Supported TLS Versions

​Firewall Configuration

​Outbound Rules Required

​Network Security

​Best Practices

Connection Stability

Retry Logic

Offline Handling

Security

​Testing Network Connectivity

​Manual Tests

​See Also

Build docs developers (and LLMs) love

Overview

Network Requirements

NIBSS Connection

Connection Parameters

Connection Configuration

MQTT Integration

MQTT Broker Configuration

MQTT Topics

MQTT Connection Handling

API Endpoints

Storm API

NetPOS Gateway

Zenith API

QR Payment API

Network Error Handling

Common Network Errors

Error Detection

Network Monitoring

Connection State

Network Type Detection

SSL/TLS Configuration

Certificate Validation

Supported TLS Versions

Firewall Configuration

Outbound Rules Required

Network Security

Best Practices

Testing Network Connectivity

Manual Tests

See Also