VibeFox SMSA Express for PrestaShop — Help

Requirements

PrestaShop: 8.0 to 9.x.

PHP: 8.0 or later. The module refuses to install on older PHP versions.

SMSA Express rate card: the prices for the price table come from your SMSA account or the SMSA sales team. Enter them in your shop 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 and ask for access to the SMSA web service with your account number. 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

1. In the back office go to Modules > Module Manager and click Upload a module. Choose the module ZIP file.

2. When the upload finishes, click Configure, or find VibeFox SMSA Express in the module list later and click Configure.

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

4. Enter your SMSA Express prices in the price table and click Save.

5. Optional: under Live rates (API) turn on Live charges, enter your SMSA passKey, the ship-from city and country, and, if your shop default currency is not SAR, the exchange rate.

On install the module creates the SMSA Express carrier with the delivery time text SMSA Express courier. The carrier is assigned to all zones and all customer groups. You can change zones, customer groups, delivery time, logo and size limits in Shipping > Carriers. Do not set prices there: the price always comes from the module.

Configuration

All settings are on the module page: Modules > Module Manager > VibeFox SMSA Express > Configure. Each section has its own Save button, which saves the whole page. Every save also clears the cached SMSA charges. A value that is not a number, a negative number, an exchange rate of 0, a currency code that is not 3 letters, or a Minimum weight above the Maximum weight is refused with an error, and nothing is saved until you correct it.

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 shop weight unit is not known to the module (product weights are then read as kg). Set kg, g, lb or oz in International > Localization (Local units).

General

Enable SMSA Express: turns the carrier on or off in all zones at once. This is the same switch as the carrier status in Shipping > Carriers.

Method title: the carrier name shown in the cart and at checkout. Default: SMSA Express. Required, up to 64 characters.

Tax: the tax rule of the carrier, or No tax. Choose No tax if your prices (the table and the SMSA charges) already include tax, for example Saudi VAT.

Live rates (API) (optional; if SMSA returns no charge, the price table is used)

Live charges: get the shipping charge from SMSA Express. 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. Leave it empty to use the shop city from Shop Parameters > Contact > Stores.

Ship-from country: the country your parcels are sent from. By default it is your shop country.

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: SMSA returns every charge with its currency code, usually SAR (the default). A charge in any currency other than this one or your shop default currency is not used.

Exchange rate: the price of 1 unit of the SMSA currency in your shop 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. Both a point and a comma are accepted as the decimal separator.

Prices (your SMSA Express rate card in your shop 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 and the trash icon to remove one. The row * Default (all other countries) applies to countries without their own row. Each row has a base price and weight columns: XS up to 1 kg, S up to 2 kg, M up to 3 kg, L up to 5 kg and XL over 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 carrier in that case.

Price applies: how the price is calculated.

Product weights are converted from your shop weight unit to kilograms.

Conditions

Minimum weight: hide the carrier when the cart weighs less, in kg. 0 means no limit.

Maximum weight: hide the carrier when the cart weighs more, in kg. Default: 30. 0 or an empty field means no limit.

Minimum order amount: show the carrier only when the cart subtotal (after discounts, before tax) reaches this amount. Leave empty to always show it.

Free shipping from: the cart subtotal (after discounts, 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.

Availability without shipping zones

Normally the carrier is offered in the zones it is assigned to in Shipping > Carriers.

Ignore shipping zones: offer SMSA Express for the countries below, whatever zone matches. While this is on, the carrier is added to all zones, also to zones created later. Switching it off removes those added zones again.

Countries: the destination countries for that mode. Leave empty to use all active countries of the shop. This field is used only when Ignore shipping zones is on.

Advanced

Debug log: logs rate calculations to logs/vfd_smsa_debug.log.php in the module folder. The file cannot be opened 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.

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 module deletes the SMSA Express settings, the carrier and the log. When off, everything is kept for a re-install. Cached charges are always removed.

How it works at checkout

At the shipping step PrestaShop asks the module for the SMSA Express price. Only physical products count: virtual products add no weight and are not included in the order amount. The module first checks the conditions: the countries of Ignore shipping zones (if on), cart weight and minimum order amount. If free shipping applies, the price is 0 and no request goes to SMSA.

With live charges on, the module 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 module converts it to your shop default currency, and the price is then shown in the customer's cart currency. 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, missing product weights, 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 carrier is hidden. The customer never sees an error. The reason is written to the log.

If you edit the carrier in Shipping > Carriers after it has orders, PrestaShop saves it as a new carrier version. The module follows the new version automatically.

The module 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 carrier is door-to-door delivery.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox SMSA Express is the first block on Modules > Module Manager > VibeFox SMSA Express > Configure, 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 shop. Below them are the line Product: presta-shipping-smsa-express and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only employees with the Configure permission for the module can change the key. The texts of the block follow the back office 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 shop address changes, or after you free a domain slot in your account, click Check now. If the license server cannot be reached, the module keeps working on the last known status.

One key works on one domain: the domain of the main shop, also in a multistore setup. Removing the key from the shop does not free its domain slot. Free the slot in your vibefox.net account.

Without an active key, the SMSA Express carrier is not shown to customers at checkout and no rate is calculated. The PrestaShop storefront does not know that you are logged in to the back office, so the carrier is hidden for you too: you can set up the module before you buy a key, but not test it at checkout. A reminder appears in Modules > Module Manager on the Alerts tab. Existing orders are not affected.

When a license expires, the module keeps working, but updates and support need a renewal. The status is checked again automatically while you work in the back office: once a day for the first 14 days after the key is entered, then once a week. No cron job is needed. Uninstalling or resetting the module 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. In Shipping > Carriers check that the carrier covers the zone of the customer's country and the customer's group (or that Ignore shipping zones is on and the country is allowed). Check 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. Products can also be limited to certain carriers in the product page.

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 module 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 is above Maximum weight. 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 to No tax.

Rates look outdated after a change: click Save on the module page. This clears the cached SMSA charges.

The page says the SMSA Express carrier was not found: the carrier was deleted in Shipping > Carriers. Reset the module in Modules > Module Manager to create it again.

Uninstall

Go to Modules > Module Manager, open the menu next to VibeFox SMSA Express and choose Uninstall. The license key and the license status are always removed. The cached charges are always removed. If Remove data on uninstall is on, the carrier is deleted (orders keep their history) and the settings and log are removed. If it is off, the carrier is only disabled and all settings are kept. Installing the module again, or a Reset, gives the carrier back the status it had before.

SMSA Express is a trademark of its respective owner. This module is not affiliated with or endorsed by SMSA Express.