eshopworldecommercesolutions magentoextensionusermanual · 2019-11-11 · 2 overview...

Version: 2.3.0Published date: August 2019

Copyright © 2019 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.2 Out of scope 4

2.3 Magento Extension and eShopWorld Checkout flow 4

2.4 Compatibility 5

2.4.1 Magento Compatibility 5

2.4.2 eShopWorld Checkout Compatibility 5

3 How it works 63.1 Prerequisites 6

3.2 Retailer platform and eShopWorld checkout flow 6

3.3 Pricing Models 7

3.4 Pricing API (hosted by eShopWorld) 8

3.5 Checkout API (hosted by eShopWorld) 9

3.5.1 Process Flow 9

3.6 Order Confirmation Request (hosted by retailer) 9

3.6.1 Process Flow 9

4 Installation and setup 114.1 Installing the extension 11

4.2 Verifying the installation 11

4.3 Accessing the extension 12

4.4 Viewing configuration 12

5 Configuration 145.1 Setting up Magento for Fixed price model 14

5.1.1 Country and Currency setup 14

- i -

5.1.2 Varnish cache setup 14

6 Security Token Service (Checkout 2.0) 166.1 Security Token Configuration 16

7 Checkout 177.1 General Configuration 17

7.2 Pricing Feed Configuration 18

7.3 Country – Currency Mapping 19

7.4 Retailer Display Configuration 20

7.5 Pricing Configuration 22

7.6 Preorder Expansion Pairs Configuration 23

7.7 Preorder URL Configuration 25

7.8 Order Confirmation Configuration 27

8 Order Confirmation 298.1 Order Confirmation v2.0 29

8.1.1 eShopWorld Order 29

8.1.2 eShopWorld Order Items 35

8.1.3 eShopWorld Order Cart Discounts 41

9 Package 439.1 General Configuration 43

9.2 Synchronisation with eShopWorld 45

9.2.1 Synchronisation status 45

9.2.2 Cron synchronisation 46

9.3 Administration interface 47

9.3.1 Shipments grid 47

9.3.2 Shipment details view 47

10 Shipping Rates 4811 Logs 4911.1 General Configuration 49

11.2 Logs Cleaning 49

- ii -

11.3 Extension Logs 50

12 Troubleshooting 5112.1 Extension not appearing on the dashboard 51

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

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

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 -

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 the international shoppers.

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 check-out.

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.2 Out of scopeThe following features are out of the scope of the extension:

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

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

- 4 -

2.4 Compatibility

2.4.1 Magento Compatibility

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

2.4.2 eShopWorld Checkout Compatibility

The eShopWorld Magento extension supports eShopWorld Checkout 1.0 and Checkout 2.0. eShopWorld Checkout 1.0 will soon be deprecated and all retailers will be moved to Checkout 2.0, which has been redesigned for scalability.

- 5 -

3 How it works3.1 PrerequisitesTo 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 international country setup, which are unique to each retailer. eShopWorld provides the tenant information to the retailers during their onboarding.

3.2 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.The following figure describes the flow between the retailer's platform and eShopWorld checkout:

- 6 -

3.3 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 Base price model, in which the product base price is exclusive of any taxes. This model utilizes the Pricing Adjustments API. Base price is taken from Magento's native price field and formulas are applied to this value to -display the localized price to shoppers. Shop-pers can select from a list of payment currency options when using the base price model.

l Billing price model, in which the product price is inclusive of all taxes. Prices are taken from the native Magento price fields. This model supports native Magento price features, such as Special Price. Only a single currency can be used when using the billing price model.

The shipping fee is not included in both models.

- 7 -

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

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

- 8 -

pricing advisor to the eShopWorld’s hosted checkout to facilitate end-to-end customer flow.

3.5 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.5.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.

3. On failure, the shopper remains on the retailer’s cart page.

3.6 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.6.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.

- 9 -

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

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.

- 10 -

