PTHMINT-91: Enable optional validation betwen amount and calculated amount

Author: zulquer

src/multisafepay/api/paths/orders/order_id/refund/request/components/checkout_data.py

@@ -150,8 +150,9 @@ def refund_by_merchant_item_id(
             )
 
         found_item = self.get_item_by_merchant_item_id(merchant_item_id)
-        if quantity < 1 or quantity > found_item.quantity:
-            quantity = found_item.get_quantity()
+        item_quantity = found_item.quantity or 0
+        if quantity < 1 or quantity > item_quantity:
+            quantity = item_quantity
 
         refund_item = found_item.clone()
         refund_item.add_quantity(quantity)

src/multisafepay/api/paths/orders/request/order_request.py

@@ -33,7 +33,11 @@
 from multisafepay.api.shared.description import Description
 from multisafepay.exception.invalid_argument import InvalidArgumentException
 from multisafepay.model.request_model import RequestModel
-from multisafepay.util.total_amount import validate_total_amount
+from multisafepay.util.total_amount import (
+    RoundingMode,
+    RoundingStrategy,
+    validate_total_amount,
+)
 from multisafepay.value_object.amount import Amount
 from multisafepay.value_object.currency import Currency
 
@@ -581,14 +585,16 @@ def add_var3(self: "OrderRequest", var3: Optional[str]) -> "OrderRequest":
         self.var3 = var3
         return self
 
-    def validate_amount(self: "OrderRequest") -> "OrderRequest":
-        """
-        Validates the total amount of the order request and the shopping cart.
-
-        Returns
-        -------
-        OrderRequest: The validated OrderRequest object.
-
-        """
-        validate = validate_total_amount(self.dict())
+    def validate_amount(
+        self: "OrderRequest",
+        *,
+        rounding_strategy: RoundingStrategy = "end",
+        rounding_mode: RoundingMode = "half_up",
+    ) -> "OrderRequest":
+        """Validates the total amount of the order request and the shopping cart."""
+        validate_total_amount(
+            self.dict(),
+            rounding_strategy=rounding_strategy,
+            rounding_mode=rounding_mode,
+        )
         return self

src/multisafepay/util/total_amount.py

@@ -5,16 +5,39 @@
 
 # See the DISCLAIMER.md file for disclaimer details.
 
-"""Total amount calculation and validation utilities for order processing."""
+"""
+Total amount calculation and validation utilities for order processing.
+
+Important:
+---------
+Different integrators (ERP/POS/e-commerce) can legitimately compute `amount`
+under different rounding policies (per-line vs end rounding, half-up vs
+bankers rounding, etc.).
+
+This module supports a **best-effort** local validator that can be configured
+to match a known policy, but the API remains the source of truth.
+
+"""
 
 import json
-from decimal import Decimal
-from typing import Union
+from decimal import ROUND_DOWN, ROUND_HALF_EVEN, ROUND_HALF_UP, Decimal
+from typing import Literal, Union
 
 from multisafepay.exception.invalid_total_amount import (
     InvalidTotalAmountException,
 )
 
