The Adyen Terminal API is based on the nexo Retail Protocol. nexo uses JSON messages to communicate to and from the terminal. Messages are in JSON format and are formed as outlined in the nexo standard. Review our guidelines on how to form and validate these messages.
We offer two types of architecture to integrate your cash register with our terminals:
- Local communication to the terminal - Directly with the terminal over the local network.
- Cloud-based communication to the terminal - Through our Terminal Gateway Platform at www.adyen.com.
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.
For local communications you will need:
- MAC encryption.
- A web server for event and display notifications (optional).
Endpoints for local communications use the format:
- https://[TERMINAL]:8443/nexo/ on port 8443 (https).
Replace [TERMINAL] with the IP or resolvable hostname of the terminal.
Validation and 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.
For more information on setting up encryption, see Secure local communications.
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.
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.
For encryption we use AES256 in cbc mode with default padding.
- Algorithm in OpenSSL: EVP_aes_256_cbc
- Algorithm in Java: AES/CBC/PKCS5Padding using a 256 bit key.
For HMAC we use HMAC_SHA256.
The cloud Terminal API architecture allows the terminal and POS to communicate over the internet, no library required. It provides endpoints to initiate payments on your payment terminals through our platform. Adyen manages the connection between the platform and the terminal. The request is forwarded to the correct terminal based on the POIID (unique terminal ID) in the request message.
For Cloud-based communications you will need:
- Basic HTTP authentication.
- A web server for event and display notifications.
Synchronous communication requires a HTTPS client with an extended time-out of more than 2 minutes. During this time the connection is kept alive and a synchronous response will follow.
Set up a Sale System HTTPS server to receive display and event notifications.
Endpoints for synchronous cloud-based communication are:
- Test payments: https://terminal-api-test.adyen.com/sync
- Live payments: https://terminal-api-live.adyen.com/sync
If during the transaction the communication has been broken for any reason, the transaction status can be retrieved by checking the status of the transaction.
Asynchronous communication with the Terminal Cloud API requires a HTTPS Server to receive event notifications. The request is automatically accepted and forwarded to the POI. The result of the Terminal request is then relayed to the notification server that is configured with the Sale System. Display notifications are also sent to this server.
Endpoints for asynchronous cloud-based communication are:
- Test payments: https://terminal-api-test.adyen.com/async
- Live payments: https://terminal-api-live.adyen.com/async
Payment notifications from the Asynchronous Terminal Cloud API are not guaranteed to be sent. Set up regular notifications to guarantee delivery of payment information notifications. For more information, see Notifications.
Alternatively, query the transaction status when you receive no response. The terminal must be connected to the Adyen payments platform to successfully query the transaction status. For more information, see Recover a payment.