Requirement for state setting in Paypal modules, for certain countries?

Hello,
This is a question about whether to se address_state as used for Paypal Express Checkout (paypalwpp.php) and Paypal Website Payments Pro (paypaldp.php), and if so, how best one might set it for Japanese states (prefectures):

General Information about my setup:
* URL: My site is currently not available publicly (Japanese version development in progress).
* ZenCart version: 1.5.5e
* Server OS: Linux 4.13.0-1-amd64
* HTTP Server: nginx/1.13.6
* PHP Version: 7.0.22-3 (Zend: 3.0.0)
* Database: MySQL 5.5.5-10.1.28-MariaDB-1
* Plugins: Multi Language EZ Pages, Multi Language Country Names
* Other: Japanese language module, ported from 1.5.1-jp and in development (Ref: Future Japanese language pack thread: https://www.zen-cart.com/showthread....5-5-and-beyond).

In paypalwpp.php (and paypaldp.php) the function setStateAndCountry sets the state (not country as far as I can tell, which is already defined by the 2-letter ISO code by this stage apparently) to send to Paypal:

Code:

---

  /**
  * Set the state field depending on what PayPal requires for that country.
  * The shipping address state or province is required if the address is in one of the following countries: Argentina, Brazil, Canada, China, Indonesia, India, Japan, Mexico, Thailand, USA
  * https://developer.paypal.com/docs/classic/api/state_codes/
  */
  function setStateAndCountry(&$info) {
    global $db, $messageStack;
    switch ($info['country']['iso_code_2']) {
      case 'AU':
      case 'US':
      case 'CA':
      // Paypal only accepts two character state/province codes for some countries.
      if (strlen($info['state']) > 2) {
        $sql = "SELECT zone_code FROM " . TABLE_ZONES . " WHERE zone_name = :zoneName";
        $sql = $db->bindVars($sql, ':zoneName', $info['state'], 'string');
        $state = $db->Execute($sql);
        if (!$state->EOF) {
          $info['state'] = $state->fields['zone_code'];
        } else {
          $messageStack->add_session('header', MODULE_PAYMENT_PAYPALWPP_TEXT_STATE_ERROR, 'error');
          $this->terminateEC(MODULE_PAYMENT_PAYPALWPP_TEXT_STATE_ERROR);
        }
      }
      break;
      case 'AT':
      case 'BE':
      case 'FR':
      case 'DE':
      case 'CH':
      $info['state'] = '';
      break;
      case 'GB':
      break;
      default:
      $info['state'] = '';
    }
  }

---

Questions:

1. Is the state required for the countries on the list in the comment section? Japan is on the list, but not in the switch statement.
2. If so, it seems that except for Australia. USA and Canada, the state is not being set. I cannot identify if there are differences in the behaviour for other countries listed there (GB seeems to break without setting anything, although how this is different from setting an empty string I don't understand).
3. In particular, I am wanting to identify if the state needs to be set for Japan (and if so, how to best go about that).

Looking at Paypal NVP/SOAP API documents, I do not find any information about whether address_state is required (on the other hand, I do see that regarding countries, for some countries setting the country code is required, but most do not appear to be). However, if one does set the state, Paypal docs show that for Japan the code to be sent must be in capital letters as follows:
Most are of the pattern <NAME>-KEN, plus the special cases HOKKAIDO, OSAKA-FU, KYOTO-FU and TOKYO-TO.

Now, if one does not need to send the names, all is fine, but if one does need to send them, then there is an issue that the code required for Paypal does not match the code best suited for address and other uses in Zen Cart.
Additionally, since I have made country names and zone (=state) names multi-language, depending on the language chosen for viewing the website (English or Japanese), the state code would be either in English or in Japanese.

One way to work around this I guess would be to put the Paypal-required state name in the ZONES table, while the language-dependent zone names are in the new extended ZONES tables (ZONES_NAME in my case). A bit of a hack, as it requires the implementation of multi-language zones first. Or else to create a new lookup table for the Paypal module to use.
Even better would be (providing I understand correctly) if Paypal would use ISO codes for the states, like they want for countries. In that case the original ZONES could be extended to include the ISO code, or extended multi language ZONES table could be used (I created it containing the state ISO code) regardless of language.

Any advice, explanations (regarding the status of the modules, for example), other tips much appreciated.
Reference: https://developer.paypal.com/docs/cl...i/state_codes/

Gernot Hassenpflug

The requirement of including the state code appears to depend on the process being used in submitting data to PayPal. Dug a little into express checkout (randomly selected NVP as the transfer method https://developer.paypal.com/docs/cl...Operation_NVP/) and was looking at specifically DoExpressCheckoutPayment which indicates that if an item is being shipped then the state code is needed for Japan (see: PAYMENTREQUEST_n_SHIPTOSTATE).

As to where to store the State Code(s) and observation of the above switch statement, basically the GB state code that is provided is unaltered, the US, AU, and CA codes are forced to a 2-character value that is stored in the database, the remaining are set to blank. Should Japan be in that list to be otherwise manipulated? Maybe and it is in conversations like this and further support that such changes get made. Ie. if no one has tried, asked, or found a solution for Japan, then it won't get incorporated. :)

Wherever the information for the state(s) is stored, it will need to be maintained up-to-date. Seeing that the designations appear to be PayPal related, I would think something directly related to PayPal and not some zone table or other location where another application may look and get confused...

Argh, looks like my reply disappeared. Short version.
Many thanks!
From what you write, it seems there is some information already when the above function operates. I don't understand what the initial information is that the switch statement is working on. Does Paypal provide state_address, and Zen Cart uses that, or modifies it, to do some internal processing later?
If there is incoming information, I presume for testing at least this could be ignored by Zen Cart (and would be, for Japan, since JP is not in the switch statement list). I presume Paypal works for Japan, since there have been posts since 2006 or so about this, with fixes to zip code processing, etc.
If state code really should/must be known inside Zen Cart to the same specs as Paypal, then as you say, a Paypal-specific table would make sense.
I am more than happy to work on this, and also to clarify in module documents what the Paypal module's assumptions/restrictions are at present.

Selecting content from the browser on the Paypal API docs page gives an easy to parse formatted list of state names and codes.
Similarly for countries, but I assume for now that all countries and their 2-letter ISO codes are already in Zen Cart.

Initial proposal for Paypal-specific tables to support state names:

1. paypal_country_names table:
paypal_country_id
paypal_country_countries_iso_code_2 <- from countries table (but could be maintained separately if required)
paypal_country_postal_code_required <- Paypal requirement here (required for some countries, not required for most)
paypal_country_name

2. paypal_state_names table:
paypal_state_id
paypal_state_countries_iso_code_2 <- identifier for country, from countries table (or from paypal_country_names table if need to maintain separately)
paypal_state_name <- not used, so could be from Zen Cart zones table, or separately maintained
paypal_state_code <- Paypal requirement here (code is actually just a Paypal-specific state name, using Latin but with accents)

Maybe better to combine two tables in one, but postal code requirement (and possible country name) will then be copied for each state.

Addendum, it seems that for those states where no state code is supplied in the Paypal API, the state name is required and this then must be exactly as written in the Paypal API (e.g., for Thailand). Thus paypal_state_name would be required as well, and maintained separately from Zen Cart zones.

Uploaded definitions for Paypal countries and states as individual Paypal-specific tables.
Not sure about:
1. How to specify the id for the table, and whether it should be in the unique index definition.
2. Whether to relate to Zen Cart zones and countries tables. Currently only ISO 2-letter code is the link, and relies on this being the same in countries table in order to find match with paypal_countries/paypal_states table(s).