ABN-298/feat: currency-aware surcharge fixed fees with FX conversion

Fixed fees and limits in the surcharge grid are now saved with the
store's base currency at time of configuration. When a sale uses a
different currency, Magento's built-in exchange rates convert the
amounts; orders are rejected if no rate exists. The admin grid headers
now display the active currency code. Explicit zero limits are
respected (null = no cap, 0 = cap at zero).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: dgjlindsay

Api/Config/RepositoryInterface.php

@@ -46,6 +46,7 @@ interface RepositoryInterface
     public const XML_PATH_SURCHARGE_DIFFERENTIAL = 'payment/two_payment/surcharge_differential';
     public const XML_PATH_SURCHARGE_LINE_DESCRIPTION = 'payment/two_payment/surcharge_line_description';
     public const XML_PATH_SURCHARGE_TAX_RATE = 'payment/two_payment/surcharge_tax_rate';
+    public const XML_PATH_SURCHARGE_FIXED_CURRENCY = 'payment/two_payment/surcharge_fixed_currency';
     public const XML_PATH_DEFAULT_PRODUCT_TAX_CLASS = 'tax/classes/default_product_tax_class';
     public const XML_PATH_VERSION = 'payment/two_payment/version';
     public const XML_PATH_DEBUG = 'payment/two_payment/debug';
@@ -352,7 +353,18 @@ public function getSurchargeTaxRate(?int $storeId = null): float;
      * @param int $days
      * @param int|null $storeId
      *
-     * @return array{percentage: int, fixed: int, limit: float}
+     * @return array{percentage: int, fixed: int, limit: float|null}
      */
     public function getSurchargeConfig(int $days, ?int $storeId = null): array;
+
+    /**
+     * Get the currency code in which surcharge fixed amounts were saved.
+     *
+     * Returns empty string if no currency was recorded (legacy data).
+     *
+     * @param int|null $storeId
+     *
+     * @return string
+     */
+    public function getSurchargeFixedCurrency(?int $storeId = null): string;
 }

Block/Adminhtml/System/Config/Field/SurchargeGrid.php

@@ -11,6 +11,7 @@
 use Magento\Config\Block\System\Config\Form\Field;
 use Magento\Framework\App\Config\ScopeConfigInterface;
 use Magento\Framework\Data\Form\Element\AbstractElement;
+use Magento\Store\Model\StoreManagerInterface;
 use Two\Gateway\Api\Config\RepositoryInterface as ConfigRepository;
 
 /**
@@ -28,6 +29,9 @@ class SurchargeGrid extends Field
     /** @var ScopeConfigInterface */
     private $scopeConfig;
 
+    /** @var StoreManagerInterface */
+    private $storeManager;
+
     /** @var string */
     private $scope = 'default';
 
@@ -37,10 +41,12 @@ class SurchargeGrid extends Field
     public function __construct(
         Context $context,
         ScopeConfigInterface $scopeConfig,
+        StoreManagerInterface $storeManager,
         array $data = []
     ) {
         parent::__construct($context, $data);
         $this->scopeConfig = $scopeConfig;
+        $this->storeManager = $storeManager;
     }
 
     /**
@@ -115,6 +121,26 @@ public function getMaxPercentage(): int
         return ConfigRepository::SURCHARGE_PERCENTAGE_MAX;
     }
 
+    /**
+     * Get the base currency code for the current scope.
+     */
+    public function getBaseCurrencyCode(): string
+    {
+        if ($this->scope !== 'default' && $this->scopeId > 0) {
+            try {
+                if ($this->scope === 'stores') {
+                    return $this->storeManager->getStore($this->scopeId)->getBaseCurrencyCode();
+                }
+                if ($this->scope === 'websites') {
+                    return $this->storeManager->getWebsite($this->scopeId)->getBaseCurrencyCode();
+                }
+            } catch (\Exception $e) {
+                // Fall through to default
+            }
+        }
+        return (string)$this->scopeConfig->getValue('currency/options/base') ?: 'USD';
+    }
+
     /**
      * Get the HTML field name for a surcharge input.
      *

Model/Config/Backend/SurchargeGrid.php

@@ -16,6 +16,7 @@
 use Magento\Framework\App\Cache\TypeListInterface;
 use Magento\Framework\Model\ResourceModel\AbstractResource;
 use Magento\Framework\Data\Collection\AbstractDb;
+use Magento\Store\Model\StoreManagerInterface;
 use Two\Gateway\Api\Config\RepositoryInterface as ConfigRepository;
 
 /**
@@ -32,18 +33,23 @@ class SurchargeGrid extends Value
     /** @var WriterInterface */
     private $configWriter;
 