4 Installation and setupThis chapter describes how to install the eShopWorld Magento extension:

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 Checkout.zip file inside the packages/eshopworld folder.

4. Install Composer using the apt-get install composer command.

5. From the Magento root directory, run the composer config repositories.eshopworld-checkout "artifact"

"packages/eshopworld command.

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

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

8. From the Magento root directory, run the php bin/magento c:c command.

9. Change the permission on www/html to:

l sudo chown -R www-data:www-data /var/www/html/.

l sudo chmod -R 755 /var/www/html/.

4.2 Verifying the installationTo verify the installation:

- 11 -

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.

- 12 -

- 13 -

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

5.1 Setting up Magento for Fixed price modeleShopWorld's Magento Plugin uses native Magento configuration to setup countries to be displayed on the eShopWorld landing page and footer. eShopWorld's module pulls countries from all Magento websites to create a list on the landing mat and footer.

l Fixed price model is in use by default for country if the Magento base currency is equal to current customer display currency.

l FX price model is in use by default for country if Magento base currency is not equal to current customer display currency. Under Pricing Configuration, the Force FX price Model Countries option forces the FX price model, which overrides the default logic.

5.1.1 Country and Currency setup l To set up a Fixed Price country, add countries to Allowed Countries in Stores > Con-

figuration > General > Allowed Countries.

l Set Base Currency in Stores > Configuration > Currency Setup to the currency to be used and the same currency set in Default Display Currency and the same currency in Allowed Currencies.

5.1.2 Varnish cache setup

A change is required to how the cache key is built. This allows FX pricing model to work with Varnish cache. The value of the cache key should include the eShopWorld currency cookie "esw.currency" or "esw.location" value. For example:

sub vcl_hash {

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

- 14 -

{ 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); }

}

Or by updating vary header

#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

if (beresp.http.Vary) {

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

}

- 15 -

6 Security Token Service (Checkout 2.0)eShopWorld 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.

Global

Client Id Unique identifier assigned to a client. Global

Client Secret

Unique secret assigned to a client. Global

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

- 16 -

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:

- 17 -

Option Description Dependency Scope

Extension Version

Read-only version number of the installed plu-gin.

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 options are 1.0 and 2.0.

None Global

Base Cur-rency

Defines the retailer base currency. None Website

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.

The following table describes the Pricing Feed Configuration options:

- 18 -


Pricing Feed Enabled

Enables or disables the functionality. None Global

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 country 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 Global

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.

- 19 -

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.

- 20 -

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

- 21 -


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 Selector in Footer Bar

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

Global

7.5 Pricing ConfigurationThis tab contains the Pricing configuration.

- 22 -

The following table describes the Pricing Configuration options:


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 FX Price Model Countries

Indicates countries that will use the FX pricing model even if the Magento base currency is the same as cus-tomer 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  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:

- 23 -

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

- 24 -


Size codeDefines the size code attribute, which will be passed in the pre-order request.

Global

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.

- 25 -

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 Sand-box 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 checkout/cart as a default URL, if empty - not set. For an empty record, a predefined value is used

None Global

- 26 -


from the 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 validated during order confirmation. eShopWorld recom-mends that you enable this option to secure order confirmation callback URL from unau-thorized 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

- 27 -


Order Status

Defines the order status of a newly created order. Default indicates the default Magento order status. Paid indicates the invoices cre-ated automatically.

None Global

- 28 -

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

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

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

- 29 -


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

- 30 -


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 varchar yes Price description.

- 31 -


delivery price description

(255)

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)

yes Price description.

Delivery Option text yes Key-value pairs used for passing additional

- 32 -


Metadata Items details.

Shopper Cur-rency Total

varchar (100)

yes Merchandise cost in the shopper currency.

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- varchar yes Uplift in the shopper currency.

- 33 -


rency Uplift (100)

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.

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.

- 34 -


Created at timestamp no

8.1.2 eShopWorld Order Items

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




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.

UPC varchar yes 12-digit Universal Product Code assigned to each

- 35 -


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

