{"title":"Protect with a library","category":"default","creationDate":1776961627,"content":"<p>If your integration uses local communications, you need to protect your integration against <a href=\"https:\/\/en.wikipedia.org\/wiki\/Man-in-the-middle_attack\" target=\"_blank\" rel=\"nofollow noopener noreferrer\" class=\"external-link no-image\">man-in-the-middle attacks<\/a>, eavesdropping, and tampering. To help you with this, we provide GitHub libraries that:<\/p>\n<ul>\n<li>Validate the terminal certificate, to confirm your POS app is communicating directly with an Adyen-supplied payment terminal.<\/li>\n<li>Encrypt communications. This prevents intruders from reading the messages transmitted between the POS app and the terminal.<\/li>\n<\/ul>\n<div class=\"sc-notice warning\"><div>\n<p>These GitHub libraries work with Terminal API and are completely separate from the <a href=\"\/pt\/point-of-sale\/classic-library-deprecation\">classic libraries, which have been deprecated<\/a>.<\/p>\n<\/div><\/div>\n<h2>Encrypt communications<\/h2>\n<p>The available libraries are:<\/p>\n<ul>\n<li>.NET - <a href=\"https:\/\/github.com\/Adyen\/adyen-dotnet-api-library\" target=\"_blank\" rel=\"nofollow noopener noreferrer\" class=\"external-link no-image\">adyen-dotnet-api-library<\/a><\/li>\n<li>Terminal API for iOS - <a href=\"https:\/\/github.com\/Adyen\/adyen-terminal-api-ios\" target=\"_blank\" rel=\"nofollow noopener noreferrer\" class=\"external-link no-image\">adyen-terminal-api-ios<\/a><\/li>\n<li>Java - <a href=\"https:\/\/github.com\/Adyen\/adyen-java-api-library\" target=\"_blank\" rel=\"nofollow noopener noreferrer\" class=\"external-link no-image\">adyen-java-api-library<\/a><\/li>\n<li>Node - <a href=\"https:\/\/github.com\/Adyen\/adyen-node-api-library\" target=\"_blank\" rel=\"nofollow noopener noreferrer\" class=\"external-link no-image\">adyen-node-api-library<\/a><\/li>\n<\/ul>\n<p>The libraries will:<\/p>\n<ul>\n<li>Serialize the request object to JSON and then encrypt and sign the request.<\/li>\n<li>Send the request and receive the response.<\/li>\n<li>Decrypt and deserialize the response and pass the content to the response object.<\/li>\n<\/ul>\n<p>Select a tab below for the Adyen GitHub library you want to use.<\/p>\n\n<div id=\"tabHm0yA\">\n    <div data-component-wrapper=\"tabs\">\n        <tabs\n                        :items=\"[{&quot;title&quot;:&quot;.NET&quot;,&quot;content&quot;:&quot;\\n&lt;h3&gt;Preparation&lt;\\\/h3&gt;\\n&lt;p&gt;Make sure that you have:&lt;\\\/p&gt;\\n&lt;ul&gt;\\n&lt;li&gt;&lt;a href=\\&quot;https:\\\/\\\/github.com\\\/Adyen\\\/adyen-dotnet-api-library#installation\\&quot; target=\\&quot;_blank\\&quot; rel=\\&quot;nofollow noopener noreferrer\\&quot; class=\\&quot;external-link no-image\\&quot;&gt;Installed our .NET library in your project&lt;\\\/a&gt;.&lt;\\\/li&gt;\\n&lt;li&gt;&lt;a href=\\&quot;\\\/pt\\\/point-of-sale\\\/design-your-integration\\\/choose-your-architecture\\\/local#install-root-cert\\&quot;&gt;Installed Adyen&#039;s root certificate&lt;\\\/a&gt;.&lt;\\\/li&gt;\\n&lt;li&gt;&lt;a href=\\&quot;\\\/pt\\\/point-of-sale\\\/design-your-integration\\\/choose-your-architecture\\\/local#set-up-shared-key\\&quot;&gt;Set up a shared key&lt;\\\/a&gt;.&lt;\\\/li&gt;\\n&lt;\\\/ul&gt;\\n&lt;h3&gt;Encrypt communications using the .NET library&lt;\\\/h3&gt;\\n&lt;ol&gt;\\n&lt;li&gt;\\n&lt;p&gt;In your C# project, import the required types.&lt;\\\/p&gt;\\n&lt;pre&gt;&lt;code class=\\&quot;language-cs\\&quot;&gt;using Adyen;\\nusing Adyen.Security;&lt;\\\/code&gt;&lt;\\\/pre&gt;\\n&lt;\\\/li&gt;\\n&lt;li&gt;\\n&lt;p&gt;Create an &lt;code&gt;EncryptionCredentialDetails&lt;\\\/code&gt; object specifying the identifier, passphrase, and version of your shared key. (For instructions, see &lt;a href=\\&quot;\\\/pt\\\/point-of-sale\\\/design-your-integration\\\/choose-your-architecture\\\/local\\\/#set-up-shared-key\\&quot;&gt;Set up a shared key&lt;\\\/a&gt;.)&lt;\\\/p&gt;\\n&lt;pre&gt;&lt;code class=\\&quot;language-cs\\&quot;&gt;var encryptionCredentialDetails = new EncryptionCredentialDetails\\n{\\n    KeyVersion = 1,\\n    AdyenCryptoVersion = 1,\\n    KeyIdentifier = \\&quot;CryptoKeyIdentifier12345\\&quot;,\\n    Password = \\&quot;p@ssw0rd123456\\&quot;\\n};&lt;\\\/code&gt;&lt;\\\/pre&gt;\\n&lt;\\\/li&gt;\\n&lt;li&gt;\\n&lt;p&gt;Create a &lt;code&gt;Config&lt;\\\/code&gt; object specifying the IP address of the terminal (for example, &lt;code&gt;https:\\\/\\\/198.51.100.1:8443\\\/nexo&lt;\\\/code&gt;) and the environment: &lt;span translate=\\&quot;no\\&quot;&gt;&lt;strong&gt;Test&lt;\\\/strong&gt;&lt;\\\/span&gt; or &lt;span translate=\\&quot;no\\&quot;&gt;&lt;strong&gt;Live&lt;\\\/strong&gt;&lt;\\\/span&gt;.&lt;\\\/p&gt;\\n&lt;pre&gt;&lt;code class=\\&quot;language-cs\\&quot;&gt;var config = new Config\\n{\\n    Environment = Model.Environment.Test,\\n    LocalTerminalApiEndpoint = @\\&quot;https:\\\/\\\/_terminal_:8443\\\/nexo\\\/\\&quot; \\\/\\\/ _terminal_ example: `https:\\\/\\\/198.51.100.1:8443\\\/nexo` (see the Wi-Fi settings of your terminal)\\n};&lt;\\\/code&gt;&lt;\\\/pre&gt;\\n&lt;\\\/li&gt;\\n&lt;li&gt;\\n&lt;p&gt;Initialize a client using the config from the previous step.&lt;\\\/p&gt;\\n&lt;pre&gt;&lt;code class=\\&quot;language-cs\\&quot;&gt;var client = new Client(config);&lt;\\\/code&gt;&lt;\\\/pre&gt;\\n&lt;\\\/li&gt;\\n&lt;li&gt;\\n&lt;p&gt;Create the &lt;code&gt;TerminalApiLocalService&lt;\\\/code&gt; using the client from the previous step.&lt;\\\/p&gt;\\n&lt;pre&gt;&lt;code class=\\&quot;language-cs\\&quot;&gt;TerminalApiLocalService terminalApiLocalService = new TerminalApiLocalService(client);&lt;\\\/code&gt;&lt;\\\/pre&gt;\\n&lt;\\\/li&gt;\\n&lt;li&gt;\\n&lt;p&gt;Make an asynchronous or synchronous call to send a Terminal API request to the payment terminal using the &lt;code&gt;TerminalApiLocalService&lt;\\\/code&gt;.&lt;\\\/p&gt;\\n&lt;pre&gt;&lt;code class=\\&quot;language-cs\\&quot;&gt;\\\/\\\/ Asynchronous call (preferred)\\nvar saleToPOIResponse = await terminalApiLocalService.RequestEncryptedAsync(paymentRequest, encryptionCredentialDetails, new CancellationToken()); \\\/\\\/ Pass cancellation token or create a new one.\\n\\\/\\\/ Synchronous (blocking) call\\n\\\/\\\/var saleToPOIResponse = terminalApiLocalService.RequestEncrypted(paymentRequest, encryptionCredentialDetails);&lt;\\\/code&gt;&lt;\\\/pre&gt;\\n&lt;\\\/li&gt;\\n&lt;\\\/ol&gt;\\n&lt;p&gt;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.&lt;\\\/p&gt;\\n&quot;,&quot;altTitle&quot;:null,&quot;oldTabId&quot;:&quot;.net_0_1&quot;,&quot;relation&quot;:&quot;&quot;},{&quot;title&quot;:&quot;iOS&quot;,&quot;content&quot;:&quot;\\n&lt;p&gt;The Terminal API for iOS library supports deriving the encryption key and encrypting and decrypting communications.&lt;\\\/p&gt;\\n&lt;h3&gt;Preparation&lt;\\\/h3&gt;\\n&lt;p&gt;Make sure that you have:&lt;\\\/p&gt;\\n&lt;ul&gt;\\n&lt;li&gt;&lt;a href=\\&quot;https:\\\/\\\/github.com\\\/Adyen\\\/adyen-terminal-api-ios#install-terminalapikit\\&quot; target=\\&quot;_blank\\&quot; rel=\\&quot;nofollow noopener noreferrer\\&quot; class=\\&quot;external-link no-image\\&quot;&gt;Installed our iOS library&lt;\\\/a&gt; (&lt;em&gt;TerminalAPIKit&lt;\\\/em&gt;) in your project.&lt;\\\/li&gt;\\n&lt;li&gt;&lt;a href=\\&quot;\\\/pt\\\/point-of-sale\\\/design-your-integration\\\/choose-your-architecture\\\/local#install-root-cert\\&quot;&gt;Installed Adyen&#039;s root certificate&lt;\\\/a&gt;.&lt;\\\/li&gt;\\n&lt;li&gt;&lt;a href=\\&quot;\\\/pt\\\/point-of-sale\\\/design-your-integration\\\/choose-your-architecture\\\/local#set-up-shared-key\\&quot;&gt;Set up a shared key&lt;\\\/a&gt;.&lt;\\\/li&gt;\\n&lt;\\\/ul&gt;\\n&lt;h3&gt;Encrypt communications&lt;\\\/h3&gt;\\n&lt;ol&gt;\\n&lt;li&gt;\\n&lt;p&gt;Derive the key used for encrypting and decrypting local communications between the terminal and your POS app. Make sure to pass the &lt;code&gt;identifier&lt;\\\/code&gt;, &lt;code&gt;passphrase&lt;\\\/code&gt;, and &lt;code&gt;version&lt;\\\/code&gt; of your shared key in string form exactly as they appear in the Customer Area. (For instructions, see &lt;a href=\\&quot;\\\/pt\\\/point-of-sale\\\/design-your-integration\\\/choose-your-architecture\\\/local\\\/#set-up-shared-key\\&quot;&gt;Set up a shared key&lt;\\\/a&gt;.)&lt;\\\/p&gt;\\n&lt;pre&gt;&lt;code class=\\&quot;language-swift\\&quot;&gt;let encryptionKey = try EncryptionKey(\\n    identifier: \\&quot;KEY_IDENTIFIER\\&quot;,\\n    passphrase: \\&quot;KEY_PASSPHRASE\\&quot;,\\n    version: KEY_VERSION\\n)&lt;\\\/code&gt;&lt;\\\/pre&gt;\\n&lt;\\\/li&gt;\\n&lt;li&gt;\\n&lt;p&gt;&lt;a href=\\&quot;https:\\\/\\\/github.com\\\/Adyen\\\/adyen-terminal-api-ios#create-terminal-api-requests\\&quot; target=\\&quot;_blank\\&quot; rel=\\&quot;nofollow noopener noreferrer\\&quot; class=\\&quot;external-link no-image\\&quot;&gt;Create your request&lt;\\\/a&gt;. For example, create a &lt;code&gt;Message&amp;lt;PaymentRequest&amp;gt;&lt;\\\/code&gt;.&lt;\\\/p&gt;\\n&lt;\\\/li&gt;\\n&lt;li&gt;\\n&lt;p&gt;Encrypt your request.&lt;\\\/p&gt;\\n&lt;pre&gt;&lt;code class=\\&quot;language-swift\\&quot;&gt;let encryptionKey: EncryptionKey = \\\/\\\/ the key you derived earlier\\nlet request: Message&amp;lt;PaymentRequest&amp;gt; = \\\/\\\/ the payment request you created\\nlet encryptedMessage: Data = try request.encrypt(using: encryptionKey)&lt;\\\/code&gt;&lt;\\\/pre&gt;\\n&lt;\\\/li&gt;\\n&lt;li&gt;\\n&lt;p&gt;Send the &lt;code&gt;encryptedMessage&lt;\\\/code&gt; to the terminal.&lt;\\\/p&gt;\\n&lt;\\\/li&gt;\\n&lt;li&gt;\\n&lt;p&gt;When you receive the response from the terminal, decrypt the response.&lt;\\\/p&gt;\\n&lt;pre&gt;&lt;code class=\\&quot;language-swift\\&quot;&gt;let key: EncryptionKey = \\\/\\\/ the key you derived earlier\\nlet response: Data = \\\/\\\/ the response you receive from the terminal\\nlet encryptedMessage: EncryptedMessage = try Coder.decode(EncryptedMessage.self, from: response)\\nlet decryptedMessage: Message&amp;lt;PaymentResponse&amp;gt; = try decrypt(PaymentResponse.self, using: key)&lt;\\\/code&gt;&lt;\\\/pre&gt;\\n&lt;\\\/li&gt;\\n&lt;\\\/ol&gt;\\n&quot;,&quot;altTitle&quot;:null,&quot;oldTabId&quot;:&quot;ios_1_2&quot;,&quot;relation&quot;:&quot;&quot;},{&quot;title&quot;:&quot;Java&quot;,&quot;content&quot;:&quot;\\n&lt;h3&gt;Preparation&lt;\\\/h3&gt;\\n&lt;p&gt;Make sure that you have:&lt;\\\/p&gt;\\n&lt;ul&gt;\\n&lt;li&gt;&lt;a href=\\&quot;https:\\\/\\\/github.com\\\/Adyen\\\/adyen-java-api-library#installation\\&quot; target=\\&quot;_blank\\&quot; rel=\\&quot;nofollow noopener noreferrer\\&quot; class=\\&quot;external-link no-image\\&quot;&gt;Installed our Java library in your project&lt;\\\/a&gt;.&lt;\\\/li&gt;\\n&lt;li&gt;&lt;a href=\\&quot;\\\/pt\\\/point-of-sale\\\/design-your-integration\\\/choose-your-architecture\\\/local#install-root-cert\\&quot;&gt;Installed Adyen&#039;s root certificate&lt;\\\/a&gt;.&lt;\\\/li&gt;\\n&lt;li&gt;&lt;a href=\\&quot;\\\/pt\\\/point-of-sale\\\/design-your-integration\\\/choose-your-architecture\\\/local#set-up-shared-key\\&quot;&gt;Set up a shared key&lt;\\\/a&gt;.&lt;\\\/li&gt;\\n&lt;\\\/ul&gt;\\n&lt;h3&gt;Encrypt communications using the Java library&lt;\\\/h3&gt;\\n&lt;ol&gt;\\n&lt;li&gt;\\n&lt;p&gt;Import the required classes.&lt;\\\/p&gt;\\n&lt;pre&gt;&lt;code class=\\&quot;language-java\\&quot;&gt;import com.adyen.Client;\\nimport com.adyen.Config;\\nimport com.adyen.enums.Environment;\\nimport com.adyen.httpclient.TerminalLocalAPIHostnameVerifier;\\nimport com.adyen.service.TerminalLocalAPI;\\nimport com.adyen.model.terminal.security.*;\\nimport com.adyen.model.terminal.*;\\nimport javax.net.ssl.SSLContext;\\nimport javax.net.ssl.TrustManagerFactory;\\nimport java.security.KeyStore;\\nimport java.security.SecureRandom;&lt;\\\/code&gt;&lt;\\\/pre&gt;\\n&lt;\\\/li&gt;\\n&lt;li&gt;\\n&lt;p&gt;Create a keystore for the terminal certificate.&lt;\\\/p&gt;\\n&lt;pre&gt;&lt;code class=\\&quot;language-java\\&quot;&gt;KeyStore keyStore = KeyStore.getInstance(KeyStore.getDefaultType());\\nkeyStore.load(null, null);\\nkeyStore.setCertificateEntry(\\&quot;adyenRootCertificate\\&quot;, adyenRootCertificate);&lt;\\\/code&gt;&lt;\\\/pre&gt;\\n&lt;\\\/li&gt;\\n&lt;li&gt;\\n&lt;p&gt;Create a &lt;code&gt;TrustManagerFactory&lt;\\\/code&gt; that trusts the Certificate Authorities in the keystore.&lt;\\\/p&gt;\\n&lt;pre&gt;&lt;code class=\\&quot;language-java\\&quot;&gt;TrustManagerFactory trustManagerFactory = TrustManagerFactory.getInstance(TrustManagerFactory.getDefaultAlgorithm());\\ntrustManagerFactory.init(keyStore);&lt;\\\/code&gt;&lt;\\\/pre&gt;\\n&lt;\\\/li&gt;\\n&lt;li&gt;\\n&lt;p&gt;Create an &lt;code&gt;SSLContext&lt;\\\/code&gt; with the desired protocol that uses our TrustManagers.&lt;\\\/p&gt;\\n&lt;pre&gt;&lt;code class=\\&quot;language-java\\&quot;&gt;SSLContext sslContext = SSLContext.getInstance(\\&quot;SSL\\&quot;);\\nsslContext.init(null, trustManagerFactory.getTrustManagers(), new SecureRandom());&lt;\\\/code&gt;&lt;\\\/pre&gt;\\n&lt;\\\/li&gt;\\n&lt;li&gt;\\n&lt;p&gt;Configure a client for the &lt;code&gt;TerminalLocalAPI&lt;\\\/code&gt; service, specifying the IP address of the terminal (for example, &lt;code&gt;https:\\\/\\\/198.51.100.1&lt;\\\/code&gt;).&lt;\\\/p&gt;\\n&lt;pre&gt;&lt;code class=\\&quot;language-java\\&quot;&gt;Config config = new Config();\\nconfig.setEnvironment(environment);\\nconfig.setTerminalApiLocalEndpoint(\\&quot;https:\\\/\\\/\\&quot; + terminalIpAddress);\\nconfig.setSSLContext(sslContext);\\nconfig.setHostnameVerifier(new TerminalLocalAPIHostnameVerifier(environment));\\nClient client = new Client(config);&lt;\\\/code&gt;&lt;\\\/pre&gt;\\n&lt;\\\/li&gt;\\n&lt;li&gt;\\n&lt;p&gt;Create a &lt;code&gt;SecurityKey&lt;\\\/code&gt; object specifying the identifier, passphrase, and version of your shared key. (For instructions, see &lt;a href=\\&quot;\\\/pt\\\/point-of-sale\\\/design-your-integration\\\/choose-your-architecture\\\/local\\\/#set-up-shared-key\\&quot;&gt;Set up a shared key&lt;\\\/a&gt;.) This object is used to encrypt the payload.&lt;\\\/p&gt;\\n&lt;pre&gt;&lt;code class=\\&quot;language-java\\&quot;&gt;SecurityKey securityKey = new SecurityKey();\\nsecurityKey.setKeyVersion(1);\\nsecurityKey.setAdyenCryptoVersion(1);\\nsecurityKey.setKeyIdentifier(\\&quot;keyIdentifier\\&quot;);\\nsecurityKey.setPassphrase(\\&quot;passphrase\\&quot;);&lt;\\\/code&gt;&lt;\\\/pre&gt;\\n&lt;\\\/li&gt;\\n&lt;li&gt;\\n&lt;p&gt;Send a Terminal API request to the payment terminal using the &lt;code&gt;TerminalLocalAPI&lt;\\\/code&gt; service.&lt;\\\/p&gt;\\n&lt;pre&gt;&lt;code class=\\&quot;language-java\\&quot;&gt;TerminalLocalAPI terminalLocalAPI = new TerminalLocalAPI(client, securityKey);\\nTerminalAPIResponse terminalAPIResponse = terminalLocalAPI.request(terminalAPIRequest);&lt;\\\/code&gt;&lt;\\\/pre&gt;\\n&lt;\\\/li&gt;\\n&lt;\\\/ol&gt;\\n&lt;p&gt;The library also contains information about how to use &lt;a href=\\&quot;https:\\\/\\\/github.com\\\/Adyen\\\/adyen-java-api-library?tab=readme-ov-file#using-the-local-terminal-api-integration-without-encryption-only-on-test\\&quot; target=\\&quot;_blank\\&quot; rel=\\&quot;nofollow noopener noreferrer\\&quot; class=\\&quot;external-link no-image\\&quot;&gt;local communications without encryption&lt;\\\/a&gt;. However, that is only allowed on test while working in parallel on implementing encryption.&lt;\\\/p&gt;\\n&quot;,&quot;altTitle&quot;:null,&quot;oldTabId&quot;:&quot;java_2_3&quot;,&quot;relation&quot;:&quot;&quot;},{&quot;title&quot;:&quot;Node&quot;,&quot;content&quot;:&quot;\\n&lt;h3&gt;Preparation&lt;\\\/h3&gt;\\n&lt;p&gt;Make sure that you have:&lt;\\\/p&gt;\\n&lt;ul&gt;\\n&lt;li&gt;&lt;a href=\\&quot;https:\\\/\\\/github.com\\\/Adyen\\\/adyen-node-api-library#installation\\&quot; target=\\&quot;_blank\\&quot; rel=\\&quot;nofollow noopener noreferrer\\&quot; class=\\&quot;external-link no-image\\&quot;&gt;Installed our Node library in your project&lt;\\\/a&gt;.&lt;\\\/li&gt;\\n&lt;li&gt;&lt;a href=\\&quot;\\\/pt\\\/point-of-sale\\\/design-your-integration\\\/choose-your-architecture\\\/local#install-root-cert\\&quot;&gt;Installed Adyen&#039;s root certificate&lt;\\\/a&gt;.&lt;\\\/li&gt;\\n&lt;li&gt;&lt;a href=\\&quot;\\\/pt\\\/point-of-sale\\\/design-your-integration\\\/choose-your-architecture\\\/local#set-up-shared-key\\&quot;&gt;Set up a shared key&lt;\\\/a&gt;.&lt;\\\/li&gt;\\n&lt;\\\/ul&gt;\\n&lt;h3&gt;Encrypt communications using the Node library&lt;\\\/h3&gt;\\n&lt;ol&gt;\\n&lt;li&gt;\\n&lt;p&gt;In your Node project, require the parts of the module you want to use.&lt;\\\/p&gt;\\n&lt;pre&gt;&lt;code class=\\&quot;language-js\\&quot;&gt;const {Client, TerminalLocalAPI} from \\&quot;@adyen\\\/api-library\\&quot;;&lt;\\\/code&gt;&lt;\\\/pre&gt;\\n&lt;\\\/li&gt;\\n&lt;li&gt;\\n&lt;p&gt;Create a &lt;code&gt;Config&lt;\\\/code&gt; object with your path to the Adyen root certificate and the IP address of the terminal (for example, &lt;code&gt;https:\\\/\\\/198.51.100.1:8443\\\/nexo&lt;\\\/code&gt;), and install and save the certificate in your project folder as &lt;code&gt;cert.cer&lt;\\\/code&gt;.&lt;\\\/p&gt;\\n&lt;pre&gt;&lt;code class=\\&quot;language-js\\&quot;&gt;const config: Config = new Config();\\nconfig.certificatePath = \\&quot;.\\\/cert.cer\\&quot;;\\nconfig.terminalApiLocalEndpoint = \\&quot;The IP of your terminal (for example https:\\\/\\\/198.51.100.1:8443\\\/nexo)\\&quot;;\\nconfig.apiKey = \\&quot;YOUR_ADYEN_API_KEY\\&quot;;&lt;\\\/code&gt;&lt;\\\/pre&gt;\\n&lt;\\\/li&gt;\\n&lt;li&gt;\\n&lt;p&gt;Create a &lt;code&gt;SecurityKey&lt;\\\/code&gt; object specifying the identifier, passphrase, and version of your shared key. (For instructions, see &lt;a href=\\&quot;\\\/pt\\\/point-of-sale\\\/design-your-integration\\\/choose-your-architecture\\\/local\\\/#set-up-shared-key\\&quot;&gt;Set up a shared key&lt;\\\/a&gt;.)&lt;\\\/p&gt;\\n&lt;pre&gt;&lt;code class=\\&quot;language-js\\&quot;&gt;const securityKey: SecurityKey = {\\n    AdyenCryptoVersion: 1,\\n    KeyIdentifier: \\&quot;keyIdentifier\\&quot;,\\n    KeyVersion: 1,\\n    Passphrase: \\&quot;passphrase\\&quot;,\\n};&lt;\\\/code&gt;&lt;\\\/pre&gt;\\n&lt;\\\/li&gt;\\n&lt;li&gt;\\n&lt;p&gt;Initialize the client and the API objects using the config, and create the &lt;code&gt;TerminalLocalAPI&lt;\\\/code&gt; service.&lt;\\\/p&gt;\\n&lt;pre&gt;&lt;code class=\\&quot;language-js\\&quot;&gt;client = new Client({ config });\\nconst terminalLocalAPI = new TerminalLocalAPI(client);&lt;\\\/code&gt;&lt;\\\/pre&gt;\\n&lt;\\\/li&gt;\\n&lt;li&gt;\\n&lt;p&gt;Create the request object.&lt;\\\/p&gt;\\n&lt;pre&gt;&lt;code class=\\&quot;language-js\\&quot;&gt;const paymentRequest: SaleToPOIRequest = {\\n\\\/\\\/ The Terminal API `MessageHeader` and `PaymentRequest`\\n}&lt;\\\/code&gt;&lt;\\\/pre&gt;\\n&lt;\\\/li&gt;\\n&lt;li&gt;\\n&lt;p&gt;Send the Terminal API request to the payment terminal using the &lt;code&gt;TerminalLocalAPI&lt;\\\/code&gt; service.&lt;\\\/p&gt;\\n&lt;pre&gt;&lt;code class=\\&quot;language-js\\&quot;&gt;const terminalApiResponse: terminal.TerminalApiResponse = await terminalLocalAPI.request(paymentRequest, securityKey);&lt;\\\/code&gt;&lt;\\\/pre&gt;\\n&lt;\\\/li&gt;\\n&lt;\\\/ol&gt;\\n&lt;p&gt;The library also contains information about how to use &lt;a href=\\&quot;https:\\\/\\\/github.com\\\/Adyen\\\/adyen-node-api-library?tab=readme-ov-file#using-the-local-terminal-api-integration-without-encryption-only-on-test\\&quot; target=\\&quot;_blank\\&quot; rel=\\&quot;nofollow noopener noreferrer\\&quot; class=\\&quot;external-link no-image\\&quot;&gt;local communications without encryption&lt;\\\/a&gt;. However, that is only allowed on test while working in parallel on implementing encryption.&lt;\\\/p&gt;\\n&quot;,&quot;altTitle&quot;:null,&quot;oldTabId&quot;:&quot;node_3_4&quot;,&quot;relation&quot;:&quot;&quot;}]\"\n            :should-update-when-url-changes='false'>\n        <\/tabs>\n    <\/div>\n<\/div>\n\n<h2>Full code samples<\/h2>\n<p>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.<\/p>\n<p>To find the details of your shared key in your <a href=\"https:\/\/ca-test.adyen.com\/\" target=\"_blank\" rel=\"nofollow noopener noreferrer\" class=\"external-link no-image\">Customer Area<\/a>:<\/p>\n<ol>\n<li>Under <strong>In-person payments<\/strong>, go to the <strong>Terminal settings<\/strong> for your merchant account or store.<\/li>\n<li>Select <strong>Integrations<\/strong> and under <strong>Terminal API<\/strong> go to <strong>Encryption key<\/strong>. <\/li>\n<li>To see the key identifier, passphrase, and version values, select <strong>Decrypted<\/strong>.<\/li>\n<\/ol>\n<div data-component-wrapper=\"code-sample\">\n    <code-sample :title=\"'Encryption using a library'\" :id=\"'encryption-using-libs'\" :code-data='[{\"language\":\"java\",\"tabTitle\":\"Java\",\"content\":\"\\\/\\\/ Import the required classes\\nimport com.adyen.Client;\\nimport com.adyen.Config;\\nimport com.adyen.enums.Environment;\\nimport com.adyen.httpclient.TerminalLocalAPIHostnameVerifier;\\nimport com.adyen.service.TerminalLocalAPI;\\nimport com.adyen.model.terminal.security.*;\\nimport com.adyen.model.terminal.*;\\nimport javax.net.ssl.SSLContext;\\nimport javax.net.ssl.TrustManagerFactory;\\nimport java.security.KeyStore;\\nimport java.security.SecureRandom;\\n\\n\\\/\\\/ Create a keystore for the terminal certificate\\nKeyStore keyStore = KeyStore.getInstance(KeyStore.getDefaultType());\\nkeyStore.load(null, null);\\nkeyStore.setCertificateEntry(\\\"adyenRootCertificate\\\", adyenRootCertificate);\\n\\n\\\/\\\/ Create a TrustManagerFactory that trusts the Certificate Authorities in the keystore\\nTrustManagerFactory trustManagerFactory = TrustManagerFactory.getInstance(TrustManagerFactory.getDefaultAlgorithm());\\ntrustManagerFactory.init(keyStore);\\n\\n\\\/\\\/ Create an SSLContext with the desired protocol that uses our TrustManagers\\nSSLContext sslContext = SSLContext.getInstance(\\\"SSL\\\");\\nsslContext.init(null, trustManagerFactory.getTrustManagers(), new SecureRandom());\\n\\n\\\/\\\/ Configure a client for the TerminalLocalAPI service\\n\\\/\\\/ specifying the IP address of the terminal, for example https:\\\/\\\/198.51.100.1:8443\\\/nexo\\nConfig config = new Config();\\nconfig.setEnvironment(environment);\\nconfig.setTerminalApiLocalEndpoint(\\\"https:\\\/\\\/\\\" + terminalIpAddress);\\nconfig.setSSLContext(sslContext);\\nconfig.setHostnameVerifier(new TerminalLocalAPIHostnameVerifier(environment));\\nClient client = new Client(config);\\n\\n\\\/\\\/ Create a SecurityKey object specifying the identifier, passphrase, and version of your shared key\\nSecurityKey securityKey = new SecurityKey();\\nsecurityKey.setKeyVersion(1);\\nsecurityKey.setAdyenCryptoVersion(1);\\nsecurityKey.setKeyIdentifier(\\\"keyIdentifier\\\");\\nsecurityKey.setPassphrase(\\\"passphrase\\\");\\n\\n\\\/\\\/ Send a Terminal API request to the payment terminal using the TerminalLocalAPI service\\nTerminalLocalAPI terminalLocalAPI = new TerminalLocalAPI(client, securityKey);\\nTerminalAPIResponse terminalAPIResponse = terminalLocalAPI.request(terminalAPIRequest);\"},{\"language\":\"cs\",\"tabTitle\":\"C#\",\"content\":\"\\\/\\\/ In your C# project, import the required types\\nusing Adyen;\\nusing Adyen.Security;\\n\\n\\\/\\\/ Create an EncryptionCredentialDetails object specifying the identifier, passphrase, and version of your shared key\\nvar encryptionCredentialDetails = new EncryptionCredentialDetails\\n{\\n    KeyVersion = 1,\\n    AdyenCryptoVersion = 1,\\n    KeyIdentifier = \\\"CryptoKeyIdentifier12345\\\",\\n    Password = \\\"p@ssw0rd123456\\\"\\n};\\n\\n\\\/\\\/ Create a Config object with the IP address of the terminal (for example, https:\\\/\\\/198.51.100.1:8443\\\/nexo)\\n\\\/\\\/ and the environment: Test or Live\\nvar config = new Config\\n{\\n    Environment = Model.Environment.Test,\\n    LocalTerminalApiEndpoint = @\\\"https:\\\/\\\/_terminal_:8443\\\/nexo\\\/\\\" \\\/\\\/ _terminal_ example: `https:\\\/\\\/198.51.100.1:8443\\\/nexo` (can be found in the WIFI settings of your terminal)\\n};\\n\\\/\\\/ Initialize a client using the config\\nvar client = new Client(config);\\n\\n\\\/\\\/ Create the TerminalApiLocalService using the client\\nTerminalApiLocalService terminalApiLocalService = new TerminalApiLocalService(client);\\n\\n\\\/\\\/ Make an asynchronous or synchronous call to send a Terminal API request to the payment terminal\\n\\\/\\\/ Asynchronous call (preferred)\\nvar saleToPOIResponse = await terminalApiLocalService.RequestEncryptedAsync(paymentRequest, encryptionCredentialDetails, new CancellationToken()); \\\/\\\/ Pass cancellation token or create a new one.\\n\\\/\\\/ Synchronous (blocking) call\\n\\\/\\\/var saleToPOIResponse = terminalApiLocalService.RequestEncrypted(paymentRequest, encryptionCredentialDetails);\"},{\"language\":\"js\",\"tabTitle\":\"NodeJS (JavaScript)\",\"content\":\"\\\/\\\/ In your Node project, require the parts of the module you want to use\\nconst {Client, TerminalLocalAPI} from \\\"@adyen\\\/api-library\\\";\\n\\n\\\/\\\/ Create a Config object with your path to the Adyen root certificate and the IP address of the terminal\\n\\\/\\\/ (for example, `https:\\\/\\\/198.51.100.1:8443\\\/nexo`), and install and save the certificate in your project folder as `cert.cer`.\\nconst config: Config = new Config();\\nconfig.certificatePath = \\\".\\\/cert.cer\\\";\\nconfig.terminalApiLocalEndpoint = \\\"The IP of your terminal (eg https:\\\/\\\/192.168.47.169)\\\";\\nconfig.apiKey = \\\"YOUR_API_KEY_HERE\\\";\\n\\n\\\/\\\/ Create a SecurityKey object specifying the identifier, passphrase, and version of your shared key\\nconst securityKey: SecurityKey = {\\n    AdyenCryptoVersion: 1,\\n    KeyIdentifier: \\\"keyIdentifier\\\",\\n    KeyVersion: 1,\\n    Passphrase: \\\"passphrase\\\",\\n};\\n\\n\\\/\\\/ Initialize the client and the API objects\\nclient = new Client({ config });\\nconst terminalLocalAPI = new TerminalLocalAPI(client);\\n\\n\\\/\\\/ Create the request object\\nconst paymentRequest: SaleToPOIRequest = {\\n\\\/\\\/ The Terminal API `MessageHeader` and `PaymentRequest`\\n}\\n\\n\\\/\\\/ Send the Terminal API request to the payment terminal\\nconst terminalApiResponse: terminal.TerminalApiResponse = await terminalLocalAPI.request(paymentRequest, securityKey);\"},{\"language\":\"swift\",\"tabTitle\":\"Swift\",\"content\":\"\\\/\\\/ Derive a key, passing the identifier, passphrase, and version of your shared key in string form\\nlet encryptionKey = try EncryptionKey(\\n        identifier: \\\"KEY_IDENTIFIER\\\",\\n        passphrase: \\\"KEY_PASSPHRASE\\\",\\n        version: KEY_VERSION\\n    )\\n\\\/\\\/ Create your Terminal API request, for example a `Message&lt;PaymentRequest&gt;`\\n\\n\\\/\\\/ Encrypt the request\\nlet encryptionKey: EncryptionKey = \\\/\\\/ the key you derived earlier\\n    let request: Message&lt;PaymentRequest&gt; = \\\/\\\/ the payment request you created\\n    let encryptedMessage: Data = try request.encrypt(using: encryptionKey)\\n\\n\\\/\\\/ Send the encryptedMessage to the terminal\\n\\n\\\/\\\/ When you receive the response from the terminal, decrypt the response\\nlet key: EncryptionKey = \\\/\\\/ the key you derived earlier\\n    let response: Data = \\\/\\\/ the response you receive from the terminal\\n    let encryptedMessage: EncryptedMessage = try Coder.decode(EncryptedMessage.self, from: response)\\n    let decryptedMessage: Message&lt;PaymentResponse&gt; = try decrypt(PaymentResponse.self, using: key)\"}]' :enable-copy-link-to-code-block=\"true\" :code-sample-card-size=\"'fullsize'\"><\/code-sample>\n<\/div>\n<h2>Troubleshooting<\/h2>\n<p><a href=\"#crypto-errors\">Crypto errors<\/a> and <a href=\"#ssl-connection-error\">SSL connection errors<\/a> indicate a problem with the protection of the local communications.<\/p>\n<h3>Crypto errors<\/h3>\n<p><strong>Example<\/strong>:<\/p>\n<pre><code class=\"language-bash\">Exception: System.Net.WebException: The remote server returned an error: (401) Unauthorized.<\/code><\/pre>\n<p>The response body contains:<\/p>\n<pre><code class=\"language-json\">{\n   \"errors\":[\n      \"Nexo Service: crypto error\"\n   ],\n   \"ServiceID\":\"1234567890\"\n}<\/code><\/pre>\n<p><strong>Cause<\/strong>: Crypto errors are related to the shared key. After you <a href=\"\/pt\/point-of-sale\/design-your-integration\/choose-your-architecture\/local#set-up-shared-key\">set up the shared key in your Customer Area<\/a>, the shared key values in your code must match the shared key values in the Customer Area.<\/p>\n<p>If you are using a library, check the values for the relevant object:<\/p>\n<ul>\n<li>With the <a href=\"\/pt\/point-of-sale\/design-your-integration\/choose-your-architecture\/local\/protect-with-library?tab=_net_1\">.NET library<\/a>, check the <code>EncryptionCredentialDetails<\/code> object.<\/li>\n<li>With the <a href=\"\/pt\/point-of-sale\/design-your-integration\/choose-your-architecture\/local\/protect-with-library?tab=java_2\">Java library<\/a>, check the<code>SecurityKey<\/code> object.<\/li>\n<li>With the <a href=\"\/pt\/point-of-sale\/design-your-integration\/choose-your-architecture\/local\/protect-with-library?tab=node_3\">Node library<\/a>, check the <code>SecurityKey<\/code> object.<\/li>\n<\/ul>\n<p><\/p>\n<p>If you are using your own code:<\/p>\n<ul>\n<li>Check the <a href=\"\/pt\/point-of-sale\/design-your-integration\/choose-your-architecture\/local\/protect#derive-key-material\">key derivation function<\/a>. This uses the passphrase of the shared key.<\/li>\n<li>Check the <a href=\"\/pt\/point-of-sale\/design-your-integration\/choose-your-architecture\/local\/protect#create-the-security-trailer\">security trailer function<\/a>. This uses the version and the identifier of the shared key.<\/li>\n<\/ul>\n<h3>SSL connection error<\/h3>\n<p><strong>Example<\/strong>:<\/p>\n<pre><code class=\"language-bash\">Exception : System.Net.WebException: The SSL connection could not be established<\/code><\/pre>\n<p><strong>Possible cause<\/strong>: Adyen's root certificate is not installed correctly.<\/p>\n<h2>See also<\/h2>\n<div class=\"see-also-links output-inline\" id=\"see-also\">\n<ul><li><a href=\"\/point-of-sale\/design-your-integration\/choose-your-architecture\/local\"\n                        target=\"_self\"\n                        >\n                    Building a local integration\n                <\/a><\/li><li><a href=\"\/point-of-sale\/design-your-integration\/choose-your-architecture\/local\/protect\"\n                        target=\"_self\"\n                        >\n                    Set up protection of local communications yourself\n                <\/a><\/li><\/ul><\/div>\n","url":"https:\/\/docs.adyen.com\/pt\/point-of-sale\/design-your-integration\/choose-your-architecture\/local\/protect-with-library","articleFields":{"description":"Use an Adyen GitHub library to protect local communications between your POS app and terminal.","feedback_component":true,"type":"page","_expandable":{"operations":""},"last_edit_on":"17-06-2021 09:45","page_id":"78b75ad0-396b-488a-90e6-df582a6f8a7d","filters_component":false,"decision_tree":"[]"},"algolia":{"url":"https:\/\/docs.adyen.com\/pt\/point-of-sale\/design-your-integration\/choose-your-architecture\/local\/protect-with-library","title":"Protect with a library","content":"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:\n\nValidate the terminal certificate, to confirm your POS app is communicating directly with an Adyen-supplied payment terminal.\nEncrypt communications. This prevents intruders from reading the messages transmitted between the POS app and the terminal.\n\n\nThese GitHub libraries work with Terminal API and are completely separate from the classic libraries, which have been deprecated.\n\nEncrypt communications\nThe available libraries are:\n\n.NET - adyen-dotnet-api-library\nTerminal API for iOS - adyen-terminal-api-ios\nJava - adyen-java-api-library\nNode - adyen-node-api-library\n\nThe libraries will:\n\nSerialize the request object to JSON and then encrypt and sign the request.\nSend the request and receive the response.\nDecrypt and deserialize the response and pass the content to the response object.\n\nSelect a tab below for the Adyen GitHub library you want to use.\n\n\n    \n        \n        \n    \n\n\nFull code samples\nSelect 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.\nTo find the details of your shared key in your Customer Area:\n\nUnder In-person payments, go to the Terminal settings for your merchant account or store.\nSelect Integrations and under Terminal API go to Encryption key. \nTo see the key identifier, passphrase, and version values, select Decrypted.\n\n\n    \n\nTroubleshooting\nCrypto errors and SSL connection errors indicate a problem with the protection of the local communications.\nCrypto errors\nExample:\nException: System.Net.WebException: The remote server returned an error: (401) Unauthorized.\nThe response body contains:\n{\n   \"errors\":[\n      \"Nexo Service: crypto error\"\n   ],\n   \"ServiceID\":\"1234567890\"\n}\nCause: 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.\nIf you are using a library, check the values for the relevant object:\n\nWith the .NET library, check the EncryptionCredentialDetails object.\nWith the Java library, check theSecurityKey object.\nWith the Node library, check the SecurityKey object.\n\n\nIf you are using your own code:\n\nCheck the key derivation function. This uses the passphrase of the shared key.\nCheck the security trailer function. This uses the version and the identifier of the shared key.\n\nSSL connection error\nExample:\nException : System.Net.WebException: The SSL connection could not be established\nPossible cause: Adyen's root certificate is not installed correctly.\nSee also\n\n\n                    Building a local integration\n                \n                    Set up protection of local communications yourself\n                \n","type":"page","locale":"pt","boost":15,"hierarchy":{"lvl0":"Home","lvl1":"Terminais","lvl2":"Design your integration","lvl3":"Escolha uma arquitetura de integra\u00e7\u00e3o para seus terminais","lvl4":"Construindo uma integra\u00e7\u00e3o local","lvl5":"Protect with a library"},"hierarchy_url":{"lvl0":"https:\/\/docs.adyen.com\/pt","lvl1":"https:\/\/docs.adyen.com\/pt\/point-of-sale","lvl2":"https:\/\/docs.adyen.com\/pt\/point-of-sale\/design-your-integration","lvl3":"https:\/\/docs.adyen.com\/pt\/point-of-sale\/design-your-integration\/choose-your-architecture","lvl4":"https:\/\/docs.adyen.com\/pt\/point-of-sale\/design-your-integration\/choose-your-architecture\/local","lvl5":"\/pt\/point-of-sale\/design-your-integration\/choose-your-architecture\/local\/protect-with-library"},"levels":6,"category":"In-person payments","category_color":"green","tags":["Protect","library"]},"articleFiles":{"encryption-using-libs.js":"<p alt=\"\">encryption-using-libs.js<\/p>"}}