W Magento Open Source wykryto poważny błąd mechanizmu zwrotów, który pozwala zapisywać dokumenty Credit Memo z ujemnymi kwotami. Problem dotyczy Magento 2.4.9 i został potwierdzony również w gałęzi rozwojowej 2.4-develop. Nieprawidłowe wartości mogą być następnie zapisywane bezpośrednio w danych zamówień, powodując niespójności w informacjach o dokonanych zwrotach.
Zgłoszenie opublikowano 11 listopada 2026 roku w oficjalnym repozytorium Magento na GitHubie. Przedstawiciel zespołu Magento niezależnie odtworzył problem i potwierdził jego występowanie. Zgłoszeniu przyznano priorytet P2 i przekazano je do dalszych prac.
Najbardziej niepokojące jest to, że Magento może wyświetlić komunikat o pomyślnym utworzeniu dokumentu zwrotu, mimo że jego końcowa wartość jest ujemna. W opisanym przypadku system zapisał dokument Credit Memo na kwotę -10 dolarów i zmienił łączną wartość zwrotów przypisaną do zamówienia na -10 dolarów.
Na czym polega błąd zwrotów w Magento 2.4.9?
Problem został opisany w oficjalnym zgłoszeniu Magento #41853 dotyczącym zapisywania Credit Memo z ujemną wartością.
Błąd występuje podczas tworzenia dokumentu Credit Memo, gdy w konfiguracji Magento aktywne jest ustawienie:
Allow Zero GrandTotal for Creditmemo = Yes
Jest to ustawienie domyślne. Pozwala ono na wystawianie dokumentów Credit Memo, których końcowa wartość wynosi zero.
Takie dokumenty mogą być potrzebne w określonych sytuacjach związanych z obsługą zamówień, korekt i rozliczeń.
Problem polega na tym, że Magento błędnie interpretuje zgodę na zerową wartość dokumentu jako możliwość zaakceptowania również wartości ujemnych.
W efekcie dokument, który powinien zostać odrzucony przez mechanizm walidacji, może zostać zapisany w bazie danych.
Czym jest Credit Memo w Magento i dlaczego jego prawidłowa wartość ma znaczenie?
Credit Memo to dokument wykorzystywany w Magento do rejestrowania zwrotu całości lub części wartości zamówienia.
W zależności od sposobu płatności oraz konfiguracji sklepu Credit Memo może być powiązany z operacją zwrotu pieniędzy za pośrednictwem operatora płatności albo dokumentować zwrot realizowany poza systemem płatniczym.
Magento rozróżnia między innymi:
- Refund: zwrot online realizowany przez integrację z operatorem płatności, jeżeli dany operator i metoda płatności obsługują tę funkcję.
- Refund Offline: zapis dokumentu zwrotu bez automatycznego przekazywania dyspozycji zwrotu do operatora płatności.
Dokument Credit Memo jest również powiązany z danymi zamówienia. Jego utworzenie może aktualizować informacje o łącznych kwotach zwróconych klientowi.
Z tego powodu nieprawidłowe kwoty zapisane w dokumentach Credit Memo mogą wpływać na dane wykorzystywane później przez administratorów, integracje księgowe, systemy raportowe i mechanizmy uzgadniania płatności.
Szczegółowy opis standardowej obsługi zwrotów znajduje się w oficjalnej dokumentacji Adobe Commerce dotyczącej Credit Memo.
Jak odtworzono problem? Magento zapisuje zwrot na kwotę -10 dolarów
Autor zgłoszenia przedstawił dokładny scenariusz pozwalający odtworzyć błąd w Magento Open Source 2.4.9.
Test przeprowadzono na zamówieniu opłaconym metodą Check / Money Order, dla którego wcześniej wystawiono fakturę.
Przebieg testu
- Utworzono prosty produkt o wartości 100 dolarów.
- Złożono zamówienie i wybrano metodę płatności Check / Money Order.
- Wygenerowano fakturę do zamówienia.
- Otwarto formularz Credit Memo.
- Ustawiono ilość zwracanych produktów na zero.
- Ustawiono wartość zwracanych kosztów dostawy na zero.
- W polu Adjustment Refund wpisano 10.
- W polu Adjustment Fee wpisano 20.
- Wybrano przycisk Refund Offline.
Przy takiej konfiguracji końcowa wartość dokumentu jest ujemna, ponieważ opłata korekcyjna przewyższa kwotę zwrotu.
| Parametr | Wartość |
|---|---|
| Wartość pierwotnego produktu | 100 USD |
| Ilość produktów do zwrotu | 0 |
| Refund Shipping | 0 USD |
| Adjustment Refund | 10 USD |
| Adjustment Fee | 20 USD |
| Końcowa wartość Credit Memo | -10 USD |
Prawidłowo działający system powinien odrzucić taki dokument, ponieważ jego końcowa wartość jest mniejsza od zera.
Tymczasem Magento zaakceptowało operację.
Komunikat wyświetlany przez Magento
Po wybraniu Refund Offline administrator otrzymał komunikat:
You created the credit memo.
Oznacza to, że system poinformował o pomyślnym utworzeniu dokumentu.
Jednocześnie w danych Credit Memo zapisano:
Grand Total: -10.00
Zmieniły się również wartości przypisane do zamówienia:
Total Refunded: -10.00
Total Offline Refunded: -10.00
Nie jest to wyłącznie problem wyświetlania błędnej kwoty na ekranie. Nieprawidłowe wartości zostały zapisane w danych dokumentu i zamówienia.
Przyczyna techniczna: nieprawidłowa walidacja isValidGrandTotal()
Źródło błędu zidentyfikowano w metodzie:
Magento\Sales\Model\Order\Creditmemo::isValidGrandTotal()
Metoda odpowiada za sprawdzanie poprawności końcowej wartości dokumentu Credit Memo.
W problematycznej implementacji zastosowano następujący warunek:
return !(
$this->getGrandTotal() <= 0
&& !$this->isAllowZeroGrandTotal()
);
Logika tego warunku powoduje, że przy aktywnym ustawieniu zezwalającym na dokumenty z zerową wartością Magento akceptuje nie tylko zero, lecz również wartości ujemne.
Jest to błąd w interpretacji warunku walidacyjnego.
Ustawienie Allow Zero GrandTotal for Creditmemo powinno dopuszczać dokument o wartości dokładnie zero, a nie każdą wartość mniejszą lub równą zero.
Jak powinno działać sprawdzanie kwoty?
Prawidłowa logika powinna rozróżniać trzy sytuacje:
- Wartość dodatnia: dokument może zostać zaakceptowany, jeżeli spełnia pozostałe wymagania.
- Wartość zero: dokument może zostać zaakceptowany wyłącznie wtedy, gdy pozwala na to konfiguracja.
- Wartość ujemna: dokument powinien zostać odrzucony niezależnie od ustawienia zezwalającego na zerową wartość.
W obecnej implementacji opisanej w zgłoszeniu trzeci przypadek nie jest prawidłowo obsługiwany.
Jakie są konsekwencje błędu dla danych zamówień?
Najważniejsze zagrożenie dotyczy spójności danych finansowych przechowywanych przez Magento.
Jeżeli system zapisuje dokument zwrotu z ujemną wartością, może następnie uwzględnić tę wartość w łącznych kwotach zwrotów przypisanych do zamówienia.
Może to prowadzić do kilku problemów.
1. Nieprawidłowe wartości zwrotów
Administrator może zobaczyć ujemną wartość Total Refunded, chociaż pole to powinno przedstawiać rzeczywiste sumy zwrotów dokonanych w związku z zamówieniem.
Ujemna wartość utrudnia interpretację historii rozliczeń.
2. Niespójności pomiędzy dokumentami i rzeczywistymi płatnościami
Zwrot offline może zostać zapisany w Magento bez wykonania odpowiadającego mu przelewu lub zwrotu przez operatora płatności.
W przypadku błędnych Credit Memo pojawia się dodatkowe ryzyko rozbieżności między danymi sklepu a historią rzeczywistych operacji finansowych.
3. Problemy z raportowaniem
Jeżeli raporty sprzedaży lub zewnętrzne systemy analityczne wykorzystują wartości Total Refunded, nieprawidłowe dane mogą zaburzać obliczenia.
Dotyczy to szczególnie raportów przedstawiających sprzedaż pomniejszoną o zwroty oraz zestawień służących do uzgadniania wartości transakcji.
4. Problemy z integracjami księgowymi i ERP
Sklepy korzystające z integracji z systemami księgowymi lub magazynowymi mogą przekazywać do nich dane dokumentów Credit Memo.
Jeżeli integracja nie sprawdza poprawności otrzymanych wartości, istnieje ryzyko przeniesienia nieprawidłowej kwoty do kolejnego systemu.
Nie oznacza to, że każdy system księgowy automatycznie przyjmie taki dokument. Rzeczywisty wpływ zależy od sposobu działania integracji oraz zastosowanych zabezpieczeń.
Czy Magento może zwrócić klientowi ujemną kwotę przez operatora płatności?
W opisanym zgłoszeniu rozróżniono zachowanie dwóch mechanizmów obsługi zwrotów.
W przypadku Refund Offline ujemny Credit Memo został zapisany, a wartości zwrotów w zamówieniu zostały zaktualizowane.
Inaczej zachował się mechanizm Refund, wykorzystywany przy zwrotach online.
W testowanym scenariuszu operacja została odrzucona na poziomie obsługi płatności.
System wyświetlił komunikat:
Online refund amount must be greater than zero.
Nie wysłano żądania wykonania zwrotu do operatora płatności.
Oznacza to, że w udokumentowanym teście błąd nie doprowadził do wykonania ujemnej transakcji płatniczej.
Nie można zatem twierdzić, że Magento automatycznie pobiera dodatkowe pieniądze od klientów lub że operatorzy płatności wykonują ujemne zwroty.
Potwierdzony problem polega na nieprawidłowym zapisywaniu dokumentów Credit Memo i aktualizowaniu danych zamówień w mechanizmie zwrotów offline.
Jak sprawdzić, czy sklep Magento posiada nieprawidłowe dokumenty Credit Memo?
Administratorzy mogą rozpocząć diagnostykę od sprawdzenia wersji Magento oraz konfiguracji obsługi dokumentów Credit Memo.
1. Sprawdź ustawienie Allow Zero GrandTotal for Creditmemo
W panelu administracyjnym przejdź do:
Stores
Configuration
Sales
Sales
Allow Zero GrandTotal
Allow Zero GrandTotal for Creditmemo
Sprawdź, czy aktywna jest wartość Yes.
To ustawienie ma bezpośredni związek z potwierdzonym scenariuszem występowania błędu.
2. Przejrzyj istniejące dokumenty Credit Memo
W sekcji Sales przejdź do listy Credit Memos.
Zwróć uwagę na dokumenty posiadające nietypowe wartości końcowe, szczególnie wartości ujemne.
Porównaj je z odpowiadającymi zamówieniami i rzeczywistymi operacjami zwrotu.
3. Sprawdź dane w bazie Magento
Administrator posiadający dostęp do bazy danych może wykonać zapytanie wyłącznie do odczytu, identyfikujące Credit Memo z ujemną kwotą.
SELECT
entity_id,
increment_id,
order_id,
grand_total,
base_grand_total,
created_at
FROM sales_creditmemo
WHERE grand_total < 0
OR base_grand_total < 0
ORDER BY created_at DESC;
Zapytanie nie modyfikuje żadnych danych.
Jeżeli Magento korzysta z niestandardowego prefiksu tabel, należy odpowiednio zmienić nazwy tabel w zapytaniu.
Warto następnie sprawdzić zamówienia posiadające ujemne sumy zwrotów:
SELECT
entity_id,
increment_id,
total_refunded,
base_total_refunded,
total_offline_refunded
FROM sales_order
WHERE total_refunded < 0
OR base_total_refunded < 0
OR total_offline_refunded < 0;
Wyniki mogą wskazać zamówienia wymagające dokładniejszej kontroli.
Należy pamiętać, że samo występowanie ujemnej wartości nie dowodzi automatycznie, że została ona utworzona wskutek błędu #41853. Trzeba sprawdzić historię dokumentów, konfigurację oraz ewentualne niestandardowe rozszerzenia.
4. Porównaj dane Magento z historią płatności
Jeżeli odnaleziono nieprawidłowe Credit Memo, porównaj je z rzeczywistymi zwrotami wykonanymi przez operatora płatności oraz dokumentacją wewnętrzną sklepu.
W przypadku zwrotów offline konieczne może być sprawdzenie dokumentów bankowych lub innych potwierdzeń faktycznego przekazania pieniędzy klientowi.
Nie należy automatycznie zmieniać wartości w bazie danych bez ustalenia rzeczywistego przebiegu rozliczenia.
Jak tymczasowo zabezpieczyć Magento przed ujemnymi Credit Memo?
W zgłoszeniu wskazano obejście polegające na zmianie konfiguracji:
Allow Zero GrandTotal for Creditmemo = No
Po wyłączeniu możliwości tworzenia Credit Memo o zerowej wartości Magento odrzuca również dokumenty z wartościami ujemnymi.
W testowanym scenariuszu pojawia się wtedy komunikat:
The credit memo's total must be positive.
Takie ustawienie może ograniczyć ryzyko zapisania dokumentów z ujemną końcową wartością.
Ma jednak istotne ograniczenie.
Zmiana blokuje również poprawne dokumenty Credit Memo z końcową kwotą równą zero. Jeżeli sklep wykorzystuje takie dokumenty w codziennej obsłudze zamówień, może to zakłócić obowiązujący proces zwrotów.
Przed zastosowaniem obejścia należy więc sprawdzić, czy zerowe Credit Memo są potrzebne i jakie procesy od nich zależą.
Nie poprawiaj ujemnych kwot bez analizy zamówienia
Ręczne ustawienie wartości Total Refunded na zero nie jest uniwersalną naprawą.
Jedno zamówienie może zawierać wiele dokumentów Credit Memo, a część zwrotów mogła zostać wykonana prawidłowo.
Zmiana wyłącznie pojedynczej wartości w tabeli zamówień może spowodować kolejne niespójności.
Bezpieczne postępowanie powinno obejmować wykonanie kopii zapasowej, identyfikację wszystkich powiązanych dokumentów i uzgodnienie danych z rzeczywistymi transakcjami.
Jest już przygotowana poprawka kodu Magento
11 listopada 2026 roku opublikowano Pull Request #41854 – Reject negative credit memo grand totals when zero totals are allowed.
Proponowana zmiana poprawia działanie metody Creditmemo::isValidGrandTotal().
Nowa walidacja ma zawsze odrzucać ujemną wartość dokumentu, niezależnie od konfiguracji zezwalającej na zerowe Credit Memo.
Jednocześnie dokumenty o wartości zero mają pozostać dozwolone, jeżeli odpowiednie ustawienie jest aktywne.
Poprawka uwzględnia również dokładność obliczeń finansowych
W projekcie rozwiązania uwzględniono problem dokładności liczb zmiennoprzecinkowych.
Niektóre działania matematyczne mogą dawać bardzo małe różnice względem oczekiwanej wartości zero.
Przykładowo operacja:
10.1 + 20.2 - 30.3
W określonych warunkach obliczeń komputerowych może nie zostać przedstawiona jako idealne zero.
Proponowana poprawka uwzględnia zaokrąglenie końcowej wartości do czterech miejsc po przecinku, zgodnie z precyzją wykorzystywaną przy zapisie kwot.
Ma to zapobiegać odrzucaniu prawidłowych dokumentów zerowych wskutek niewielkich błędów arytmetycznych.
Jakie testy obejmuje poprawka?
Autor przygotował testy jednostkowe i integracyjne sprawdzające:
- odrzucanie Credit Memo z ujemną wartością,
- akceptowanie dokumentów zerowych, jeżeli zezwala na to konfiguracja,
- odrzucanie dokumentów zerowych, gdy odpowiednia opcja jest wyłączona,
- prawidłową obsługę dodatnich kwot,
- zachowanie przy bardzo małych wartościach ujemnych,
- brak zapisu nieprawidłowego dokumentu i brak zmiany sum zwrotów w zamówieniu.
Propozycja obejmuje również testy związane z administracyjnymi operacjami Refund i Refund Offline.
Według stanu na 11 listopada 2026 roku Pull Request pozostaje otwarty i oczekuje na przegląd kodu. Nie potwierdzono jeszcze wydania stabilnej aktualizacji zawierającej tę poprawkę.
Zespół Magento oficjalnie potwierdził występowanie błędu
Istotnym wydarzeniem z 11 listopada 2026 roku było niezależne odtworzenie problemu przez przedstawiciela zespołu Magento.
Błąd potwierdzono na aktualnej gałęzi rozwojowej 2.4-develop.
Zgłoszenie otrzymało oznaczenie potwierdzonego problemu po ręcznej weryfikacji oraz priorytet P2.
Utworzono również wewnętrzne zadanie dotyczące jego obsługi, a zgłoszenie skierowano do dalszych prac rozwojowych.
Oznacza to, że problem nie opiera się już wyłącznie na obserwacjach pierwotnego autora. Został niezależnie odtworzony w środowisku projektu Magento.
Nie ma jednak podstaw, aby twierdzić, że błąd występuje masowo w sklepach produkcyjnych albo że spowodował już szeroko udokumentowane straty finansowe.
Czy problem dotyczy również Adobe Commerce?
Zgłoszenie zostało odtworzone na Magento Open Source 2.4.9 oraz w gałęzi 2.4-develop.
Adobe Commerce i Magento Open Source współdzielą istotne elementy mechanizmu obsługi zamówień, jednak nie potwierdzono w zgłoszeniu pełnej listy wydań Adobe Commerce dotkniętych tym problemem.
Administratorzy Adobe Commerce mogą sprawdzić działanie analogicznej walidacji w swoich instalacjach, ale nie należy automatycznie uznawać wszystkich wersji Adobe Commerce za podatne na identyczny błąd.
Znaczenie mogą mieć również indywidualne modyfikacje systemu, rozszerzenia oraz poprawki wdrożone w konkretnym środowisku.
Dlaczego poprawność zwrotów jest szczególnie ważna w dużych sklepach?
Sklepy realizujące dużą liczbę zamówień często korzystają z dodatkowych systemów do zarządzania sprzedażą, magazynem, księgowością i analizą danych.
Informacje o zamówieniach i zwrotach mogą być przekazywane do tych systemów automatycznie.
Jeżeli dane źródłowe zawierają nieprawidłowe wartości, problem może zostać przeniesiony na kolejne etapy przetwarzania informacji.
W szczególności warto kontrolować:
- zgodność wartości Credit Memo z rzeczywistymi zwrotami,
- poprawność sum Total Refunded w zamówieniach,
- zgodność danych Magento z rozliczeniami operatorów płatności,
- prawidłowość raportów sprzedaży po uwzględnieniu zwrotów,
- spójność danych przekazywanych do systemów ERP i księgowych,
- reakcję integracji na nietypowe lub ujemne wartości dokumentów.
W przypadku rozbudowanego sklepu internetowego szczególne znaczenie ma nie tylko prawidłowe przyjmowanie płatności, ale również spójność całego procesu obsługi zamówień, zwrotów i dokumentów sprzedażowych.
Najczęściej zadawane pytania
Czy Magento 2.4.9 może zapisać Credit Memo z ujemną wartością?
Tak. Potwierdzono scenariusz, w którym Magento 2.4.9 akceptuje ujemną wartość dokumentu, gdy aktywne jest ustawienie Allow Zero GrandTotal for Creditmemo i administrator korzysta z operacji Refund Offline.
Czy ujemny Credit Memo oznacza, że klientowi pobrano dodatkowe pieniądze?
Nie. Zapisanie ujemnego dokumentu nie jest równoznaczne z wykonaniem transakcji przez operatora płatności. W opisanym teście zwrot online został odrzucony, a operator nie otrzymał żądania zwrotu.
Czy błąd zmienia informacje zapisane w zamówieniu?
Tak. W potwierdzonym scenariuszu zapisano ujemny Grand Total dokumentu Credit Memo oraz ujemne wartości Total Refunded i Total Offline Refunded zamówienia.
Czy wyłączenie Allow Zero GrandTotal for Creditmemo rozwiązuje problem?
Stanowi potwierdzone obejście dla opisanego scenariusza, ale jednocześnie blokuje również poprawne dokumenty Credit Memo z zerową końcową wartością.
Czy błąd można wykryć bez modyfikowania bazy danych?
Tak. Można przejrzeć dokumenty Credit Memo w panelu administracyjnym oraz zastosować zapytania SQL typu SELECT, które odczytują dane bez ich zmieniania.
Czy dostępna jest oficjalna poprawka Magento?
Przygotowano Pull Request #41854, jednak według informacji z 11 listopada 2026 roku pozostaje on na etapie przeglądu. Nie potwierdzono jeszcze udostępnienia stabilnego wydania z poprawką.
Co powinni zrobić właściciele i administratorzy sklepów Magento?
Administratorzy instalacji Magento Open Source 2.4.9 powinni sprawdzić konfigurację Credit Memo i przeanalizować dokumenty zwrotów pod kątem ujemnych wartości.
Jeżeli sklep korzysta z funkcji Refund Offline, warto zweryfikować poprawność dokumentów oraz sum zwrotów zapisanych w zamówieniach.
Do czasu udostępnienia oficjalnej poprawki można rozważyć wyłączenie możliwości wystawiania zerowych Credit Memo, jeżeli nie są one potrzebne w bieżącym procesie obsługi sprzedaży.
W przypadku wykrycia nieprawidłowych wartości konieczne jest ustalenie rzeczywistego przebiegu rozliczeń przed wprowadzaniem zmian w danych zamówień.
Potwierdzony błąd pokazuje, że prawidłowe działanie sklepu nie kończy się na przyjęciu zamówienia i pobraniu płatności. Równie ważne jest zachowanie spójnych danych podczas zwrotów, korekt i rozliczeń.
Jeżeli Twój sklep Magento wymaga diagnostyki błędów, weryfikacji integracji lub pomocy w przywróceniu prawidłowego działania, netPOINT oferuje wsparcie techniczne w zakresie sklepów internetowych, systemów sprzedażowych i administracji serwerami.