Adyen API Bug: Wrong Path For Checkout Recurring Endpoint

Nov 28, 2025 by Alex Johnson 58 views

Introduction

In this article, we will discuss a bug found in the Adyen Ruby API Library related to the checkout recurring endpoint. This bug causes requests to be sent to an incorrect path, leading to unexpected behavior. We will explore the details of the issue, the steps to reproduce it, the actual and expected behavior, and the code snippets that highlight the problem. This issue was found in version 11.1.0 of the Adyen Ruby API Library, and this article aims to provide a comprehensive understanding of the bug and its potential impact.

It is essential to address this bug to ensure that developers using the Adyen Ruby API Library can rely on the correct endpoints for their checkout recurring operations. By identifying the root cause and providing a clear explanation, we hope to contribute to the resolution of this issue and improve the overall quality of the library.

This article is structured to provide a detailed analysis of the bug, starting with a clear description of the problem, followed by step-by-step instructions on how to reproduce it. We will then compare the actual behavior with the expected behavior, providing clarity on the impact of the bug. Code snippets and version information will be included to give a complete picture of the issue. Finally, we will discuss the implications of this bug and potential solutions to address it.

Description of the Issue

The core of the issue lies in the incorrect path being used for the checkout recurring endpoint within the Adyen Ruby API Library. According to the API documentation, the endpoint should be https://checkout-test.adyen.com/v71/storedPaymentMethods. However, due to a configuration issue within the library, requests are being sent to https://pal-test.adyen.com/pal/servlet/Recurring/v71/storedPaymentMethods. This discrepancy leads to requests being routed to the wrong service, potentially causing failures or unexpected responses.

The problem originates from how the Recurring service is instantiated within the Adyen::Client class. The library incorrectly creates an instance of the Recurring service, which is intended for a different part of the Adyen API, rather than the Checkout::RecurringApi service, which is the correct one for handling checkout recurring operations. This misconfiguration results in the wrong base URL being used for the API calls.

The implications of this bug are significant. Developers relying on the Adyen Ruby API Library for their checkout recurring functionality will encounter errors and inconsistencies. This can lead to failed payment transactions, incorrect data being stored, and a poor user experience. It is crucial to rectify this issue to ensure the reliability and accuracy of the Adyen integration.

To further illustrate the impact, consider a scenario where a merchant is using the library to process recurring payments. If the requests are being sent to the wrong endpoint, the payment transactions may fail, leading to lost revenue and customer dissatisfaction. Additionally, the merchant's system may not receive the correct notifications and updates, causing further complications in managing recurring payments. Therefore, fixing this bug is essential for maintaining the integrity of the payment processing system.

Steps to Reproduce

To effectively demonstrate and understand the bug, reproducing it is crucial. Here are the step-by-step instructions to reproduce the incorrect path issue for the checkout recurring endpoint in the Adyen Ruby API Library:

Install Version 11.1.0: Begin by installing version 11.1.0 of the Adyen Ruby API Library. This can be done using RubyGems with the command gem install adyen-ruby-api-library -v 11.1.0. Ensure that the installation completes successfully without any errors.
Create an Adyen::Client Instance: After installing the library, create an instance of the Adyen::Client. This is the primary entry point for interacting with the Adyen API. You will need to configure the client with your API key and environment settings. The basic code for this step looks like this:
```
require 'adyen'

client = Adyen::Client.new(
  api_key: 'YOUR_API_KEY',
  environment: :test
)
```
Replace YOUR_API_KEY with your actual Adyen API key. Setting the environment to :test will use the test endpoints, which is suitable for reproducing the issue without affecting live transactions.
Call the stored_payment_methods Method: Next, call the stored_payment_methods method on the client.checkout.recurring_api object. This method is intended to retrieve stored payment methods for a customer. The call will trigger a request to the endpoint, and you can observe the URL being used.
```
response = client.checkout.recurring_api.stored_payment_methods({
  merchant_account: 'YOUR_MERCHANT_ACCOUNT',
  shopper_reference: 'YOUR_SHOPPER_REFERENCE'
})
```
Replace YOUR_MERCHANT_ACCOUNT and YOUR_SHOPPER_REFERENCE with your actual merchant account and shopper reference.
Observe the Request URL: By inspecting the logs or network traffic, you will notice that the request is being made to https://pal-test.adyen.com/pal/servlet/Recurring/v71/storedPaymentMethods instead of the expected https://checkout-test.adyen.com/v71/storedPaymentMethods. This confirms the bug.

By following these steps, you can easily reproduce the issue and verify that the request is indeed being sent to the incorrect endpoint. This reproduction is crucial for understanding the scope and impact of the bug.

Actual Behavior

