Address PR feedback

Author: gcatanese

doc/CloudDeviceApi.md

@@ -20,7 +20,7 @@ New features and products will be released exclusively on the Cloud device API
 
 ### Setup
 
-First you must initialise the Client **setting the closest** [Region](https://docs.adyen.com/point-of-sale/design-your-integration/terminal-api/#cloud):
+First you must initialise the Client (see an example on TEST):
 ``` java
 // Import the required classes
 import com.adyen.Client;
@@ -32,12 +32,30 @@ import java.math.BigDecimal;
 import java.time.OffsetDateTime;
 import java.time.ZoneOffset;
 
-// Setup Client and Service
-Client client = new Client("YOUR_API_KEY", Environment.TEST);
+// Setup Client on TEST
+Client client = new Client(new Config().apiKey("test").environment(Environment.TEST));
+
 CloudDeviceApi cloudDeviceApi = new CloudDeviceApi(client);
 
 ```
+On LIVE environment you must **set the closest** [Region](https://docs.adyen.com/point-of-sale/design-your-integration/terminal-api/#cloud)
+``` java
+// Import the required classes
+import com.adyen.Client;
+import com.adyen.enums.Environment;
+import com.adyen.service.clouddevice.CloudDeviceApi;
+import com.adyen.model.clouddevice.*;
+import com.adyen.model.tapi.*;
+import java.math.BigDecimal;
+import java.time.OffsetDateTime;
+import java.time.ZoneOffset;
+
+// Setup Client on LIVE (Region is required)
+Client client = new Client(new Config().apiKey("test").environment(Environment.LIVE).terminalApiRegion(Region.US));
 
+CloudDeviceApi cloudDeviceApi = new CloudDeviceApi(client);
+
+```
 ### Send a payment SYNC request
 
 ```java
@@ -115,10 +133,12 @@ The Cloud device API allows your integration to check the status of the terminal
 // list of payment terminals or SDK mobile installation IDs
 ConnectedDevicesResponse connectedDevices = cloudDeviceApi.getConnectedDevices("myMerchant");
 System.out.println(connectedDevices.getUniqueDeviceIds());
+// [P400Plus-123456789, AMS1-000168242800763]
 
 // check the payment terminal or SDK mobile installation ID 
 DeviceStatusResponse deviceStatus = cloudDeviceApi.getDeviceStatus("myMerchant", "AMS1-000168242800763");
 System.out.println(deviceStatus.getStatus());
+// ONLINE
 ```
 ### Helper classes
 
@@ -148,9 +168,9 @@ The Adyen Java library supports encrypting request and response payloads, allowi
 //  Encryption credentials from the Terminal configuration on CA
 EncryptionCredentialDetails encryptionCredentialDetails =
     new EncryptionCredentialDetails()
-        .adyenCryptoVersion(0)
+        .adyenCryptoVersion(1)
         .keyIdentifier("CryptoKeyIdentifier12345")
-        .keyVersion(0)
+        .keyVersion(1)
         .passphrase("p@ssw0rd123456");
 
 // Use EncryptedCloudDeviceApi instead of CloudDeviceApi

doc/MigratingToCloudDeviceApi.md

@@ -8,12 +8,6 @@ The Terminal (Cloud) API (`TerminalCloudAPI`) was built manually with hand-craft
 
 Because the Cloud device API models are generated from the spec rather than hand-crafted, there are differences in class names, enum naming conventions, field types, and accessor methods. This guide describes these differences and what to be aware of when adopting the Cloud device API.
 
-### Who should migrate?
-
-- **New integrations**: use the Cloud device API from the start. See the [Cloud device API documentation](CloudDeviceApi.md).
-- **Updating your cloud integration**: you should consider migrating to the Cloud device API to benefit from the improvements listed below.
-- **Not making changes**: you can continue using the Terminal (Cloud) API. It remains functional, but you will miss out on the benefits of the Cloud device API.
-
 ## Benefits of the Cloud device API
 
 The Cloud device API introduces several improvements over the Terminal (Cloud) API:
@@ -23,6 +17,13 @@ The Cloud device API introduces several improvements over the Terminal (Cloud) A
 - **Improved security**: supports OAuth authentication alongside API key authentication.
 - **Device management endpoints**: query connected devices and check their status directly from your integration.
 - **New features**: future In-Person Payments features and products will be released exclusively on the Cloud device API.
+
+### Who should migrate?
+
+- **New integrations**: use the Cloud device API from the start. See the [Cloud device API documentation](CloudDeviceApi.md).
+- **Updating your cloud integration**: you should consider migrating to the Cloud device API to benefit from the improvements listed below.
+- **Not making changes**: you can continue using the Terminal (Cloud) API. It remains functional, but you will miss out on the benefits of the Cloud device API.
+
 - **Generated from the OpenAPI specification**: unlike the hand-crafted Terminal (Cloud) API models, the Cloud device API is auto-generated from the [Adyen OpenAPI spec](https://github.com/Adyen/adyen-openapi). This brings consistency with every other service in the library (Checkout, Management, Transfers, etc.), ensures the models stay in sync with the API, and provides built-in `fromJson()`/`toJson()` serialization, fluent setters, and Jackson support out of the box.
 
 ## Key differences
@@ -128,6 +129,9 @@ Some field types differ in the generated models.
 
 The most common change. The Cloud device API models use `java.time.OffsetDateTime` for timestamp fields, whereas the Terminal (Cloud) API models use `XMLGregorianCalendar`.
 
+The key difference is how each type handles timezone information. `XMLGregorianCalendar` allows an undefined timezone: when constructed from `new GregorianCalendar()` without an explicit timezone, it inherits the JVM default. 
+This means the same wall-clock time (e.g. 14:30:00) could be serialized as `14:30:00+01:00` on a server in Amsterdam or `14:30:00-05:00` on one in New York — two different points in time. `OffsetDateTime` always carries an explicit offset, so `OffsetDateTime.now(ZoneOffset.UTC)` always serializes as `2025-01-15T14:30:00Z`, unambiguously.
+
 **Terminal (Cloud) API:**
 ```java
 import javax.xml.datatype.XMLGregorianCalendar;
@@ -149,6 +153,10 @@ transactionIDType.setTimeStamp(OffsetDateTime.now(ZoneOffset.UTC));
 
 Some date fields (e.g. `Instalment.firstPaymentDate`) use `java.time.LocalDate` in the Cloud device API instead of `String`.
 
+`LocalDate` has no timezone or offset information — it represents a calendar date only (year, month, day). When the library serializes a `LocalDate`, it uses the date as-is without any timezone conversion. 
+This means the date sent to the API is whatever date your system clock shows in its local timezone. If your server runs in a timezone that is behind UTC and the transaction happens near midnight UTC, the local date may be one day behind. 
+**Ensure the system timezone is set correctly and consistently across all environments where the SDK runs.**
+
 **Terminal (Cloud) API:**
 ```java
 instalment.setFirstPaymentDate("2025-01-15");

doc/TerminalApi.md

@@ -13,9 +13,9 @@ import javax.xml.datatype.DatatypeFactory;
 import javax.xml.datatype.XMLGregorianCalendar;
 
 // Step 2: Initialize the client object
-Client client = new Client("YOUR_API_KEY", Environment.TEST);
+Client client = new Client(new Config().apiKey("test").environment(Environment.TEST));
 
-// for LIVE environment use
+// for LIVE environment set the region
 // Config config = new Config();
 // config.setEnvironment(Environment.LIVE);
 // config.setTerminalApiRegion(Region.EU);