Local communication to the terminal

Local communication involves the POS communicating with the terminal over a local network.


The local Terminal API architecture allows the terminal and POS to communicate over a local network., no library required. Details of the payment are then communicated to the Adyen payments platform over the internet.

Requirements

  • MAC encryption.
  • A web server for event and display notifications (optional).

Endpoint and network

Endpoints take the following format:

Example endpoint name
https://_terminal_:8443/nexo/

In the above URL,  _terminal_  is the IP or resolvable name of the terminal.

The terminal receives nexo messages on port 8443 (https). 

Architecture diagram

Encryption

The nexo specification includes limited MAC encryption primitive definitions. The standard also defines the encryption type, but only for specific fields. Use transport-independent security that covers the complete message and includes both encryption and authentication. Terminal API security is based on on some well-defined primitives.

Shared Keys

Our encryption implementation uses a shared key. The key material is derived using HKDF from, for example, a passphrase that is shared between parties. This shared secret can be of any desired quality or length. 

Replay attack

This implementation uses a fixed shared key between parties. This is a potential vector for replay attacks. The Nexo protocol states that a ServiceID cannot be re-used within a timeframe of 24 hours. Together with a timestamp check, the replay attack is prevented on application level.

Encryption algorithms

For encryption we use AES256 in cbc mode with default padding.

  • Alorithm in OpenSSL: EVP_aes_256_cbc
  • Algorithm in Java: AES/CBC/PKCS5Padding using a 256 bit key.

For HMAC we use HMAC_SHA256.

Message format

For more information on how to form Terminal API messages, see Structuring and validating Terminal API messages.

Next steps

Derive an encryption key

Derive an encryption key to secure communication between devices using the Terminal API.

link

Encrypt and decrypt messages

Configure encryption in the Terminal API to protect messages communicated between the terminal and the cash register.

link