VibeFox Ozow for Adobe Commerce — ヘルプ

Requirements

Magento: Magento Open Source or Adobe Commerce 2.4.6 to 2.4.9, on your own server or hosting, on premises or on Adobe Commerce on cloud infrastructure. The module does not work with Adobe Commerce as a Cloud Service (the SaaS edition), which does not accept PHP modules.

PHP: 8.1 to 8.4, with the curl extension for the Ozow GetTransaction API.

Currency: South African rand (ZAR). The payment method is shown only when the order (cart) currency is ZAR. Ozow charges whole cents.

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 store: your store must be reachable from the internet, without 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

The module is one ZIP file. It is a Composer package and can also be copied into app/code. Run the commands in the Magento root folder as the user that owns the Magento files.

1. With Composer: put the ZIP file into a folder that your project uses as a Composer "artifact" repository and run composer require vibefox/module-ozow-payment. Without Composer: unpack the ZIP file into app/code/Vibefox/OzowPayment/, so that registration.php is directly in that folder.

2. Run bin/magento module:enable Vibefox_OzowPayment and bin/magento setup:upgrade. In production mode also run bin/magento setup:di:compile and bin/magento setup:static-content:deploy, then bin/magento cache:flush.

3. In the Admin go to Stores > Configuration > Sales > Payment Methods and open VibeFox Ozow Pay. When the Magento PayPal module is enabled, the group is listed under Other Payment Methods. Paste your VibeFox license key into License key in the license block, the first row of the group, and click Activate (see License key).

4. Enter the Site Code and Private Key, and preferably the API Key, from your Ozow merchant dashboard. Keep Test mode at Yes, set Enable Ozow to Yes, click Save Config and place a test order in ZAR. When everything works, set Test mode to No and click Save Config to accept real payments.

The module adds the Instant EFT (Ozow) payment method to the Magento checkout. It is off after installation (Enable Ozow = No). The module uses the standard Magento order states and creates no order statuses of its own. It creates its own tables for the Ozow payment attempts and their events. The notification and return 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.

Configuration

All settings are in Stores > Configuration > Sales > Payment Methods > VibeFox Ozow Pay, in the standard Magento configuration form. Like other Magento settings, they can be changed for a website with the Scope switcher at the top of the page; Title and Description also for a store view. Remove data on uninstall exists only in the Default Config. Save Config saves the whole page. Amounts accept "9.99" and "9,99". The group has no sub-sections; below, its fields are grouped by purpose in the order of the page.

If a value is wrong, Magento shows an error and nothing on the page is saved: an empty Title or a title longer than 128 characters (Enter a title of 1 to 128 characters.); a Sort order that is not a whole number (Sort order must be a whole number.); a Minimum Order Total or Maximum Order Total that is not a number of 0 or greater (Order total must be zero or greater.). The Site Code and keys are saved as entered, only spaces at the start and end are removed; their format is not checked when you save.

General

Enable Ozow: shows or hides Ozow at checkout. It is shown only when the Site Code and Private Key are set. Default: No.

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

Description: the text shown under the payment method when the customer selects it 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.

Sort order: the position among the payment methods at checkout. A whole number.

Ozow credentials

Copy the Site Code, Private Key and API Key from your Ozow merchant dashboard.

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 invoiced. The API must report the payment as complete, for this order, with the same amount, and, when the API reports them, the same currency, Site Code and transaction. Without an API Key a payment with a valid signature is accepted.

Magento stores the Private Key and API Key encrypted and shows only a mask (******) after saving. Leave the mask unchanged to keep the saved key, type a new value to change it. To delete a saved key, clear the field and click Save Config.

Test mode: Ozow uses the same Site Code and keys for tests: payments are created with IsTest=true and no money moves. While it is on, customers see TEST MODE: no money is transferred. under the payment method, and orders paid in test mode get the note TEST MODE: no money was received; do not ship this order. Set it to No to accept real payments. A test payment never pays an order in live mode or an order started in live mode. Default: Yes.

Conditions

Payment from Applicable Countries: All Allowed Countries offers Ozow for every country your store allows, Specific Countries only for the countries below.

Payment from Specific Countries: offer Ozow only for billing addresses in these countries.

Minimum Order Total: offer Ozow only from this order total, in the base currency of your store. Empty means no minimum.

Maximum Order Total: offer Ozow only up to this order total, in the base currency. Empty means no maximum.

Ozow callbacks and verification

