VibeFox SMSA Express 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).
PHP: 8.0 or later.
SMSA Express rate card: the prices for the price table come from your SMSA account or the SMSA sales team. Enter them in your store default currency. If your rate card is in SAR, AED or another currency, convert it first.
SMSA passKey (for live charges only): live charges use the SMSA web service (SECOM, operation getShipCharges). SMSA issues the passKey on request: ask your SMSA account manager or write to info@smsaexpress.com. The passKey may differ from the API key of the SMSA e-commerce portal. SMSA has no test (sandbox) server for this service.
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_smsa_express-oc3-(version).ocmod.zip and the OpenCart 4 package vfd_smsa_express.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_smsa_express-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 SMSA Express 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 SMSA Express prices in the price table.
6. Optional: under Live rates (API) turn on Live charges, enter your SMSA passKey, the ship-from city and country, and, if your store default currency is not SAR, the exchange rate.
7. Turn on Enable SMSA Express and click Save.
OpenCart 4
1. In the admin go to Extensions > Installer, click Upload and choose the file vfd_smsa_express.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 SMSA Express, click Install (the green + button), then Edit (the pencil button).
4. Enter the license key and the settings as in steps 4 to 7 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 SMSA Express and save. If you install the extension again after an uninstall, the SMSA Express settings you kept are used again.
Configuration
All settings are on the extension page: Extensions > Extensions > Shipping > VibeFox SMSA Express > Edit. The sections are listed on the left. One Save button saves the whole page without reloading it. Every save also clears the cached SMSA charges. An invalid method title, a value that is not a number, a negative number, an exchange rate of 0, a currency code that is not 3 letters, a wrong price in the table, a Minimum weight (kg) above the Maximum weight (kg) or a sort order that is not a whole number is refused with an error, and nothing is saved until you correct it. Only admin users with the modify permission for this extension can save the settings.
When live charges are on, warnings above the settings tell you about a missing passKey, ship-from city or exchange rate, or an empty price table. A warning also appears if the store has no kg weight class and its default weight unit is not known to the extension (product weights are then read as kg). Add a kg weight class in System > Localisation > Weight Classes.
General
The settings apply to every geo zone. You can limit the method to a geo zone in Conditions, or to a list of countries with Ignore shipping zones.
Enable SMSA Express: shows or hides SMSA Express at checkout. Default: off.
Method title: the shipping method name shown to the customer in the cart and at checkout. Default: SMSA Express. Required, 64 characters at most, without the characters < > ; = # { }.
Sort order: the position of SMSA Express among the shipping methods at checkout. A whole number.
Live rates (API) (optional; if SMSA returns no charge, the price table is used)
Live charges: get the shipping charge from SMSA Express. When off, nothing is sent to SMSA during checkout. Default: off.
SMSA passKey: the key of the SMSA web service (SECOM). After saving, the field stays empty and shows Saved — leave empty to keep it. Type a new value only to change it. Tick Remove the saved passKey to delete it. If the log shows "Invalid Passkey", the key is not accepted by this service. Ask SMSA for a web-service passKey.
Ship-from city: the city your parcels are sent from, spelled as SMSA does, for example Riyadh, Jeddah or Dammam. Required for live charges: OpenCart has no store city, so it is never taken from the store address.
Ship-from country: the country your parcels are sent from. The first option, Store country, uses the country of your store from System > Settings > Store > Local. This is the default.
Shipment type: sent to SMSA as the shipment type. DLV (the default) is standard delivery. Change it only if SMSA gave you another code.
Currency of SMSA charges: the 3-letter code of the currency SMSA returns charges in, usually SAR (the default). A charge in any currency other than this one or your store default currency is not used.
Exchange rate: the price of 1 unit of the SMSA currency in your store default currency, for example 0.27. Not needed when both currencies are the same. Without it, charges in another currency are not used and the price table applies.
Prices (your SMSA Express rate card in your store default currency; used when live charges are off, and as the fallback when SMSA returns no charge)
Price table: one row per destination country. Click Add country to add a row. The row * All other countries applies to countries without their own row. Each row has a Base price and weight columns: XS ≤1 kg, S ≤2 kg, M ≤3 kg, L ≤5 kg and XL >5 kg. An empty or 0 weight column uses the base price. A base price of 0 means free shipping. Rows without any price are not saved. If a country has two rows, the first one is used. Both "9.99" and "9,99" are accepted.
Price for countries not in the table: used when the table has no row for the destination country (and no * row) or the row has no price for this weight. Leave it empty to hide the method in that case.
Price applies: how the price is calculated.
Product weights are converted from their OpenCart weight class to kilograms.
Conditions
Minimum weight (kg): hide the method when the cart weighs less. 0 means no limit (default).
Maximum weight (kg): hide the method when the cart weighs more. Default: 30. 0 or an empty field means no limit.
Minimum order amount: show the method only when the subtotal of the products that need shipping (after the coupon, before tax) reaches this amount. Leave it empty to always show it.
Free shipping from: the subtotal of the products that need shipping (after the coupon, before tax) from which SMSA Express shipping is free. When the cart reaches it, the price is 0 and no request goes to SMSA. Leave it empty to never offer free shipping.
Tax class: the tax class of the shipping cost, or No tax (default). Choose No tax if your prices (the table and the SMSA charges) already include tax, for example Saudi VAT.
Geo zone: offer SMSA Express only for addresses in this geo zone. All zones (default) means no limit. Not checked while Ignore shipping zones is on. Geo zones are managed in System > Localisation > Geo Zones.
Availability without shipping zones
Normally the method is offered for the addresses of the geo zone chosen in Conditions.
Ignore shipping zones: offer SMSA Express for the countries below, whatever the geo zone. When off, the geo zone decides and the country list is not used.
Countries: the destination countries for that mode. Leave it empty to use all countries enabled in the store. This field is used only when Ignore shipping zones is on.
Advanced
Debug log: logs rate calculations to storage/logs/vfd_smsa_debug.log.php. The file cannot be read from the web. No customer addresses and no keys are logged. Errors of live charges are always logged, even when this option is off. Turn the log off when you are done. When the file reaches 5 MB, it is moved to vfd_smsa_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 SMSA Express settings and the log. When off (default), the settings are kept for a re-install. Cached charges are always removed.
Import / Export
Export: click Download JSON to save the settings as a JSON file. The passKey is not exported.
Import: paste previously exported JSON and click Import to restore the settings, for example on another store. The values are checked like a normal save. The saved passKey is kept.
How it works at checkout
When OpenCart shows the shipping methods, it asks the extension for the SMSA Express price. If a Geo zone is set (and Ignore shipping zones is off) and the address is outside it, SMSA Express is not offered. Only products with Requires Shipping set to Yes count: other products add no weight and are not included in the order amount. The extension then checks the conditions: the countries of Ignore shipping zones (if on), cart weight and minimum order amount. Gift certificates, reward points and store credit are not taken into account. If free shipping applies, the price is 0 and no request goes to SMSA.
With live charges on, the extension sends SMSA your ship-from city and country, the customer's city and country, the shipment type, the parcel weight in kg and a cash on delivery amount of 0. SMSA answers with the charge and its currency. The extension converts it to your store default currency and rounds it to its decimals. The price is then shown in the customer's currency with the tax of the selected Tax class. A live charge is requested only after the customer has entered a delivery address with a city.
Each charge is cached for an hour, so the same cart does not trigger a new request. A failed request is cached for 5 minutes. After a timeout or server error, SMSA is not asked again for 2 minutes. After a rejected key, it is not asked again for 5 minutes. So the checkout never waits for a failing service on every refresh. The request timeout is 12 seconds.
Whenever SMSA returns no usable charge (no passKey, no city entered yet, an invalid key, a timeout, an error, no service to the city or an unknown currency), the price table is used. If the table and Price for countries not in the table give no price, the method is hidden. The customer never sees an error. The reason is written to the log.
The extension only calculates the shipping price. It does not create SMSA shipments, print AWB labels, handle returns or track parcels. Cash on delivery and its fee are not included in the live charge. There is no SMSA retail point selector: the method is door-to-door delivery. It adds nothing to orders: the order shows the method title and the shipping cost like any other OpenCart shipping method.
On OpenCart 4 the customer clicks Choose in the shipping method block of the checkout page and picks SMSA Express in the window Shipping method options. The method works the same way as on OpenCart 3.
License key
The extension works with a VibeFox license key from vibefox.net. The license block License — VibeFox SMSA Express is the first block on Extensions > Extensions > Shipping > VibeFox SMSA Express > 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-smsa-express 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, SMSA Express 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
SMSA Express does not appear at checkout: check that the license is active and Enable SMSA Express is on. Check Geo zone (or, with Ignore shipping zones on, Countries), the weight limits and Minimum order amount. Check that the country or * has a price, or that Price for countries not in the table is set. Check that the products have Requires Shipping set to Yes.
Customers see the table price instead of the SMSA charge: SMSA needs the customer's city, so until it is entered the table price is shown. The table is also used when SMSA does not answer, rejects the key or the city, or returns the charge in a currency without an exchange rate. Look at the Log field on the extension page for the reason.
"Invalid Passkey" in the log: the key is not accepted by the SMSA web service. Ask SMSA for a web-service passKey.
The customer's city is not accepted: SMSA expects its own city spelling. Check the city in the delivery address and the Ship-from city.
The settings are not saved and an error is shown: a number field contains text or a negative value, the exchange rate is 0, the currency code is not 3 letters, or Minimum weight (kg) is above Maximum weight (kg). Correct the value named in the message and click Save again.
Tax is charged twice on shipping: your rate card or SMSA charges may already include VAT. Set Tax class to No tax.
Rates look outdated after a change: click Save on the extension page. This clears the cached SMSA charges.
The page says "Warning: You do not have permission to modify VibeFox SMSA Express!": your admin user group may only view the settings. Give the group the modify permission for extension/shipping/vfd_smsa_express (OpenCart 3) or extension/vfd_smsa_express/shipping/vfd_smsa_express (OpenCart 4) in System > Users > User Groups.
For developers: the SMSA web service address can be replaced with the setting vfd_smsa_api_url (for tests); it has no field on the settings page.
Uninstall
Go to Extensions > Extensions, choose the type Shipping and click Uninstall (the red − button) next to VibeFox SMSA Express. The license key and license status of this extension are always removed. OpenCart always resets Enable SMSA Express, Sort order, Tax class and Geo zone. The cached charges are always removed. If Remove data on uninstall is on, the SMSA Express settings and the debug log are deleted as well. If it is off, the other settings are kept and are used again when you install the extension again. 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 SMSA Express in the list of installed extensions, then Delete (the red bin button) to remove the uploaded package.
SMSA Express is a trademark of its respective owner. This extension is not affiliated with or endorsed by SMSA Express.