Sensepass KCP adapter

Client Support Documentation

Generated 2025-12-29 14:21 UTC • Converter: minimal

Overview

SensepassKCPadapter is an Android application that serves as a bridge between KCP (Korea Credit Card Processing) payment terminals and the SensePass payment processing platform. It enables secure, real-time communication between physical payment terminals and SensePass cloud services, allowing merchants to process payments through their existing KCP terminal infrastructure.

---

What is SensepassKCPadapter?

The SensepassKCPadapter application is a critical component in the SensePass payment ecosystem. It:

• Bridges KCP payment terminals with SensePass cloud services

• Maintains persistent WebSocket connections for real-time payment processing

• Manages device pairing and authentication

• Monitors connection status and automatically recovers from network issues

• Logs all activities for troubleshooting and compliance

• Runs continuously in the background as a foreground service

Use Cases

• Point-of-Sale (POS) payment processing

• Retail store payment terminals

• Restaurant payment systems

• Any merchant location using KCP-compatible payment terminals

---

Key Features

1. Automatic Connection Management

• Automatically establishes and maintains WebSocket connections to SensePass servers

• Automatic reconnection on network interruptions

• Connection status monitoring with real-time updates

2. Device Pairing

• Secure pairing process using pairing codes

• Support for both production and test environments

• Persistent pairing data storage

3. Background Operation

• Runs as a foreground service (visible notification)

• Automatically starts on device boot

• Continues running even when the app is closed

• Battery optimization aware

4. Comprehensive Logging

• Detailed file-based logging of all operations

• Automatic log transmission to SensePass servers

• Daily log rotation (keeps last 30 days)

• Viewable logs directly on the device

5. Network Management

• Handles network connectivity changes

• Automatic IP detection for terminal configuration

• Support for both test and production environments

---

System Requirements

Minimum Requirements

• Android Version: 5.0 (API 21) or higher

• Recommended: Android 7.1.2 (API 25) or higher

• Tested On: Verifone X990 with Android 7.1.2 (VanOS)

• Network: Stable internet connection (Wi-Fi or mobile data)

• Storage: Minimal storage required (logs stored in Documents folder)

Hardware Compatibility

• Compatible with KCP-compatible payment terminals

• Works on Android tablets and dedicated payment terminal devices

---

Installation

Step 1: Obtain the Application

• Receive the APK file from SensePass support team

• Ensure you have the correct version for your environment (production or test)

Step 2: Install on Device

1. Enable "Install from Unknown Sources" in Android settings (if required)

2. Transfer the APK file to the device

3. Open the APK file and follow installation prompts

4. Grant all requested permissions when prompted

Step 3: Verify Installation

• The app icon should appear in the app drawer

• Launch the application to verify it opens correctly

Permissions Required

• Internet: Required for WebSocket connections

• Boot Completed: Allows automatic startup on device reboot

• Storage (Android 9 and below): Required for log file storage

---

Initial Setup and Pairing

First-Time Setup

When you first launch the application, you'll be presented with the Pairing Screen. This is a one-time setup process that links your payment terminal to your SensePass merchant account.

Pairing Process

1. Obtain Pairing Code

• Log into your SensePass merchant dashboard

• Navigate to Device Management

• Generate a new pairing code

1. Enter Pairing Information

• Pair Code: Enter the pairing code from your dashboard

• POS Name: Enter a descriptive name for this terminal (e.g., "Main Counter", "Store Front")

1. Complete Pairing

• Click the "Pair" button

• The app will communicate with SensePass servers to register your device

• Upon success, you'll see a confirmation message with your Device ID

• The app will automatically save all pairing information

1. Update KCPPay data

• Terminal IP: (Optional) Enter the local IP address of your KCP terminal, or leave blank for auto-detection