This row says that Ozow signs the notification and the customer return with SHA-512, that an API Key adds the GetTransaction check and that the callback URLs are sent with each payment. It shows the notification URL, which looks like https://your-store/wcpozowpay/checkout/notify/, and the return URL, which looks like https://your-store/wcpozowpay/checkout/back/, built from the base URL of the default store view. Each payment sends the URLs of the store view where the order was placed: the notification URL, and the return URL as the success, cancel and error URL. If your Ozow site is set to fixed URLs, enter these URLs there. The row also says that refunds are made in the Ozow dashboard.

While Enable Ozow is Yes, the row also shows warnings: Enter the Ozow Site Code and Private Key. The method stays hidden until configured.; Ozow accepts South African rand (ZAR) only. when the currency of the default store view is not ZAR; and TEST MODE: no money is transferred. while test mode is on.

Advanced

Debug Log: the module writes to var/log/ozow_p_debug.log.php in the Magento folder. The file cannot be opened from the web and is rotated at 5 MB. Errors and warnings, for example an Ozow answer with an invalid hash or a failed order update, are always written. This setting allows additional information and debug entries. Keys, hashes, tokens and e-mail addresses are hidden in the log. Default: No.

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

Remove data on uninstall: when Yes, uninstalling the module with its data removes the module settings of all scopes, its cache and the log (see Uninstall). The license key is always removed. Orders, invoices and the Ozow payment records are always kept. Default: No.

Checkout

At the payment step the customer chooses the payment method (by default Instant EFT (Ozow)) and sees the description. After Place Order, Magento places the order in Pending Payment. No invoice is created and no order e-mail is sent yet. The module 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 from the billing address 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 confirmed 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 order (a random token of the attempt is checked), and the amount and currency must match the order. With an API Key the payment is also checked with the GetTransaction API. The notification and the return are handled even when Enable Ozow is No or the license is not active.

After a successful payment Magento creates the invoice with the Ozow transaction ID (with -capture added) as the transaction ID, the order moves to Processing and the order e-mail is sent. The customer sees the standard order success page with Ozow payment confirmed. A customer who comes back in another browser lands on the home page with the same message. If Ozow or the bank is still investigating the payment, or the GetTransaction API has not confirmed it yet, the customer sees a page with We are waiting for Ozow to confirm your payment., Do not pay again until the payment status is known. and a Check again link; the next Ozow notification or Check again completes the order. If the payment needs review by the store, the success page shows Your Ozow payment requires review. Do not pay again.

If the customer cancels on the Ozow page or the payment fails, the order is cancelled (the stock goes back), the cart is restored and the customer is back in the cart with The Ozow payment was not completed. You can try again. The customer can pay again or choose another payment method. A test payment for a live order also cancels the order, with Ozow reported a TEST payment for a live order. The order was not marked as paid.

If the payment cannot be started (the module is disabled, the license is not active, the Site Code or Private Key is missing, the order currency is not ZAR or the total is zero), the order is cancelled, the cart is restored and the customer sees Ozow could not start payment. Please check your order before retrying. If the cart already has an Ozow payment that is still open, pending, under review or paid, no second payment is started: the new order is cancelled with the note This cart already has an Ozow payment. Do not pay again. and the customer is sent to the status of the earlier payment.

Magento cancels orders that stay in Pending Payment longer than the Pending Payment Order Lifetime (Stores > Configuration > Sales > Sales > Orders Cron Settings). If Ozow later reports a payment for a cancelled order, the order is not invoiced and not reopened: a note asks you to review the payment in the Ozow dashboard.

The module works with the standard Magento checkout. It takes one-time payments in ZAR only. It has no refunds from Magento, no authorization and later capture, no subscriptions, no saved bank accounts or tokenization. Ozow is not offered for orders created in the Admin.

Orders and refunds

Order statuses

Pending Payment: the order was placed and the customer was sent to Ozow, but Ozow has not confirmed the payment yet. When Ozow or the bank is investigating the payment, the note Ozow payment is pending investigation by the bank. The order will update when Ozow sends the final status. is added. There is no invoice.

Processing: Ozow confirmed the payment. The invoice is created with the Ozow transaction ID, and a note shows how the payment was confirmed (notification, return or check), the transaction and, with an API Key, Confirmed by the Ozow GetTransaction API. A test payment also gets TEST MODE: no money was received; do not ship this order.

On Hold: no invoice is created, and the note tells why: the paid amount or currency differs from the order; the GetTransaction API contradicts the signed payment; or the GetTransaction API has not confirmed the payment yet. In the last case the next Ozow notification or Check again releases the hold and invoices the order. In the other cases check the payment in your Ozow dashboard and process the order yourself. If an order is on hold for another reason, for example set by you, a later payment only adds the note Ozow payment received for an order on Hold. Review it manually before fulfilment.