Retailer Cur-rency Price Info Before Discount

varchar (100)

yes

Price before the discount is applied in the retailer cur-rency. The value is a combination of a three-letter currency identifier (in the ISO 4217 format) followed 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

varchar (255)

yes Price title.

- 36 -


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-letter currency identifier (in the ISO 4217 format) followed by a number.

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

varchar (255)


- 37 -


Description

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 Standard Cata-log Item

integer yesIndicates whether the product is a non-standard cata-log 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- varchar yes Item delivery charge in the shopper currency.

- 38 -


rency Item Deliv-ery

(20)

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-rency Item Taxes

varchar (20)

yes Item taxes charge in the shopper currency.

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- varchar yes Taxes on delivery cost in the shopper currency.

- 39 -


rency Item Uplift (20)

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.

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.

- 40 -

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

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)


- 41 -


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.

Shopper Currency Cart Discount Description

varchar (255)


- 42 -

9 Package This chapter describes the integration between Magento shipments and eShopWorld package.

9.1 General ConfigurationThis tab contains general information to enable the package extension features.

- 43 -

The following table describes the General Configuration options:


Extension Ver-sion

Read-only version number of the installed extension.

None Global

Enable Pack-age Syn-chronization

Indicates if the eShopWorld package syn-chronization is enabled.

None Global

Brand Code Defines the brand code, which is a retailer- None Global

- 44 -


specific identifier.

eShopWorld Package Allowed Coun-tries

Countries selected in this list will have package integration enabled. The ship-ment address will be used to trigger the integration.

None Global

Enable Cron Synchronization

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

None Global

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

Global

Batch SizeMaximum number of Magento shipments to synchronize with eShopWorld.

Enable cron synchronization

Global

9.2 Synchronisation with eShopWorld

9.2.1 Synchronisation status

Custom Magento shipment status allows the extension to maintain synchronization workflow, a change in status change is recorded in the shipment comment as a note.

Status Description

Pending

The default status when the package synchronization is enabled and a new shipment is created in Magento. It indicates that the shipment is ready to be pushed to eShopWorld. You can only push the shipment to eShopWorld if the status is Pending.

SynchronizedIndicates that the shipment has been pushed to eShopWorld without errors. If a successful message is returned by eShopWorld, this is stored

- 45 -

Status Description

in the shipment comment and eShopWorld logs.

ErrorIndicates that the shipment been pushed to eShopWorld but an error is encountered. The error message returned by eShopWorld is stored in the shipment comment and eShopWorld logs.

Ignored

The shipment synchronization status will be set to Ignored if any of the following conditions apply:

l Shipment synchronization is disabled.

l The shipment country is not enabled in eShopWorld package allowed countries.

If the country is enabled in eShopWorld package allowed countries after the order is placed, you can change the Ignored status to Pending in the shipment details view.

9.2.2 Cron synchronisation

The Cron job is used to send eShopWorld shipment updates from Magento. A request is sent for each shipment with Pending shipment status. The following table states the shipment status update based on a response from eShopWorld’s Package 2.0 API:

Global code return Sync action

204 Success Update record status to Synchronized.

400 Bad Request

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

- 46 -

Global code return Sync action

400 Invalid AsnApiRequest error status: Leave current record status. 999 General error: Update record status to Error.

401 Unau-thorized

Leave current record status

404 (not found) Leave current record status

500 Server Error Leave current record status

9.3 Administration interface

9.3.1 Shipments grid l eShopWorld synchronization status column with current shipment status.

l Action to push the shipment to eShopWorld.

9.3.2 Shipment details view 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.

- 47 -

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

- 48 -

11 Logs 11.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

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

- 49 -


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

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

- 50 -

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

12.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 :

"require": {

"magento/product-community-edition": "2.2.1",

"composer/composer": "@alpha",

"eshopworld/module-checkout": "2.3.0"

}

- 51 -

eshopworldecommercesolutions magentoextensionusermanual · 2019-11-11 · 2 overview...

Documents