eShopWorldeCommerceSolutions MagentoExtensionUserManual · l Package 2.0 integration for eShopWorld orders. l Logs configuration. 2.3.0 August 2019 Added Checkout 2.0 pricing advisor

Version: 2.4.1

Published date: May 2020

Copyright © 2020 by eShopWorld. All rights reserved. Information contained herein is subject tochange without notice.

eShopWorld eCommerce Solutions

Magento Extension User Manual

Table of Contents1 About this document 1

1.1 Intended audience 1

1.2 Document revision history 1

2 Overview 4

2.1 Features 4

2.1.1 Out of scope 5

2.2 Magento Extension and eShopWorld Checkout flow 5

3 How does it work? 7

3.1 Retailer Platform and eShopWorld Checkout Flow 7

3.2 Pricing Models 8

3.3 Pricing API (hosted by eShopWorld) 8

3.4 Checkout API (hosted by eShopWorld) 10

3.4.1 Process Flow 10

3.5 Order Confirmation Request (hosted by retailer) 10

3.5.1 Process Flow 10

3.6 Package Integration 11

3.6.1 Hub model 11

3.6.1.1 Hub model flow 13

3.6.1.2 Cron synchronization 16

3.6.1.3 Administration interface 17

- i -

3.6.2 Ship from Store (Hubless model) 18

3.6.2.1 Ship from Store flow 19

3.7 Returns Integration 22

3.7.1 Magento Entity Types 23

3.7.1.1 Credit Memo 23

3.7.1.2 Return Merchandise Authorization (RMA) 23

3.8 Catalog Integration 24

3.8.1 Triggering catalog exports 25

4 Getting Started 26

4.1 Installing the extension 26

4.2 Verifying the installation 27

4.3 Accessing the extension 27

4.4 Viewing configuration 27

5 Configuring Magento 29

5.1 Setting up Magento for the Fixed price model 29

5.1.1 Country and Currency setup 29

5.2 Setting up Magento for the Calculated Pricing model 29

5.2.1 Prerequisites 29

5.2.2 Country and currency setup 30

5 Working with the eShopWorld extension 32

6 Security Token Service 34

7 Checkout 35

- ii -

7.1 General Configuration 35

7.2 Pricing Advisor Feed Configuration 36

7.3 Country – Currency Mapping 37

7.4 Retailer Display Configuration 38

7.5 Pricing Configuration 40

7.6 Product Metadata Items 41

7.7 Preorder URL Configuration 43

7.8 Order Confirmation Configuration 44

8 Order Fulfillment 46


8.2 Package/ASN Configuration 46

8.3 Returns Configuration 48

9 Catalog 50


10 Logs 52


10.2 Logs Cleaning 52

11 Shipping Rates 53

11.1 Add new rates 53

11.1.1 Rate Information 54

11.1.2 Conditions 55

12 Extension Logs 56

- iii -

13 Order Confirmation 57

13.1 Order Confirmation v2.0 57

13.1.1 eShopWorld Order 57

13.1.2 eShopWorld Order Items 62

13.1.3 eShopWorld Order Cart Discounts 68

14 Information for Developers 71

14.1 Setting up the Varnish cache 71

14.2 Setting up the package reference 72

14.2.1 Package reference in the Magento Shipment API 73

14.3 Cookies 73

14.4 Extension API 74

14.4.1 REST APIs 74

14.4.1.1 Guest checkout request 74

14.4.1.2 Logged in user checkout request 74

14.4.2 GraphQL API 75

14.4.2.1 Checkout request 75

14.4.3 Set shipping country used by extension in API call 75

14.5 Frontend widget customization 76

14.5.1 Welcome mat 76

14.5.2 Footer 77

14.6 Catalog asynchronous integration for Magento Commerce Cloud 77

14.6.1 Get eShopWorld calculated price 77

- iv -

15 Troubleshooting 79

15.1 Extension not appearing on the dashboard 79

- v -

1 About this documentThis document provides an overview of the eShopWorld Magento extension and provides instructions on how to install and use the extension. For the latest version of this document, go to the eShopWorld Developer Portal.

1.1 Intended audienceThis document is intended for developers who want to integrate the eShopWorld Magento extension with their existing e-commerce platform.

1.2 Document revision historyVersion Date Description

2.0.1 December 2018 Created the initial version for v2 of the extension. Also added Loyalty Card Number to the Order Confirmation 1.1 request.

2.1.0 March 2019

New features added:

l Basic authentication on order confirmation point.

l Ability to set custom order confirmation URL.

l Paid order status option for new order creation.

l Country configuration to match the eShopWorld checkout display, including saving tax on item-level for countries where tax is added at the eShopWorld checkout.

l Multi-website support.

Enhancements to existing features:

l FX shipping overrides with conditions.

l FX model working with native Magento func-tionality cart discounts with pricing rules and fixed tier pricing.

- 1 -

https://devportal.eshopworld.com/docs/magento-overview

Version Date Description

l Added FX pricing model support for bundle and group product types.

2.2.0 May 2019

New features added:

l Checkout 2.0 fixed price support.

l Package 2.0 integration for eShopWorld orders.

l Logs configuration.

2.3.0 August 2019 Added Checkout 2.0 pricing advisor support.

2.3.5 March 2020

New features added:

l Order fulfillment and details on package integ-ration for the Hub and Hubless (Ship from Store) shipping models.

l Returns integration.

l Setting the package reference for the Hub ship-ping model.

l Added the new Developer section.

l Setting the package reference for the Hub ship-ping model.

l Renamed the FX pricing model to Calculated.

l Updated the Catalog Integration in How does it work.

2.4.0 April 2020 Added Asynchronous operations for Commerce Cloud.

2.4.1 May 2020

l Added Product Metadata Items under Checkout and removed Preorder Expansion Pairs.

l Updated the General Configuration screenshot under Catalog.

- 2 -

Version Date Description

l Added REST APIs and GraphQL API sections to the Information for Developers.

l Updated the welcome mat and footer images in Information for Developers > Frontend widget cus-tomization.

l Changed the 'Asynchronous operations for Magento Commerce Cloud' heading title to 'Cata-log asynchronous integration for Magento Com-merce Cloud'.

l Updated Shipping Rates with information on adding new rates.

- 3 -

2 OvervieweShopWorld's Magento extension integration allows retailers to get access to a network of 25+ global carriers, 40+ global hubs, multiple PSPs and acquirers, 40+ payment methods, 100+ currencies, multilingual checkout, and much more.

The eShopWorld Magento extension creates a seamless international shopping experience with an optimized journey per shipping country. Magento’s cart is integrated with eShopWorld’s hosted checkout, providing a seamless shopping journey to international shoppers.

The eShopWorld Magento extension supports Magento® Community and Enterprise editions 2.2.x and 2.3.x.

2.1 FeaturesThe following are some of the features of the eShopWorld Magento extension:

l Cross-border shoppers are automatically provided with local prices in their currency across the Magento shopping experience through eShopWorld’s GeoIP implementation.

l Registered shoppers benefit from faster checkout by utilizing saved data within the eShopWorld hosted checkout.

l Retailers can enable the eShopWorld landing mat and country/language selectors so that shoppers can change their country and language preferences. Multi-language sup-port is integrated via Magento’s language configuration and eShopWorld’s hosted checkout.

l Tax and duty display options can be set to maximized conversion rate with eShopWorld’s Pricing Advisor. Tax and duty are updated in Magento once an order is placed to reflect the breakdown of order details based on the actual order.

l Pricing is natively integrated with Magento allowing the full support of catalog and cart price rules.

l Shipping rules per country can be configured within the extension. Additionally, retailers can configure the countries that they want their native checkout to support and the coun-tries that will utilize eShopWorld’s optimized international checkout.

- 4 -

