VibeFox Ozow for PrestaShop — Help

Requirements

PrestaShop: 8.0 to 9.x.

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

Currency: South African rand (ZAR). The payment method is shown only for carts in ZAR. Ozow charges whole cents, so the currency should use 2 decimals.

Ozow account: an Ozow merchant account with the Site Code and Private Key of your Ozow site, from your Ozow merchant dashboard. The API Key is optional but recommended. Ozow uses the same Site Code and keys for test and live payments.

Reachable site: your shop must be reachable from the Internet, without password protection or a firewall blocking Ozow, so that Ozow notifications arrive. The notification is accepted even while the shop is in maintenance mode.

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 Ozow Pay 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 the Site Code and Private Key, and preferably the API Key, from your Ozow merchant dashboard.

5. Turn on Enable/Disable and click Save. Make a test payment with Test mode on, then turn test mode off to accept real payments.

On install the module creates two order statuses, Awaiting Ozow payment and Ozow payment on hold. PrestaShop offers a new payment module for all currencies, countries and customer groups. You can limit them in Payment > Preferences; there ZAR must be allowed for the module. A country enabled later must also be ticked for the module there.

Configuration

All settings are on the module page: Modules > Module Manager > VibeFox Ozow Pay > Configure. Each section with a Save button saves the whole page. Above the fields the page warns you when the Site Code or Private Key is missing (Ozow is then hidden at checkout), when the shop's default currency is not ZAR, when the currency has more than 2 decimals (set it to 2 in International > Localization > Currencies), and shows Test mode is on: no real payments are accepted. Do not ship orders paid in test mode. while test mode is on.

Ozow

Enable/Disable: Enable Ozow payments turns the payment method on or off. Default: off.

Title: the payment method name customers see at checkout. It is also the payment method name stored in the order. Default: Instant EFT (Ozow).

Description: the text shown under the payment method at checkout. Default: Pay instantly and securely from your South African bank account. You will be redirected to Ozow to choose your bank and approve the payment. In test mode the line TEST MODE: no money will be charged. is added under it (only when the description is not empty).

Ozow credentials

Copy the Site Code, Private Key and API Key from your Ozow merchant dashboard (Merchant details / Sites). The section links to the Ozow integration documentation at hub.ozow.com.

Site Code: the Site Code of the Ozow site that receives the payments. Answers for another Site Code are rejected.

Private Key: signs every payment request and verifies every Ozow answer. Keep it private. Without it the payment method is hidden and no Ozow answer is accepted.

API Key (recommended): optional. With an API Key, every successful payment is also confirmed with the Ozow GetTransaction API before the order is marked paid. The API must report the payment as complete, for this cart, with the same amount, currency and Site Code.

Saved keys are never shown again. The field stays empty and shows Saved — leave empty to keep it. Type a new value only to change it.

Clear saved secrets: tick Private Key or API Key and save to remove a saved key. An empty field keeps the saved value.

Test mode: Ozow uses the same Site Code and keys for tests: payments are created with IsTest=true and no money moves. Orders paid in test mode get an order message; do not ship them. Turn test mode off to accept real payments. A test payment never pays an order in live mode. Default: on.

Payment notifications

The notification, success, cancel and error URLs are sent to Ozow with every payment, so nothing has to be configured in the Ozow dashboard, unless your Ozow site is set to fixed URLs. The section shows all four URLs: Notification URL, Success URL, Cancel URL and Error URL. They are module links of your shop (controllers notify and return). If your Ozow site uses fixed URLs, copy them exactly as the settings show them.

Advanced

Debug log: logs payment requests and Ozow responses to logs/ozow_p_debug.log.php in the module folder (not readable from the web). Errors and warnings are always logged. Keys, hashes, tokens and customer data are never logged. Default: off.

Log: shows the current size and the end of the log, with a Clear log button.

Delete data on uninstall: removes the settings and logs of this module when it is uninstalled (Ozow data saved on orders is kept). Default: off.

Checkout

At the payment step the customer chooses the payment method (by default Instant EFT (Ozow)) and confirms the order. The module sends the customer to the hosted Ozow payment page with a signed request for the cart total in ZAR. The bank statement reference is Cart and the cart number (up to 20 Latin letters, digits, spaces and dashes). The customer's name is passed to Ozow. No order exists yet at this point. On the Ozow page the customer chooses a South African bank and approves the payment in the banking app.

Ozow then notifies the shop and sends the customer back. Both carry the same signed answer and both are processed the same way, so the order is created even when one of them is lost. The order is marked paid only after Ozow confirms it: the hash must verify with your Private Key, the Site Code must be yours, the answer must belong to this payment attempt of the cart, and the amount and currency must match the cart. With an API Key the payment is also checked with the GetTransaction API.

