VibeFox Mondial Relay for OpenCart — Help

Requirements

OpenCart: 3.0.x (tested on 3.0.5.0) or 4.0.2 and later (tested on 4.1.0.3), with the default theme.

PHP: 8.0 or later.

Mondial Relay account: the brand code (Enseigne) and the Private Key come with a Mondial Relay business account: see the professionals section of mondialrelay.fr, your "Connect" customer area or your sales contact. The map selector needs only the brand code. The list of nearest points needs both. For tests Mondial Relay provides the brand code BDTEST13 with the Private Key PrivateK.

VibeFox license key: bought on vibefox.net. One key works on one domain.

Installation

The download is one zip file with the packages for both OpenCart versions. Unpack it on your computer. It contains README.txt, the OpenCart 3 package vfd_mondialrelay-oc3-(version).ocmod.zip and the OpenCart 4 package vfd_mondialrelay.ocmod.zip. Install only the package for your OpenCart version. The license key is the same for both versions.

OpenCart 3

1. In the admin go to Extensions > Installer, click Upload and choose the file vfd_mondialrelay-oc3-(version).ocmod.zip. The extension adds no OCMOD modifications, so you do not need to refresh Extensions > Modifications. Instead of the Installer, you can copy the contents of the upload folder of this package into the root folder of your store.

2. Go to Extensions > Extensions and choose the extension type Shipping. Find VibeFox Mondial Relay and click Install (the green + button).

3. Click Edit (the pencil button) to open the settings page.

4. Paste your VibeFox license key into License key in the license block at the top of the Edit page and click Activate (see License key).

5. Enter your brand code (Enseigne) and, for the list mode, the Private Key. Fill in Country prices (for example a row for France) or a Fallback cost, turn on Enable/Disable and click Save.

OpenCart 4

1. In the admin go to Extensions > Installer, click Upload and choose the file vfd_mondialrelay.ocmod.zip. Do not rename the file: OpenCart 4 takes the extension code from the file name, and a renamed package does not work.

2. The package appears in the list of installed extensions on the same page. Click Install (the green + button) next to it.

3. Go to Extensions > Extensions and choose the extension type Shipping. Find VibeFox Mondial Relay, click Install (the green + button), then Edit (the pencil button).

4. Enter the license key and the settings as in steps 4 and 5 for OpenCart 3. The settings page and its fields are the same in both versions.

After install the method is off until you turn on Enable/Disable and save. If you install the extension again after an uninstall, the settings you kept are used again.

Configuration

All settings are on the extension page: Extensions > Extensions > Shipping > VibeFox Mondial Relay > Edit. The sections are listed on the left. One Save button saves the whole page without reloading it. Every save also clears the cached pickup point lists. Only admin users with the modify permission for this extension can save the settings.

Warnings at the top of the page show problems that hide the method: a missing brand code, a missing Private Key in list mode, no price for France, Belgium or Spain, and a store weight unit the extension does not know (product weights are then taken as kg). If Name is empty, longer than 64 characters or contains one of the characters < > ; = # { }, Min weight (kg) is greater than Max weight (kg), or the brand code is not valid, the page shows an error and nothing is saved. A number field with a value that is not a number (or is negative) is reported after Save and keeps its previous value; the other settings are saved.

General

Mondial Relay Point Relais delivery for France, Belgium, Luxembourg, Spain, Portugal and the Netherlands. The method is offered in its geo zone (see Availability), or, with Ignore shipping zones, in the listed countries.

Enable/Disable: shows or hides Mondial Relay at checkout. Default: off.

Name: the shipping method name shown to customers in the cart and at checkout. Default: Mondial Relay Point Relais. Required, up to 64 characters.

Tax status: None (default) means the prices in the table are final. A Taxable option with a tax class name means OpenCart adds the shipping tax of that tax class on top of the prices.

Sort order: the position of Mondial Relay among the shipping methods at checkout. A whole number.

Mondial Relay account

Brand code (Enseigne): required, up to 8 letters and digits, for example BDTEST13 for tests. Used by the pickup point map and by the Web Service. Without it customers cannot choose a Point Relais, so the method is not shown at checkout.

Private Key: needed only for the List of nearest points selector. After saving, the field stays empty and shows Saved - leave empty to keep it. Type a new value only to change it. To delete the saved key, tick Remove the saved Private Key and click Save. When the brand code and the Private Key are set, the connection to the Mondial Relay Web Service is tested every time you save the settings, and a message shows whether they are valid.

Pickup point selector

The customer must choose a Point Relais before continuing to the payment step. The point is saved to the order.

Selector: how the customer chooses a Point Relais.

Rates (in your store default currency, tax excluded)

Mondial Relay has no public rate API: the price comes from this table.

Country prices: price by destination country and parcel weight. Click Add country to add a row and the remove button to delete one. Choose * Default as the country for all other countries. Each row has a Price and weight columns: XS up to 1 kg, S 1-2 kg, M 2-3 kg, L 3-5 kg and XL over 5 kg. An empty or 0 weight column uses the Price column. If Price is empty too, the delivery for that weight is free, so fill in Price when you use only some weight columns. Decimals with a dot or a comma (4.90 or 4,90). Rows without any price and rows with an unknown country are dropped when you save, and values that are not numbers are reported and left empty.

