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.
The available libraries are:
- .NET - adyen-dotnet-api-library
- iOS - adyen-terminal-api-ios
- Java - adyen-java-api-library
- Node - adyen-node-api-library
These GitHub libraries work with Terminal API and are completely separate from the classic libraries, which have been deprecated.
Select a tab below for the Adyen GitHub library you want to use.
Requirements
- Make sure that you have:
Use the .NET library
-
In your C# project, create a
Config
object specifying:- The URL of the terminal.
- The environment:
Test
orLive
.
Config config = new Config { Environment = Model.Environment.Test, LocalTerminalApiEndpoint = @"https://_terminal_:8443/nexo/" }; -
Create a
Client
object using theConfig
object created in the previous step.Client client = new Client(config);
-
Create the TerminalLocalApi service using the client created in the previous step.
Service.TerminalLocalApi posPaymentLocalApi = new Service.TerminalLocalApi(client);
-
Create an
EncryptionCredentialDetails
object specifying the identifier, passphrase, and version of your shared key.EncryptionCredentialDetails encryptionCredentialDetails = new EncryptionCredentialDetails { AdyenCryptoVersion = 1, KeyIdentifier = "KEY_IDENTIFIER", Password = "KEY_PASSPHRASE", KeyVersion = 1 }; -
When you send a Terminal API request to the payment terminal, use the
TerminalLocalApi
service specifying aSaleToPOIRequest
object and theEncryptionCredentialDetails
object.SaleToPOIResponse response = posPaymentLocalApi.TerminalRequest(saleToPOIRequest, encryptionCredentialDetails);
The library 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.
Troubleshooting
Crypto errors and SSL connection errors indicate a problem with the protection of the local communications.
Crypto errors
Example:
Exception: System.Net.WebException: The remote server returned an error: (401) Unauthorized.
The response body contains:
{ "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 the
SecurityKey
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
Example:
Exception : System.Net.WebException: The SSL connection could not be established
Possible cause: Adyen's root certificate is not installed correctly.