The BillingState field within the Lookup request message follows the ISO 3166-2 format per the EMV® 3DS specification. To review the specific Subdivision codes for each Country, it is recommended you review the listings on the ISO Online Browsing Platform (OBP). This can be located at: https://www.iso.org/obp/ui#home. In order to locate the Country listing, be sure to select “Country Codes” from the radio button options prior to searching for the Country name you are seeking. The results will display pertinent information for the matching Country values, including the Subdivision codes (provinces, districts, municipalities, etc).
Example of the ISO 3166 standards information presented by the Online Browsing Platform (OBP) -
At the bottom of each Country Code search result page, you will also be shown a Change history of country code. This is beneficial to review past values as they relate to the present values listed above.
Example of the Change history of country code (China - CN) -
In all cases, it is strongly recommended that the values presented in the BillingState field are reflected as the 3166-2 code as indicated by the ISO specification. This field, per EMV 3DS specification, allows for up to 3 character alphanumeric values AN(3). The expected format for this field will be the value following the hyphen in the 3166-2 code. For example the ISO 3166-2 code for Ohio is US-OH; the value expected to be passed in to BillingState would be OH.
Examples of mapping ISO 3166-2 code to BillingState field -
3166-2 code | Expected BillingState field value |
---|
US-OH | OH |
CN-AH | AH |
GB-LND | LND |
In the next section, we will cover additional considerations when applying logic to the BillingState field value.
Additional Considerations:
Understand when to populate BillingState and when to leave it blank
Certain downstream providers have strict validation on the values in BillingState as they relate to the Billing Country. If the value provided does not match the ISO 3166 specification of 3166-2 codes related to the Country, you may experience authentication errors. Due to this, if there is uncertainty in the format of the value for BillingState, it is recommended not to pass a value. However, certain Country values are identified as requiring a value for BillingState. At this time, these Country values are known to require BillingState:
US (United States of America)
CN (China)
Do NOT pass a placeholder value such as “NA” to satisfy perceived required validation while indicating not applicable. This will present issues with downstream providers.
Due to known downstream format validation, it is recommended the BillingState value be provided in upper case capitalization, if the value contains alpha characters i.e. OH instead of oh.
Based on the ISO Change history of country code for CN (China) on 2017-11-23 the specification was modified to move all subdivision codes for CN from numeric to alpha. The numeric values are still accepted by downstream providers and should still be considered valid on the authentication message.
EMV® is a registered trademark in the U.S. and other countries and an unregistered trademark elsewhere. The EMV trademark is owned by EMVCo, LLC.