The actual behavior of the Adyen Ruby API Library, version 11.1.0, when calling the checkout recurring endpoint, deviates significantly from the expected behavior. Instead of routing the request to the correct checkout service endpoint, the library mistakenly directs it to the recurring service endpoint. This misdirection occurs because the Recurring service is incorrectly instantiated within the Adyen::Client class.

Specifically, when the stored_payment_methods method is invoked via client.checkout.recurring_api, the library constructs a request to https://pal-test.adyen.com/pal/servlet/Recurring/v71/storedPaymentMethods. This URL is associated with the older Recurring API, which is distinct from the newer checkout-specific API. The consequences of this incorrect routing can be substantial.

The primary issue is that the request will likely fail or return unexpected results. The Recurring API and the checkout API have different request and response formats, and the endpoints are designed to handle different types of operations. Sending a checkout-related request to the recurring endpoint will not yield the desired outcome, potentially disrupting payment processing and other critical functionalities.

Moreover, this incorrect behavior can lead to confusion and frustration for developers. When the API calls do not behave as documented, developers may spend considerable time debugging and troubleshooting, which can delay project timelines and increase development costs. It also erodes trust in the reliability of the library, which is crucial for maintaining a positive developer experience.

To illustrate further, consider the scenario where a merchant is attempting to retrieve a list of stored payment methods for a customer. If the request is routed to the incorrect endpoint, the merchant's system may not receive the necessary data, preventing the merchant from processing payments or managing customer payment preferences effectively. This can lead to a breakdown in the payment workflow and negatively impact the merchant's business operations.

Expected Behavior

The expected behavior of the Adyen Ruby API Library when interacting with the checkout recurring endpoint is that it should correctly route requests to the appropriate Adyen Checkout API endpoint. Specifically, when the stored_payment_methods method is called, the library should send the request to https://checkout-test.adyen.com/v71/storedPaymentMethods for the test environment or https://checkout.adyen.com/v71/storedPaymentMethods for the live environment. This ensures that the request is handled by the correct service designed for checkout-related operations.

This correct routing is essential for several reasons. First and foremost, it ensures that the API call reaches the intended service, which is configured to process the request according to the expected format and logic. The Checkout API is specifically designed for handling checkout-related operations, such as retrieving stored payment methods, processing payments, and managing payment sessions. Sending the request to the correct endpoint guarantees that the operation is executed as intended.

Furthermore, the expected behavior includes receiving a well-structured and predictable response from the API. The Checkout API returns data in a specific format, which the client library is designed to parse and handle. If the request is routed to the wrong endpoint, the response may be in an unexpected format, leading to errors and making it difficult for the application to process the data correctly.

In addition, the correct behavior supports a seamless and reliable payment processing experience. When the API calls are routed correctly, merchants can confidently manage their customers' stored payment methods, process recurring payments, and handle other checkout-related tasks without encountering unexpected issues. This reliability is crucial for maintaining customer trust and ensuring smooth business operations.

To further emphasize the importance of the expected behavior, consider the scenario where a merchant is setting up recurring payments for a customer. If the API library correctly routes the request to the Checkout API, the merchant can retrieve the customer's stored payment methods, select the appropriate method for the recurring payment, and set up the schedule. This entire process relies on the correct routing and response handling of the API calls. Any deviation from the expected behavior can disrupt this process and lead to errors.

Code Snippet and Root Cause Analysis

To understand the root cause of the issue, let's examine the relevant code snippets from the Adyen Ruby API Library. The problem appears to stem from how the Recurring service is instantiated within the Adyen::Client class. The incorrect instantiation leads to the wrong service URL being used for the checkout recurring endpoint.

The first relevant snippet is from lib/adyen/services/recurring/recurring_api.rb:

module Adyen
  module Services
    module Recurring
      class RecurringApi < Service
        def stored_payment_methods(request, headers: {})
          endpoint = '/storedPaymentMethods'
          @client.post(
            endpoint,
            request.to_json,
            headers
          )
        end
      end
    end
  end
end

This snippet shows the RecurringApi class within the Adyen::Services::Recurring module. It defines the stored_payment_methods method, which is intended to be used for recurring payments. However, this is not the correct class for checkout-related recurring operations.

The second crucial snippet is from lib/adyen/client.rb:

def initialize(api_key: nil, client: nil, environment: :test, logger: nil, **opts)
  # ...
  @services = {
    # ...
    recurring: Services::Recurring::RecurringApi.new(self),
    # ...
  }.freeze
  # ...
end


def checkout
  @checkout ||= OpenStruct.new(
    recurring_api: Services::Checkout::RecurringApi.new(self)
  )
end

Here, the Adyen::Client class initializes the @services hash, which includes an instance of Services::Recurring::RecurringApi. This is where the problem begins, as the client is creating an instance of the general RecurringApi instead of the checkout-specific Checkout::RecurringApi. When client.checkout.recurring_api is called, it should ideally instantiate the Checkout::RecurringApi.