l Payment options are provided on the eShopWorld hosted checkout. These options are optimized for each market. Once the payment is made, the order is created in Magento and the Order Confirmation page is displayed to the shoppers.

2.1.1 Out of scope

The following features are out of the scope of the extension:

l Cart price rules for shipping: The extension does not support shopping cart price rules for shipping.

l Checkout UI customization: Checkout is a module that the eShopWorld extension integ-rates with, but UI cannot be customized from within the extension configuration. A guide is provided to the retailers regarding UI customization and is defined during the scoping stage of eShopWorld integration.

l Checkout configuration: The eShopWorld extension has a dependency on the con-figuration by eShopWorld. The extension can only enable configurations that have already been enabled on eShopWorld’s Checkout module, for example:

l Additional countries and currencies.

l Shipping methods - configured to support overrides within eShopWorld’s services to allow overrides to apply.

l Payment methods (the payment methods cannot be controlled from within the exten-sion).

l Gift Cards: The extension does not support gift cards.

l Native Magento tax rules: The extension currently does not support native Magento tax rules.

2.2 Magento Extension and eShopWorld Checkout flowThe following figure explains the flow between the Magento extension and eShopWorld Checkout.

- 5 -

- 6 -

3 How does it work?This chapter describes the following topics:

l Retailer Platform and eShopWorld Checkout Flow

l Pricing Models

l Pricing API

l Checkout API

l Order Confirmation Request

l Package Integration

l Returns Integration

3.1 Retailer Platform and eShopWorld Checkout FloweShopWorld's hosted cross-border checkout collects shopper data, such as delivery, product, and pricing information. It processes the payment and creates an order on the eShopWorld platform and the retailer's e-commerce engine. For more information on the eShopWorld Checkout and the features, click here.

To use eShopWorld’s optimized international hosted checkout, retailers must have a tenant set up by eShopWorld. A tenant contains retailer-specific configuration and provides services, such as hosted checkout, logistics service configuration, and inter-national country setup, which are unique to each retailer. eShopWorld provides the tenant information to the retailers during their onboarding.

The following figure describes the flow between the retailer's platform and eShopWorld checkout:

- 7 -

https://devportal.eshopworld.com/docs/platform-components

3.2 Pricing ModelsA pricing model defines how the in-country product price is displayed on the site. Pricing models can be defined per country. The eShopWorld Magento extension supports the following pricing models:

l Calculated pricing model: In this model, in most cases, the product base price is exclus-ive of any taxes. This model uses the Pricing Advisor API. The base price is taken from Magento's native base price field and formulas are applied to this value to display the loc-alized price to shoppers.

l Fixed price model: In this model, in most cases, the product price is inclusive of all taxes. Prices are taken from the native Magento price fields.

3.3 Pricing API (hosted by eShopWorld)Pricing Advisor is a collection of services that provide a maintenance-free pricing solution for the international markets.

- 8 -

Key features include:

l Pricing Advisor API: A service that sets the uplift, estimated tax, estimated duty, foreign exchange, and rounding rules per shipping country. These values are set up during the scoping phase and are unique to each retailer.

l Pricing Advisor Magento Synchronization: A synchronization service that is included with the Magento extension. This service updates daily foreign exchange, uplift, estimated tax, estimated duty, and rounding rules.

l Pricing Advisor Magento Configuration: An interface that sets the prices for each shipping country in Magento.

l Pricing Advisor Magento Price Display: A feature that displays updated prices across Magento based on the pricing advisor for the international market.

l Pricing Advisor Checkout Integration: A feature that sends the prices set up by the pricing advisor to the eShopWorld’s hosted checkout to facilitate end-to-end flow.

- 9 -

3.4 Checkout API (hosted by eShopWorld)The information that is passed from the retailer's site to the eShopWorld Checkout is called the Checkout API (or Preorder) request. This payload provides the order data that relates to a shopper's cart. There are two types of checkout flows:

l eShopWorld supported countries, where the shopper cuts across to the eShopWorld Checkout.

l Traditional or domestic e-commerce platform flow for non-eShopWorld supported countries.

3.4.1 Process Flow

The following steps explain the process flow:

1. When a shopper clicks Proceed to Checkout after adding products to their cart, a call is made to the Checkout API.

2. On success, an eShopWorld redirect URL is passed in the response and the shopper is redirected to the eShopWorld checkout. On failure, the shopper remains on the retailer’s cart page.

3.5 Order Confirmation Request (hosted by retailer)The extension provides an API endpoint for the eShopWorld system to send a request with order confirmation to the retailer's system, which is called the Order Confirmation API. The URL is {domain}/eShopWorld/order/confirm.

3.5.1 Process Flow

The following steps explain the process flow:

1. When a shopper clicks Pay Now, the payment is processed, and an Order Confirmation API payload is sent by the eShopWorld system to the Order Confirmation API endpoint containing the product, shipping, service level, and payment data for the order.

2. When the Order Confirmation request is received by this endpoint:

1. The request data is validated.

2. A search for the checkout order number is made in the database to make sure it

- 10 -

exists.

3. When found, the request data is persisted into the retailer's e-commerce platform.

3. On success, the Order Confirmation endpoint sends a response to the eShopWorld sys-tem indicating that the order confirmation action is successful, and the order is created on the eShopWorld platform. The shopper is then presented with the Order Confirmation page. On failure, the shopper is redirected to a failure notification URL supplied by the retailer. No order is created on the retailer's platform or the eShopWorld platform.

3.6 Package Integration eShopWorld provides a range of models, including Hub and Ship from Store for retailers to fulfill orders. Each model has a different order process flow.

3.6.1 Hub model

The Hub model is used when a retailer ships goods to the eShopWorld distribution hub. From there, the goods are shipped to the shopper. To use the Hub model, the package data must be sent to eShopWorld in advance of the packages physically arriving at the hub. The data can be synchronized via eShopWorld's Magento extension based on the shipments created in Magento. During the synchronization stage, the order tracking is also updated, which allows shoppers to track the order using the eShopWorld Order Tracking portal.

When using the Hub model, you can set the package reference in the standard process. If the package reference is not set, the default order increment ID from Magento is set as the package reference. The limitation with using order increment ID is that only full order shipments are supported. If you require split or partial shipment, the package reference must be set according to the tracking specification using the native Magento shipment API. For more information on the package reference, see "Setting up the package reference " on page 72.

Key features:

- 11 -

l Extension of the Magento native shipment API to include package_reference.

l Integration with eShopWorld Package API to include the POST endpoint.

l Cron job, which can be set for x frequency to run the POST endpoint.

l Native Magento shipment tracking updates.

l Ability to view the order view synchronization status:

l Ability to view the order tracking information.

- 12 -

l Ability to view the order tracking link.

3.6.1.1 Hub model flow

The following diagram explains the Hub model:

- 13 -

1. Shopper adds the item to their cart on Magento -Magento Quote table. This is the native Magento shopper journey.

- 14 -

2. When the shopper clicks Checkout, a call is made to the eShopWorld Checkout API. The Checkout API request is integrated with the eShopWorld extension, which sends eShopWorld Magento cart information, such as product information, shipping country, currency, locale, shipping rates (if setup) and customer details (if the shopper is logged in). eShopWorld generates hosted checkout based on the data received and responds with the Checkout URL to redirect the shopper.

3. The eShopWorld hosted Checkout is generated based on the data.

4. The shopper enters their delivery details, payment details and clicks Pay Now.

5. The payment is authorized and an order created in the eShopWorld system.

6. The order confirmation request is sent from eShopWorld to Magento to confirm payment successfully. The order confirmation request contains additional order information, such as the breakdown of the order including tax and duty in the shopper currency and retailer currency.

7. The order is created based on the quote in Magento. The invoice is created and the order status is updated to Processing. Additional custom data from step 6 is saved in the eShopWorld custom tables within Magento. The data can be viewed via the Admin panel.