+    /** @var StoreManagerInterface */
+    private $storeManager;
+
     public function __construct(
         Context $context,
         Registry $registry,
         ScopeConfigInterface $config,
         TypeListInterface $cacheTypeList,
         WriterInterface $configWriter,
+        StoreManagerInterface $storeManager,
         AbstractResource $resource = null,
         AbstractDb $resourceCollection = null,
         array $data = []
     ) {
         parent::__construct($context, $registry, $config, $cacheTypeList, $resource, $resourceCollection, $data);
         $this->configWriter = $configWriter;
+        $this->storeManager = $storeManager;
     }
 
     /**
@@ -116,9 +122,39 @@ public function afterSave()
             }
         }
 
+        // Persist the base currency so fixed amounts remain meaningful
+        // even if the store's default currency changes later
+        $currencyCode = $this->resolveBaseCurrency($scope, $scopeId);
+        $this->configWriter->save(
+            ConfigRepository::XML_PATH_SURCHARGE_FIXED_CURRENCY,
+            $currencyCode,
+            $scope,
+            $scopeId
+        );
+
         return parent::afterSave();
     }
 
+    /**
+     * Get the base currency for the scope being saved.
+     */
+    private function resolveBaseCurrency(string $scope, int $scopeId): string
+    {
+        try {
+            if ($scope === 'stores' && $scopeId > 0) {
+                return $this->storeManager->getStore($scopeId)->getBaseCurrencyCode();
+            }
+            if ($scope === 'websites' && $scopeId > 0) {
+                return $this->storeManager->getWebsite($scopeId)->getBaseCurrencyCode();
+            }
+        } catch (\Exception $e) {
+            // Fall through to global default
+        }
+        return (string)$this->getFieldsetDataValue('currency/options/base')
+            ?: (string)$this->_config->getValue('currency/options/base')
+            ?: 'USD';
+    }
+
     /**
      * Validate a surcharge field value.
      *

Model/Config/Repository.php

@@ -492,10 +492,19 @@ public function getDefaultTaxRate(?int $storeId = null): float
     public function getSurchargeConfig(int $days, ?int $storeId = null): array
     {
         $prefix = sprintf('payment/two_payment/surcharge_%d_', $days);
+        $limitValue = $this->getConfig($prefix . 'limit', $storeId);
         return [
             'percentage' => (int)$this->getConfig($prefix . 'percentage', $storeId),
             'fixed' => (int)$this->getConfig($prefix . 'fixed', $storeId),
-            'limit' => (float)$this->getConfig($prefix . 'limit', $storeId),
+            'limit' => $limitValue !== null ? (float)$limitValue : null,
         ];
     }
+
+    /**
+     * @inheritDoc
+     */
+    public function getSurchargeFixedCurrency(?int $storeId = null): string
+    {
+        return (string)$this->getConfig(self::XML_PATH_SURCHARGE_FIXED_CURRENCY, $storeId);
+    }
 }

Service/Order/ComposeOrder.php

@@ -71,6 +71,7 @@ public function execute(Order $order, string $orderReference, array $additionalD
                 (float)$order->getGrandTotal(),
                 $selectedTermDays,
                 $buyerCountry,
+                $order->getOrderCurrencyCode(),
                 $storeId
             );
 

Service/Order/SurchargeCalculator.php

@@ -7,6 +7,8 @@
 
 namespace Two\Gateway\Service\Order;
 
