eshopworldecommercesolutions magentoextensionusermanual · 2020-04-22 · the eshopworld magento...

Version: 2.3.5Published date: April 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 11.1 Intended audience 1

1.2 Document revision history 1

2 Overview 32.1 Features 3

2.1.1 Out of scope 4

2.2 Magento Extension and eShopWorld Checkout flow 4

3 How does it work? 63.1 Retailer Platform and eShopWorld Checkout Flow 6

3.2 Pricing Models 7

3.3 Pricing API (hosted by eShopWorld) 7

3.4 Checkout API (hosted by eShopWorld) 8

3.4.1 Process Flow 9

3.5 Order Confirmation Request (hosted by retailer) 9

3.5.1 Process Flow 9

3.6 Package Integration 10

3.6.1 Hub model 10

3.6.1.1 Hub model flow 13

3.6.1.2 Cron synchronisation 15

3.6.1.3 Administration interface 16

3.6.2 Ship from Store (Hubless model) 17

3.6.2.1 Ship from Store flow 18

3.7 Returns Integration 21

3.7.1 Magento Entity Types 22

3.8 Catalog Integration 23

4 Installation and setup 264.1 Installing the extension 26

4.2 Verifying the installation 27

- i -

4.3 Accessing the extension 27

4.4 Viewing configuration 27

5 Configuration 295.1 Setting up Magento for 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

6 Security Token Service 316.1 Security Token Configuration 31

7 Checkout 327.1 General Configuration 32

7.2 Pricing Feed Configuration 33

7.3 Country – Currency Mapping 34

7.4 Retailer Display Configuration 35

7.5 Pricing Configuration 37

7.6 Preorder Expansion Pairs Configuration 38

7.7 Preorder URL Configuration 40

7.8 Order Confirmation Configuration 42

8 Order Fulfillment 448.1 General Configuration 44

8.2 Package/ASN Configuration 44

8.3 Returns Configuration 46

9 Catalog 489.1 General Configuration 48

10 Logs 5010.1 General Configuration 50

10.2 Logs Cleaning 50

11 Shipping Rates 5212 Extension Logs 53

- ii -

13 Order Confirmation 5413.1 Order Confirmation v2.0 54

13.1.1 eShopWorld Order 54

13.1.2 eShopWorld Order Items 59

13.1.3 eShopWorld Order Cart Discounts 65

14 Developer 6814.1 Setting up the Varnish cache 68

14.2 Setting the package reference 69

14.2.1 Package reference in the Magento Shipment API 70

14.3 Cookies 70

14.4 Extension API 71

14.5 Frontend Widgets Customization 72

14.6 Asynchronous Operations for Magento Commerce Cloud 73

14.6.1 Get eShopWorld calculated price 73

15 Troubleshooting 7515.1 Extension not appearing on the dashboard 75

- iii -

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 type.

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 2019New features added:

l 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 New Developer section added

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 2020New features added:

l Asynchronous operations for Commerce Cloud.

- 2 -

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.

- 3 -

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.

- 4 -

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:

- 6 -

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

3.2 Pricing ModelsA pricing model defines how the in-country product price is displayed on the retailer's site. The retailer defines the pricing model 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 exclusive 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 retailers with a maintenance-free pricing solution for the international markets.

- 7 -

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 customer flow.

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

- 8 -

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 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 system 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.

- 9 -

4. 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, which is described in the following sections.

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, retailers have the option to set the package reference in their standard process. If the package reference is not set, the default 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 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, "Configuration" on page 29.

Key features:

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

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

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

- 10 -

l Native Magento shipment tracking updates.

l Ability to view the order view synchronization status:

l Ability to view the order tracking information.

- 11 -

l Ability to view the order tracking link.

- 12 -

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.

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.

- 14 -

13. The package arrives at the eShopWorld hub.

Steps 16-20 take place prior to 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 synchronisation

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.301 Invalid brand code status: Leave current record status.

- 15 -

Code Description Sync action

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

l eShopWorld synchronization status column with current shipment status.

l Action to push the shipment to eShopWorld.

Shipment details view

- 16 -

l Action to push the shipment to eShopWorld.

l eShopWorld sync information and status action in the block section. You can manually change the shipment sync status to any listed status.

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.

- 17 -

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

l Native Magento shipment tracking.

3.6.2.1 Ship from Store flow

The following diagram explains the Ship from Store model:

- 18 -

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,

- 19 -

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.

- 20 -