+RoundingStrategy = Literal["end", "line"]
+RoundingMode = Literal["half_up", "half_even", "down"]
+
+
+def _decimal_rounding(mode: RoundingMode) -> str:
+    if mode == "half_even":
+        return ROUND_HALF_EVEN
+    if mode == "down":
+        return ROUND_DOWN
+    return ROUND_HALF_UP
+
 
 def _convert_decimals_to_float(
     obj: Union[Decimal, dict, list, object],
@@ -45,10 +68,28 @@ def _convert_decimals_to_float(
     return obj
 
 
-def validate_total_amount(data: dict) -> bool:
+def validate_total_amount(
+    data: dict,
+    *,
+    rounding_strategy: RoundingStrategy = "end",
+    rounding_mode: RoundingMode = "half_up",
+) -> bool:
     """
     Validate the total amount in the provided data dictionary.
 
+    Important
+    ---------
+    This validator uses a specific calculation/rounding model:
+    - Applies tax per item (if any) and sums the precise Decimal totals.
+    - Quantizes the final total to 2 decimals.
+    - Converts to cents using HALF_UP.
+
+    If the input `amount` was produced under a different policy (per-line rounding,
+    different tax rounding, unit prices with more than 2 decimals, etc.), the SDK
+    may disagree with external systems. In those cases, prefer letting the API
+    validate and/or use `calculate_total_amount_cents()` to compute a consistent
+    amount under this validator's rules.
+
     Parameters
     ----------
     data (dict): The data dictionary containing the amount and shopping cart details.
@@ -69,13 +110,26 @@ def validate_total_amount(data: dict) -> bool:
         return False
 
     amount = data["amount"]
-    total_unit_price = __calculate_totals(data)
+    total_unit_price = calculate_total_amount(
+        data,
+        rounding_strategy=rounding_strategy,
+        rounding_mode=rounding_mode,
+    )
 
-    # Convert total_unit_price to cents (integer) for comparison
-    total_unit_price_cents = int(total_unit_price * 100)
+    # Convert to cents (integer) for comparison.
+    # Note: total_unit_price is already quantized to 2 decimals in calculate_total_amount().
+    total_unit_price_cents = calculate_total_amount_cents(
+        data,
+        rounding_strategy=rounding_strategy,
+        rounding_mode=rounding_mode,
+    )
 
     if total_unit_price_cents != amount:
-        msg = f"Total of unit_price ({total_unit_price}) does not match amount ({amount})"
+        delta = amount - total_unit_price_cents
+        msg = (
+            f"Total of unit_price ({total_unit_price}) does not match amount ({amount}). "
+            f"Expected amount: {total_unit_price_cents} (delta: {delta})."
+        )
         # Create a JSON-serializable copy of data by converting Decimal to float
         serializable_data = _convert_decimals_to_float(data)
         msg += "\n" + json.dumps(serializable_data, indent=4)
@@ -84,7 +138,48 @@ def validate_total_amount(data: dict) -> bool:
     return True
 
 
-def __calculate_totals(data: dict) -> Decimal:
+def calculate_total_amount(
+    data: dict,
+    *,
+    rounding_strategy: RoundingStrategy = "end",
+    rounding_mode: RoundingMode = "half_up",
+) -> Decimal:
+    """
+    Calculate the order total (major units) using the same logic as the validator.
+
+    This is useful to generate a consistent `amount` before submitting an Order.
+    """
+    return __calculate_totals(
+        data,
+        rounding_strategy=rounding_strategy,
+        rounding_mode=rounding_mode,
+    )
+
+
+def calculate_total_amount_cents(
+    data: dict,
+    *,
+    rounding_strategy: RoundingStrategy = "end",
+    rounding_mode: RoundingMode = "half_up",
+) -> int:
+    """Calculate the expected `amount` (minor units) using the validator's logic."""
+    total = calculate_total_amount(
+        data,
+        rounding_strategy=rounding_strategy,
+        rounding_mode=rounding_mode,
+    )
+    cents = (total * 100).to_integral_value(
+        rounding=_decimal_rounding(rounding_mode),
+    )
+    return int(cents)
+
+
+def __calculate_totals(
+    data: dict,
+    *,
+    rounding_strategy: RoundingStrategy = "end",
+    rounding_mode: RoundingMode = "half_up",
+) -> Decimal:
     """
     Calculate the total unit price of items in the shopping cart using precise Decimal arithmetic.
 
@@ -97,6 +192,7 @@ def __calculate_totals(data: dict) -> Decimal:
     Decimal: The total unit price of all items in the shopping cart with precise decimal calculation.
 
     """
+    rounding = _decimal_rounding(rounding_mode)
     total_unit_price = Decimal("0")
     for item in data["shopping_cart"]["items"]:
         tax_rate = __get_tax_rate_by_item(item, data)
@@ -109,10 +205,18 @@ def __calculate_totals(data: dict) -> Decimal:
         # Calculate item price with tax
         item_price = unit_price * quantity
         item_price += tax_rate_decimal * item_price
+
+        # Some systems (e.g., ERPs/POS) round per line item; others round at the end.
+        if rounding_strategy == "line":
+            item_price = item_price.quantize(
+                Decimal("0.01"),
+                rounding=rounding,
+            )
+
         total_unit_price += item_price
 
     # Round to 2 decimal places for currency
-    return total_unit_price.quantize(Decimal("0.01"))
+    return total_unit_price.quantize(Decimal("0.01"), rounding=rounding)
 
 
 def __get_tax_rate_by_item(

tests/multisafepay/e2e/conftest.py

@@ -0,0 +1,28 @@
+"""Configuration for end-to-end tests."""
+
+import os
+
+import pytest
+
+
+def pytest_collection_modifyitems(
+    config: pytest.Config,  # noqa: ARG001
+    items: list[pytest.Item],
+) -> None:
+    """
+    Skip all e2e tests when API_KEY is missing.
+
+    These tests perform real API calls. In most local/CI environments the secret
+    isn't present, so we prefer a clean skip over hard errors during fixture setup.
+    """
+    api_key = os.getenv("API_KEY")
+    if api_key and api_key.strip():
+        return
+
+    skip = pytest.mark.skip(reason="E2E tests require API_KEY (not set)")
+    for item in items:
+        # This hook runs for the whole session (all collected tests), even when
+        # this conftest is only loaded due to e2e tests being present/deselected.
+        # Ensure we only affect e2e tests.
+        if item.nodeid.startswith("tests/multisafepay/e2e/"):
+            item.add_marker(skip)

tests/multisafepay/integration/amounts/__init__.py

@@ -0,0 +1,6 @@
+"""
+Offline amount/total validation scenarios.
+
+These tests focus on local amount/cart validation logic. They do not perform
+network calls and should not require API_KEY.
+"""

tests/multisafepay/integration/amounts/_helpers.py

@@ -0,0 +1,47 @@
+"""Shared helpers for offline amount/total validation scenario tests."""
+
+from __future__ import annotations
+
+from decimal import Decimal
+
+
+def data(
+    *,
+    amount: int,
+    items: list[dict],
+    tax_tables: dict | None = None,
+) -> dict:
+    """Build a minimal `validate_total_amount` input dict."""
+    result: dict = {
+        "amount": amount,
+        "shopping_cart": {"items": items},
+    }
+    if tax_tables is not None:
+        result["checkout_options"] = {"tax_tables": tax_tables}
+    return result
+
+
+def no_tax_tables() -> dict:
+    """Tax tables configuration that yields 0% tax under selector 'none'."""
+    return {
+        "default": {"shipping_taxed": True, "rate": 0.0},
+        "alternate": [
+            {"name": "none", "standalone": False, "rules": [{"rate": 0.0}]},
+        ],
+    }
+
+
+def vat_tables() -> dict:
+    """Common VAT tables used for scenarios (21% and 9%)."""
+    return {
+        "default": {"shipping_taxed": True, "rate": 0.21},
+        "alternate": [
+            {"name": "BTW21", "standalone": True, "rules": [{"rate": 0.21}]},
+            {"name": "BTW9", "standalone": True, "rules": [{"rate": 0.09}]},
+        ],
+    }
+
+
+def d(value: str) -> Decimal:
+    """Convenience Decimal constructor for test readability."""
+    return Decimal(value)