8. The order confirmation response is received from Magento to ESW. When the success response is received by eShopWorld, the payment is captured between 30 minutes to 2 hours and 30 minutes later. The order confirmation request is attempted thrice with a waiting time of one minute for a success response. If a response is not received within the time limit, the order is automatically cancelled in eShopWorld’s database, which can potentially cause misalignment of order status. If an error response is sent by Magento, for example, due to issues with stock, the order is cancelled.

9. The Order Confirmation page hosted by eShopWorld is displayed to the shopper.

10. The order with the Processing status is fetched by WMS/ERP. The orders are imported into WMS ready for processing and dispatch.

11. The order is picked and packed. The Shipment ID is printed as a barcode on the pack-age generated by the retailer’s WMS. Retailers print a barcode on the shipment to identify package contents, this could be order number (which is only used if only full order fulfillment exclusively) or unique shipment reference.

12. The order is collected by the courier and delivered to the eShopWorld distribution hub.

- 15 -

13. The package arrives at the eShopWorld hub.

Steps 16-20 take place before step 13 because these are background processes that occur automatically based on existing processes and systems.

14. The barcode is scanned at the eShopWorld hub, the shipment label is printed, and the package is collected by the courier. The barcode is the package reference from step 16 and synchronized with eShopWorld at step 20.

15. The package is delivered to the shopper.

16. A unique shipment ID is passed to Magento. Unique shipment ID is optional data sent from WMS to Magento to identify the package. Retailers must populate package_reference using Magento shipment API to synchronize unique shipment ID.

17. WMS pushes the update to Magento to create a shipment.

18. Magento creates shipments in Magento.

19. Magento updates the order status to Complete when the shipment is created for the full order.

20. The Magento extension sends the package information to eShopWorld every x minutes. Additionally, the package reference is set as a unique shipment ID if it exists. If not, the order order number is set as the package reference. The Magento tracking is also updated with the eShopWorld carrier and tracking ID set as package reference.

21. Tracking order or returns are managed via the eShopWorld Order Tracking portal and Returns portal respectively.

3.6.1.2 Cron synchronization

The Cron job is used to send eShopWorld shipment updates from Magento. A request is sent for each shipment that has the shipment status as Pending. The following table shows the shipment status update based on a response from the eShopWorld Package API:

Code Description Sync action

204 Success Update record status to Synchronized.

400 Bad Request1001 The invalid model status: Update record status to Error.

101 Required brand code status: Leave current record status.

- 16 -

Code Description Sync action

301 Invalid brand code status: Leave current record status.

316 Invalid number of package references status: Update record status to Error.

317 Required order references status: Update record status to Error.

318 Eshop setup error status: Leave current record status.

400 Invalid AsnApiRequest error status: Leave current record status.

999 General error: Update record status to Error.

401 Unauthorized Leave current record status

404 Not Found Leave current record status

500 Server Error Leave current record status

3.6.1.3 Administration interface

Shipments grid

The Action column allows you to push the shipment to eShopWorld. The eShopWorld synchronization status column indicates the current shipment status.

Shipment details

Allows you to manually change the shipment sync status to any listed status.

- 17 -

3.6.2 Ship from Store (Hubless model)

The Ship from Store, also known as Hubless model, is a shipping model that allows retailers to ship the goods directly to the shoppers using eShopWorld’s Ship from Store application. To use the Ship from Store model, a shipment must be created in Magento to complete the full order process flow and order processing within Magento.

Key features:

l Integration with the eShopWorld Package API using the GET endpoint.

l Creation of shipments on Magento based on the GET endpoint.

l Cron job, which can be set for x frequency to run the GET endpoint.

l Additional custom data stored in the custom eShopWorld tables on Magento.

l Serial Number/Unique engraving number (UEN), WarrantyID, packageReference, car-rierReference, and eswpackageReference, which are stored in the eshopworld_ship-ment table.

- 18 -

l Native Magento shipment tracking.

3.6.2.1 Ship from Store flow

The following diagram explains the Ship from Store model:

- 19 -

1. Shopper adds an item to their cart on Magento (Magento Quote table). This is the native Magento shopper journey.

2. When the shopper clicks Checkout, a call is made to the eShopWorld Checkout API. The Checkout API request is integrated with the eShopWorld extension, which sends eShopWorld Magento cart information, such as product information, shipping country,

- 20 -

currency, locale, shipping rates (if setup) and customer details (if the shopper is logged in). eShopWorld generates hosted checkout based on the data received and responds with the Checkout URL to redirect the shopper.

3. The eShopWorld hosted Checkout is generated based on the data.

4. The shopper enters their delivery details, payment details and clicks Pay Now.

5. The payment is authorized and an order created in the eShopWorld system.

6. The order confirmation request is sent from eShopWorld to Magento to confirm payment successfully. The order confirmation request contains additional order information, such as a breakdown of the order including tax and duty in the shopper currency and retailer currency.

7. The order is created based on the quote in Magento. The invoice is created and the order status is updated to Processing. Additional custom data from step 6 is saved in the eShopWorld custom tables within Magento. The data can be viewed via the Admin panel.

8. The order confirmation response is received from Magento to ESW. When the success response is received by eShopWorld, the payment is captured between 30 minutes to 2 hours and 30 minutes later. The order confirmation request is attempted thrice with a waiting time of one minute for a success response. If a response is not received within the time limit, the order is automatically cancelled in eShopWorld’s database, which can potentially cause misalignment of the order status. If an error response is sent by Magento, for example, due to issues with stock, the order is cancelled.

9. The Order Confirmation page hosted by eShopWorld is displayed to the shopper.

10. The order exists in the Ship from Store application. Orders with successful payment are synchronized across eShopWorld’s systems and therefore exist in the Ship from Store application. An email notification will be sent to the store clerk to advise when an order will exist in the Ship from Store application ready for processing.

11. The store clerk processes the order and enters additional information, for example, a unique number and warranty ID.

12. Material information, for example, Carat content is added to the commercial invoice (for cross-border only).

13. The shipment label is printed and collected by the courier.

14. The Ship from Store application updates eShopWorld database with Shipped status.

- 21 -

15. Magento reads shipments from the eShopWorld database since the last update and cre-ates shipments in Magento including UEN and tracking ID. Shipment synchronization cron job runs every x minutes. The job queries the eShopWorld Package API, which returns all shipments created between timestamps. The From timestamp will be from the last time the job has run and the To timestamp is the current time. The query will return order number, SKU ID, quantity, UEN, and package ID. This information will be used to create a ship-ment in Magento. The package reference is recorded as the tracking number and eShopWorld is set as the carrier. This automatically sets the tracking URL in the backend admin and customer account section.

16. Magento updates the order status to Complete once a shipment is created for the full order. This is as per the native Magento order process.

17. Tracking order or returns are managed via the eShopWorld Tracking Portal and Returns Portal respectively.

3.7 Returns IntegrationThe eShopWorld Magento extension allows you to create returns and issue refunds in Magento based on processed returns in the eShopWorld hub. eShopWorld's return model allows shoppers to send their return orders either to the eShopWorld hub or directly to your warehouse.To keep systems synchronized, you can enable returns synchronization within the eShopWorld extension. Only the Hub model synchronization is currently supported. A hub model is when a shopper returns goods to the eShopWorld distribution hub. To learn more about the Returns Configuration, "Returns Configuration" on page 48.

Once eShopWorld receives the returned package, the returns centre admin inspects the package before authorizing the refund. Each item from return must be accepted or rejected. After the package passes the inspection, eShopWorld changes the return status to Proceed. This happens in real-time. During the cron job run, the Magento extension requests the returns with

- 22 -

the Approved status. The returned records are then replicated in Magento by creating the selected Magento entity type.