After a successful payment the customer sees the standard order confirmation page. If Ozow or the bank is still investigating the payment, the page says We are waiting for Ozow to confirm your payment. You will receive an e-mail as soon as it is confirmed — there is no need to pay again. If the order is on hold, it says Your Ozow payment was received and is being reviewed by the store. We will contact you if anything is needed. If an investigated payment later fails or the unpaid order is cancelled, it says Your Ozow payment was not completed. Please contact us about this order. If Ozow has not confirmed the payment yet when the customer comes back, a page shows the waiting text with Check again and Back to checkout buttons.

If the customer cancels on the Ozow page or the payment fails, no order is created. The customer goes back to the checkout with the same cart and sees The Ozow payment was cancelled. You can try again or choose another payment method. or The Ozow payment was not completed. You can try again or choose another payment method.

If the cart is not in ZAR, the customer sees Ozow accepts payments in South African rand (ZAR) only. Please choose another payment method.

The module takes one-time payments in ZAR only. It has no refunds from PrestaShop, no subscriptions, no saved bank accounts or tokenization, and no payment links sent from the back office.

Orders and refunds

Order statuses

No order yet: the customer was sent to Ozow and has not paid, cancelled, or Ozow has not confirmed the payment yet. Only the cart exists.

Payment accepted: the payment was confirmed. The order message shows the amount and the Ozow transaction ID, and whether the payment was confirmed by the GetTransaction API. The transaction ID of the order payment is the Ozow TransactionId. A test payment gets the message TEST MODE — no money was received, do not ship this order.

Awaiting Ozow payment: Ozow or the bank is investigating the payment. The order is updated when Ozow sends the final status.

Ozow payment on hold: the order message tells why: the paid amount or currency differs from the cart; a payment arrived for an order that had already been cancelled; or, with an API Key, the GetTransaction API could not confirm the payment yet or contradicts it. Check the payment in your Ozow dashboard and change the order status. If the API could not answer, the next Ozow notification completes the order.

Payment error: a payment that was under investigation was cancelled, abandoned or failed. A later successful Ozow answer for it still marks the order paid.

An order that is already paid is never changed back, and a cancelled or refunded order is never re-opened. If a second payment arrives for an order that is already paid, a message asks you to refund the duplicate in your Ozow dashboard. If an order is on hold for another reason, for example set by you, a later payment only adds a message and you set the order to Payment accepted yourself.

Ozow payment block

The order page shows an Ozow payment block with the transaction reference and attempt, the Ozow transaction ID, the status, the requested amount, the amount reported by Ozow, the Ozow message and a TEST MODE mark for test payments.

Refunds

Refunds from PrestaShop are not supported. Refund the payment in your Ozow merchant dashboard, then record the refund in PrestaShop manually.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Ozow Pay is the first block on Modules > Module Manager > VibeFox Ozow Pay > 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-payment-ozow 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, Ozow is not shown to customers at checkout. If a payment is started anyway, the customer sees This payment method is not available. Please choose another one. The PrestaShop storefront does not know that you are logged in to the back office, so the payment method 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: payments already started are still confirmed.

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

Ozow does not appear at checkout: check that the license is active, Enable/Disable is on, the Site Code and Private Key are filled in and the cart currency is ZAR. In Payment > Preferences check that the module is allowed for ZAR, the customer's country and the customer's group. The settings page shows a warning when something is missing.

The payment went through, but no order was created: the Ozow notification did not reach the shop and the customer did not come back. Check that your shop is reachable from the Internet (no password protection or firewall blocking Ozow). If your Ozow site is set to fixed URLs, check that the URLs are exactly the ones shown in Payment notifications. Turn on Debug log and read the log on the Configure page.

The notification answers Invalid hash: the Private Key in the settings does not belong to the Ozow site that sent the answer. Copy it again from the Ozow merchant dashboard. Nothing is changed.

The notification answers Unknown site: the answer came from another Ozow site. Check the Site Code.

The notification answers Order mismatch or Order not found: the answer does not belong to a payment started in this shop. Nothing is changed.

The notification answers Gateway not configured: the Site Code or Private Key is missing. Fill them in; Ozow may retry.

The notification answers Payment not confirmed yet: the answer could not be applied yet. With an API Key, the GetTransaction API could not confirm the payment (the order is on hold and the next notification completes it; if it stays on hold, check the API Key and the payment in your Ozow dashboard). It is also the answer when the customer's return was being processed for the same cart at the same moment, or when the order could not be created; see the log.

A test payment did not pay the order: the module is in live mode. Test payments never pay an order in live mode; the order message or the log says so.

Order is Ozow payment on hold after payment: read the order message and check the payment in your Ozow dashboard, then set the order to Payment accepted or refund the payment in Ozow.

Uninstall

Go to Modules > Module Manager, open the menu next to VibeFox Ozow Pay and choose Uninstall. The license key and license status of this module are always removed. If Delete data on uninstall is on, the module settings and the log are removed. If it is off, all settings are kept for a later re-install. The Ozow payment records and the order statuses Awaiting Ozow payment and Ozow payment on hold are always kept, so late notifications of old orders are still recognised after a re-install. Existing orders keep their payment messages and transaction IDs.

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