Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

PaymentAddress 'region' inconsistencies #663

Open
TSMatthews opened this issue Dec 15, 2017 · 32 comments

Comments

@TSMatthews
Copy link

commented Dec 15, 2017

I'm having a number of issues integrating our checkout with the payment request API when it comes to shipping options / shipping address forms. These centre around the address 'region', e.g. 'CA' in the US.

Project info / requirement
To give some background, I have a requirement to have shipping options that are available to certain regions within a country. This could be for legal reasons, e.g. in the US, only being able to ship certain goods to certain states. I must therefore, verify user inputted address region values against our shipping options when determining which shipping options to pass to the payment request interface.

Lack of 'region' input
Depending on the country however, sometimes the region is mandatory (US, Australia), optional (Ireland), missing (Qatar). Can this field be mandatory for all countries? (i.e. we would need 'region' to be mandatory in all cases so we can verify our shipping options against the user's country and state)

Inconsistency of input type and value
For both address forms that could be used, i.e. billing and shipping, the value retrieved from the user is not in a consistent format, in terms of input type and response value. On web browsers (as far as I've tested), the region is a dropdown. However, depending on the country, the value returned is not consistent, e.g. it's a 2 letter code such as 'CA' for the US, state name such as 'Delhi' for India, and 'Co. Dublin' for Ireland.

On mobile browsers (and possibly some web, but generally mobile), the 'region' is a free form input, so the customer could enter anything essentially, e.g. 'CA', 'California', 'Californnn'. In this case, we have no direct solution for mapping this value.

Overall solution proposal

  • 'Region' is mandatory.
  • 'Region' returns the state as a 2 letter code (ISO 3166-2), from a pre-defined set of values.
@rsolomakhin

This comment has been minimized.

Copy link
Collaborator

commented Dec 15, 2017

Two-letter codes could work for India using the isoid field. However, our Australia data has three-letter abbreviations for states. Moreover, our Ireland data shows some isoid fields with a one letter instead of two.

As for requiring the region in every country, from what I understand, that does not work well in all countries. For example, Google's address in Ireland is "Barrow St, Dublin 4". I do not have to specify the "Co. Dublin" county in order for my package to be delivered there.

All that being said, we can do a better job of normalizing addresses that we return from the browser. I definitely agree that Chrome should not be returning "Californnn" in the API.

@lararennie @roubert @sebsg

@TSMatthews

This comment has been minimized.

Copy link
Author

commented Dec 18, 2017

Thanks for your response.

Three letter codes would be fine for Australia. Even 1 letter codes for Ireland - if the response values were always consistent and therefore an expected value.

I understand what you mean in terms of requiring the region in every country maybe not working the best. I am actually located in Ireland, and you are correct, we don't always need the county (however that is only in Dublin where there is Dublin 1, 2, 3, 4, etc.). Therefore, we are used to always stating our county also on most address forms, or making our addresses fit online forms.

If these addresses were just for reference / printing on a shipping label, there would be no issue. It really is that need to validate addresses against regions, especially in countries where it is common for merchants to only ship to certain regions within a country. Coming from a country where our addresses don't usually fit online address forms (also only introduced postcodes in the last year or two), I don't think it is much effort for users to enter their region once off in their browser saved address, as they would then have all the benefits of using payment request checkout thereafter.

@rsolomakhin

This comment has been minimized.

Copy link
Collaborator

commented Dec 18, 2017

Those are all very good points. What should we do for countries that don't use regions (e.g., Denmark)?

Denmark address input screenshot

@marcoscaceres

This comment has been minimized.

Copy link
Member

commented Dec 19, 2017

I think this is again a quality of implementation issue, but possibly something we need to add more guidance on in the spec. The browser should be validating region/state information based on the user's country choice... and some countries need to have a mandatory state option, like in Australia.

Would that work?

@oconnortmaster

This comment has been minimized.

Copy link

commented Dec 19, 2017

The issue I have with the 'quality of implementation issue' argument is that this is what has been the issue in the past where vendors implement a spec somewhat differently according to their own interpretations, which is the case at point.

This has led to small or sometimes very large differences in the implementation, that the developer community has to negotiate around, leading to a typically bloated codebase being pushed down the wire to end users and the expense that comes with that to all parties. This leads to slow adoption of the API by the developer community or in a worst case scenario, prohibits adoption altogether which is definitely something we don't want to see.

I would definitely add guidance to the spec, but would probably like something more prescriptive as to the required attributes in a PaymentAddress response.
The PaymentAddress doesn't state that a country is a required attribute, so however unlikely it is, an implementation could in theory omit this value in the response and render the whole PaymentAddress useless as it would be too ambiguous to decide which is the correct address.

I propose that we indicate what is required or non nullable to the interface for certain attributes in the PaymentAddress, specifically (country, addressLine, city & recipient). For the 'region' attribute, the guidance should be updated to return an ISO 3166 code also, otherwise null for countries such as Denmark as noted above.

What do you think?

@TSMatthews

This comment has been minimized.

Copy link
Author

commented Dec 19, 2017

Countries that don't use regions shouldn't be an issue. If we refer to our main issue which is validating a shipping address's region against the regions in that country for selecting region specific shipping options - we wouldn't have this issue for a country with no regions, as the shipping options would not be region specific.

However, just while on topic - I have seen that for the Qatari address form, there is no 'region' when regions are in use in Qatar https://en.wikipedia.org/wiki/ISO_3166-2:QA, where I have requests from merchants for shipping options defined for certain regions. It seems to be the same for Denmark https://en.wikipedia.org/wiki/ISO_3166-2:DK.

@marcoscaceres

This comment has been minimized.

Copy link
Member

commented Dec 20, 2017

It sounds like mandating ISO 3166-2 for region would be the way to go (where applicable) - and null or empty string otherwise.

@aestes, @adrianba, @rsolomakhin, @mnoorenberghe, @zkoch... it's a fairly significant change to implementations, but it does resolve a potential huge mess for merchants who would otherwise get a bunch of different values (as @TSMatthews points out).

This is what browsers do now:

  • Chrome: region is always a free-form text input field, right @rsolomakhin?
  • Microsoft Pay: provides a drop-down in certain cases (e.g., Australia and Canada)... but not in others (e.g., Argentina allows for free form input for province) and but doesn't follow ISO 3166-2.
  • Safari/ApplePay: free-form input field.
  • Firefox: plan was to make it text input.

If there is agreement that ISO 3166-2 is the way to go, then I can add this to #654

@rsolomakhin

This comment has been minimized.

Copy link
Collaborator

commented Dec 20, 2017

@marcoscaceres: The ISO codes would be OK for us. @sebsg: Can we use the "isoid" field for normalization where possible?

@rsolomakhin

This comment has been minimized.

Copy link
Collaborator

commented Dec 20, 2017

@marcoscaceres: Would it be better to introduce an additional "region_iso_id" field to avoid breaking existing users of the API?

@marcoscaceres

This comment has been minimized.

Copy link
Member

commented Dec 20, 2017

Could be, but it would still leave region potentially too unrealiable to be useful and add a vector for error (the two might not agree or browser’s language might not match site’s language, leading to confusion). That might be ok tho.

@sebsg

This comment has been minimized.

Copy link

commented Dec 20, 2017

@rsolomakhin

This comment has been minimized.

Copy link
Collaborator

commented Dec 20, 2017

Empty string is fine.

@marcoscaceres

This comment has been minimized.

Copy link
Member

commented Dec 20, 2017

agree, that’s what we do with the rest of them.

@rsolomakhin

This comment has been minimized.

Copy link
Collaborator

commented Dec 20, 2017

@sebsg : That's empty string for the "region_iso_id" field, to be clear. No changes to the "region" field.

@sebsg

This comment has been minimized.

Copy link

commented Dec 20, 2017

@marcoscaceres

This comment has been minimized.

Copy link
Member

commented Dec 20, 2017

  • cough * regionCode * cough * 🤧😇
@rsolomakhin

This comment has been minimized.

Copy link
Collaborator

commented Dec 20, 2017

that works

@marcoscaceres

This comment has been minimized.

Copy link
Member

commented Dec 20, 2017

Ok cool, I’ll draft something up.

@marcoscaceres

This comment has been minimized.

Copy link
Member

commented Dec 20, 2017

@TSMatthews, would appreciate your thoughts also as we proceeded. I’ll ping you also for review if that’s ok?

@TSMatthews

This comment has been minimized.

Copy link
Author

commented Dec 20, 2017

@marcoscaceres happy to review.

Just to clarify on the addition of the new field (regionCode / region_iso_id) - is this now the field that will be mapped to from the 'region' dropdown on the UI (if there are regions for the country in question)? Want to be clear how both of these fields - 'region' and 'regionCode' would coexist and what we collect from the user.

As a note, chrome was mentioned above as always being a free form input for region - seems to be dropdown on web with mapped values (inconsistent format depending on country), input on mobile.

@adrianba

This comment has been minimized.

Copy link
Contributor

commented Dec 21, 2017

Sorry for the delay - not many people about in the office at the moment for some reason...

This is what browsers do now:

  • Chrome: region is always a free-form text input field, right @rsolomakhin?
  • Microsoft Pay: provides a drop-down in certain cases (e.g., Australia and Canada)... but not in others (e.g., Argentina allows for free form input for province) and but doesn't follow ISO 3166-2.
  • Safari/ApplePay: free-form input field.
  • Firefox: plan was to make it text input.

Right now, Microsoft Pay adheres to Microsoft-wide GeoPol standards. It's not out of the question for us to change but is going to require conversations with a bunch of teams so we'll have to investigate in the New Year.

@marcoscaceres

This comment has been minimized.

Copy link
Member

commented Jan 24, 2018

@TSMatthews, sorry for the delay... just coming back to this now:

Just to clarify on the addition of the new field (regionCode / region_iso_id) - is this now the field that will be mapped to from the 'region' dropdown on the UI (if there are regions for the country in question)? Want to be clear how both of these fields - 'region' and 'regionCode' would coexist and what we collect from the user.

  • region would be either what the browser presented to the user in the drop down, or whatever the user typed in (so, remains fairly unreliable... but might see convergence across browsers over time).
  • regionCode would be the ISO 3166-2 code, or empty string when it can't be determined.

At least regionCode should help address most inconsistency issues you identified, with region serving as a fallback in the worst of cases.

Could that work?

@marcoscaceres

This comment has been minimized.

Copy link
Member

commented Jan 24, 2018

@TSMatthews I've staged the changes here:
ab1ba80

If you prefer to read them in HTML, please see #654 (there is a "preview" link at the top, but includes all the changes I'm planing to make to PaymentAddress... just search for regionCode).

@TSMatthews

This comment has been minimized.

Copy link
Author

commented Jan 26, 2018

@marcoscaceres Thank you.

'regionCode' does seem like it will help the inconsistency issues as it must be valid ISO3166-2.

Just so I am clear.. the forms could still have 'region' or 'regionCode' right? And it's really up to the browser vendors to implement it?

We would not have 'regionCode' being an expected field returned from every address form? 'regionCode' solves inconsistency of value issues, but if it's not a mandatory field, it won't fix our issue that we always need this value (original post -> need region as consistent data and always present, so that we can verify against shipping rules / options specific to certain regions).

@sebsg

This comment has been minimized.

Copy link

commented Jan 26, 2018

@mnoorenberghe

This comment has been minimized.

Copy link
Contributor

commented Jan 26, 2018

Firefox: plan was to make it text input.

We planned to use dropdowns backed by the ISO 3166-2 codes but that didn't get implemented yet… not sure what we'll ship for an MVP. We do already try to normalize to the region codes where possible e.g. we know that California => CA.

@TSMatthews It's still not clear to me from the discussion whether you are expecting the regionCode to be populated in countries where the region isn't used in a mailing address? e.g. Belgium. You said it's not an issue for countries with no regions but I'm talking about countries with regions which aren't used in mailing addresses.

@stpeter

This comment has been minimized.

Copy link

commented Mar 2, 2018

@sebsg You wrote: "We have the data for most countries and I'm trying to get the data for the rest." Is this an open-source dataset (or standardized registry) that other implementations can use? A common approach would help reduce user confusion across browsers.

@mnoorenberghe The original posting from @TSMatthews mentioned shipping options, so it seems that we wouldn't necessarily need to gather the regionCode in places like Belgium that don't require regions for mail delivery. However, supporting that level of nuance adds a further level of business logic to the code, and it seems easier to gather the regionCode if the country has defined regions in the dataset / registry. What do you think?

@mnoorenberghe

This comment has been minimized.

Copy link
Contributor

commented Mar 16, 2018

@sebsg You wrote: "We have the data for most countries and I'm trying to get the data for the rest." Is this an open-source dataset (or standardized registry) that other implementations can use? A common approach would help reduce user confusion across browsers.

IIUC, it's from https://github.com/googlei18n/libaddressinput/wiki/AddressValidationMetadata and it's what we use in Fx already.

@mnoorenberghe The original posting from @TSMatthews mentioned shipping options, so it seems that we wouldn't necessarily need to gather the regionCode in places like Belgium that don't require regions for mail delivery. However, supporting that level of nuance adds a further level of business logic to the code, and it seems easier to gather the regionCode if the country has defined regions in the dataset / registry. What do you think?

Shipping options require knowing two things:

  1. Can I ship to this address (taking into account regional laws)?
  2. How much are the shipping options?

My point is that in order to know (1), you may need to know the region if there are regional laws (e.g. if one province in Belgium prohibits the purchasing of ivory).

libaddressinput doesn't currently have regions for Belgium and indicates that they're not required for mailing labels so it's easiest for us to pretend they don't exist but I'm trying to get this understanding standardized as I don't want some browsers returning regions for Belgium and others not.

@marcoscaceres

This comment has been minimized.

Copy link
Member

commented Apr 30, 2018

@mnoorenberghe,

libaddressinput doesn't currently have regions for Belgium and indicates that they're not required for mailing labels so it's easiest for us to pretend they don't exist but I'm trying to get this understanding standardized as I don't want some browsers returning regions for Belgium and others not.

I don't know if we can standardize that behavior. That seems overly prescriptive and would be too closely tied to libaddressinput (which neither Edge or Safari rely on).

PaymentAddress CTor automation moved this from To Do to Done May 16, 2018

@mnoorenberghe

This comment has been minimized.

Copy link
Contributor

commented May 16, 2018

@mnoorenberghe,

libaddressinput doesn't currently have regions for Belgium and indicates that they're not required for mailing labels so it's easiest for us to pretend they don't exist but I'm trying to get this understanding standardized as I don't want some browsers returning regions for Belgium and others not.

@marcoscaceres

I don't know if we can standardize that behavior. That seems overly prescriptive and would be too closely tied to libaddressinput (which neither Edge or Safari rely on).

Sorry, just noticed this reply now…

What I'm talking about isn't tied to libaddressinput at all. It's tied to whether the country writes subdivisions as part of their mailing address (e.g. on an envelope). Since users won't expect to be asked to select their subdivision for a shipping address in some countries that don't use them for mailing, I expect that in Firefox we won't show a subdivision field and therefore won't populate the region or regionCode fields for those countries such as Belgium, Germany, etc. Perhaps the spec and/or MDN should be more clear that an empty string can be valid for mailing purposes.

@marcoscaceres

This comment has been minimized.

Copy link
Member

commented May 16, 2018

Perhaps the spec and/or MDN should be more clear that an empty string can be valid for mailing purposes.

Good point. I'll spin up a separate issue to clarify!

@marcoscaceres

This comment has been minimized.

Copy link
Member

commented Jan 22, 2019

We failed to get this implemented across UAs in a timely manner, but we remain committed to having this in the spec.

Our plan is to remove regionCode from V1 of the spec, but immediately add it back as v1.1 of the spec. We hope that will buy implementers some time to implement the feature, but without delaying the standardization process.

@marcoscaceres marcoscaceres referenced a pull request that will close this issue Feb 21, 2019

Open

Add regionCode attribute to PaymentAddress #836

2 of 8 tasks complete
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
8 participants
You can’t perform that action at this time.