3.7.1 Magento Entity Types

You can select the type of entity that will be created in Magento when approved eShopWorld returns are synchronized. The options are Credit Memo and Return Merchandise Authorization (RMA).

3.7.1.1 Credit Memo

When this option is selected, the Magento extension creates an offline credit memo during the synchronization process. Only accepted line items are included in the credit memo. The credit memo Grand Total value matches the refunded amount (subtotal, shipping, and tax that is the combined value of tax and duty), and the extension saves the return reasons per item in a custom database table. To display the return reason in the admin credit memo view, customize the credit memo template.

3.7.1.2 Return Merchandise Authorization (RMA)

This option is only available for the Magento Enterprise Edition, which supports RMA. When RMA is selected, the eShopWorld Magento extension creates an RMA entry during the synchronization process. Both approved and rejected items are a part of the RMA. Rejected

- 23 -

item is saved as Received and the approved item is saved as Authorized. The Magento RMA item return reason codes are extended to match the options supported by eShopWorld.

3.8 Catalog IntegrationeShopWorld requires a product catalog from retailers to calculate correct duties and taxes. This information is used for checkout calculations as well as customs and duty declarations. Catalog integration exports catalog data and the custom attributes via Magento using product information that exists in Magento. The data is sent to eShopWorld and synchronized. The catalog configuration has preselected default mappings of the Magento product attribute, which are required by eShopWorld.

However, some fields that are required for the eShopWorld catalog integration do not exist in the default Magento attributes. Therefore, the extension creates the following three additional product attributes during installation or when you update the eShopWorld Magento extension:

l HS Code

l HS Region

l Material Description

You can view these fields in the eShopWorld category of the product view:

- 24 -

3.8.1 Triggering catalog exports

You can trigger catalog exports to eShopWorld using the Export to eShopWorld Catalog option under Actions. Once the products are added to the queue, they are synchronized by message queues in Magento. The max_input_vars PHP setting limits the number of inputs that can be set when posting forms. To increase the limit, change to the value to max_input_vars in the php.ini file.

Note: Catalog integration works only with simple products, as displayed in the Type field. For most attributes, the source value data can be a Parent product. For more information, see Configuration > Product Attributes Mapping.

- 25 -

4 Getting StartedThis section describes how to get started and install the eShopWorld Magento extension. To adhere to the best practices and manage extension dependencies correctly, use Composer for the installation and update process.

Always install the downloaded extension on a staging server first to detect any issues that might arise. Before migrating, take a backup of your Production environment.

4.1 Installing the extensionTo install the extension, perform the following steps:

1. Create a packages folder in the Magento root directory.

2. Create an eshopworld folder within the packages folder that you just created.

3. Place the module-eshopworld.{version}.zip file inside the packages/eshopworld folder.

4. From the Magento root directory, run the composer config repositories.eshopworld-checkout "artifact" "packages/eshopworld command. The following entry is created in the composer.json file:

5. From the Magento root directory, run the composer update eShopWorld/module-checkout:{version} command.

6. From the Magento root directory, run the php bin/magento setup:upgrade command.

7. From the Magento root directory, run the php bin/magento cache:clean command.

- 26 -

8. Update permissions on the localhost folder for var/cache, generated, pub. For more information on permissions, click here.

4.2 Verifying the installationTo verify the installation, perform the following steps:

1. Sign in to the Magneto 2 administration panel using your credentials.

2. Navigate to Stores > Configuration > Advanced > Advanced.

4.3 Accessing the extensionTo access the extension, perform the following steps:

1. Sign in to the Magneto 2 administration panel using your credentials.

2. Navigate to eShopWorld > Configuration.

4.4 Viewing configurationTo view the configuration, perform the following steps:

1. Sign in to the Magento 2 administration panel using your credentials.

2. Navigate to eShopWorld > Configuration. The extension settings are organized in nes-

- 27 -

https://devdocs.magento.com/guides/v2.3/install-gde/composer.html#set-file-permissions

ted logical tabs.

- 28 -

5 Configuring MagentoThis chapter provides instructions on the Magento configuration required to set up eShopWorld's Magento Plugin.

5.1 Setting up Magento for the Fixed price modelThe eShopWorld Magento extension uses the native Magento configuration to setup countries to be displayed on the eShopWorld landing page and footer. The extension pulls the countries from all allowed countries in Magento websites to create a list on the landing mat and footer.

l The Fixed Pricing model is used by default for a country if the Magento base currency is equal to the current shopper display currency. You can override this behavior using the Force FX Pricing Model Countries option under Pricing Configuration.

l The Calculated Pricing model is used by default for a country if the Magento base cur-rency is not equal to the current shopper display currency.

5.1.1 Country and Currency setup l To set up a Fixed Price country, add the country to allowed countries by navigating to

Stores > Configuration > General > Allowed Countries.

l To set up the currency to be used, add the base currency by navigating to Stores > Configuration > Currency Setup. The same currency must be set up in Default Display Currency as well as Allowed Currencies.

5.2 Setting up Magento for the Calculated Pricing modelThe Calculated pricing model works by utilizing the eShopWorld Pricing Advisor to convert a retailer's Magento global or website-level price and applying the eShopWorld custom formula to display the in-country prices.

5.2.1 Prerequisites l Pricing Advisor must be set up to use the Calculated Pricing model. Each retailer has a

different configuration because the estimated duty and tax varies based on the product set and average order value in each target market.

- 29 -

l Pricing Advisor must be run at least once to populate the currency rates and the custom eShopWorld data required to generate the eShopWorld calculated price. You can run Pri-cing Advisor manually by setting the Import Service (Stores > Currency Rates) to eShopWorld FxRates.

5.2.2 Country and currency setup

You can set up the country and currency relationships by navigating to eShopWorld > Checkout > Country - Currency Mapping. Each country supports a single currency and the defaults are automatically setup within the installation.

l To set up the Calculated pricing model countries, add the country to the allowed countries (Stores > Configuration > General > Allowed Countries). The allowed countries are included in the Country selector on the landing mat and footer.

l To set up the currency to be used, add the currency as the base currency (Stores > Con-figuration > Currency Setup).

l If different Default Display Currency and Allowed Currencies are set up, the Calculated pricing model is enabled for the selected country at the website level.

l If a different Default Display Currency cannot be set up, then the Fixed pricing model is enabled for the selected country. However, if you want to use the Calculated pricing model, an override must be set under eShopWorld > Checkout > Pricing Configuration > Force Calculated Pricing Model Countries.

Note:

l A single website can support multiple countries using the Calculated pricing model, Fixed pricing model, and native domestic countries.

l All currencies that will be supported by the Pricing Advisor must be enabled in the default configuration (Stores > Configuration > Currency Setup > Allowed Cur-rencies).

l All currencies that are enabled at the website-level for the Calculated pricing model must be enabled at the Default Config level to allow the Calculated pricing cron to update the foreign exchange rates.

- 30 -

l The countries for which the tax is added and displayed separately in the Totals section at the eShopWorld Checkout can be set up using the eShopWorld Tax on Checkout Side Only Countries option under Pricing Configuration.

- 31 -

5 Working with the eShopWorld extensionAfter installing the extension, you can access the eShopWorld settings and other options by clicking ESHOPWORLD in the left navigation area of the Magento admin panel.

The eShopWorld options are categorized into three main categories - Settings, Shipping, and Logs. Each category contains suboptions:

Settings

l "Security Token Service" on page 34

l "Checkout " on page 35

l "Order Fulfillment " on page 46

l "Catalog" on page 50

l "Logs " on page 52

Shipping "Shipping Rates" on page 53

- 32 -

Logs "Extension Logs" on page 56

- 33 -