• Terminal Port: Default is 15000 (usually doesn't need to change)

• Test Mode: Toggle ON for testing, OFF for production

• click save

1. Return to Main Screen

• After successful pairing, you'll be taken to the main screen

• The service will automatically start and maintain connection

Re-pairing

If you need to pair with a different merchant account or update settings:

1. From the main screen, click "Pairing"

2. Update any necessary information

3. Complete the pairing process again

4. The new pairing data will overwrite the previous configuration

Manual Device ID Entry

If you already have a Device ID from a previous pairing:

1. Enable "Manual Entry" mode on the pairing screen

2. Enter your Device ID in the "New Device ID" field

3. Complete the pairing process

---

Application Components

Main Screen

The main screen displays:

• Status Indicator: Shows current connection status

• Green Background: Service is running and connected

• White Background: Service is stopped

• "Connecting...": Service is starting up

• Pairing Button: Navigate to pairing screen to update device configuration

• View Logs Button: Opens the current log file in a text viewer

• Send Logs Button: Manually triggers immediate transmission of logs to SensePass servers

Pairing Screen

The pairing screen allows you to:

• Enter or update pairing information

• Start/Stop the SPConnector service manually

• View current connection status

• Complete device pairing with SensePass

Background Service

The application runs a foreground service that:

• Maintains WebSocket connections to SensePass servers

• Handles payment message routing between terminal and cloud

• Automatically reconnects on network issues

• Logs all activities for troubleshooting

Boot Receiver

Automatically starts the service when:

• Device boots up

• Application is updated

• Device is restarted

This ensures the payment terminal is always ready, even after power outages or device restarts.

---

How It Works

Architecture Overview

┌─────────────────┐
│  KCP Terminal   │
│  (Local Network)│
└────────┬────────┘
         │ TCP/IP
         │ (Port 15000)
         ▼
┌─────────────────┐
│ SensepassKCP    │
│    Adapter      │
│  (This App)     │
└────────┬────────┘
         │ WebSocket
         │ (Secure)
         ▼
┌─────────────────┐
│  SensePass      │
│  Cloud Services │
└─────────────────┘

Connection Flow

1. Initial Connection

• App starts and loads saved pairing data

• Establishes WebSocket connection to SensePass servers

• Registers device using Device ID from pairing

1. Payment Processing

• Payment request arrives from SensePass cloud

• App receives message via WebSocket

• Message forwarded to KCP terminal via local network

• Terminal processes payment and responds

• Response sent back to SensePass via WebSocket

1. Connection Monitoring

• App continuously monitors connection status

• Automatically reconnects if connection drops

• Logs all connection events

WebSocket Communication

• Protocol: Secure WebSocket (WSS)

• Server:

• Production: https://api.sensepass.com

• Test: https://api.sandbox.sensepass.com

• Authentication: Device ID (from pairing process)

• Reconnection: Automatic with exponential backoff

Local Network Communication

• Protocol: TCP/IP

• Port: 15000 (default, configurable)

• IP Address: Local IP of KCP terminal (auto-detected or manual)

---

User Interface

Main Screen Elements

Status Display

• Real-time connection status

• Color-coded for quick visual reference

• Updates every second

Navigation Buttons

• Pairing: Access pairing configuration

• View Logs: Open log files for review

• Send Logs: Manually transmit logs to support

Pairing Screen Elements

Input Fields

• Pair Code (required)

• POS Name (required)

• Terminal IP (optional)

• Terminal Port (default: 15000)

• Test Mode toggle

Action Buttons

• Start/Stop SPConnector

• Pair Device

• Back to Main Screen

Status Indicators

• SPConnector running status

• Connection status

• Error/success messages

---

Troubleshooting

Common Issues and Solutions

Issue: "Status: Stopped" (Service Not Running)

Symptoms:

• Status indicator shows white background

• No connection to SensePass

Solutions:

1. Check if device is paired:

• Go to Pairing screen

• Verify pairing information is saved

• Re-pair if necessary

1. Manually start service:

• Go to Pairing screen

• Click "Start SPConnector"

• Wait for status to change to "Running"

1. Check network connection:

• Verify device has internet access

• Test Wi-Fi or mobile data connection

• Ensure firewall isn't blocking connections

Issue: Cannot Pair Device

Symptoms:

• Pairing fails with error message

• "Invalid Pairing Code" error

Solutions:

1. Verify pairing code:

• Check code hasn't expired (generate new one if needed)

• Ensure code is entered correctly

1. Check network:

• Ensure device can reach SensePass servers

• Verify test/production mode matches your environment

1. Verify terminal connection:

• Ensure KCP terminal is powered on

• Check terminal IP address is correct

• Verify terminal is on same network as Android device

Logging and Diagnostics

Log File Location

Logs are stored in the device's Documents folder:

• Path: /Documents/SPBridgeLogs/

• File Format: spbridge_YYYY-MM-DD.txt

• Retention: Last 30 days of logs

Log Contents

Logs include:

• Connection events (connect, disconnect, reconnect)

• Payment message routing

• Error messages and stack traces

• Service lifecycle events

• Network status changes

• Pairing operations

Viewing Logs

On Device:

1. Open the app

2. Click "View Logs" button

3. Log file opens in default text viewer

Via File Manager:

1. Open file manager app

2. Navigate to Documents folder

3. Open SPBridgeLogs folder

4. Select desired log file

Log Transmission

Logs are automatically transmitted to SensePass servers:

• Frequency: Every 1 minute OR when 100 log entries accumulate

• Manual: Click "Send Logs" button for immediate transmission

• Includes: Device ID, POS Name, timestamp, and log entries

Log Levels

• INFO: Normal operations and status updates

• WARNING: Non-critical issues that should be noted

• ERROR: Errors that may affect functionality

• DEBUG: Detailed diagnostic information

---

Maintenance

Regular Maintenance Tasks

1. Monitor Status

• Check app status daily

• Verify connection is "Running"

• Review any error messages

1. Review Logs

• Periodically check logs for errors

• Look for connection issues

• Monitor payment processing success rate

1. Update Application

• Install updates when provided by SensePass

• Updates may include bug fixes and improvements

• Re-pairing usually not required after updates

1. Network Health

• Monitor network stability

• Ensure adequate bandwidth

• Check for network outages

Backup and Recovery

Pairing Data:

• Pairing information is stored locally on device

• If device is replaced, you'll need to re-pair

• Keep pairing codes secure

Logs:

• Logs are stored locally and transmitted to servers

• Old logs (30+ days) are automatically deleted

• Important logs are available from SensePass support

Version Information

• Current Version: 1.0

• SPConnector Version: 1.5

• Minimum Android: 5.0 (API 21)

• Target Android: 14 (API 34)

Security Notes

• All communications are encrypted (WSS)

• Device authentication via Device ID

• Logs may contain sensitive information - handle securely

---

Revision History

Version	Date	Changes
1.0	29.12.2025	Initial support documentation

---

Document Version: 1.0

Last Updated: 29.12.2025

Maintained By: SensePass Support Team