Protect with a library

Use an Adyen GitHub library to protect local communications between your POS app and terminal.

If your integration uses local communications, you need to protect your integration against man-in-the-middle attacks, eavesdropping, and tampering. To help you with this, we provide GitHub libraries that:

Validate the terminal certificate, to confirm your POS app is communicating directly with an Adyen-supplied payment terminal.
Encrypt communications. This prevents intruders from reading the messages transmitted between the POS app and the terminal.

These GitHub libraries work with Terminal API and are completely separate from the classic libraries, which have been deprecated.

Encrypt communications

The available libraries are:

.NET - adyen-dotnet-api-library
Terminal API for iOS - adyen-terminal-api-ios
Java - adyen-java-api-library
Node - adyen-node-api-library

The libraries will:

Serialize the request object to JSON and then encrypt and sign the request.
Send the request and receive the response.
Decrypt and deserialize the response and pass the content to the response object.

Select a tab below for the Adyen GitHub library you want to use.

Preparation

Make sure that you have:

Encrypt communications using the .NET library

In your C# project, import the required types.


Copy code
using Adyen;
using Adyen.Security;

Create an EncryptionCredentialDetails object specifying the identifier, passphrase, and version of your shared key. (For instructions, see Set up a shared key.)


Copy code
var encryptionCredentialDetails = new EncryptionCredentialDetails
{
    KeyVersion = 1,
    AdyenCryptoVersion = 1,
    KeyIdentifier = "CryptoKeyIdentifier12345",
    Password = "p@ssw0rd123456"
};

Create a Config object specifying the IP address of the terminal (for example, https://198.51.100.1:8443/nexo) and the environment: Test or Live.


Copy code
var config = new Config
{
    Environment = Model.Environment.Test,
    LocalTerminalApiEndpoint = @"https://_terminal_:8443/nexo/" // _terminal_ example: `https://198.51.100.1:8443/nexo` (see the Wi-Fi settings of your terminal)
};

Initialize a client using the config from the previous step.


Copy code
var client = new Client(config);

Create the TerminalApiLocalService using the client from the previous step.


Copy code
TerminalApiLocalService terminalApiLocalService = new TerminalApiLocalService(client);

Make an asynchronous or synchronous call to send a Terminal API request to the payment terminal using the TerminalApiLocalService.


Copy code
// Asynchronous call (preferred)
var saleToPOIResponse = await terminalApiLocalService.RequestEncryptedAsync(paymentRequest, encryptionCredentialDetails, new CancellationToken()); // Pass cancellation token or create a new one.
// Synchronous (blocking) call
//var saleToPOIResponse = terminalApiLocalService.RequestEncrypted(paymentRequest, encryptionCredentialDetails);

The library also contains information about how to use local communications without encryption. However, that is only allowed on test while working in parallel on implementing encryption.

Full code samples

Select a tab in the code sample block below to see the code for encrypting communications. In all cases you need to know the key identifier, passphrase, and version of your shared key.

To find the details of your shared key in your Customer Area:

Under In-person payments, go to the Terminal settings for your merchant account or store.
Select Integrations and under Terminal API go to Encryption key.
To see the key identifier, passphrase, and version values, select Decrypted.

Encryption using a library

 // Import the required classes
import com.adyen.Client;
import com.adyen.Config;
import com.adyen.enums.Environment;
import com.adyen.httpclient.TerminalLocalAPIHostnameVerifier;
import com.adyen.service.TerminalLocalAPI;
import com.adyen.model.terminal.security.*;
import com.adyen.model.terminal.*;
import javax.net.ssl.SSLContext;
import javax.net.ssl.TrustManagerFactory;
import java.security.KeyStore;
import java.security.SecureRandom;
 
// Create a keystore for the terminal certificate
KeyStore keyStore = KeyStore.getInstance(KeyStore.getDefaultType());
keyStore.load(null, null);
keyStore.setCertificateEntry("adyenRootCertificate", adyenRootCertificate);
 
// Create a TrustManagerFactory that trusts the Certificate Authorities in the keystore
TrustManagerFactory trustManagerFactory = TrustManagerFactory.getInstance(TrustManagerFactory.getDefaultAlgorithm());
trustManagerFactory.init(keyStore);
 
// Create an SSLContext with the desired protocol that uses our TrustManagers
SSLContext sslContext = SSLContext.getInstance("SSL");
sslContext.init(null, trustManagerFactory.getTrustManagers(), new SecureRandom());
 
// Configure a client for the TerminalLocalAPI service
// specifying the IP address of the terminal, for example https://198.51.100.1:8443/nexo
Config config = new Config();
config.setEnvironment(environment);
config.setTerminalApiLocalEndpoint("https://" + terminalIpAddress);
config.setSSLContext(sslContext);
config.setHostnameVerifier(new TerminalLocalAPIHostnameVerifier(environment));
Client client = new Client(config);
 
// Create a SecurityKey object specifying the identifier, passphrase, and version of your shared key
SecurityKey securityKey = new SecurityKey();
securityKey.setKeyVersion(1);
securityKey.setAdyenCryptoVersion(1);
securityKey.setKeyIdentifier("keyIdentifier");
securityKey.setPassphrase("passphrase");
 
// Send a Terminal API request to the payment terminal using the TerminalLocalAPI service
TerminalLocalAPI terminalLocalAPI = new TerminalLocalAPI(client, securityKey);
TerminalAPIResponse terminalAPIResponse = terminalLocalAPI.request(terminalAPIRequest);

Troubleshooting

Crypto errors and SSL connection errors indicate a problem with the protection of the local communications.

Crypto errors

Example:


Copy code
Exception: System.Net.WebException: The remote server returned an error: (401) Unauthorized.

The response body contains:


Copy code
{
   "errors":[
      "Nexo Service: crypto error (9)"
   ],
   "ServiceID":"1234567890"
}

Cause: Crypto errors are related to the shared key. After you set up the shared key in your Customer Area, the shared key values in your code must match the shared key values in the Customer Area.

If you are using a library, check the values for the relevant object:

With the .NET library, check the EncryptionCredentialDetails object.
With the Java library, check theSecurityKey object.
With the Node library, check the SecurityKey object.

If you are using your own code:

Check the key derivation function. This uses the passphrase of the shared key.
Check the security trailer function. This uses the version and the identifier of the shared key.

Crypto error	Cause
crypto error (1)	There is a problem with parsing the request. This can be due to a syntax error.
crypto error (2)	The version number of the shared key in your code is unknown.
crypto error (3)	There is a problem with the message header of the request.
crypto error (4)	There is a problem with the body of the request.
crypto error (5)	There is a problem with the security trailer of the encrypted message. The trailer uses the version and identifier of the shared key.
crypto error (6)	There is a problem with the passphrase of the shared key.
crypto error (7)	The nonce is missing or incorrect. The nonce must have a length of 16 bytes.
crypto error (8)	The HMAC key is missing or incorrect. The HMAC key must have a length of 32 bytes.
crypto error (9)	The shared key details in your code do not match the shared key that is set up in your Customer Area.

SSL connection error