SAP Commerce Cloud Integration Guide

Download plugin here

This document is a high-level technical document which provides a guidance on the installation process of the Loqate Address Lookup extension on the SAP Commerce.


The expected audience for this document is technical specialists who will be involved in Loqate integration into SAP Commerce Cloud. These specialists are expected to be familiar with the SAP Commerce Cloud platform and installing extensions/add-ons for it. 

Supported Environments

This add-on is designed and tested with B2C version 1905 of SAP Commerce Cloud.

Supported in Extension

Extension for Loqate integration supports the address Lookup feature. The extension is designed utilizing the SAP integration patterns offered on the platform and tested against the standard B2C accelerator offered by SAP. 

How to use this document

This document is split largely into two sections – the first explaining the installation process and the second demonstrating how to use the Loqate Address Lookup extension. There’s also a short final section detailing some mitigation steps for Log4j2 vulnerabilities.

If this is your first time working through this guide then we recommend you start at the beginning and take it step by step, to make sure you cover everything. If you want to look for a specific section however, you can use the links below:


Add-on Installation Steps

Download Add-on

  • Get the addon pack from Loqate.
  • Unpack and copy the folders loqateaddon, loqatebackofficeext, loqatewebservices into custom folder of SAP Commerce Suite (<HYBRIS_HOME>/bin/custom)

Update localextension.xml

  • Add extension <extension name= loqateaddon />
  • Add extension <extension name= loqatebackofficeext />
  • Add extension <extension name= loqatewebservices />
  • Check the presence of the target storefront extension
  • Other OOB(Out-of-Box) extensions required are mentioned in the localextension.xml available in archive (Sample and localextensions.xml is available in config folder)

Run installation command

  • Stop Hybris server if already running. Depending on the server start mode we can use one of following method to stop Hybris server.
    • If the Hybris server was started with embedded mode, press Ctrl+C to stop Hybris server
    • If the Hybris server was stared with service mode, use this command to stop:
      • Windows: hybrisserver.bat stop
      • Unix: ./ stop

  • Go to <HYBRIS_HOME>/bin/platform and run the following command if it was not applied in this terminal:
    • Windows: setantenv.bat
    • Unix: ./

  • Go to <HYBRIS_HOME>/bin/platform and run the installation add-on with the command:
    Install the addon as below
    ant addoninstall -Daddonnames="loqateaddon" -

  • Depending on the project, the storefront name may differ from the default storefront name that is provided by Hybris.

OOB Code Changes

List of files that are changed as a part of Loqate extension will be available in OOB folder in hybris/config/customize/modules folder.

The following OOB extensions need to be modified for the Loqate feature: 

  • yacceleratorstorefront
  • acceleratorstorefrontcommons
  • commercefacades
  • acceleratorservices

Storefront Changes

OOB yacceleratorstorefront is used as the template storefront for Loqate add-on development. Below files are updated for Loqate Address lookup capture and verification. If merchant application is using any custom files, update the same with the changes for Loqate from below file list.

yacceleratorstorefront files: 

  • accountAddressBookPage.jsp 
  • addressFormElements.tag 
  • addressFormSelector.tag 
  • billAddressFormSelector.tag 
  • billingAddressFormElements.tag 
  • billingAddressFormElements.tag 
  • silentOrderPostPage.jsp        

acceleratorstorefrontcommons files: 


commercefacades files: 

  • commercefacades-beans.xml           

acceleratorservices files: 


Rebuild System

  1. Go to <HYBRIS_HOME>/bin/platform and rebuild the system with the command: ant clean all.

    Note: ant customize all will also be required if you are using OOB storefront.
    This will copy the OOB file from hybris/config/customize/ to respective OOB folder i.e., hybris/bin/modules.

Update the system

If you have already performed full initialization, then you need to update your Hybris system as follows:

  • Open web browser, go to HAC → Platform → Update
  • Check the 3 checkboxes under General Settings:
    • Update running system, create essential data, Localize types.

  • Check the loqateaddon, loqatebackofficeext, loqatewebservices checkbox further down under Project data settings.

  • Click on the Update button to update the Hybris system.

Loqate Configuration

In order to get started, we need to create an account in Loqate:

Once your account is created, you need to create services which can be configured to SAP Hybris forms associated to MyAccount, Shipping and Billing pages.  

These services are split up into two groupings: 

  • Address Validation 
  • Email and Phone Validation 

Address Validation 

Follow these steps to set up address validation on both your Shipping and Billing pages in SAP Hybris. 

