Adyen API Bug: String Response Instead Of JSON Object

Introduction

In this article, we will discuss a peculiar bug encountered while using the Adyen API in the test environment. Specifically, the issue revolves around the /abort API, which, instead of returning the expected JSON object, returns a string. This unexpected behavior leads to a JsonSyntaxException and disrupts the normal workflow of payment cancellation. We'll delve into the details of the problem, the steps to reproduce it, the actual and expected behaviors, and provide a code snippet to illustrate the implementation. This issue highlights the importance of robust testing environments and the challenges developers face when integrating with third-party APIs.

Description of the Issue

When attempting to cancel an ongoing payment using the Adyen /abort API within the test environment, a critical error arises. The API unexpectedly returns a string instead of the anticipated JSON object. This discrepancy causes a breakdown in the JSON conversion process, which is handled by the com.adyen:adyen-java-api-library:29.0.0 SDK. It is important to note that this issue is exclusively observed in the test environment and has not been replicated in the production environment. The problem surfaced around November 19th and has since been 100% reproducible, indicating a consistent and underlying cause. Furthermore, investigations into the balance-platform logs have not yielded any relevant information pertaining to the abort operation, adding to the complexity of the debugging process. Understanding the nuances of this issue is crucial for developers working with the Adyen API, as it directly impacts the reliability and stability of payment processing workflows. A string response where a JSON object is expected throws a wrench in the integration, underscoring the need for careful monitoring and error handling in test environments.

Steps to Reproduce

To effectively address the bug, it's crucial to understand the precise steps required to reproduce it. Here’s a breakdown of the process:

1. Initiate a Payment: The first step involves calling the /payments API to create and initiate a payment transaction. This simulates a user attempting to make a purchase or complete a payment process.
2. Trigger Abort API: Before the payment transaction reaches its final completion status, invoke the /abort API to cancel the ongoing payment. This action mimics a scenario where a user or the system decides to halt the transaction midway.

By following these two steps, developers can consistently replicate the issue in the test environment, making it easier to diagnose and resolve the root cause of the problem. The ability to reproduce a bug reliably is paramount for effective debugging and ensures that the fix addresses the core issue rather than just masking symptoms. This systematic approach to reproduction aids in isolating the problem and verifying the effectiveness of any proposed solutions. Ensuring these steps are accurately followed is crucial for a comprehensive understanding and resolution of the Adyen API bug.

Actual Behavior

The actual behavior observed when the bug is triggered is quite specific and indicative of a data type mismatch. The system throws a JsonSyntaxException, which is a clear signal that there's an issue with how JSON data is being parsed. The exception message, java.lang.IllegalStateException: Expected BEGIN_OBJECT but was STRING at line 1 column 2 path $, provides further insight. It indicates that the JSON parser was expecting to find the beginning of a JSON object (BEGIN_OBJECT), typically denoted by an opening curly brace {, but instead encountered a string. This means that the Adyen API is returning a plain string when a JSON object is expected, leading to a parsing failure. The exception also points to the Troubleshooting.md document in the google/gson library, suggesting that the unexpected JSON structure is the root cause of the problem. This behavior is critical to understand as it highlights a discrepancy between the expected data format and the actual data format returned by the API. Recognizing this discrepancy is the first step in identifying the source of the bug and implementing a suitable fix. The fact that a string is returned instead of a JSON object disrupts the expected data flow and causes the integration to fail, emphasizing the need for consistent data formats in API interactions.

Expected Behavior

The expected behavior of the Adyen /abort API is straightforward and aligns with standard API conventions. Upon a successful cancellation request, the API should return an HTTP status code of 200 OK, indicating that the request was successfully processed. Along with the status code, the API is expected to provide a response payload in JSON format. This JSON payload would typically contain details about the cancellation, such as a status code, a descriptive message, and potentially other relevant information regarding the aborted transaction. Adhering to this expected behavior ensures that the client application can correctly interpret the response and take appropriate actions, such as updating the user interface or logging the event. The consistency of returning a 200 status with a JSON payload is crucial for reliable API interactions. Any deviation from this standard, such as returning a string instead of a JSON object, disrupts the expected workflow and can lead to errors in the client application. Therefore, the adherence to the expected behavior is essential for the smooth and predictable operation of the payment cancellation process. Returning the correct status code and a well-structured JSON response is not just a matter of best practice but a necessity for robust API integration.

Code Snippet

To better illustrate the context in which the bug occurs, let's examine a Kotlin code snippet that demonstrates the implementation of the abort payment functionality:

private suspend fun abortPayment(payment: OrderingPayment): Either<OrderingError, Unit> = Either.catch {
    val abortServiceId = RandomStringUtils.randomAlphanumeric(10)
    withTags(payment.logTags()) {
        LOG.debug { "Aborting transaction, saleId=${payment.saleId}, abortServiceId=${abortServiceId}, paymentServiceId=${payment.serviceId}, category=${payment.category}" }
    }
    val abortRequest = TerminalAPIRequestBuilder(payment.saleId, abortServiceId, payment.terminalPoiId).withAbortRequest(
        AbortRequest().apply {
            abortReason = "MerchantAbort"
            messageReference = MessageReference().apply {
                messageCategory = payment.messageCategory
                saleID = payment.saleId
                serviceID = payment.serviceId
                poiid = payment.terminalPoiId
            }
        }
    ).build()
    withContext(Dispatchers.IO) { api.sync(abortRequest) }
    Unit.right()
}.getOrElse { e ->
    withTags(payment.logTags()) {
        LOG.exception(e) { "Error while aborting payment for order: ${payment.idempotencyUuid}" }
    }
    OrderingError.RemoteError(e).left()
}

