Aller au contenu principal

Local Interface

Local Till Interface: By using the local till interface you connect directly with a socket to the terminal device. The benefit is that you have a fast connection as both your application and the terminal device are in the same local network. The drawback is that you need to know the terminal's IP address. The Local Till Interface documentation changes depending on the application version installed on the terminal device.

1. Prerequisites​

  • A registered terminal (TID assigned, PayDroid OS and Wallee App up to date).
  • Local Till API feature enabled in the terminal configuration.
  • POS device must be on the same local network as the terminal.
  • Ensure firewall allows LAN traffic between POS and terminal.

2. Discovering the Terminal​

There are two common ways to connect:

  1. mDNS / Bonjour discovery – POS automatically finds available terminals on the LAN.
  2. Static IP assignment – Terminal is configured with a fixed IP address, and the POS connects directly.

Example discovery response:

{
  "terminalId": "32518857",
  "ip": "192.168.1.45",
  "port": 8080
}

3. Starting a Transaction​

Once the terminal is reachable, send a POST request to its local API:

POST http://192.168.1.45:8080/transactions/start
Content-Type: application/json

Example request body:

{
  "amount": {
    "currency": "CHF",
    "value": "23.60"
  },
  "transactionType": "PURCHASE",
  "reference": "ORDER-12345"
}

Response:

{
  "transactionId": "abc123",
  "status": "PENDING"
}

4. Receiving Status Updates​

The terminal can notify the POS of status changes via WebSocket callback or by polling the API.

Example status event:

{
  "transactionId": "abc123",
  "status": "APPROVED",
  "amount": {
    "currency": "CHF",
    "value": "23.60"
  },
  "reference": "ORDER-12345",
  "timestamp": "2025-09-25T10:24:00Z"
}

5. Testing the Integration​

  1. Connect POS and terminal to the same LAN.
  2. Trigger a small test transaction.
  3. Verify the terminal prompts the customer.
  4. Check that the POS receives the status update and final transaction result.