Choose your integration
Before you build a point-of-sale (POS) integration, choose the method your POS uses to reach the payment terminal (our POI). We offer three primary methods, and the right one is decided almost entirely by where your POS software runs. This page helps you pick, then points you to the next step.
How to choose
Answer one question — where does your POS software run relative to the terminal?
| Where your POS software runs | Use |
|---|---|
| On a till, PC, or kiosk on the same local network as the terminal | Local API |
| On the payment terminal itself, as an Android app | App-to-App |
| In the cloud or off-site, reaching terminals over the internet | Cloud API |
Tip
Not sure, and running on a local till or kiosk? Start with Local API over HTTP — it is the simplest to build and the most widely supported. Move to TCP/IP only if you need a persistent, low-latency socket.
If you are integrating a market-specific protocol — Concert (France), Protocollo 17 (Italy), LTI, or MDB (unattended) — see Market-specific protocols. These run on the terminal as adapters onto the same engines described here, and are documented separately.
Compare the methods
The rows below are the differences that actually affect the decision. Local API and App-to-App share the same Nexo Retailer (Sale-to-POI v3.1) message model, so concepts transfer between them; Cloud API uses a different REST model.
| Local API | Cloud API | App-to-App | |
|---|---|---|---|
| Where your POS runs | On the local network | Anywhere, over the internet | On the terminal (Android) |
| Connects via | Terminal IP (HTTP or TCP/IP) | Market Pay Gateway | On-device (Android Intent) |
| Network required | Local network | Internet | None — same device |
| Security model | Local network scope | TLS, certificates, webhooks | Android app trust |
| Works offline | Yes | No | Yes |
| Session (Login / Logout) | Yes | No | Yes |
| Message model | Nexo Retailer v3.1 | REST (non-Nexo) | Nexo Retailer v3.1 |
| Best for | Fixed lanes, maximum reliability | Cloud POS, centrally managed estates | Android POS on the POI |
Local API
Your POS communicates directly with the terminal over your local network. To take a payment, you send an API request straight to the terminal's IP address, and the shopper completes the transaction on the device.
Choose Local API if your POS runs on a till, PC, or kiosk on the same network as the terminal, you want the simplest reliable setup, or you need the store to keep taking payments with no internet.
HTTP or TCP/IP?
Local API offers the same operations over two transports. Pick one per integration:
| HTTP | TCP/IP (socket) | |
|---|---|---|
| Message shape | Flat JSON |
SaleToPOIRequest envelope |
| Result delivery |
POST, then GET-poll (202 → 200) |
Streamed on the open socket |
| Framing | Standard HTTP | 4-byte big-endian length prefix |
| Default port | 8080 |
|
| Choose it when | You want the simplest, most portable build | You need a persistent, low-latency connection |
Cloud API
Your POS communicates with the terminal over the internet using our Cloud API. To take a payment, you send a request to the Market Pay Gateway, which forwards it to the terminal for the shopper to complete.
Choose Cloud API if your POS runs in the cloud or off-site, you manage terminals centrally across many sites, or you prefer REST/JSON over the internet. Be ready to manage TLS certificates and a notification webhook, and note there is no in-store offline mode.
App-to-App
Your POS Android app talks directly to the payment application installed on the same terminal. Your app launches the payment app with the transaction details; the shopper completes the payment there, and the result is relayed back to your app. See App-to-App integration.
Choose App-to-App if your POS is an Android app running on the payment terminal itself — it is the fastest and most secure option, needs no network, and works offline.
Market-specific protocols
Beyond the three primary methods, Market Pay terminals interoperate with several market-specific protocols that Market Pay does not own. Each runs on the terminal as a thin adapter that maps onto the Nexo Retailer engine used by Local API and App-to-App, so the transaction behaviour is the same — only the external message format differs.
| Protocol | Market / use |
|---|---|
| Concert (Protocole Caisse) | France |
| Protocollo 17 (ECR17) | Italy |
| LTI | Wallee |
| MDB | Unattended / vending |
See the Market-specific protocols section for configuration and links to each external specification.
Next steps
Once you have chosen a method:
- Set up connectivity — Configure your network and Connect your terminal to POS.
- Follow the getting-started guide for your method: the Local API quickstart, the Cloud API section, or the App-to-App section.
- Certify your integration with the POS Test Suite before go-live.