Shipping page 

  • Click on Add Service in your newly created account. 

  • Click on Start setup to add services. 

  • Next, select platform as Website.

  • In the URL section provide the URL of the Shipping Page. Here's an example:

  • When you click the Next button, a script is generated – note this down, as this code needs to be included in some of the tags files that will need to be configured. 

  • Click on Launch in-page setup for further configuration, and for mapping the Loqate fields with SAP Hybris form attributes. 

Once you’ve done that, you will see this page:

You will also see the following error message – don’t worry, this is fine. 

  • Click continue the setup directly on your site link.


This will now navigate to the Shipping page of your SAP Hybris application, where you will see the Loqate widget on the right-hand side of the screen. This will automatically detect your Hybris fields and allow you to map them to Loqate fields. 

You have two options for adding a new service – you can either select one of the services shown on the right-hand side and click Configure, or scroll to the bottom of the page on the right-hand side, select the Add another service drop-down and choose a service. 

Click on Address Validation to configure lookup feature.

  • This will take you to a form which will allow you to map the appropriate fields. 
    • Your Fields correspond to SAP Hybris Form Attributes. 
    • Our Fields corresponds to Loqate Attributes. 

  • Once you start mapping, the widget will recognize the attributes in the form and highlight them in Green. This means that the current configuration is being applied to the field. 

  • Once the configuration is done, click on the Done button and then Save button to create the services. 

  • Here is a sample Address Validation service configuration that is applied to the Shipping page of SAP Hybris: 


Billing page 

Like the Shipping page, services need to be created and configuration needs to be applied for the Billing page. Repeat the process, using the URL of your Billing page. 

Here’s an example of what that might look like: 

  • Following the same steps for adding a new service and launching the in-page setup, the Loqate widget will appear on your Billing page, where you can configure the address validation for your payment section. 


  • Here is a sample configuration applied for the payment section: 

Email and Cell phone validation 

Next you need to configure Email and Cell phone validation, using essentially the same process. 

From the in-page setup screen, you can select the Email validation and Cell phone validation options, again either from the drop-down at the bottom of the page or the individual service options: 


  • Here’s an example Cell phone validation configuration: 

  • Here’s an example Email validation configuration: 


  • Note that the Email and Cell phone validation services only need to be configured for the Shipping page. 


Altogether there are four services which need configuring. Please make sure that you don’t create any additional services/API keys apart from what is required.  