The correct class for handling checkout recurring operations is defined in lib/adyen/services/checkout/recurring_api.rb:

module Adyen
  module Services
    module Checkout
      class RecurringApi < Service
        def stored_payment_methods(request, headers: {})
          endpoint = '/storedPaymentMethods'
          @client.post(
            endpoint,
            request.to_json,
            headers
          )
        end
      end
    end
  end
end

This class, Checkout::RecurringApi, is the one that should be used for checkout-related recurring operations. However, due to the incorrect instantiation in Adyen::Client, the requests are being routed to the RecurringApi in the general Services::Recurring module.

The root cause, therefore, is the incorrect instantiation of the Recurring service within the Adyen::Client class. This leads to the use of the wrong base URL for the checkout recurring endpoint, causing the requests to be sent to https://pal-test.adyen.com/pal/servlet/Recurring/v71/storedPaymentMethods instead of https://checkout-test.adyen.com/v71/storedPaymentMethods.

Implications and Potential Solutions

The implications of this bug in the Adyen Ruby API Library are significant, particularly for merchants and developers relying on the library for handling checkout recurring payments. The incorrect routing of requests can lead to several issues, including:

Failed Transactions: Since the requests are being sent to the wrong endpoint, they are unlikely to be processed correctly, leading to transaction failures. This can result in lost revenue and customer dissatisfaction.
Data Inconsistencies: The mismatch between the expected and actual endpoints can cause data inconsistencies, as the response formats and data structures may differ between the two services. This can lead to errors in data processing and reporting.
Integration Issues: Developers integrating the Adyen API into their applications may encounter difficulties and unexpected behavior, leading to increased development time and costs.
Compliance Concerns: Incorrectly handled recurring payments can raise compliance concerns, particularly with regulations like PCI DSS, which require secure handling of payment data.

To address this bug, several potential solutions can be considered:

Correct Service Instantiation: The primary solution is to correct the instantiation of the Recurring service within the Adyen::Client class. Instead of instantiating Services::Recurring::RecurringApi, the client should instantiate Services::Checkout::RecurringApi when the checkout context is used. This will ensure that the requests are routed to the correct endpoint.
Update Client Initialization: Modify the checkout method in Adyen::Client to correctly instantiate the Checkout::RecurringApi.
```
def checkout
  @checkout ||= OpenStruct.new(
    recurring_api: Services::Checkout::RecurringApi.new(self)
  )
end
```
This ensures that the checkout recurring API uses the correct service.
Testing and Validation: Implement comprehensive testing and validation procedures to ensure that all API calls are being routed to the correct endpoints. This includes unit tests, integration tests, and end-to-end tests.
Documentation Updates: Update the library's documentation to reflect the correct usage of the checkout recurring endpoint and to provide guidance on how to avoid this issue.
Release a Patch: Release a patch version of the library that includes the fix for this bug. This will allow developers to update their dependencies and resolve the issue in their applications.

By implementing these solutions, the Adyen Ruby API Library can be corrected to ensure that checkout recurring payments are handled correctly, leading to a more reliable and seamless payment processing experience for merchants and developers.

Conclusion

In conclusion, the bug identified in the Adyen Ruby API Library, version 11.1.0, concerning the incorrect path for the checkout recurring endpoint, poses a significant issue that needs to be addressed. The misrouting of requests to the older Recurring API instead of the intended Checkout API can lead to transaction failures, data inconsistencies, and integration challenges for developers and merchants relying on this library.

The root cause of this issue lies in the incorrect instantiation of the Recurring service within the Adyen::Client class, where the general Services::Recurring::RecurringApi is instantiated instead of the checkout-specific Services::Checkout::RecurringApi. This leads to the use of the wrong base URL for the checkout recurring endpoint, causing requests to be sent to https://pal-test.adyen.com/pal/servlet/Recurring/v71/storedPaymentMethods instead of the correct https://checkout-test.adyen.com/v71/storedPaymentMethods.

To rectify this issue, the key solution involves correcting the service instantiation within the Adyen::Client class. By ensuring that the Services::Checkout::RecurringApi is instantiated for checkout-related recurring operations, the requests will be routed to the correct endpoint. Additionally, thorough testing, documentation updates, and the release of a patch version are crucial steps to ensure the reliability and usability of the library.

Addressing this bug is essential for maintaining the integrity of payment processing and ensuring a seamless experience for both developers and merchants. By taking the necessary corrective actions, the Adyen Ruby API Library can continue to be a trusted tool for handling checkout recurring payments.

For further information on Adyen's API and services, you can visit the official Adyen documentation website at Adyen Developer Documentation.