6 Security Token ServiceeShopWorld APIs and User Interface are secured using a single security system called Security Token Service (STS). eShopWorld uses the STS platform to issue, validate as well as renew security tokens that are required to authenticate with eShopWorld APIs and access API endpoints. The following is the Security Token Service Configuration:

Option Description Scope

EnvironmentDefines the eShopWorld API environment. The options are Sandbox and Production.

Website

Client Id Unique identifier assigned to a client. Website

Client Secret

Unique secret assigned to a client. Website

After entering the details, click Test credentials to validate the credentials.

- 34 -

7 Checkout This chapter describes the following options:

l General Configuration

l Pricing Advisor Feed Configuration

l Country-Currency Mapping

l Retailer Display Configuration

l Pricing Configuration

l Product Metadata Items

l Preorder URL

l Order Confirmation

7.1 General ConfigurationThis tab contains options to enable the checkout extension features.

For the extension to work, you must provide information in each of the fields on this screen.

- 35 -


Extension Version

Read-only version number of the extension. Global

Checkout Functionality Enabled

Indicates if the eShopWorld Checkout is enabled. Global

Preorder Schema

Defines the schema to be used by the Preorder API call. The option is only available for 1.0.

Global

eShopWorld Checkout Countries

Countries for which the extension is enabled. When the shopper's country is one of the countries defined here, they are redirected to the eShopWorld Checkout.

Global

7.2 Pricing Advisor Feed ConfigurationThis tab contains configuration options for the FX Rates synchronization.

- 36 -


Pricing Feed Enabled Enables the functionality. Website

Synchronization Start Time Determines the time when the cron checks the pricing feed for the pricing updates. This check takes place daily.

Global

Synchronization Stop TimeDetermines the time when the cron stops run-ning.

Global

Frequency of RequestsDetermines the wait time between the requests. The default value is 10 minutes.

Global

Last Update DateRead-only date and time when the rates are updated.

Website

Automatically Clean FPC and Block HTML Cache After Feed Update

Indicates if the FPC and the Block HTML cache should be refreshed automatically after pricing updates.

Global

7.3 Country – Currency MappingWhen this feature is enabled, the country and currency are mapped as a combined selection from a single dropdown menu on the welcome mat and/or footer bar. You can enable this feature by setting Country – Currency Display Together on Landing Page and/or Country - Currency Display Together on Footer Bar to Yes in the Retailer Display Configuration panel.

- 37 -

7.4 Retailer Display ConfigurationThis tab allows you to configure the retailer display to suit your requirements.

- 38 -


GeoIP Location

Defines whether MaxMind GeoIP service will be used to determine shopper location and pre-select matched store.

The domain to work with MaxMind GeoIP service must be whitelisted by eShopWorld first. If the GeoIP is disabled, the default store will be used.

Global

Country - Currency Display Together

Defines whether the country and currency are displayed together.

Global

Enable Countries Selector

Defines whether the country selector will be available for shoppers to select their shipping country.

Global

Enable Currencies Selector

Defines whether the currency selector will be available for shoppers to select their preferred shopping currency.

Global

Enable Landing Page

Defines whether the landing page is enabled. If you select Yes, the landing page will be displayed where shoppers can select the preferred language, currency, and country.

Global

Enable Language Selector on Land-ing Page

Defines whether the language selector will be available on the landing page.

Global

Enable Footer Bar

Defines whether the same selectors as per the landing page will be available in the footer area. If you select Yes, the same set of selectors will be displayed in the footer area.

Global

Enable Language Selector in Footer

Defines whether the language selector will be available in the footer bar.

Global

- 39 -


Bar

7.5 Pricing ConfigurationThis tab allows you to specify the pricing configuration. You can specify countries where you want to display the tax separately on the checkout as well as countries where you want to apply the calculated pricing model regardless of the currency.


eShopWorld Tax on Checkout Side Only

Indicates the countries where tax is added and displayed separately on the eShopWorld checkout under Total and

Global

- 40 -


Countries is not part of the subtotal.

Force Calculated Price Model Coun-tries

Indicates countries that will use the Calculated pricing model even if the Magento base currency is the same as customer display currency. This model uses the retailer's base currency with the pricing feed calculations (FX, retailer uplift, duty and taxes) applied.

Global

7.6  Product Metadata ItemsThis tab allows you to specify additional data that you want to send in the preorder request to eShopWorld. The additional data includes product attributes and custom option mappings. If any attribute or mapping is not defined on this tab, it is not sent in the preorder request.

- 41 -

Option Description

Color Code

Defines the color code attribute.

Size Code

Defines the size code attribute.

Other Product Attributes to Dis-play on

Allows you to add additional product attributes that you want to display on the eShopWorld Checkout page. Checkout Attribute Name is how the additional product attribute will be displayed on the checkout. For example, 'Manufacturer'. To remove an attribute, click the delete icon under Action.

- 42 -

Option Description

Checkout

Product Custom Options to Dis-play on Checkout

Allows you to add custom options that you want to display on the eShopWorld Checkout page. Checkout Name is how the custom option will be displayed on the checkout. For example, 'Engraving'. The option will be displayed on the checkout only if the Custom Option Label at the global level matches the value. To remove an attribute, click the delete icon under Action.

7.7 Preorder URL ConfigurationThis tab allows you to configure preorder callback URLs.


Order Noti-fication Url

Defines the URL that is used for order confirmation. N/A indicates eshopworld/order/confirm as a default URL, if empty - not set. This functionality only works for the eShopWorld checkout Sandbox environment. For production, this field should be empty. For an empty record, a predefined value is used from the eShopWorld database.

Global

Continue Defines the URL that is used when a shopper clicks Continue Global

- 43 -


Shopping Url

Shopping at the checkout. N/A indicates base URL as a default URL, if empty - not set. For an empty record, a predefined value is used from the eShopWorld database.

Back to Cart Url

Defines the URL that is used when a shopper clicks Back to Cart on the checkout. N/A indicates checkout/cart as a default URL, if empty - not set. For an empty record, a predefined value is used from the eShopWorld database.

Global

7.8 Order Confirmation ConfigurationThis tab contains configuration related to the order confirmation request. The Order confirmation schema must match the configuration agreed with eShopWorld:

Option Description Dependency Scope

Enable Basic Auth for Order Confirmation

Indicates if the basic auth credentials, that is, the username and password should be validated dur-ing order confirmation. eShopWorld recommends that you enable this option to secure order con-firmation callback URL from unauthorized third-party requests.

None Global

Username Unique username provided by the user. Enable basic authentication for order con-

Global

- 44 -


firmation

Password Unique password provided by the user. Enable basic auth for order confirmation

Global

Order StatusOrder status of a newly created order. Default indicates the default Magento order status. Paid indicates the invoices created automatically.

None Global

- 45 -

8 Order Fulfillment The Order Fulfillment screen allows you to specify the General, Package/ASN, and Returns configuration options to enable the package extension features.

8.1 General ConfigurationThe following table describes the General Configuration options:


Extension Ver-sion

Read-only version number of the installed extension.

None Global

Brand Code Retailer-specific identifier. None Website

8.2 Package/ASN ConfigurationThe following table describes the Package/ASN Configuration option. To learn about the Package integration, including Hub model and Ship from Store model, see "Package Integration " on page 11.

- 46 -


Enable Pack-age/ASN

Indicates if the eShopWorld package syn-chronization is enabled.

None Global

When you select Yes in the Enable Package/ASN field, the following additional fields are displayed:


Model

Indicates the package model to use. The options are Hub Model and Hubless - Ship from Store, and Mixed - Specified Per Country.

l When you select Hubless - Ship from Store, the Last Update Date field is displayed. This is a read-only date and time when the shipments were synchronized.

l When you select Mixed - Specified Per Country, the Country-Model

None Global

- 47 -


field is displayed, which allows you to configure package/ASN with a dif-ferent model per country.