If you do create any additional services, you can delete them via the Dashboard page in your Loqate account ( 


 HAC Configuration

There are some configurations that need to be applied through HAC. Details can be configured in 

Sample is available in the config folder. 

  • loqate.script: the script which was generated in Loqate (see Loqate Configuration section) while creating new services, which needs to be included in SAP Hybris forms. 

  • geolocation.enabled: the property which turns on or off address validation using the Geolocation feature.

  • hybris.loqate.countrymap: the property which contains a mapping between Hybris and Loqate country codes. This property is used for limiting/restricting address searches based on the countries which users select. 

The following properties should all be present in 

Property Key: 


OOB Payment Mock URL 

Property Value: 


Property Key: 



Loqate Script which need to be included in forms 

Property Value: 

(function(n,t,i,r){var u,f;n[i]=n[i]||{},n[i].initial={accountCode:"CMPNYXXXXX",host:""},n[i].on=n[i].on||function(){(n[i].onq=n[i].onq||[]).push(arguments)},u=t.createElement("script"),u.async=!0,u.src=r,f=t.getElementsByTagName("script")[0],f.parentNode.insertBefore(u,f)})(window,document,"pca","//") 

Property Key: 



API details of Geolocation 

Property Value: 


Property Key: 



API details of Find 

Property Value: 

Property Key: 



API details of Retrieve 

Property Value: 

Property Key: 



Loqate Verify API 

Property Value: 

Property Key: 



Switch to enable/disable Geolocation 

Property Value: 


Property Key: 



Other configuration 

Property Value: 


Property Key: 



Geolocation key 

Property Value: 


Property Key: 


Other configuration 

Property Value: 


Property Key: 



Switch to enable/disable Verify Logic 

Property Value: 


Property Key: 


Other configuration 

Property Value: 

"Select CountryCode,AL-Albania,AD-Andorra,AT-Austria,BY-Belarus,BE-Belgium,BA-Bosnia and Herzegovina,BG-Bulgaria,CA-Canada,CN-China,HR-Croatia,CY-Cyprus,CZ-Czech Republic,DK-Denmark,EE-Estonia,FO-Faroe Islands,FI-Finland,FR-France,DE-Germany,GI-Gibraltar,GR-Greece,GL-Greenland,GG-Guernsey,VA-Holy See (Vatican City State),HK-Hong Kong, China,HU-Hungary,IS-Iceland,IE-Ireland,IM-Isle of Man,IT-Italy,JP-Japan,JE-Jersey,KP-Korea, Democratic People's Republic of,KR-Korea, Republic of,LV-Latvia,LI-Liechtenstein,LT-Lithuania,LU-Luxembourg,MO-Macao, China,MK-Macedonia,MT-Malta,MD-Moldova,MC-Monaco,ME-Montenegro,NL-Netherlands,NO-Norway,PL-Poland,PT-Portugal,RO-Romania,RU-Russian Federation,SM-San Marino,RS-Serbia,SK-Slovakia,SI-Slovenia,ES-Spain,SE-Sweden,CH-Switzerland,TW-Taiwan, China,TR-Turkey,UA-Ukraine,GB-United Kingdom,US-UnitedStates,VN-Viet Nam" 

Property Key: 



Other configuration 

Property Value: 

"Select PhoneCode,+355-Albania,+376-Andorra,+43-Austria,+375-Belarus,+32-Belgium,+387-Bosnia and Herzegovina,+359-Bulgaria,+1-Canada,+86-China,+385-Croatia,+357-Cyprus,+420-Czech Republic,+45-Denmark,+372-Estonia,+298-Faroe Islands,+358-Finland,+33-France,+49-Germany,+350-Gibraltar,+30-Greece,+299-Greenland,+44-1481-Guernsey,+379-Holy See (Vatican City State),+852-Hong Kong, China,+36-Hungary,+354-Iceland,+353-Ireland,+44-1624-Isle of Man,+39-Italy,+81-Japan,+44-1534-Jersey,+82-Korea, Democratic People's Republic of,+82-Korea, Republic of,+371-Latvia,+423-Liechtenstein,+423-Lithuania,+352-Luxembourg,+853-Macao, China,+389-Macedonia,+356-Malta,+373-Moldova,+377-Monaco,+382-Montenegro,+31-Netherlands,+47-Norway,+48-Poland,+351-Portugal,+40-Romania,+7-Russian Federation,+378-San Marino,+381-Serbia,+421-Slovakia,+386-Slovenia,+34-Spain,+46-Sweden,+41-Switzerland,+886-Taiwan, China,+90-Turkey,+380-Ukraine,+44-United Kingdom,+1-UnitedStates,+84-Viet Nam" 

Property Key: 

prod.envirnoment.enabled = false 


Geolocation related attribute 

Property Value: 



Also, the of loqateaddon should have the following configurations: 

  • loqateaddon.javascript.paths.responsive=/responsive/common/js/loqateaddon.js;/responsive/common/js/intlTelInput.js 

  • loqateaddon.css.paths.responsive=/responsive/common/css/loqateaddon.css;/responsive/common/css/intlTelInput.css 


 Backoffice Configuration [Optional - recommended on Demo to leave this feature off]

The following steps are optional and only required if you configure the Find Address feature using the Geolocation attributes like latitude and longitude. 

To enable the Geolocation search, you need to turn on the geolocation.enabled flag through HAC (as mentioned in the previous step). By default, this feature is turned off, and the latitude and longitude search will not be displayed in forms. 

Configurations related to Geolocation 

  • Navigate to Backoffice, where on the left-hand side you can find the Loqate section. 

  • Click on Loqate to expand this section, and you will see Loqate Configurations

  • Click on the + button to create a new Geolocation configuration. 
  • Fill in all the fields on the following form: 


Attribute details and descriptions

Attribute Description
Loqate Environment This will have either value as Test or Live
accountcode The Loqate account code value for the particular environment 
accountHost The Loqate account host value for the particular environment 
accountURL The Loqate account URL value for the particular environment 
geolocationAPIUrl The Loqate Geolocation API URL for the particular environment
geolocationAPIKey The Loqate Geolocation API Key value for the particular environment


  • Here is a sample configuration for a Geolocation: 

Phone Validation Change

Implementing a phone number - country flag integration on the Shipping, Billing and My Address pages requires a third-party open-source JavaScript/jQuery plugin called International Telephone Input (a plugin for entering and validating international telephone numbers). This adds a flag dropdown to any input, displays a relevant placeholder, and provides formatting/validation methods. It is also widely known as intl-tel-input. 

  • You will need to integrated the following necessary scripts/styles/images of the plugin into SAP Commerce: 


Files associated


How to use: the Shipping Page

ere we will demonstrate how Loqate functionality works on the Shipping page, starting with UK addresses before moving on to US addresses. 

UK addresses 

Navigate to the Shipping page and select UNITED KINGDOM from the COUNTRY/REGION drop-down. This will load the address form related to the UK: 

  • When a user starts entering details into the ADDRESS LINE 1 field, events will be triggered, and the lookup will return suggestions for the address being entered (using UK address data). Here’s an example of what that looks like: 

  • Once the user selects an address from the lookup, the remaining fields like ADDRESS LINE 2, CITY, POST CODE etc. will be automatically populated based on the address that the user selected. 

  • Users can also make Post Code lookups - when they start to enter a value into the POST CODE field, suggestions will be returned in the same way. Here’s an example: 


  • Selecting a suggested address will populate the remaining fields. 


US addresses 

If a user selects UNITED STATES from the COUNTRY/REGION drop-down, this will change the form to display US-specific fields. 

  • Any lookups that the user makes now will pull through US results.

  • Selecting an address from the list of suggestions will automatically populate the remaining fields, including STATE/PROVINCE. 


Phone Number Validation for Shipping Page

The PHONE NUMBER field contains a country flag and country code, which by default will be loaded based on the country selected from the COUNTRY/REGION drop-down list. Here’s how that looks for the US, and the UK: 

  • When a user manually enters a country code, the corresponding flag will automatically display in the PHONE NUMBER field. Here’s an example: 

  • Likewise, if a customer manually changes the flag icon, the corresponding country code will automatically display: 

  • When a correct phone number is entered, a green tick icon will display on the right-hand side of the field. 

Email Validation for Shipping Page

The Loqate email validation tool will clearly show whether an entered email is valid or not. 

  • An invalid email address will display a red cross icon on the right-hand side of the field: 

  • A valid email address will display a green tick icon on the right-hand side of the field: 

Address validation for the Shipping page 

If the loqate.verify.enabled flag is set to TRUE, the Loqate Address Verification tool will be enabled, and will call the Loqate Verify API to validate the user’s address: 


This occurs when user submits the Shipping page. The ADDRESS LINE 1, ADDRESS LINE 2, CITY and ZIP/POSTAL CODE (or POST CODE in the UK) fields will be populated based on the response of the Verify API, and this will be submitted to Backend for further processing. 

Geolocation [Optional: recommended on Demo to leave this feature off] 

To enable this option, navigate to HAC and search for the geolocation.enabled flag. By default, the value is set to false. 

  • Set this flag to true In order to turn on the Geolocation Find Address feature.

  • Once this is on, you will see the following section appearing in Address forms. This allows the user to search for an address based on its Latitude/Longitude. 

  • To use this, enter Latitude and Longitude details into the appropriate fields and click on FIND ADDRESS.

  • Address suggestions will be returned based on the Lat and Long details provided: 

  • When the user selects and address, this will automatically populate the corresponding address fields as normal: 


How to use: the Billing Page

By default, when a user navigates to Billing page, the USE MY DELIVERY ADDRESS checkbox is checked, and any data that was entered in the Shipping page is carried over to the Payment page. 

However, a user can uncheck this option if they want and enter a different billing address.  

If this is the case, the user can complete the form on the Billing page in exactly the same way as on the Shipping page (see above for full details).


How to use: My Account Page

This page allows users to save addresses to their accounts. This follows many of the same steps as the previous pages. 

  • From the My Account page, click the Add Address button: 

  • This brings up the Add Address form: 

  • As with the Shipping and Billing pages, the option users select from the COUNTRY/REGION drop-down list will determine how the fields are named on the form (i.e. UK customers will see POST CODE, US customers will see ZIP/POSTAL CODE, etc.). 

  • When the user starts entering details in ADDRESS LINE 1, the lookup will return suggestions for the address being entered (based on the country selected). Here’s an example of what that looks like: 

  • When the User selects an address from the lookup, the remaining fields will be automatically populated based on the address the user chose. 

  • Similarly, there is also a lookup available for POST CODE or ZIPCODE/POSTAL CODE: 


  • When user selects a suggested address, the remaining fields will be automatically populated: 

  • Once the address is saved, the user is taken to the Edit Address page

  • Phone Number and Email validation are available on the My Account page, in the same way as they are on the Shipping and Billing pages: 

  • The Geolocation feature is also available on the My Account page, and is controlled using the same flag (geolocation.enabled) as on the Shipping and Billing pages: 


Log4j2 vulnerability (CVE-2021-44228)

On Dec 9, 2021 a very serious vulnerability in the popular Java-based logging package Log4j was disclosed. This vulnerability allows an attacker to execute code on a remote server - a so-called Remote Code Execution (RCE). Because of the widespread use of Java and Log4j this is likely one of the most serious vulnerabilities on the Internet.It is CVE-2021-44228 and affects version 2 of Log4j between versions 2.0-beta-9 and 2.14.1. It is patched in 2.15.0. 

How to mitigate CVE-2021-44228 

The change is not specific to the Loqate cartridge, and the jar comes with the OOB Sap Commerce package. This change does not have any custom code change specific to Loqate. 

You can check the following in case you haven’t already handled any mitigation steps for CVE-2021-44228. 

NOTE: Please note that the below version was recommended earlier and might change to handle some of the other log4j CVE’s. However, the steps remain the same. Details regarding this are mentioned in the section below. 

Temporary Mitigation 

If you are using Log4j v2.10 or above, and cannot upgrade, then set the property:  

  • log4j2.formatMsgNoLookups=true 

Additionally, you can set an environment variable for these same affected versions: 


Or remove the JndiLookup class from the classpath. For example, you can run a command like this to remove the class from the log4j-core: 

  • zip -q -d log4j-core-*.jar org/apache/logging/log4j/core/lookup/JndiLookup.class 

PatternLayout patterns can be modified to specify the message converter as %m{nolookups} instead of just %m.  

  • For releases >=2.0-beta9 and <=2.10.0 this is not a recommended strategy as it will likely result in a long-term vulnerability 

Hybris Commerce Package comes with log4j versions2.13.3 in its latest version (2105/2011) and2.9.1version in older version (1905) 


Permanent mitigation 

When the following steps are applied, you can verify whether this solution has worked by checking that there are no issues in start-up after updating the log4j jars. 

  • Take a backup of the three existing jars (i.e. log4j-api, log4j-core and log4j-slf4-impl) from here: 
  • -\hybris\bin\platform\ext.\core\lib 
  • Replace the jars with the latest one (i.e. 2.16.0) 
  • Start the Hybris server and validate for any errors while starting up 

Here are the repo locations from where you can download the log4j related jars: 

Here are some external articles which provide useful additional information on this issue: 

Other Log4j CVEs 

While CVE-2021-44228 is the most notable Log4j vulnerability, there are a few others that you should be aware of. 

Log4j Vulnerability CVE-2021-44832  

A medium severity vulnerability which lets an attacker with control over the Log4j configuration set a malicious data source for the JDBC appender.  

The data source refers to an attacker-controlled JNDI URI that will execute arbitrary code on the application using Log4j.  

Although this is a Code Execution attack, it demands a crucial precondition: the attacker must have permissions to modify the log4j.xml file, which should only be available to a highly privileged actor. Alternatively, it requires an attacker to spoof a remote server from which the application imports the log4j.xml file, only if the application uses a remote log4j.xml file in the first place, and if it imports the file using an insecure connection (HTTP). 

Since there is a very low chance of all these conditions coming together to allow an attack, the vulnerability was given a medium vulnerability score, which rates it as a Highly Complex attack, with High Privileges needed. 

Mitigation: if you are using the Log4j 2.17.x branch for Java 8 and later, upgrade to 2.17.1. 


Log4j Vulnerability CVE-2021-45105 (16 Dec)  

Fixed in Log4j 2.17.0, 2.12.3 and 2.3.1 

Apache Log4j2 versions 2.0-alpha1 through 2.16.0 (excluding 2.12.3) did not protect from uncontrolled recursion from self-referential lookups.  

When the logging configuration uses a non-default Pattern Layout with a Context Lookup (for example, $${ctx:loginId}), attackers with control over Thread Context Map (MDC) input data can craft malicious input data that contains a recursive lookup, resulting in a StackOverflowError (runtime error that cannot be caught by an application.  

StackOverflowError indicates that the application stack is exhausted, and is usually caused by deep or infinite recursion that will terminate the process. This is also known as a DOS (Denial of Service) attack. 

Mitigation: upgrade to Log4j 2.3.1 (for Java 6), 2.12.3 (for Java 7), or 2.17.0 (for Java 8 and later).


Log4j Vulnerability CVE-2021-45046 (14 Dec) 

Fixed in Log4j 2.16.0 (Java 8) and 2.12.2 (Java 7) 

It was found that the fix to address CVE-2021-44228 in Apache Log4j 2.15.0 was incomplete in certain non-default configurations.  

When the logging configuration uses a non-default Pattern Layout with a Context Lookup (for example, $${ctx:loginId}), attackers with control over Thread Context Map (MDC) input data can craft malicious input data using a JNDI Lookup pattern, resulting in an information leak, remote code execution in some environments and local code execution in all environments. 

Mitigation: upgrade to Log4j 2.3.1 (for Java 6), 2.12.3 (for Java 7), or 2.17.0 (for Java 8 and later). 

Additional resources: