Frequently Asked Questions (FAQ) / Support

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

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
1. 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:
  1. US (United States of America)
  2. CN (China)
2. 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.

Modern browsers are being updated to increase performance and security. In recent months, Google Chrome and Apple’s Safari have made significant changes to how cookies are managed by default within the browsers. If you are using cookies as part of your checkout flow, you may be impacted. For information on the impacts and remediations, please refer to our Technical Bulletins.

Title	Technical Bulletin

Title	Technical Bulletin
Google Chrome SameSite cookie changes
Safari, iPad, and iOS Cookie Changes

NOTE: Use of a WebView to render a 3-D Secure challenge within a native application is not an officially supported integration. This will limit Cardinal’s supportability and it is strongly advised to utilize the native Cardinal Mobile SDK for APP based transactions.

In Android versions following the release of Android 5.0 (Lollipop), you must explicitly set the permissions allowed within the rendered WebView control. One occurrence of these permissions where we have seen the impact on the 3DS challenge flow is allowable third party cookies. If the ACS is using cookies to track user sessions and render the challenge screens, the lack of this permission will prevent the content from rendering and likely will result in a blank screen.

In order to alleviate this issue, when rendering your WebView control, you will need to use the setAcceptThirdPartyCookies method within the CookieManager to establish this permission.

This logic may look similar to the following:

// Accept Third Party Cookies
CookieManager cookieManager = CookieManager.getInstance();
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.LOLLIPOP) {
    cookieManager.setAcceptThirdPartyCookies(webView, true);
}
// else { 
// it's always true for API version below 5.0 (Lollipop) 
// }

Production environment:

kg668dbov0.execute-api.us-east-1.amazonaws.com
writer.cardinalcommerce.com
includes.ccdc02.com
songbird.cardinalcommerce.com
centinelapi.cardinalcommerce.com
hostedfields.cardinalcommerce.com
https://geo.cardinalcommerce.com
https://0geo.cardinalcommerce.com
https://1geo.cardinalcommerce.com

Staging environment:

kg668dbov0.execute-api.us-east-1.amazonaws.com
writer.cardinalcommerce.com
includestest.ccdc02.com
songbirdstag.cardinalcommerce.com
centinelapistag.cardinalcommerce.com
hostedfieldsstag.cardinalcommerce.com
geostag.cardinalcommerce.com
0geostag.cardinalcommerce.com
1geostag.cardinalcommerce.com

Cardinal strongly discourages adding the wildcard domain *.cardinalcommerce.com to an allowlist in the staging environment.

Merchants are required to pass the Amount and Currency Code on the Lookup Request. Amount needs to be sent without any decimals for any currency and depending on the Currency Code, Centinel will retrieve the correct Purchase Exponent (or, ISO Minor Unit), apply it to the Amount and set the value on the AReq.