Canceled: the payment was cancelled, abandoned or failed at Ozow, a test payment arrived for a live order, the payment could not be started, the cart already had an Ozow payment, or the order was cancelled in Magento. The note shows the Ozow status and transaction.

A paid order is never changed back, and repeated notifications and returns, even at the same moment, never invoice an order twice. If a second payment arrives for a cart that is already paid, a note on the paid order asks you to refund the duplicate in your Ozow dashboard. The notes are order comments that the customer does not see.

Ozow payment information

On the admin order page (Sales > Orders > View) the payment information shows the payment method title and, after the payment, Ozow transaction, Payment reference and Test mode. Below it, a VibeFox Ozow Pay section lists every payment attempt with Payment reference, Attempt, Ozow transaction, Status, Requested / received amount, Test mode and Ozow message, followed by the processed Ozow events. It is shown also when the module is disabled. The customer sees only the payment method title.

Refunds

Refunds from Magento are not supported. Refund the payment in your Ozow merchant dashboard, then record it in Magento with a credit memo and Refund Offline.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Ozow Pay is the first row of the VibeFox Ozow Pay group in Stores > Configuration > Sales > Payment Methods (Default Config scope), 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: magento-payment-ozow and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only Admin users whose role allows the Payment Methods configuration section can change the key. The texts of the block follow the Admin interface locale (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 module keeps working on the last known status.

One key works on one domain: the domain of the default store view, also when the installation has several websites or stores. Removing the key from the store 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 order is cancelled, the cart is restored and the customer sees Ozow could not start payment. Please check your order before retrying. The Magento storefront does not know that you are logged in to the Admin, 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 the System Messages of the Admin, with the links Enter the license key and Dismiss, which hides it for 7 days. 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: once a day for the first 14 days after the key is entered, then once a week, by the Magento cron and while you work in the Admin. Uninstalling the module with its data always removes the license key and license status.

Troubleshooting

Ozow does not appear at checkout: check that the license is active and Enable Ozow is Yes for the website of the store, that the Site Code and Private Key are filled in and that the cart currency is ZAR. The Ozow callbacks and verification row shows a warning when something is missing. Check Payment from Applicable Countries and Payment from Specific Countries against the customer's billing address, and Minimum Order Total and Maximum Order Total.

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 store is reachable from the internet (no password protection or firewall blocking Ozow). If your Ozow site is set to fixed URLs, check that they are the URLs shown in Ozow callbacks and verification. Read the Log field.

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 store. Nothing is changed. Invalid request means that required Ozow fields are missing.

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: with an API Key, the GetTransaction API could not confirm the payment. The order is on hold and the next notification or Check again completes it. If it stays on hold, check the API Key and the payment in your Ozow dashboard.

The notification answers Please retry: the customer's return was being processed for the same cart at the same moment, or the order could not be updated. Ozow may retry; see the log.

Notifications fail while the store is in maintenance mode: Magento maintenance mode closes the whole site, the notification and return URLs too. The order is confirmed by the next notification or return that reaches the store.

A test payment did not pay the order: the module is in live mode or the order was started in live mode. Test payments never pay such an order; the order note says so and the order is cancelled.

The order is On Hold after payment: read the order note and check the payment in your Ozow dashboard, then process the order yourself or refund the payment in Ozow.

The settings page or the checkout looks unchanged after installing or updating: run bin/magento setup:upgrade and bin/magento cache:flush; in production mode also setup:di:compile and setup:static-content:deploy.

Uninstall

Deleting the module code alone removes nothing from the database: the license key and the settings stay. To remove the data, uninstall the module with the Magento command:

Installed with Composer: run bin/magento module:uninstall --remove-data Vibefox_OzowPayment. It removes the data and the code.

Installed in app/code: run bin/magento module:uninstall --non-composer Vibefox_OzowPayment to remove the data, then bin/magento module:disable Vibefox_OzowPayment, delete the folder app/code/Vibefox/OzowPayment and run bin/magento setup:upgrade.

The license key and license status are always removed. If Remove data on uninstall is Yes, the module settings of all scopes, its cache and the log are removed too. If it is No, the settings are kept for a re-install. The tables with the Ozow payment attempts and events are always kept, so late notifications of old orders are still recognised after a re-install. Existing orders keep their invoices, payment notes and transaction IDs.

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