Enable Cron Synchronization

Indicates if the eShopWorld package syn-chronization is enabled.

None Global

Cron FrequencyRun the POST API call every x minutes to send the package data to eShopWorld.

Enable Cron Synchronization: Yes

Global

Batch SizeNumber of packages to send each POST API call.

Enable Cron Syncronization: Yes

Global

8.3 Returns ConfigurationThe following table describes the Returns Configuration option. To learn about the Returns Hub model, see "Returns Integration" on page 22.


Enable Returns Integration

Indicates if the eShopWorld returns syn-chronization is enabled.

None Global

When you select Yes in the Enable Returns Integration field, the following additional fields are displayed:

- 48 -


Return Type

Defines what type of Magento entity will be created during sync. The options are Credit Memo and RMA. RMA is only available for Enterprise edition.

None Global

Model Defines the model to use. None Global

Country - ModelDefines the model that can be in use for the specified country.

Model: Mixed - Specified Per Country

Global

Last Update Date

Read-only date and time when the returns were synchronized.

None Website

Enable Cron Synchronization

Defines if the cron should synchronize records between eShopWorld and Magento.

None Global

Cron Frequency Defines how often the cron job will run.Enable cron synchronization

Global

- 49 -

9 CatalogThe Catalog screen allows you to map the eShopWorld product attributes to Magento attributes. This mapping is required to export products cross-border and for the catalog integration process. If the catalog export is enabled, the following eShopWorld product attributes are mandatory and must be mapped:

l productCode

l name

l description

l countryOfOrigin

l hsCode

l hsCodeRegion

l material

9.1 General Configuration

- 50 -


Enable CatalogIndicates if the eShopWorld catalog export is enabled.

None Global

Product Attrib-utes Mapping

Configuration to set up the mapping between eShopWorld attributes and Magento product attributes. Source pri-ority indicates a priority order for the product attribute value.

None Global

- 51 -

10 Logs 10.1 General ConfigurationThis tab allows you to enable or disable the Log feature.


Enable Logs Indicates if the Log feature is enabled. Global

10.2 Logs CleaningThis tab allows you to enable or disable the Log Cleaning feature.

The following table describes the Log Cleaning Configuration options:


Enable Log Cleaning Cron

Indicates if the Log Cleaning feature is enabled. Global

Cron Frequency Time when the cron job will run. Global

Days to Store Log Data Before Deleting

Number for days for which the logs should be retrained before they are removed from the database.

Global

- 52 -

11 Shipping RatesOn the Shipping Rates screen, you can define the shipping rate overrides that you want to pass in the preorder request to eShopWorld.

The way the shipping rates are applied can be defined through the Magento 2 built-in mechanism, which acts the same as the Magento 2 default cart price rules. When these shipping rates are defined, the eShopWorld extension validates them during the preorder request. If the shipping rates apply to the active cart, the rates information is passed over to the eShopWorld API along with the preorder request.

11.1 Add new ratesYou can add new shipping rates by clicking the Add New Rate button. When you click this button, the following screen is displayed:

- 53 -

The shipping method that you want to apply to the eShopWorld checkout must be act-ive and current shopper country and currency must match the country and currency as defined in existing the shipping method.

11.1.1 Rate Information

Field/Option Description

Method Name

Name used to identify the method internally.

Active Activates the method.

Service Level

Delivery method - POST or EXP2. The values are as agreed with eShopWorld.

- 54 -

Field/Option Description

Country Country for which the method is enabled.

CurrencyCurrency that is applicable to the shipping method. By default, this is the cur-rency of the selected country. For example, if you select Australia, the default currency will be the Australian Dollar.

Shipping Cost

Shipping cost in the selected currency.

11.1.2 Conditions

This section allows you to set additional conditions that must be met before the method can be applied. The eShopWorld extension supports the native Magento conditions that also exist for promotions rule settings, for example, cart attributes like total item quantity, total weight, subtotal (in base currency), and so on. Additionally, the eShopWorld extension supports these conditions - Subtotal with Discount in Shipping Method Currency (where the subtotal includes discount and is defined in the currency of the current method) and Subtotal in Shipping Method Currency (where the subtotal is defined in the currency of the current method).

- 55 -

12 Extension LogsThe Extension Logs screen displays logs that are created by the extension. The extension creates logs on sending and receiving the preorder request, sending pricing update requests, handling order confirmation requests, and package post requests.

- 56 -

13 Order ConfirmationOrder confirmation supports the separation of the order data into separate tabs. The Order View tab can be accessed by clicking Sales in the left panel and then selecting View from the Actions list for an order. For more information, see the Magento documentation.

13.1 Order Confirmation v2.0The order-level, item-level, and discount-level details are displayed on the eShopWorld Order, eShopWorld Order Items, eShopWorld Cart Discounts tabs respectively that you can access under Order View.

13.1.1 eShopWorld Order

This tab displays the order-level details. These attributes are passed in from eShopWorld's Order Confirmation request.

The following table describes the eShopWorld order attributes:

- 57 -

Field Type Allow null Description

Entity ID int (10) no Unique ID.

Retailer Cart Idvarchar (255)

no Order number or cart identifier for the retailer.

Order numbervarchar (255)

no Order number or cart identifier of the brand.

Retailer Currency Payment Amount

varchar (100)

yesThree-letter identifier of the retailer currency in the ISO 4217 format and the amount paid in the retailer currency.

Shopper Cur-rency Payment Amount

varchar (100)

yesThree-letter identifier of the shopper currency in the ISO 4217 format and the amount paid in the shopper currency.

Retailer Fx Group Id

varchar (255)

yes

Value of the retailerFxGroupId being used. If no value is provided, either the latest retail-erFxGroupId that exists in the eShopWorld data-base is used.

Payment Timevarchar (255)

yesDate and time when the order was pre-authorised or payment was made.

Payment methodvarchar (255)

yes Details of the payment method.

Payment Method Card Brand

varchar (255)

yes Card brand information.

Fraud holdvarchar (255)

yesIndicates if there is any fraud hold or fraudulent activity.

- 58 -


Retailer Promo Codes

text yes Promo code applied.

Delivery Country Iso

varchar (20)

yesISO 3166 format two-letter country identifier for the delivery country.

Shopper culture language ISO

varchar (20)

yesLanguage ISO code for the shopper in the ISO 639-1 format.

Email marketing opt in

integer(11)

yesIndicates if the shopper wants to subscribe to email marketing.

Delivery Optionvarchar (255)

yes Preferred delivery option for the shopper.

Retailer currency delivery price before discount

varchar (255)

yes Price before the discount is applied.

Retailer currency delivery price dis-count amount

varchar (255)

yes Amount of the discount.

Retailer currency delivery price dis-count percentage

varchar (255)

yes Percentage value of the discount.

Retailer currency delivery price

varchar (255)

yes Order delivery charge in the retailer currency.

Retailer currency delivery price title

varchar (255)

yes Price title.

- 59 -


Retailer currency delivery price description

varchar (255)

yes Price description.

Shopper currency delivery price before discount

varchar (255)

yes Price before the discount is applied.

Shopper currency delivery price dis-count amount

varchar (255)

yesDiscount amount in shopper currency on delivery price.

Shopper currency delivery price dis-count percentage

varchar (255)

yesDiscount percentage in shopper currency on delivery price.

Shopper currency delivery price

varchar (255)

yes Order delivery charge in the shopper currency.

Shopper currency delivery price title

varchar (255)

yes Price title.

Shopper currency delivery price description

varchar (255)


Delivery Option Metadata Items

text yesKey-value pairs used for passing additional details.

Shopper Cur-rency Total

varchar (100)

yes Merchandise cost in the shopper currency.

- 60 -


Shopper Cur-rency Delivery

varchar (100)

yes Delivery cost in the shopper currency.