15. Magento reads shipments from the eShopWorld database since the last update and cre-ates shipments in Magento including UEN and tracking ID. Shipment synchronisation 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 eShopWorld’s hub. eShopWorld's return model allows shoppers to send their return orders either to the eShopWorld hub or directly to your warehouse. In order to keep systems synchronized, you can enable returns synchronization within the eShopWorld extension. Only the Hub model synchronization is currently supported. To learn more about the Returns Configuration, "Returns Configuration" on page 46.

In the case of returns, a hub model is when a shopper returns goods to the eShopWorld distribution hub. When eShopWorld receives a return package, a clerk 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 the Approved status. Returned records are then replicated in Magento by creating the selected Magento entity type.

- 21 -

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).

l 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 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 the credit memo template.

- 22 -

l

l 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 be part of the RMA. Rejected item is saved with status Return received and approved with status 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 allow eShopWorld to assign the correct duties and taxes. This information is used for checkout calculations, customs and duty declarations when operating a cross border business and other downstream processes.Catalog integration exports catalog data plus additional custom attributes via Magento using product information that exists in Magento. The data is sent to eShopWorld and synchronized.

- 23 -

Catalog configuration has preselected default mapping of Magento product attribute that are required by eShopWorld.Some required fields for eShopWorld catalog integration do not exist in default Magento attributes. The extension creates three additional product attributes during installation or update of the eShopWorld Magento extension. Custom attributes created by the extension are:

l HS Code

l HS Region

l Material Description

These attributes are available under Products View in the eShopWorld section.

Catalog exports to eShopWorld can be triggered 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 PHP setting "max_input_vars" limits the number of inputs that can be set when posting forms. To increase the limit, change to max_input_vars in php.ini.

- 24 -

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, seeConfiguration > Product Attributes Mapping.

- 25 -

4 Installation and setupThis section describes how to 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:

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:

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:

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

2. Navigate to eShopWorld > Configuration.

4.4 Viewing configurationTo view the configuration:

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

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

- 27 -

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

- 28 -

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

5.1 Setting up Magento for Fixed price modeleShopWorld's Magento extension uses the native Magento configuration to setup countries to be displayed on the eShopWorld landing page and footer. eShopWorld's module 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 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 in Stores > Con-

figuration > General > Allowed Countries.

l To set up the currency to be used, add Base Currency in 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 eShopWorld’s Pricing Advisor to convert a retailer's Magento global or website-level price and applying eShopWorld’s 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, then 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, then an override must be set in eShopWorld > Checkout > Pricing Configuration > Force Calculated Pricing Model Countries.

Notes:

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 Price model must be enabled at the 'Default Config' level to allow the Calculated Pricing cron to update the foreign exchange rates.

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

- 30 -

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.

6.1 Security Token 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.

- 31 -

7 Checkout This chapter describes the following configuration options:

l General

l Pricing Feed

l Country-Currency Mapping

l Retailer Display

l Pricing

l Preorder Expansion Pairs

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:

The following table describes the General Configuration options:

- 32 -

Option Description Dependency Scope

Extension Version

Read-only version number of the installed plugin. None Global

Checkout Functionality Enabled

Indicates if the eShopWorld Checkout is enabled. None Global

Preorder Schema

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

None Global

eShopWorld Checkout Countries

Defines the 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.

None Global

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

- 33 -

The following table describes the Pricing Feed Configuration options:


Pricing Feed Enabled

Enables or disables the functionality. None Website

Rates Syn-chronisation Start Time

Determines the time when Magento 2 checks the FX rates for any changes. This check takes places daily.

None Global

Rates Syn-chronisation Stop Time

Determines the time when Magento 2 stops checking for new FX rates and coun-try adjustments.

None Global

Frequency of Requests

Determines the frequency at which the FX rate changes should be checked.

None Global

Last Update Date

Read-only date when FX rates were updated.

None Website

Automatically Clean FPC and Block HTML Cache After Rate Import

Defines if the FPC and the Block HTML cache should be refreshed automatically after the FX rate import.

None 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.

- 34 -

7.4 Retailer Display ConfigurationRetailer Display refers to the landing page and footer bar that can be toggled on or off. This tab allows you to configure the retailer display to suit your requirements.

- 35 -

The following table describes the Retailer Display Configuration options:


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 countries 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 Defines whether the languages selector will be available Global

- 36 -


Selector in Footer Bar

in the footer bar.

7.5 Pricing ConfigurationThis tab contains the Pricing configuration.

