Solution Overview
Tapro semi-integration decouples your business system from the payment terminal — business logic stays on the POS side while payment processing is handled by the Tapro terminal. The two collaborate through the Taplink SDK or Nexus API.
Product Architecture
Choosing an Integration Form
Start with one question: Are your POS software and payment terminal on the same device?
| Your Situation | Integration Form | Connection Method |
|---|---|---|
| Same Android device | On-Device | Intent (IPC) |
| Two devices, same site | Cross-Device | LAN / Cable / Auto |
| Two devices, cloud POS or multi-store management | Cross-Device | Cloud |
| Customer display required | Sub-Screen | Direct display connection |
Hybrid Deployment: Different stores can use different forms. For example, headquarters uses Cloud for centralized management, store counters use On-Device for speed, and customer-facing windows use Sub-Screen.
On-Device
POS and Tapro run on the same Android device. The SDK launches Tapro via Intent — IPC latency is in the low milliseconds. Suitable for Android all-in-one devices, tablets, and handheld terminals.
Integration only requires initializing the Taplink SDK with your appId and clientSecret. The SDK automatically detects the local Tapro app and establishes the connection — no IP, port, or cabling configuration needed.
Currently Android only. Windows and iOS support is planned.
Cross-Device
POS and payment terminal are separate devices. Choose a connection method based on your site conditions:
| Method | Description | Best For |
|---|---|---|
| LAN | WebSocket/TLS over the same network | Devices on the same network, wireless flexibility needed |
| Cable | USB or RS232 direct connection | Devices side by side, maximum stability |
| Auto | SDK automatically selects LAN or Cable and falls back as needed | Hands-off connection management |
| Cloud | Merchant backend dispatches orders to the terminal via Nexus API | Cloud POS / SaaS / multi-store management |
LAN, Cable, and Auto establish local connections through the Taplink SDK. Cloud mode uses Nexus SDK / API to dispatch orders from the cloud — no local connection required.
LAN
Connected via WebSocket over TLS (WSS):
- Transport security: TLS 1.2+ encryption, HMAC-SHA256 message signing, 24-hour session validity
- Port: Random port 8443-8453, shown on the Tapro UI
- Device discovery: First connection requires manual IP + port entry. After that, mDNS (
_taplink._tcp.local) handles automatic discovery and adapts to DHCP-driven IP changes
Cable
| Type | Protocol | Use Case |
|---|---|---|
| USB AOA | Android Open Accessory 2.0 | Android ↔ Android, plug and play |
| USB-VSP | CDC-ACM virtual serial port | Windows ↔ Android |
| RS232 | Standard serial | Traditional POS ↔ terminal |
The SDK monitors USB / serial ports automatically and establishes communication once a physical link is detected — no manual port configuration required.
Cable mode is now available. You can connect to TaPro over USB VSP, RS232, or USB AOA using the Taplink SDK.
Auto
The SDK decides between LAN and Cable automatically — no need to specify a connection method.
Selection strategy:
- Cable is tried first (lower latency, no network dependency)
- Falls back to LAN when Cable is unavailable
- Link health is monitored continuously; if the active link drops, the SDK attempts the other one
Automatic switching only occurs while idle. If the link drops mid-transaction, the SDK returns a connection error and lets the POS decide whether to retry or cancel — it never switches links silently during a transaction.
Cloud
The merchant backend sends payment orders through the Nexus API. SUNBAY pushes the instruction to wake up Tapro for payment collection, and the transaction result is returned via Webhook. Ideal when the POS is cloud-based or you need to manage multiple stores centrally.
View Cloud Integration Documentation →
Sub-Screen
For scenarios where a customer-facing display needs to show amount and payment status (restaurants, retail checkouts, etc.). The display is physically attached to the terminal — no connection method configuration needed.
Key difference: Sub-Screen integration applies a stricter success criteria — the connection is only considered successful when the terminal’s customer display has lit up and entered the ready-for-payment state. If the display fails to activate, the SDK returns a clear failure reason, preventing the “looks connected but the screen is dark” situation.
On the Tapro terminal UI, Sub-Screen appears as a dedicated tab, separate from other Cross-Device methods, for easy identification.
Core Components
Taplink SDK (Local Integration)
Powers On-Device, local Cross-Device connections (LAN / Cable / Auto), and Sub-Screen integration.
- Platforms: ✅ Android (released), 🚧 Windows / iOS (planned)
- Capabilities: Payment API wrapper, connection management, auto-reconnect, mDNS device discovery
Nexus SDK / API (Cloud Integration)
Powers Cross-Device Cloud connections.
- SDK (recommended): Java, Node.js, Python, PHP, Go, .NET
- API: RESTful, language-agnostic
- Capabilities: Payment requests, order dispatch, transaction queries, Webhook notifications
Security and Compliance
| Layer | Measures |
|---|---|
| General | Permission checks (authorized transaction types only), card number masking, PCI DSS compliant |
| Local connections | App ID + Client Secret auth, HMAC-SHA256 signing, TLS 1.2+ encryption (LAN) |
| Cloud connections | API Key auth, Webhook signature verification, HTTPS end-to-end |
| Certifications | PCI DSS Level 1, EMV chip card certified |