Shopper Cur-rency Delivery Duty

varchar (100)

yes Duty on the delivery cost in the shopper currency.

Shopper Cur-rency Delivery Taxes

varchar (100)

yes Taxes on delivery cost in the shopper currency.

Shopper Cur-rency Taxes

varchar (100)

yes Taxes in the shopper currency.

Shopper Cur-rency Other Taxes

varchar (100)

yes Other taxes in the shopper currency.

Shopper Cur-rency Admin-istration

varchar (100)

yesOrder administration charge in the shopper cur-rency.

Shopper Cur-rency Duty

varchar (100)

yes Duty in the shopper currency.

Shopper Cur-rency Uplift

varchar (100)

yes Uplift in the shopper currency.

Retailer Currency Total

varchar (100)

yes Merchandise total in the retailer currency.

Retailer Currency Delivery

varchar (100)

yes Delivery cost in the retailer currency.

- 61 -


Retailer Currency Delivery Duty

varchar (100)

yesDuty on the delivery charge in the retailer cur-rency.

Retailer Currency Delivery Taxes

varchar (100)

yesTaxes on the delivery charge in the retailer cur-rency.

Retailer Currency Taxes

varchar (100)

yesTaxes element in the overall Order Payment amount in the retailer currency.

Retailer Currency Other Taxes

varchar (100)

yesOther taxes element in the overall Order payment amount.

Retailer Currency Administration

varchar (100)

yes Administration charge in the retailer currency.

Retailer Currency Duty

varchar (100)

yes Duty charge in the retailer currency.

Retailer Currency Uplift

varchar (100)

yes Uplift in the retailer currency.

Created at timestamp no

13.1.2 eShopWorld Order Items

This tab displays the item-level details. These attributes are passed in from eShopWorld's Order Confirmation request.

- 62 -




no Order number or cart identifier of the brand.

Quantity int (10) yes Quantity of the product unit.

Product Codevarchar (255)

yesRetailer’s unique identification code or SKU for the order article.

UPCvarchar (255)

yes12-digit Universal Product Code assigned to each item.

Product HS Code

varchar (255)

yes HS code of the product.

Product titlevarchar (255)

yes Title of the product.

Product descrip-tion

varchar (255)

yes Description of the product.

- 63 -


Retailer Cur-rency Price Info Before Discount

varchar (100)

yes

Price before the discount is applied in the retailer currency. The value is a combination of a three-let-ter currency identifier (in the ISO 4217 format) fol-lowed by a number.

Retailer Cur-rency Price Info Discount Amount

varchar (100)

yesAmount of the discount in the retailer currency. The value is a combination of a three-letter identifier (in the ISO 4217 format) followed by a number.

Retailer Cur-rency Price Info Discount per-centage

varchar (100)

yes Discount percentage in the shopper currency.

Retailer Cur-rency Price Info Price

varchar (100)

yes

Retailer Cur-rency Price Info Title

varchar (255)

yes Price title.

Retailer Cur-rency Price Info Description

varchar (255)


Shopper Cur-rency Price Info Before Discount

varchar (100)

yes

Price before the discount is applied in the shopper currency. The value is a combination of a three-let-ter currency identifier (in the ISO 4217 format) fol-lowed by a number.

- 64 -


Shopper Cur-rency Price Info Discount Amount

varchar (100)

yesAmount of the discount in the shopper currency. The value is a combination of a three-letter identifier (in the ISO 4217 format) followed by a number.

Shopper Cur-rency Price Info Discount per-centage

varchar (100)

yes Discount percentage in the shopper currency.

Shopper Cur-rency Price Info Price

varchar (100)

yes

Shopper Cur-rency Price Info Title

varchar (255)

yes Price title.

Shopper Cur-rency Price Description

varchar (255)


Product Image Url

varchar (255)

yes Thumbnail image URL of the product.

Product Colorvarchar (255)

yes Color of the item.

Product Sizevarchar (255)

yes Size of the item.

Product Is Non integer yes Indicates whether the product is a non-standard

- 65 -


Standard Cata-log Item

catalog item.

Product Metadata Items

text yes Key-value pairs used for passing additional details.

Estimated Deliv-ery Date

varchar (255)

yes Estimated delivery date of the cart items.

Line Item Idvarchar (20)

yes Item sequence or the ID of the line item.

Shopper Cur-rency Item Sub Total

varchar (20)

yesItem subtotal, that is, the value of the merchandise in the shopper currency.

Shopper Cur-rency Item Uplift

varchar (20)

yes Item uplift in the shopper currency.

Shopper Cur-rency Item Deliv-ery

varchar (20)

yes Item delivery charge in the shopper currency.

Shopper Cur-rency Item Deliv-ery Duty

varchar (20)

yes Item delivery duty in the shopper currency.

Shopper Cur-rency Item Deliv-ery Taxes

varchar (20)

yes Item delivery taxes in the shopper currency.

Shopper Cur- varchar yes Item taxes charge in the shopper currency.

- 66 -


rency Item Taxes

(20)

Shopper Cur-rency Item Other Taxes

varchar (20)

yes Other taxes charge in the shopper currency.

Shopper Cur-rency Item Administration

varchar (20)

yes Item administration charge in the shopper currency.

Shopper Cur-rency Item Duty

varchar (20)

yes Item duty charge in the shopper currency.

Retailer Cur-rency Item Sub Total

varchar (20)

yesItem subtotal, that is, the value of the merchandise in the retailer currency.

Retailer Cur-rency Item Uplift

varchar (20)

yes Taxes on delivery cost in the shopper currency.

Retailer Cur-rency Item Deliv-ery

varchar (20)

yes Item delivery charge in the retailer currency.

Retailer Cur-rency Item Deliv-ery Duty

varchar (20)

yes Item delivery duty in the retailer currency.

Retailer Cur-rency Item Deliv-ery Taxes

varchar (20)

yes Item delivery taxes in the retailer currency.

- 67 -


Retailer Cur-rency Item Taxes

varchar (20)

yes Item taxes charge in the retailer currency.

Retailer Cur-rency Item Other Taxes

varchar (20)

yes Other taxes charge in the retailer currency.

Retailer Cur-rency Item Administration

varchar (20)

yes Item administration charge in the retailer currency.

Retailer Cur-rency Item Duty

varchar (20)

yes Item duty charge in the retailer currency.

Metadata Items text yes Key-value pairs used for passing additional details.

13.1.3 eShopWorld Order Cart Discounts

The following table describes the ESW cart discounts attributes:




noOrder number or cart identifier of the brand.

Titlevarchar (255)

yesTitle of the promotion or voucher code.

Description varchar yes Description of the promotion or

- 68 -


(255) voucher code.

Retailer Currency Cart Discount Before Discount

varchar (100)

yesPrice before the discount is applied.

Retailer Currency Cart Discount Amount

varchar (100)


Retailer Currency Cart Discount Percentage

varchar (100)

yesPercentage value of the dis-count.

Retailer Currency Cart Discount Price

varchar (100)

yes Price.

Retailer Currency Cart Discount Title

varchar (255)

yes Price title.

Retailer Currency Cart Discount Description

varchar (255)


Shopper Currency Cart Discount Before Discount

varchar (100)

yesPrice before the discount is applied.

Shopper Currency Cart Discount Amount

varchar (100)


Shopper Currency Cart Discount Percentage

varchar (100)

yesPercentage value of the dis-count.

Shopper Currency Cart Discount Price

varchar (100)

yes Price.

Shopper Currency Cart Discount varchar yes Price title.

- 69 -


Title (255)

Shopper Currency Cart Discount Description

varchar (255)


- 70 -

14 Information for Developers14.1 Setting up the Varnish cacheTo allow the calculated pricing model to work with Varnish cache, the value of the cache key must include the eShopWorld currency (esw-currency) or the location (esw-location) cookie.

