Switch JSON parsing to Gson for improved reliability

CHANGELOG.md

@@ -1,3 +1,13 @@
+### v4.4.0 (2026-02-24)
+* * *
+
+### Improvements:
+* Replaced the internal regex-based JSON parser with [Google Gson](https://github.com/google/gson) for reliable, spec-compliant JSON handling.
+* Added comprehensive test coverage for the internal `JsonUtil` utility.
+
+### Dependencies:
+* Added `com.google.code.gson:gson:2.13.2` as a compile dependency (transitive for SDK consumers). Minimum compatible Gson version is `2.8.6`. See [README](README.md#dependencies) for version conflict guidance.
+
 ### v4.3.0 (2026-02-20)
 * * *
 

README.md

@@ -64,6 +64,42 @@ dependencies {
 </dependency>
 ```
 
+### Dependencies
+
+The Chargebee Java SDK uses [Gson](https://github.com/google/gson) `2.13.2` for JSON processing. Gson is declared as a regular dependency of the SDK and is therefore included transitively when the SDK is added to a project.
+
+#### Gson version conflicts
+
+Projects that already depend on a different version of Gson may encounter version conflicts. The build tool resolves a single version based on its dependency resolution strategy, which can lead to mismatches.
+
+**Gradle** selects the highest version by default. If the project uses an older Gson version, Gradle will resolve to the highest version (`2.13.2`) by default. To pin a specific version:
+
+```kotlin
+configurations.all {
+    resolutionStrategy {
+        force("com.google.code.gson:gson:2.13.2")
+    }
+}
+```
+
+**Maven** uses the nearest-wins strategy, meaning a direct dependency declared in the project takes precedence over the SDK's transitive dependency. If an older version is declared directly, it will override the SDK's version. To align versions, either upgrade the direct dependency or use `<dependencyManagement>`:
+
+```xml
+<dependencyManagement>
+    <dependencies>
+        <dependency>
+            <groupId>com.google.code.gson</groupId>
+            <artifactId>gson</artifactId>
+            <version>2.13.2</version>
+        </dependency>
+    </dependencies>
+</dependencyManagement>
+```
+
+**Minimum compatible Gson version**: `2.8.6`. The SDK relies on `JsonParser.parseString()`, which was introduced in Gson 2.8.6. Versions older than 2.8.6 will cause a `NoSuchMethodError` at runtime.
+
+**Recommended**: Gson `2.10.1` or later is recommended for best compatibility. Projects unable to upgrade should verify that the resolved Gson version is at least `2.8.6`.
+
 ### Install JAR files
 ***
 

VERSION

@@ -1 +1 @@
-4.3.0
+4.4.0

build.gradle.kts

@@ -7,7 +7,7 @@ plugins {
 }
 
 group = "com.chargebee"
-version = "4.3.0"
+version = "4.4.0"
 description = "Java client library for ChargeBee"
 
 // Project metadata
@@ -42,6 +42,7 @@ repositories {
 }
 
 dependencies {
+    implementation("com.google.code.gson:gson:2.13.2")
     testImplementation("org.junit.jupiter:junit-jupiter:5.13.0")
     testRuntimeOnly("org.junit.platform:junit-platform-launcher")
     testImplementation("org.mockito:mockito-core:4.11.0")

src/main/java/com/chargebee/v4/exceptions/APIException.java

@@ -9,6 +9,8 @@
 import com.chargebee.v4.internal.JsonUtil;
 import com.chargebee.v4.transport.Request;
 import com.chargebee.v4.transport.Response;
+import com.google.gson.JsonArray;
+import com.google.gson.JsonObject;
 
 import java.util.ArrayList;
 import java.util.List;
@@ -229,11 +231,12 @@ public String getJsonResponse() {
   private List<String> extractParams(String jsonResponse) {
     List<String> paramsList = new ArrayList<>();
     if (jsonResponse != null) {
-      String param = JsonUtil.getString(jsonResponse, "param");
+      JsonObject obj = JsonUtil.parse(jsonResponse);
+      String param = JsonUtil.getString(obj, "param");
       if (param != null) {
         paramsList.add(param);
       } else {
-        String paramArray = JsonUtil.getArray(jsonResponse, "param");
+        JsonArray paramArray = JsonUtil.getJsonArray(obj, "param");
         if (paramArray != null) {
           paramsList.addAll(JsonUtil.parseArrayOfString(paramArray));
         }
@@ -245,7 +248,8 @@ private List<String> extractParams(String jsonResponse) {
   /** Extract error_cause_id from error response. */
   private String extractErrorCauseId(String jsonResponse) {
     if (jsonResponse != null) {
-      return JsonUtil.getString(jsonResponse, "error_cause_id");
+      JsonObject obj = JsonUtil.parse(jsonResponse);
+      return JsonUtil.getString(obj, "error_cause_id");
     }
     return null;
   }