+use Magento\Directory\Model\CurrencyFactory;
+use Magento\Framework\Exception\LocalizedException;
 use Two\Gateway\Api\Config\RepositoryInterface as ConfigRepository;
 use Two\Gateway\Api\Log\RepositoryInterface as LogRepository;
 use Two\Gateway\Model\Config\Source\SurchargeType;
@@ -38,14 +40,21 @@ class SurchargeCalculator
      */
     private $logRepository;
 
+    /**
+     * @var CurrencyFactory
+     */
+    private $currencyFactory;
+
     public function __construct(
         ConfigRepository $configRepository,
         Adapter $apiAdapter,
-        LogRepository $logRepository
+        LogRepository $logRepository,
+        CurrencyFactory $currencyFactory
     ) {
         $this->configRepository = $configRepository;
         $this->apiAdapter = $apiAdapter;
         $this->logRepository = $logRepository;
+        $this->currencyFactory = $currencyFactory;
     }
 
     /**
@@ -54,14 +63,17 @@ public function __construct(
      * @param float $grossAmount Order gross amount
      * @param int $selectedTermDays The term the buyer selected
      * @param string $buyerCountry ISO Alpha-2 country code
+     * @param string $orderCurrency ISO currency code of the order
      * @param int|null $storeId
      *
      * @return array{amount: float, tax_rate: float, description: string}
+     * @throws LocalizedException if fixed fee currency conversion fails
      */
     public function calculate(
         float $grossAmount,
         int $selectedTermDays,
         string $buyerCountry,
+        string $orderCurrency,
         ?int $storeId = null
     ): array {
         $surchargeType = $this->configRepository->getSurchargeType($storeId);
@@ -72,6 +84,7 @@ public function calculate(
 
         $feeBase = $this->getFeeBase($grossAmount, $selectedTermDays, $buyerCountry, $storeId);
         $config = $this->configRepository->getSurchargeConfig($selectedTermDays, $storeId);
+        $fixedCurrency = $this->configRepository->getSurchargeFixedCurrency($storeId);
 
         $surcharge = 0.0;
 
@@ -82,12 +95,17 @@ public function calculate(
             $surcharge += $feeBase * ($config['percentage'] / 100);
         }
         if ($hasFixed) {
-            $surcharge += $config['fixed'];
+            $fixedAmount = (float)$config['fixed'];
+            $surcharge += $this->convertAmount($fixedAmount, $fixedCurrency, $orderCurrency);
         }
 
-        // Apply limit cap
-        if ($config['limit'] > 0 && $surcharge > $config['limit']) {
-            $surcharge = $config['limit'];
+        // Apply limit cap (null = not set = no cap; 0 = explicit zero cap)
+        $limit = $config['limit'];
+        if ($limit !== null) {
+            $limit = $this->convertAmount($limit, $fixedCurrency, $orderCurrency);
+            if ($surcharge > $limit) {
+                $surcharge = $limit;
+            }
         }
 
         // Round up to next cent
@@ -98,6 +116,8 @@ public function calculate(
             'fee_base' => $feeBase,
             'surcharge_type' => $surchargeType,
             'config' => $config,
+            'fixed_currency' => $fixedCurrency,
+            'order_currency' => $orderCurrency,
             'result' => $surcharge,
         ]);
 
@@ -160,4 +180,30 @@ private function fetchMerchantFee(
 
         return (float)($response['total_fee'] ?? 0);
     }
+
+    /**
+     * Convert an amount between currencies if needed.
+     *
+     * @throws LocalizedException if Magento has no exchange rate for the pair
+     */
+    private function convertAmount(float $amount, string $fromCurrency, string $toCurrency): float
+    {
+        if ($amount == 0 || $fromCurrency === '' || $fromCurrency === $toCurrency) {
+            return $amount;
+        }
+
+        try {
+            $currency = $this->currencyFactory->create()->load($fromCurrency);
+            return (float)$currency->convert($amount, $toCurrency);
+        } catch (\Exception $e) {
+            throw new LocalizedException(
+                __(
+                    'Cannot convert surcharge from %1 to %2. '
+                    . 'Please configure currency exchange rates under Stores > Currency Rates.',
+                    $fromCurrency,
+                    $toCurrency
+                )
+            );
+        }
+    }
 }