[Bug]: Nulling out or resetting surcharge configurations for terminal settings does not work

[sdkindy]

Description

Adyen terminal settings API does not allow resetting surcharge configurations (so they no longer apply)

Steps to reproduce

TerminalSettings terminalSettings = new TerminalSettings();
// Toggle off surcharging
terminalSettings.setSurcharge(null);

This should work to basically reset surcharge configurations so none apply on the terminal devices assigned to the store. We get a 200 back, but it no-ops and doesn't actually undo the surcharge configurations.

The suggestion from support was to pass an empty string. Given your library, this would not work or be viable given that the expected value is a Surcharge object.

This is a significant issue.

Actual behavior

You cannot toggle off surcharging after setting it in terminal settings for a store.

Expected behavior

You should be able to set and toggle off surcharging; it shouldn't be a one and done user action.

Code snippet or screenshots (if applicable)

Relevant code block (notice how our expectation as a consumer of this library is that we should be able to toggle on/off surcharging interchangeably):

  TerminalSettings terminalSettings = new TerminalSettings();

        FeeStructure feeStructure = practiceBillingSettingDao.getOrCreatePracticeBillingSetting(requestContext)
                .getFeeStructure();

        if (FeeStructure.SURCHARGE.equals(feeStructure)) {
            // Toggle on surcharging
            List<ModelConfiguration> configurations = AdyenConstants.SUPPORTED_PAYMENT_METHODS.stream()
                    .map(paymentMethodSetupInfo -> new ModelConfiguration().brand(paymentMethodSetupInfo.getValue())
                            .currencies(List.of(new Currency().currencyCode("USD")
                                    .percentage(paymentConfig.getPassTheFeePercentageSurcharge().doubleValue())))
                            .sources(List.of(AdyenConstants.ADYEN_CP_TERMINAL_SETTINGS_SURCHARGE_FUNDING_SOURCE)))
                    .toList();

            Surcharge surcharge = new Surcharge();
            surcharge.setConfigurations(configurations);
            surcharge.setAskConfirmation(true);
            terminalSettings.setSurcharge(surcharge);
        } else {
            // Toggle off surcharging
            terminalSettings.setSurcharge(null);
        }

        adyenGateway.updateTerminalSettings(adyenStoreIdentity.getStoreId(), terminalSettings).join();

AdyenGateway#updateTerminalSettings:

public CompletableFuture<TerminalSettings> updateTerminalSettings(
            @NotNull String storeId,
            @NotNull TerminalSettings terminalSettings) {
        TerminalSettingsStoreLevelApi terminalSettingsStoreLevelApi = new TerminalSettingsStoreLevelApi(
                this.adyenMerchantClient);
        return CompletableFuture.supplyAsync(() -> {
            try {
                return terminalSettingsStoreLevelApi.updateTerminalSettingsByStoreId(storeId, terminalSettings);
            } catch (Exception e) {
                printError(e);
                CompletableFuture<TerminalSettings> failedFuture = new CompletableFuture<>();
                failedFuture.completeExceptionally(e);
                return failedFuture.join(); // this will throw the exception in the calling thread
            }
        });
    }

Adyen Java API Library version

38.0.0.0

Java version

17.0.12

Operating System

macOS

Additional context

This is not an OS-specific issue.

[gcatanese]

Hi @sdkindy, I see the issue as we don't include null fields in the requests, while in this case the Management API use null to clear the existing values.
Did you try to pass to an empty object, new Surcharge()?

[sdkindy]

Hi @sdkindy, I see the issue as we don't include null fields in the requests, while in this case the Management API use null to clear the existing values. Did you try to pass to an empty object, new Surcharge()?

No, that isn't intuitive. Is that what you're saying will actually work? I will try that, and see if that works. I will close the ticket once I confirm this works. Documentation may be helpful here for folks' future reference.

[sdkindy]

@gcatanese I tested this via Postman and it does not work. Are you certain this will work using the Java API library? Can you confirm on your end? It would be helpful if you verified whether this is a bug on your end and correct it if so. Thank you.

[gcatanese]

@sdkindy I agree it is not intuitive (and undocumented), I was trying to find a workaround.
Unfortunately the API expects an attribute surcharge set as null, while the SDK doesn't allow that.

With Postman I assume it works when passing null but it doesn't work when passing an empty object, right?
I need to contact the dev team responsible for the feature to discuss the best solution in this case, I agree it is a significant issue and we'll do our best to resolve it.

[sdkindy]

Exactly. The API expects null but the SDK doesn’t allow it. This is an issue that needs to be fixed on your end. On Nov 18, 2025, at 5:20 AM, Beppe Catanese ***@***.***> wrote:gcatanese left a comment (Adyen/adyen-java-api-library#1584) @sdkindy I agree it is not intuitive (and undocumented), I was trying to find a workaround. Unfortunately the API expects an attribute surcharge set as null, while the SDK doesn't allow that. With Postman I assume it works when passing null but it doesn't work when passing an empty object, right? I need to contact the dev team responsible for the feature to discuss the best solution in this case, I agree it is a significant issue and we'll do our best to resolve it. —Reply to this email directly, view it on GitHub, or unsubscribe.You are receiving this because you were mentioned.Message ID: ***@***.***>