The following table describes the Pricing Configuration options:

- 37 -


eShopWorld Tax on Checkout Side Only Countries

Indicates the countries where tax is added and dis-played separately on the eShopWorld checkout under Total and is not part of the subtotal.

Global

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 cal-culations (FX, retailer uplift, duty and taxes) applied.

Global

7.6  Preorder Expansion Pairs ConfigurationThis tab contains the attribute mappings configuration. eShopWorld checkout allows retailers to send additional product attributes with the preorder request. On this tab, you can define the relationship between the store attributes and the eShopWorld extension attributes. If any mapping attribute is not defined, the attribute is not sent in the request. The following table describes the Preorder Expansion Pairs Configuration options:

- 38 -

The following table describes the PreOrder Expansion Pairs Configuration options:


Catalog codeDefines the catalog code attribute, which will be passed in the preorder request.

Global

Color codeDefines the color code attribute, which will be passed in the pre-order request.

Global

Color descrip-tion

Defines the color description attribute, which will be passed in the preorder request.

Global

Size code Defines the size code attribute, which will be passed in the pre- Global

- 39 -


order request.

Style codeDefines the style code attribute, which will be passed in the pre-order request.

Global

Is per-sonalised

Defines the Is personalised attribute, which will be passed in the preorder request.

Global

Monogram text

Defines the monogram text attribute, which will be passed in the preorder request.

Global

Monogram colour

Defines the monogram colour attribute, which will be passed in the preorder request.

Global

Gift wrappedDefines the Gift wrapped attribute, which will be passed in the preorder request.

Global

Is return pro-hibited

Defines the Is return prohibited attribute, which will be passed in the preorder request.

Global

7.7 Preorder URL ConfigurationThis tab contains configuration related to preorder callback URLs.

- 40 -

The following table describes the PreOrder Url Configuration options:


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.

l For preorder schema 2.0, this functionality only works for eShopWorld checkout Sandbox environment.

l For production, this field should be empty.

l For an empty record, a predefined value is used from the eShopWorld database.

None Global

Continue Shopping Url

Defines the URL that is used when a shopper clicks Continue 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.

None Global

Back to Cart Url

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

None Global

- 41 -


eShopWorld database.

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:

The following table describes the Order Confirmation Configuration options:


Enable Basic Auth for Order Confirmation

Defines if the basic auth credentials, that is, the username and password should be val-idated during order confirmation. eShopWorld recommends that you enable this option to secure order confirmation callback URL from unauthorized third-party requests.

None Global

Username A unique username provided by a user.

Enable basic authentication for order con-firmation

Global

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

Global

Order StatusDefines the order status of a newly created order. Default indicates the default Magento

None Global

- 42 -


order status. Paid indicates the invoices cre-ated automatically.

- 43 -

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 10.


Enable Pack- Indicates if the eShopWorld package syn- None Global

- 44 -


age/ASN chronization is enabled.

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 field is displayed, which allows you

None Global

- 45 -


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 21.


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:

- 46 -


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

- 47 -

9 Catalog9.1 General ConfigurationThe following table describes the General Configuration options:


Enable Cata-log

Indicates if the eShopWorld catalog export is enabled.

None Website

Prodict Attrib-utes Mapping

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

None Website

- 48 -

- 49 -

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

The following table describes the Log Cleaning Configuration option:


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 Number for days for which the logs should be retrained Global

- 50 -


Data Before Deleting before they are removed from the database.

- 51 -

11 Shipping RatesOn the Shipping Rates screen, you can define the shipping rate overrides. This is the configuration section for the eShopWorld supported functionality. You can define the shipping rates to be passed along with the preorder request. The way 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 extension validates them during the preorder request. If the shipping rates apply to the active customer cart, the rates information is passed over to eShopWorld API along with the preorder request.

- 52 -

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.

- 53 -

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:

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.

- 54 -


Order numbervarchar (255)

no Order number or cart identifier of the brand.

Retailer Cur-rency 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 retailerFxGroupId that exists in the eShopWorld database is used.

Payment Timevarchar (255)

yesDate and time when the order was preau-thorised 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.

Retailer Promo Codes

text yes Promo code applied.

Delivery Country varchar yes ISO 3166 format two-letter country identifier for

- 55 -


Iso (20) 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 the 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.

Retailer currency delivery price description

varchar (255)

yes Price description.

- 56 -


Shopper cur-rency delivery price before dis-count

varchar (255)

yes Price before the discount is applied.

