VibeFox Ozow for WooCommerce — Help

Requirements

WordPress: 6.2 or later.

WooCommerce: 8.0 or later, installed and active. The plugin refuses to activate without it.

PHP: 8.0 or later.

Currency: South African rand (ZAR). The payment method is hidden for other currencies. Ozow charges whole cents, so WooCommerce 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 site must be reachable from the Internet, without maintenance mode, password protection or a firewall blocking Ozow, so that Ozow notifications arrive.

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

Installation

1. In WordPress go to Plugins > Add New > Upload Plugin, choose the plugin ZIP file and click Install Now. You can also upload the wcp_ozow_pay folder to /wp-content/plugins/ by FTP.

2. Click Activate.

3. Open the settings: WooCommerce > Settings > Payments > Ozow > Manage, or click Settings under the plugin name on the Plugins page.

4. Enter your VibeFox license key in the license block at the top of the page and click Activate.

5. Enter the Site Code and Private Key, and preferably the API Key, from your Ozow merchant dashboard.

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

Configuration

All settings are on one page: WooCommerce > Settings > Payments > Ozow. Above the fields the page warns you when the Site Code or Private Key is missing (Ozow is then hidden at checkout), when the store currency is not ZAR, when WooCommerce uses more than 2 decimals, and shows Test mode is on: no real payments are accepted. Do not ship orders paid in test mode. while test mode is on. In the list of payment methods, Ozow is marked as needing setup until the Site Code and Private Key are filled in.

General

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

Title: the payment method name customers see at checkout. 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.

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 order, with the same amount, currency and Site Code.

Test mode: Enable Ozow 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 note; 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 the notification URL. It looks like https://your-site/wc-api/ozow_pay/?ozow_notify=1. If your Ozow site uses fixed URLs, copy it exactly as the settings show it.

Advanced

Debug log: Log payment requests and Ozow responses writes details to WooCommerce > Status > Logs, source wcp_ozow_pay. Errors and warnings are always logged. Keys, hashes and customer data are never logged. Default: off.

Delete data on uninstall: Remove the settings and logs of this plugin when it is deleted (Ozow data saved on orders is kept). Default: off.

Checkout

The customer chooses the payment method (by default Instant EFT (Ozow)) and places the order. The plugin sends the customer to the hosted Ozow payment page with a signed request for the order total in ZAR. The bank statement reference is Order and the order number (up to 20 Latin letters, digits, spaces and dashes). The customer's name is passed to Ozow. On the Ozow page the customer chooses a South African bank and approves the payment in the banking app.

Ozow then notifies the store and sends the customer back. Both carry the same signed answer, and both are processed the same way, so the order is updated 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 carry the key of this order, and the amount and currency must match the order. With an API Key the payment is also checked with the GetTransaction API.

After a successful payment the customer lands on the order received page. If Ozow has not confirmed the payment yet, 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 the customer cancels on the Ozow page or the payment fails, the order becomes Failed and the customer goes back to the Pay for order page with 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. The customer can pay the same order again.

The payment method works on the classic checkout, on the Checkout block and on the Pay for order page (only for orders in ZAR). It is compatible with WooCommerce High-Performance Order Storage (HPOS).

The plugin takes one-time payments in ZAR only. It has no refunds from WooCommerce, no subscriptions, no saved bank accounts or tokenization, and no payment links sent from the admin.

Orders

Order statuses

Pending payment: the customer was sent to Ozow and has not paid yet, or Ozow has not confirmed the payment yet.

Processing: the payment was confirmed. This is the standard WooCommerce status after payment; orders with only virtual downloadable products become Completed. The order note shows the amount and the Ozow transaction ID, and whether the payment was confirmed by the GetTransaction API. The transaction ID of the order is the Ozow TransactionId. A test payment gets the note TEST MODE — no money was received, do not ship this order.

On hold: the order note tells why. Ozow or the bank is investigating the payment (the order is updated when Ozow sends the final status); the paid amount or currency differs from the order; 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.

Failed: the customer cancelled the payment, the payment was abandoned or Ozow reported an error. The customer can pay again from the order.

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 note 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 note and you set the order to Processing yourself.

Refunds

Refunds from WooCommerce are not supported. Refund the payment in your Ozow merchant dashboard and record the refund in WooCommerce manually.

License key

The plugin works with a VibeFox license key from vibefox.net. The license block is at the top of WooCommerce > Settings > Payments > Ozow. Paste the key into License key and click Activate. The block shows the status, for example the date the license is active until and your domain. Use Check now to check the status again, Change key to enter another key and Remove key to remove it from this site. The link Manage licenses and domains in your account opens your vibefox.net account.

One key works on one domain. Removing the key from a site 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. Logged-in store managers still see the payment method, marked (unlicensed — visible to admins only), so you can set up and test the plugin before you buy a key. A reminder appears on the Plugins page and on WooCommerce pages. Existing orders are not affected: payments already started are still confirmed.

When a license expires, the plugin keeps working, but updates and support need a renewal. The status is checked again automatically in the background.

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 store or order currency is ZAR. The settings page shows a warning when something is missing.

The payment went through, but the order stays Pending payment: the Ozow notification did not reach the store and the customer did not come back. Check that your site is reachable from the Internet (no maintenance mode, password protection or firewall blocking Ozow). If your Ozow site is set to fixed URLs, check that the notification URL is exactly the one shown in the settings. Turn on Debug log and look at WooCommerce > Status > Logs, source wcp_ozow_pay.

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.

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 an order of this store. 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 Order busy: another Ozow answer for the same order was being processed at the same moment. The answer is not applied; the next notification or the customer return applies it.

The notification answers Payment not confirmed 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.

The customer sees Ozow accepts payments in South African rand (ZAR) only: the order is in another currency. Ozow cannot be used for it.

A test payment did not pay the order: the gateway is in live mode. Test payments never pay an order in live mode; a note on the order says so.

Order is On hold after payment: read the order note and check the payment in your Ozow dashboard, then set the order to Processing or refund the payment in Ozow.

The license block shows an error: follow the message in the block. For example, if the key is already used on another domain, free a slot in your vibefox.net account and click Check now. If the site address changed, click Check now to activate the key for the new domain. If the license server cannot be reached, the plugin keeps working on the last known status.

Uninstall

Deactivating the plugin keeps all data. To remove it, deactivate and delete it on the Plugins page. The license key and license status of this plugin are always removed. The gateway settings, the other options of the plugin and its logs are removed only if Delete data on uninstall was on. Otherwise they stay for a later re-install. Existing orders keep their payment notes and transaction IDs.

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