Search

Are you looking for test card numbers?

Would you like to contact support?

Point-of-sale icon

Protect with a library

Use an Adyen GitHub library to protect local communications between your cash register 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 cash register is communicating directly with an Adyen-supplied payment terminal.
  • Encrypt communications. This prevents intruders from reading the messages transmitted between the cash register and terminal.

The available libraries are:

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

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

Before you begin

Use the .NET library

  1. In your C# project, create a Config object specifying:

    • The URL of the terminal.
    • The environment: Test or Live.
    • Your merchant account.
    Config config = new Config
        {
            Endpoint = "https://TerminalApiEndpoint:8443/nexo/",
            Environment = Model.Enum.Environment.Test,
            MerchantAccount = "YOUR_MERCHANT_ACCOUNT"
        };
  2. Create a Client object using the Config object created in the previous step.

    Client client = new Client(config);
  3. Create the PosPaymentLocalApi service using the client created in the previous step.

    Service.PosPaymentLocalApi posPaymentLocalApi = new Service.PosPaymentLocalApi(client);
  4. 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
        };
  5. When you send a Terminal API request to the payment terminal, use the PosPaymentLocalApi service specifying a SaleToPOIRequest object and the EncryptionCredentialDetails object.

    SaleToPOIResponse response = posPaymentLocalApi.TerminalApiLocal(saleToPOIRequest, encryptionCredentialDetails);

Before you begin

Use the Java library

  1. In your Java project, create a Config object, specifying:

    • Your merchant account.
    • The path to Adyen's root certificate.
    • The URL of the terminal without the :8443/nexo part.
    Config config = new Config();
    config.setMerchantAccount("Your merchant account");
    config.setTerminalCertificate("Local path to the Adyen root certificate");
    config.setTerminalApiLocalEndpoint("URL of the terminal, for example https://192.168.68.117, WITHOUT the port/nexo part :8443/nexo/");
  2. Create a Client object using the Config object created in the previous step, and setting the environment to TEST or LIVE.

    Client terminalLocalAPIClient = new Client(config);
    terminalLocalAPIClient.setEnvironment(Environment.TEST, null);
  3. Create the TerminalLocalAPI service using the client created in the previous step.

    TerminalLocalAPI terminalLocalAPI = new TerminalLocalAPI(terminalLocalAPIClient);
  4. Create a SecurityKey object specifying the identifier, passphrase, and version of your shared key.

    SecurityKey securityKey = new SecurityKey();
    securityKey.setAdyenCryptoVersion(1);
    securityKey.setKeyIdentifier(“Key identifier");
    securityKey.setPassphrase(“Key passphrase”);
    securityKey.setKeyVersion(1);
  5. When you send a Terminal API request to the payment terminal, use the TerminalLocalAPI service specifying a TerminalApiRequest object and the SecurityKey object.

    TerminalAPIResponse terminalAPIResponse = terminalLocalAPI.request(terminalApiRequest, securityKey);

Before you begin

Use the Node library

  1. In your Node project, create a Config object, specifying:

    • Your merchant account.
    • The path to Adyen's root certificate.
    • The URL of the terminal without the :8443/nexo part.
    const config: Config = new Config();
    config.merchantAccount = "Your merchant account";
    config.certificatePath = "Local path to the Adyen root certificate";
    config.terminalApiLocalEndpoint = "URL of the terminal, for example https://192.168.68.117, WITHOUT the port/nexo part :8443/nexo/";
  2. Create a Client object using the config object created in the previous step, and setting the environment to TEST or LIVE.

    const client = new Client({ config });
    client.setEnvironment("TEST");
  3. Create the TerminalLocalAPI service using the client created in the previous step.

    const terminalLocalAPI = new TerminalLocalAPI(client);
  4. Create a SecurityKey object specifying the identifier, passphrase, and version of your shared key.

    const securityKey: SecurityKey = {
        adyenCryptoVersion: 1,
        keyIdentifier:“Key identifier",
        keyVersion: 1,
        passphrase: “Key passphrase",
    };
  5. When you send a Terminal API request to the payment terminal, use the TerminalLocalAPI service specifying a TerminalApiRequest object and the SecurityKey object.

    const terminalApiResponse: TerminalApiResponse =
     await terminalLocalAPI.request(terminalAPIPaymentRequest, securityKey);

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

The following error types indicate a problem with the protection of the local communications.

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.

Crypto error

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"
}

Possible cause: The shared key details in your code don't match the shared key that is set up in your Customer Area.

See also