Shopper cur-rency delivery price discount amount

varchar (255)

yesDiscount amount in shopper currency on deliv-ery price.

Shopper cur-rency delivery price discount percentage

varchar (255)

yesDiscount percentage in shopper currency on delivery price.

Shopper cur-rency delivery price

varchar (255)

yes Order delivery charge in the shopper currency.

Shopper cur-rency delivery price title

varchar (255)

yes Price title.

Shopper cur-rency 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.

- 57 -


Shopper Cur-rency Delivery

varchar (100)

yes Delivery cost in the shopper currency.

Shopper Cur-rency Delivery Duty

varchar (100)

yesDuty on the delivery cost in the shopper cur-rency.

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 Cur-rency Total

varchar (100)

yes Merchandise total in the retailer currency.

Retailer Cur-rency Delivery

varchar (100)

yes Delivery cost in the retailer currency.

- 58 -


Retailer Cur-rency Delivery Duty

varchar (100)

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

Retailer Cur-rency Delivery Taxes

varchar (100)

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

Retailer Cur-rency Taxes

varchar (100)

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

Retailer Cur-rency Other Taxes

varchar (100)

yesOther taxes element in the overall Order pay-ment amount.

Retailer Cur-rency Admin-istration

varchar (100)

yes Administration charge in the retailer currency.

Retailer Cur-rency Duty

varchar (100)

yes Duty charge in the retailer currency.

Retailer Cur-rency 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.

- 59 -




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.

- 60 -


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.

- 61 -


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

- 62 -


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.

- 63 -


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.

- 64 -


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.

Descriptionvarchar (255)

yesDescription of the promotion or voucher code.

- 65 -


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 Title

varchar (255)

yes Price title.

- 66 -


Shopper Currency Cart Discount Description

varchar (255)


- 67 -

14 Developer14.1 Setting up the Varnish cacheThis allows 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. For example:

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 {

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

}

#Fetch

- 68 -

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

if (beresp.http.Vary) {

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

}

}

14.2 Setting 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 10.

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:

- 69 -

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. 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_reference. This will update all native Magento views, such as customer account and backend admin to add tracking links to eShopWorld’s tracking portal.

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

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

the default store country from configuration is used.

l For example: esw-location:{"country":{"iso_code":"US"}}

l esw-currency: Used by extension for front-end widgets selectors to track current cur-rency

- 70 -

l 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 welcome-mat widget was already displayed for shop-per.

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.Guest checkout requestPOST /V1/eshopworld/checkout/guest-carts

BODY PARAMS

cart_id* (string)

Cart identifier.

RESPONSE 200

String url

Url to eShopWorld checkout

Logged in user checkout requestPOST /V1/eshopworld/checkout/carts/mine

HEADER PARAMS

Authorization: Bearer <customer authentication token>

RESPONSE 200

String url

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.

- 71 -

If more countries are allowed within Magneto configuration for one store, the extension allows you to set a different shipping country via the header in the API request.Set shipping country used by extension in API call1. Via Header in requestESW-COUNTRY: {{country abbreviation ISO-3166-1 ALPHA-2}}example: ESW-COUNTRY:US2. Via Cookie in request

14.5 Frontend Widgets CustomizationThe Welcome mat and drop-down selections are 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 Shipping country, currency and language options displayed in frontend widget are based on Magento configuration. Shipping countries are based on all countries selected in the General → Allowed Countries.

l Mapping between country and currency is supported by extension and can be changed in eShopWorld: Checkout → Country - Currency Mapping configuration.

- 72 -

l Any further option overrides can be achieved by using interceptor or observer for eshop-world_js_configuration_build event .

14.6 Asynchronous Operations for Magento Commerce CloudThe following changes might required to allow asynchronous operations to work with Commerce Cloud:

1. Create a .magento.env.yaml file in root directory of the project and add the following 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

namespace Vendor\Module\Example;

use EShopWorld\Checkout\Pricing\TaxManager;

class ExampleClass

{

/**

* @var TaxManager

*/

- 73 -

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

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->taxMan-ager->applyRetailerTaxes($this->taxManager->convertCurrency($basePrice, $currencyCodeFrom, $currencyCodeTo), null, $coun-tryCodeTo)), $this->taxManager->getCurrencyExponent());

}

}

- 74 -

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"

}

In addition, 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}"

}

- 75 -

eshopworldecommercesolutions magentoextensionusermanual · 2020-04-22 · the eshopworld magento...

Documents