This code snippet shows the abortPayment function, which takes an OrderingPayment object as input and attempts to abort the payment transaction. The function constructs an AbortRequest using the TerminalAPIRequestBuilder and sends it to the Adyen API via the api.sync(abortRequest) call. The Either.catch block is used for error handling, allowing the function to return either a Unit.right() on success or an OrderingError.RemoteError(e).left() on failure. The logging statements provide valuable context for debugging, including the saleId, abortServiceId, paymentServiceId, and category of the payment. The messageReference within the AbortRequest includes details about the original payment message, such as the messageCategory, saleID, serviceID, and poiid. This code illustrates the typical flow of aborting a payment using the Adyen API and highlights the point at which the JsonSyntaxException might occur if the API returns a string instead of a JSON object. Examining the request building and the API call within this snippet helps pinpoint potential areas for investigation and resolution of the bug. The use of coroutines (withContext(Dispatchers.IO)) indicates that the API call is being made asynchronously, which is a common practice in modern application development. This code snippet serves as a practical example of how the Adyen API is used in a real-world scenario and underscores the importance of handling API responses correctly.

Adyen Java API Library Version

The specific version of the Adyen Java API Library being used in this project is 29.0.0. This information is crucial because it helps narrow down the scope of the issue. Knowing the exact version allows developers to consult the library's release notes and changelogs to see if there are any known bugs or breaking changes that might be related to the problem. Additionally, it helps in determining if the issue has been addressed in later versions of the library. When reporting bugs or seeking support, providing the library version is a standard practice, as it ensures that the support team or other developers have the necessary context to understand and address the problem effectively. In this case, knowing that version 29.0.0 is being used allows for targeted investigations into any version-specific issues or incompatibilities. Furthermore, it facilitates collaboration among developers who might be experiencing similar problems, as they can compare their setups and identify common factors. The library version acts as a key piece of information for troubleshooting and resolving issues related to the Adyen API integration.

Java Version and Operating System

The Java version used in this project is 21, which is a relatively recent version of the Java Development Kit (JDK). The operating system on which the issue is occurring is Linux. This information is important for several reasons. The Java version can influence the behavior of the application, as different JDK versions may have variations in their implementations and bug fixes. Knowing that Java 21 is being used helps in identifying any potential compatibility issues or bugs specific to this version. Similarly, the operating system can also play a role, as certain issues may be platform-specific. Linux, being a widely used operating system for servers and development environments, has its own set of characteristics that could potentially interact with the Adyen API library. Providing this context helps in narrowing down the possible causes of the bug. For instance, if the issue is only reproducible on Linux and not on other operating systems, it suggests that there might be a platform-specific problem. Similarly, if the issue is only seen with Java 21, it could indicate a JDK-related bug. Therefore, including the Java version and operating system details is a crucial step in providing a comprehensive overview of the environment in which the bug is occurring, facilitating more effective troubleshooting and resolution.

Additional Context

To further aid in diagnosing the issue, additional contextual information is provided. The approximate time of occurrence of the bug is noted as 2025-11-25T09:10:23.346390179Z. While this specific timestamp might not be directly relevant to the root cause, it can be helpful for correlating the error with other events or logs in the system. If there were any deployments, configuration changes, or other activities around this time, it might provide clues about what triggered the bug. Additionally, an example of the parameters used in the API call is provided: saleId=S1F2-000158243353990, serviceId=91h0rgz4y4, category=Payment. These parameters give insight into the specific values being passed to the Adyen API, which can be useful for identifying any patterns or anomalies. For instance, if the bug only occurs with certain saleId formats or within a particular category, it could indicate a data-related issue. The combination of the timestamp and parameter example offers a more complete picture of the context surrounding the bug, enabling developers to make more informed decisions during the debugging process. This holistic view is crucial for effective problem-solving and ensures that no potential factors are overlooked.

Conclusion

In conclusion, the issue of the Adyen /abort API returning a string instead of a JSON object in the test environment is a significant bug that disrupts the expected payment cancellation workflow. The consistent reproducibility of this issue, coupled with the detailed information provided—including the steps to reproduce, the actual and expected behaviors, a relevant code snippet, the Adyen Java API Library version, the Java version, the operating system, and additional context—lays a solid foundation for effective troubleshooting and resolution. Understanding the nuances of this bug is crucial for developers integrating with the Adyen API, as it highlights the importance of robust testing and error handling. By addressing this issue, developers can ensure a more reliable and stable payment processing system. For further reading and best practices on API integration and error handling, you can visit the official Adyen documentation or other trusted resources like https://docs.adyen.com/. This external link will provide additional insights and support in navigating complex API interactions.