Magento 2 PayPal Smart Buttons: German Shipping Fails Due to Region Code Mismatch (BW vs BAW)

A critical issue has surfaced for Magento Open Source 2.4.8-p5 users leveraging PayPal Smart Buttons, particularly affecting express checkout for German customers. The problem, detailed in GitHub issue #41774, highlights a discrepancy in region codes between PayPal's standard ISO 3166-2 identifiers and Magento's internal directory data, leading to failed shipping callbacks and a frustrating checkout experience.

The core of the problem lies with German addresses, specifically those in Baden-Württemberg. When a customer attempts an express checkout via the PayPal Smart Button on a Product Detail Page (PDP) and selects a German shipping address in Baden-Württemberg, PayPal sends the region code as BW (its ISO 3166-2 subdivision suffix). However, Magento's default directory_country_region table, as defined in vendor/magento/module-directory/Setup/Patch/Data/InitializeDirectoryData.php, stores Baden-Württemberg under the code BAW.

This mismatch causes the shipping callback in vendor/magento/module-payment-services-paypal/Model/ShippingCallback/AddressValidator.php to fail. Specifically, the loadByCode('BW', 'DE') call returns no region, triggering a STATE_ERROR. The result is an HTTP 422 response to PayPal, which then displays delivery restriction messages like "Your order cannot be shipped to this county," preventing the customer from proceeding with the purchase.

The issue author, in-session, meticulously investigated the problem, confirming that Magento's internal region lookup does not account for the commonly used ISO 3166-2 codes provided by external services like PayPal. This isn't a case of missing or custom region configuration but a fundamental difference in how region identifiers are stored and expected.

While the immediate impact is on German addresses, the discussion in the comments section raises a significant concern: this underlying issue could affect other countries where Magento's region codes diverge from ISO 3166-2 identifiers. This suggests a broader architectural challenge for Magento's region data handling in the context of international e-commerce and third-party integrations.

The proposed long-term solution involves enhancing Magento's region data structure to include a dedicated ISO 3166-2 identifier field, preserving existing codes for backward compatibility. This would provide a standardized mapping that could benefit all integrations – from payment gateways to shipping carriers – ensuring consistent region resolution across the Magento ecosystem.

For developers and merchants facing this issue now, a temporary workaround has been provided. It involves modifying the getRegionIdByCode() method within vendor/magento/module-payment-services-paypal/Model/ShippingCallback/AddressValidator.php to include a mapping for German ISO subdivision codes to Magento's internal region codes. This ensures that when PayPal sends BW, Magento correctly translates it to BAW (and similarly for other German regions).


    private function getRegionIdByCode(?string $regionCode, ?string $countryId): int
    {
        try {
            if ($regi null || $countryId === null) {
                throw new LocalizedException(__('STATE_ERROR'));
            }
            // Temporary fix: German ISO subdivision codes to Magento region codes.
            if ($countryId === 'DE') {
                $regi
                    'BW' => 'BAW',
                    'BY' => 'BAY',
                    'BE' => 'BER',
                    'BB' => 'BRG',
                    'HB' => 'BRE',
                    'HH' => 'HAM',
                    'HE' => 'HES',
                    'MV' => 'MEC',
                    'NI' => 'NDS',
                    'NW' => 'NRW',
                    'RP' => 'RHE',
                    'SL' => 'SAR',
                    'SN' => 'SAS',
                    'ST' => 'SAC',
                    'SH' => 'SCN',
                    'TH' => 'THE',
                ][$regionCode] ?? $regionCode;
            }
            $region = $this->regionFactory->create()->loadByCode($regionCode, $countryId);
            
            // PayPal may provide the full region name instead of a code.
            if (!$region->getRegionId()) {
                $region = $this->regionFactory->create()->loadByName(
                    $regionCode,
                    $countryId
                );
            }
        } catch (Exception $exception) {
            $this->logger->error("Failed to find region for given code", [
                'exception_message' => $exception->getMessage(),
                'region_code' => $regionCode
            ]);
            return 0;
        }

        return (int) $region->getRegionId();
    }

This workaround, while effective for Germany, is not a general international solution and would need to be maintained as a Composer patch until an official upstream fix is released. For Magento merchants and developers, this issue underscores the importance of robust internationalization and the need for standardized data handling across various e-commerce components and third-party services.

Start with the tools

Explore migration tools

See options, compare methods, and pick the path that fits your store.

Explore migration tools