Fallback cost: used for countries without a row in the table. Leave it empty to hide the method for them.

Calculation type: how the price is counted.

Free shipping from: the cart subtotal (after discounts, without tax) from which the delivery is free. Leave it empty for no free shipping.

Availability

Min weight (kg): hide the method when the cart weighs less. 0 means no limit (default).

Max weight (kg): hide the method when the cart weighs more. Mondial Relay accepts parcels up to 30 kg in Points Relais. Default: 30. 0 means no limit. An empty field means 30 kg.

Minimum subtotal: show the method only when the cart subtotal (products that need shipping, after discounts, without tax) is at least this amount. Leave it empty to always show it.

Geo zone: offer the method only for addresses in this geo zone. All zones (default) means everywhere. Geo zones are managed in System > Localisation > Geo Zones. Not checked when Ignore shipping zones is on.

Ignore shipping zones: when on, the Geo zone is not checked: the method is offered only in the countries below, or in every supported country when the list is empty.

Countries (ignore zones): the destination countries for that mode. This field is used only when Ignore shipping zones is on. The list has only the countries with Points Relais.

Advanced

Debug log: writes rate calculations, Web Service calls and the point choices to storage/logs/vfd_mrel_debug.log.php (on OpenCart 4 system/storage/logs/vfd_mrel_debug.log.php). The file cannot be read from the web. Errors are always logged, even with this option off. Keys and customer data are never logged. When the file reaches 5 MB, it is moved to vfd_mrel_debug.old.log.php and a new log is started.

Log: shows the size and the latest entries of the debug log. Click Clear log to empty it.

Remove data on uninstall: when on, uninstalling the extension deletes the settings and the log. When off (default), they are kept for a re-install. The cached point lists are always removed. The pickup points saved in orders are kept.

Import / Export

Export: click Download JSON to save the settings as a JSON file, without the Private Key.

Import: paste previously exported JSON and click Import to restore the settings, for example on another store. The same checks as Save apply. The saved Private Key is kept.

How it works at checkout

The method is offered only for countries with Points Relais: France, Belgium, Luxembourg, Spain, Portugal and the Netherlands. It is hidden when customers could not choose a point: without a brand code, or in list mode without the Private Key. If a Geo zone is set and the address is outside it, the method is not offered. With Ignore shipping zones on, the geo zone is not checked and only the countries of that list are served (all supported countries when it is empty).

When OpenCart shows the shipping methods, it asks the extension for the price. Only products with Requires Shipping set to Yes count: other products add no weight and are not included in the subtotal. Product weights are converted from their OpenCart weight class to kg. The subtotal is the price of the products that need shipping, after the coupon discount and before tax. The extension checks the cart weight and the minimum subtotal. The price comes from the row of the country (or the * row): the weight column, else Price. Without a row, the fallback cost is used. If there is no price, the method is hidden. If the subtotal reaches Free shipping from, the price becomes 0. The price is calculated in your default currency, rounded to its decimals, and shown in the customer's currency with the tax of the selected Tax status. No request goes to Mondial Relay to calculate the price.

On OpenCart 4 the customer clicks Choose in the shipping method block of the checkout page and picks Mondial Relay in the window Shipping method options. The prices are the same as on OpenCart 3.

The extension does not request live rates: Mondial Relay has no public rate API. It does not create shipments, print labels or track parcels. Create the shipments in your Mondial Relay "Connect" space using the Point Relais number shown in the order. Home delivery (Domicile) is not offered.

Pickup points

When the customer selects the Mondial Relay option at the delivery method step, a Mondial Relay pickup point box appears under it.

Map mode: the button Choose a Point Relais opens the official Mondial Relay map in a window for the delivery country, postcode and parcel weight. After the customer picks a point, it is shown as Selected: and the button changes to Change Point Relais. The map widget is loaded from widget.mondialrelay.com and its map library from unpkg.com only when the customer opens the map. Mention this in your privacy policy.

List mode: a drop-down - Choose a Point Relais - shows the 10 nearest points for the delivery postcode, with their distance. The chosen point is shown with its opening hours. The list is loaded by your server, so no third-party script runs in the browser for it. Lists are cached for 12 hours, an empty answer for 1 hour, and a failed request is remembered for 5 minutes. The Web Service timeout is 10 seconds. Without a postcode the customer sees Enter your postcode to see the nearest pickup points. If no point is found or the list is not available, the customer sees a message such as "The list of pickup points is not available right now. Please use the map." and the map is offered.

The chosen point is saved for the customer's session at once. A point is required. When the customer clicks Continue, the store checks the point again. Without one, the customer sees Please choose a Mondial Relay pickup point. and cannot continue to payment. A point in another country than the delivery address is refused with a message that the point is not in the delivery country. In list mode the point is also checked against the list for the address. After the order is placed, the choice is cleared, so the next cart chooses again.

