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 |
| Two devices, cloud POS or multi-store management | Cross-Device | Cloud |
| Tapro runs on the CPad Pay Sub-Screen edition | 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 equipped with the CPad Pay Sub-Screen edition use Sub-Screen.
On-Device
This is the App-to-App mode shown in the architecture diagram. 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
This covers the LAN / Cable / Cloud modes shown in the architecture diagram. 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 |
| Cloud | Merchant backend dispatches orders to the terminal via Nexus API | Cloud POS / SaaS / multi-store management |
LAN and Cable 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 | Direct Android ↔ Android device connection |
| USB-VSP | CDC-ACM virtual serial port | Windows ↔ Android |
| RS232 | Standard serial | Traditional POS ↔ terminal |
The integration must explicitly select the cable protocol that matches the terminal configuration in ConnectionConfig: CableProtocol.USB_VSP, CableProtocol.RS232, or CableProtocol.USB_AOA.
Cable mode is now available. You can connect to Tapro over USB VSP, RS232, or USB AOA using the Taplink SDK.
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
Sub-Screen mode is available only when Tapro runs on the CPad Pay Sub-Screen edition. It displays the amount and payment status on the customer-facing screen, which is physically attached to the terminal, so no connection method configuration is needed.
Sub-Screen mode is not supported on other Tapro devices or editions.
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), 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 |