sub vcl_hash {

if (req.http.cookie ~ "X-Magento-Vary=" || req.http.cookie ~ "esw.-

currency=")

{ hash_data(regsub(req.http.cookie, "^.*?X-Magento-Vary=([^;]+);*.*$",

"\1") + regsub(req.http.cookie, "^.*?esw.currency=([^;]+);*.*$",

"\1")); }

#For multi site configurations to not cache each other's content

if (req.http.host) { hash_data(req.http.host); }

else

{ hash_data(server.ip); }

#To make sure http users don't see ssl warnin

if (req.http.X-Forwarded-Proto) { hash_data(req.http.X-Forwarded-

Proto); }

}

Varnish rules can also be updated via Vary header. For example:

#Recv

if (req.http.Cookie ~ "esw.currency=") {

set req.http.Esw-currency = regsub(req.http.cookie, "^.*?esw.currency=

([^;]+);*.*$", "\1");

} else {

- 71 -

set req.http.Esw-currency = "";

}

#Fetch

if (beresp.http.Content-Type ~ "text/(html|xml)") {

if (beresp.http.Vary) {

set beresp.http.Vary = beresp.http.Vary ",Esw-currency";

}

}

14.2 Setting up the package reference

This section applies to the Hub shipping model only. To learn about this model, including the model features and flow, see "Hub model" on page 11.

The package reference can be set when you are creating shipments. If no package reference is set, the order increment ID from Magento is set as the package reference. The limitation with using order increment ID is that only full order shipments are supported. If you require split shipment, then package reference must be set according to the tracking specification using native Magento Shipment API. eShopWorld’s Magento extension sends package data to eShopWorld based on the shipments created for eShopWorld orders in Magento. You can create shipments in Magento and have the option to set a package_reference in eshopworld_shipment.

l To populate package_reference in eshopworld_shipment, you can use the native Magento shipment API and populate new extension attribute package_reference, as shown in the following image:

- 72 -

14.2.1 Package reference in the Magento Shipment API

When the Package API is triggered via cron, shipments with the Pending synchronization status are sent to eShopWorld.

l If no value is set in package_reference in eshopworld_shipment table, the order increment ID will be set as package_reference in eshopworld_shipment and sent to eShopWorld. If a value exists in package_reference in eshopworld_shipment, then this value is sent to eShopWorld.

l The tracking information is updated in Magento shipment on the successful run of the Package API. eShopWorld is set as carrier and tracking ID will be set as package_ref-erence. This will update all native Magento views, such as customer account and backend admin to add tracking links to the eShopWorld Tracking portal.

l The weight from the Magento shipment is sent to eShopWorld as part of the package integration. If no weight is set in the shipment, the product weight from the order item is used.

14.3 Cookies l esw-location: Determines the shipping address of the shopper. If no value is present,

the default store country from configuration is used. For example, esw-location:{"country":{"iso_code":"US"}}.

- 73 -

l esw-currency: Used by extension for front-end widgets selectors to track current currency. For example, esw-currency:USD.

l esw-geoip: Determines if GeoIP should be used to get shopper current country location.

l esw-landing-played: Determines if the welcome mat widget was already displayed to the shopper.

14.4 Extension APIThe eShopWorld extension provides an API for requesting eShopWorld’s redirect checkout URL. This functionality can be used to build a headless commerce experience with the eShopWorld checkout.

14.4.1 REST APIs

14.4.1.1 Guest checkout request

POST /V1/eshopworld/checkout/guest-carts

Body Parameters Description

cart_id* (string) Cart identifier.

Response Description

200 URL to eShopWorld Checkout.

14.4.1.2 Logged in user checkout request

POST/V1/eshopworld/checkout/carts/mine

Header Parameters Description

Authorization Bearer

- 74 -


200 URL to eShopWorld Checkout.

By default, the source of the shipping country for eShopWorld extension is taken from the Magento configuration Country options > default country. If more countries are allowed within Magento configuration for one store, the extension allows you to set a different shipping country via the header in the API request.

14.4.2 GraphQL API

14.4.2.1 Checkout request

query getEShopWorldCheckout($cartId: String!) { eShopWorldCheckout

(cartId: $cartId) }

Parameter Description

cartId* (string) Cart identifier.


data.eShopWorldCheckout URL to eShopWorld Checkout.

14.4.3 Set shipping country used by extension in API call

You can set the shipping country using the following ways:

l Via the header in the API request - ESW-COUNTRY: {{country abbreviation ISO-3166-1 ALPHA-2}}. For example, ESW-COUNTRY:US.

l Via the cookie in the request.

- 75 -

14.5 Frontend widget customizationThe welcome mat and drop-down selections are a part of the extension templates. The default stylesheet provides the Magento Luma theme. If you want to change the default output provided by the extension, override the theme in Custom Theme. This is the basis of template customization in Magento.

l The shipping country, currency, and language options displayed in the front-end widget are based on the Magento configuration. The shipping countries are based on all countries selected under General > Allowed Countries.

l Only a unique country per website is allowed within multiple running websites. The extension supports the mapping between a country and currency and you can change it by navigating to Checkout > Country - Currency Mapping.

l Further option overrides can be done by using interceptor or observer for the eshop-world_js_configuration_build event.

14.5.1 Welcome mat

- 76 -

14.5.2 Footer

14.6 Catalog asynchronous integration for Magento Com-merce CloudThe following changes are required to allow asynchronous operations to work with Commerce Cloud:

1. Create a .magento.env.yaml file in the root directory of the project and add the fol-lowing snippet to the file:

stage:

deploy:

CRON_CONSUMERS_RUNNER:

cron_run: true

max_messages: 10000

consumers: []

2. Commit and deploy the changes.

For more information on asynchronous operations, see the Magento documentation.

14.6.1 Get eShopWorld calculated price

The following example shows how to get the calculated price for a product. In this example, the base price is 59 USD and the price is converted from USD to CAD:

<?php

- 77 -

https://devdocs.magento.com/guides/v2.3/config-guide/mq/manage-message-queues.html

namespace Vendor\Module\Example;

use EShopWorld\Checkout\Pricing\TaxManager;

class ExampleClass

{

/**

* @var TaxManager

*/

private $taxManager;

public function __construct(TaxManager $taxManager)

{

$this->taxManager = $taxManager;

}

public function getCalculatedPrice()

{

$basePrice = 59.00;

$currencyCodeFrom = 'USD';

$currencyCodeTo = 'CAD';

$countryCodeTo = 'CA';

return round($this->taxManager->applyRoundingModel($this->taxManager-

>applyRetailerTaxes($this->taxManager->convertCurrency($basePrice,

$currencyCodeFrom, $currencyCodeTo), null, $countryCodeTo)), $this-

>taxManager->getCurrencyExponent());

}

}

- 78 -

15 TroubleshootingThis chapter provides procedures for troubleshooting the common problems encountered when installing the eShopWorld Magento extension.

15.1 Extension not appearing on the dashboardIf the eShopWorld Magento extension does not appear on the dashboard, edit the composer.json file and check the following path entries for the eShopWorld extension folder:

"repositories": {

"0": {

"type": "composer",

"url": "https://repo.magento.com/"

},

"eshopworld-checkout": {

"type": "artifact",

"url": "./packages/eshopworld"

}

Also, check the following entry in require to ensure that the Magento edition and the eShopWorld extension version are up-to-date.

"require": {

"magento/product-community-edition": "{version}",

"composer/composer": "@alpha",

"eshopworld/module-checkout": "{version}"

}

- 79 -

eShopWorldeCommerceSolutions MagentoExtensionUserManual · l Package 2.0 integration for eShopWorld orders. l Logs configuration. 2.3.0 August 2019 Added Checkout 2.0 pricing advisor

Documents