On OpenCart 4 the Mondial Relay pickup point box appears in the window Shipping method options, under the Mondial Relay option, and the map opens inside that window. The Escape key closes only the map. The Continue button of the window does not go on without a valid point, with the same messages.

When the order is placed, the point stays with the order. The shipping method of the order shows the method name followed by the point name, address and number, for example Mondial Relay Point Relais: TABAC DU LOUVRE, 12 RUE DE RIVOLI, 75001 PARIS (FR-066974), so the customer sees it in the order e-mail and in the order history of their account. The new order e-mail to the store shows the point with its number in the comment block. In Sales > Orders the order page shows a Mondial Relay pickup point panel with the point name, address and Point Relais number, or No Point Relais was saved for this order. On OpenCart 4 the panel is shown above History. OpenCart 4 keeps one order for the checkout and updates it each time the customer confirms again, and the point of the order is updated with it. If the customer switches that order to another shipping method, its point is removed.

License key

The extension works with a VibeFox license key from vibefox.net. The license block License — VibeFox Mondial Relay is the first block on Extensions > Extensions > Shipping > VibeFox Mondial Relay > Edit, above the settings. Paste the key into License key and click Activate. After that the block shows the key masked, the status (for example the date the license is active until and your domain) and the buttons Check now to check the status again, Change key to enter another key and Remove key to remove the key from this store. Below them are the line Product: opencart-shipping-mondialrelay and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only admin users with the Modify permission for the extension can change the key. The texts of the block follow the admin language (English and Russian are included).

If the key is not accepted, the block says why, for example Key not found, This key belongs to another product, Domain limit reached or License expired on a date. After the store address changes, or after you free a domain slot in your account, click Check now. If the license server cannot be reached, the extension keeps working on the last known status.

One key works on one domain: the store address from the OpenCart configuration. Removing the key from the store does not free its domain slot. Free the slot in your vibefox.net account.

Without an active key, Mondial Relay is not shown to customers at checkout and no rate is calculated. An admin user who is logged in to the admin in the same browser still sees the method in the store, marked (unlicensed — visible to admins only), so you can set up and test the extension before you buy a key. On OpenCart 4 this preview is not available: the store does not see the admin login, so without an active key the method is hidden for everybody. After you have opened the Edit page once, a reminder appears on the admin Dashboard. Close it with × to hide it for 7 days. Existing orders are not affected.

When a license expires, the extension keeps working, but updates and support need a renewal. The status is checked again automatically when you open the admin Dashboard or the Edit page: once a day for the first 14 days after the key is entered, then once a week. No cron job is needed. Uninstalling the extension always removes the license key and license status.

Troubleshooting

Mondial Relay does not appear at checkout: check that the license is active and Enable/Disable is on. Check Geo zone, or Ignore shipping zones and its country list. Check the warnings at the top of the extension page: the method is hidden without a brand code, in list mode without the Private Key, for a country without a price, outside the weight and subtotal limits, and for countries without Points Relais. Check that the products have Requires Shipping set to Yes.

Web Service test failed after saving: the message shows the Mondial Relay error, for example an invalid brand code or an invalid security key. Check the brand code and the Private Key with Mondial Relay.

The list of points is empty or not available: the customer needs a delivery postcode first. If the Web Service fails, the map is offered instead. Turn on Debug log, reload the checkout and look at the Log field on the extension page for the reason.

The map does not open: the map is loaded from widget.mondialrelay.com and unpkg.com. Check that a privacy or script blocker, or a Content Security Policy of your store, does not block them. If the map cannot be loaded, the customer sees "The Mondial Relay map could not be loaded. Please try again later or choose another shipping method."

The order page says No Point Relais was saved for this order: the order was placed without a point of the delivery country. The reason is written to the log. Ask the customer for the Point Relais before you create the shipment.

The page says "Warning: You do not have permission to modify VibeFox Mondial Relay!": your admin user group may only view the settings. Give the group the modify permission for extension/shipping/vfd_mondialrelay (OpenCart 3) or extension/vfd_mondialrelay/shipping/vfd_mondialrelay (OpenCart 4) in System > Users > User Groups.

Uninstall

Go to Extensions > Extensions, choose the type Shipping and click Uninstall (the red − button) next to VibeFox Mondial Relay. The license key and license status of this extension are always removed. OpenCart always resets Enable/Disable, Sort order, Tax status and Geo zone. The cached pickup point lists are always removed. If Remove data on uninstall is on, the other settings and the debug log are deleted as well. If it is off, they are kept and are used again when you install the extension again. The pickup points saved in orders are always kept, and existing orders keep their shipping method and cost.

On OpenCart 4, to remove the files of the extension as well, go to Extensions > Installer after the uninstall and click Uninstall (the orange − button) next to VibeFox Mondial Relay in the list of installed extensions, then Delete (the red bin button) to remove the uploaded package.

Mondial Relay is a trademark of its respective owner. This extension is not affiliated with or endorsed by Mondial Relay.