VibeFox Windcave 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.

Windcave account: you need a Windcave merchant account with REST API credentials: an API username and an API key. Windcave issues them separately for the UAT test environment (uat.windcave.com) and for production (sec.windcave.com). Ask Windcave support or your account manager for them. PxPay keys do not work with this extension. The payment methods you want to offer (cards, wallets and others) must be enabled on your Windcave account.

Notification: your store must be reachable from the internet, so that Windcave can send its payment notification. Nothing has to be set up at Windcave for it.

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 wcp_windcave_payment_gateway-oc3-(version).ocmod.zip and the OpenCart 4 package wcp_windcave_payment_gateway.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 wcp_windcave_payment_gateway-oc3-(version).ocmod.zip. The extension has no OCMOD modifications, so Extensions > Modifications does not need a refresh. 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 type Payments. Find VibeFox Windcave Payment Gateway and click Install (the green + button). Your admin user needs the right to modify the payment extensions list.

3. Click Edit (the pencil button) to open the settings page. Paste your VibeFox license key into License key in the license block at the top of the page and click Activate (see License key).

4. Enter your REST API username and key: the UAT credentials for test mode, the production credentials for live payments (see Configuration).

5. Choose the transaction type and the payment methods, turn on Enable/Disable and click Save. Make a test payment with Test mode on, then turn Test mode off to take real payments.

OpenCart 4

1. In the admin go to Extensions > Installer, click Upload and choose the file wcp_windcave_payment_gateway.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 type Payments. Find VibeFox Windcave Payment Gateway, click Install (the green + button), then Edit (the pencil button).

4. Enter the license key, the Windcave credentials and the settings as in steps 3 to 5 for OpenCart 3. The settings page and its fields are the same in both versions. Only the notification URL is different (see Windcave REST API).

A new install starts with the payment method turned off.

Configuration

All settings are on the extension page: Extensions > Extensions > Payments > VibeFox Windcave Payment Gateway > Edit. The sections are listed on the left; the Save button under the list saves the whole page. While test mode is on, the page shows Test mode is on: payments go to the Windcave UAT environment and no real money is taken. If the payment method is enabled but the current mode has no API username or key, the page warns that it is hidden at checkout, for example Windcave is enabled but the UAT API username / key are empty — the payment method is hidden at checkout. Without the right to modify the extension the page shows the settings but cannot save them.

When you save, Title must not be empty and must be at most 128 characters long (Enter a title for the payment method (at most 128 characters).), Sort Order must be a whole number (Sort Order must be a whole number.), Total must be a number, 0 or greater (Total: enter a number, 0 or greater.), and the selected geo zone and order statuses must exist; otherwise nothing is saved and the page shows the error.

Windcave

Enable/Disable: Enable Windcave 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: Credit/Debit Card (Windcave). Required, at most 128 characters.

Description: the text shown to the customer at the Confirm Order step, above the confirm button. Default: You will be redirected to the secure Windcave payment page to complete your payment.

Sort Order: the position of Windcave among the payment methods at checkout. Leave it empty or enter a whole number; negative numbers are allowed.

Geo Zone: offer Windcave only for payment addresses in the selected geo zone. Default: All zones. Geo zones are set up in System > Localisation > Geo Zones.

Total: the checkout total, in the default currency of the store, that an order must reach before Windcave is offered: a number, 0 or greater. Leave it empty to offer it for any total.

Windcave REST API

Enter the REST API credentials issued by Windcave (username and API key, not the PxPay keys). Production and UAT credentials can be saved side by side. Test mode uses only the UAT credentials, live mode only the production credentials. The section links to the Windcave REST API documentation.

Test mode: uses the Windcave UAT test environment (uat.windcave.com). No real money is taken. New payments use the UAT credentials. Refunds and captures always go to the environment in which the order was paid. Default: off.

Production API username: the REST API username for sec.windcave.com.

Production API key: the REST API key for sec.windcave.com.

UAT API username: the REST API username for uat.windcave.com (test mode).

UAT API key: the REST API key for uat.windcave.com (test mode).

Saved API 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. To remove a saved key, tick Clear the saved key on save under the field and click Save.

Notification URL: shows the address to which Windcave sends its payment notification (Fail-Proof Result Notification). It is built from the storefront address of your OpenCart installation and looks like https://your-store/index.php?route=extension/payment/wcp_windcave_payment_gateway/notify on OpenCart 3 and https://your-store/index.php?route=extension/wcp_windcave_payment_gateway/payment/wcp_windcave_payment_gateway.notify on OpenCart 4. There is nothing to configure at Windcave: the extension sends its return addresses and this notification address with every payment session. The address must be reachable from the internet, otherwise orders are confirmed only when the customer returns from Windcave. Neither the customer's return nor the notification is signed by Windcave, so the extension never trusts them on their own: it always reads the result of the session from the Windcave REST API with the credentials of the environment the session was created in.

Payment

Transaction type: how the payment is taken. Default: Purchase.

Purchase (capture immediately): the money is taken when the customer pays.

Auth (authorise now, capture later): the money is only reserved. The order gets the Windcave Payment On Hold Status, and you take the money with Capture Windcave payment in the order tab, or release it by refunding the full amount. Uncaptured authorisations expire after a few days.

Payment methods: the methods shown on the Windcave payment page: Cards, Account2Account (NZ bank transfer), Apple Pay, Google Pay, PayPal, Alipay, WeChat Pay, UnionPay, Interac, humm. You can select several. The methods must be enabled on your Windcave account. Leave the field empty (Every method enabled on the account) to show every method enabled on the account. Default: Cards.

Orders

OpenCart creates the order at the Confirm Order step without a status (a missing order). The order gets a status only after Windcave has approved the payment. Each field below lists your OpenCart order statuses.

Order Status After Payment: set after an approved Purchase or after a capture. Default: Processing.

Windcave Payment On Hold Status: an Auth payment that is authorised but not captured yet, or an approved payment that does not match the order (amount, currency, reference). A note explains why; check it before shipping. Default: Pending, because OpenCart has no On hold status. You can create your own status in System > Localisation > Order Statuses and select it here.

Cancelled Order Status: not set by the extension. An approved payment that arrives for an order in this status does not change it; a note asks you to refund it in Windcave Payline or restore the order. Default: Canceled.

Refunded Status: set after the payment is fully refunded, or the authorisation is released, from the order page. Default: Refunded.

Advanced

Debug log: logs API requests and payment events to windcave_p_debug.log.php in the OpenCart logs folder (storage/logs). The file cannot be opened from the web. While this is off, only errors and warnings are logged. API keys, card data and customer personal data are never logged. Default: off.

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

Clean uninstall: deletes the extension settings and logs when the extension is uninstalled. Payment data saved with orders (Windcave transaction IDs needed for refunds) is always kept. Default: off.

The extension version is shown at the bottom of the section.

Import / Export

Export: Download JSON saves the settings as a JSON file. API keys are not exported.

Import: paste previously exported JSON and click Import to restore the settings. Saved API keys are kept.

Checkout

At the Payment Method step the customer chooses the payment method (by default Credit/Debit Card (Windcave)). At the Confirm Order step the customer sees your description; in test mode also Test mode: payments go to the Windcave UAT environment, no real money is taken. OpenCart creates the order at this step, still without a status. When the customer clicks Confirm Order, the extension creates a Windcave payment session for the order total in the order currency and sends the customer to the Windcave Hosted Payment Page. The OpenCart order number is sent as the merchant reference, together with the order language and the customer's name, e-mail, phone and billing address (and the shipping address when the order needs shipping). On OpenCart 4 the customer picks the payment method with the Choose button of the payment method block, in the window Payment method options, and clicks Confirm Order at the bottom of the checkout page.

After paying, the customer returns to your store. The order is marked paid only after Windcave confirms it: the extension asks the Windcave REST API for the result of the session, both when the customer returns and when the Windcave notification arrives. A per-cart lock makes sure the payment is applied only once. The order then gets its status the standard OpenCart way, with the usual order e-mails and stock update, and the customer sees the OpenCart order success page with Your Windcave payment has been received. For an order on hold (an authorisation or a payment that does not match the order) the page shows Your payment was received by Windcave. The store will check it before processing your order — please do not pay again.

If the customer comes back from the approved payment but the result is not known yet, a Payment confirmation page shows We are waiting for Windcave to confirm your payment. You will receive an e-mail as soon as it is confirmed — please do not pay again. and a Check again button. The notification sets the order status as soon as Windcave confirms the payment.

If the customer comes back without a completed payment, the order stays without a status, the cart is kept and the checkout page shows one of these messages:

Declined: Your payment was declined. Please try again or choose another payment method.

Cancelled or expired: The payment was not completed on the Windcave page. Your cart is saved — you can try again or choose another payment method.

Not confirmed yet: We could not confirm your payment yet. If you completed the payment, please do not pay again — you will receive a confirmation e-mail as soon as Windcave confirms it.

Return could not be processed: We could not process your return from the payment page. If you were charged, please contact us before paying again.

On OpenCart 4 these messages are shown above the checkout page.

The customer can try again with the same cart (OpenCart 3 creates a new order every time the Confirm Order step is shown; OpenCart 4 keeps one order for the checkout and updates it, so the same order is paid in a new Windcave session). A new attempt first checks the previous sessions of the cart: if one is already paid, that payment is applied, the customer goes to the success page and no second payment is started; if the customer never used the payment page and the order did not change, the customer is sent back to the same page. If the previous payment is being confirmed at that moment, the customer sees Your previous payment for this order is being confirmed right now. Please wait a minute and check your e-mail before trying again.

If Windcave cannot start the payment, the customer stays at the Confirm Order step with a message above the button: Windcave could not start the payment with the details of this order. Please check your billing details and try again, or choose another payment method. or The payment could not be started because the payment service is temporarily unavailable. Please try again in a moment or choose another payment method. The reason is written to the log. If the current mode has no credentials, the customer sees This payment method is not available at the moment. Please choose another payment method or contact us.

On OpenCart 4, if the order of the checkout got a status without a Windcave payment or was closed by the store meanwhile, the next Confirm Order sends the customer back to the checkout with This order can no longer be paid. Please check your cart and confirm the order again. above the checkout page, and the cart is paid with a new order. If the order of the checkout is already paid but the cart has changed since, including a new quantity, the customer is sent back to the checkout and the new cart is paid with a new order.

The notification and the return of the customer also work while the store is in maintenance mode: OpenCart 3 lets payment extension requests through, and on OpenCart 4 the extension adds a startup action for them.

The extension has no subscriptions or recurring payments, no saved cards, no embedded card form on your site (the customer always pays on the Windcave page), no support for the PxPay 2.0 API, and it does not add surcharges. If Windcave adds a surcharge, the order is matched against the main transaction.

Orders and refunds

Order statuses

No status (missing order): the customer was sent to Windcave and has not paid, Windcave has not confirmed the payment yet, or the payment was declined, cancelled or expired. In Sales > Orders such orders are shown only with the filter Order Status set to Missing Orders.

Order Status After Payment (default Processing): a Purchase payment was approved and matches the order. A note shows the amount, the transaction ID, the auth code, the card type with the masked card number and the environment (UAT or production).

Windcave Payment On Hold Status, authorised (default Pending): an Auth payment was approved but not captured yet. The note explains how to capture or release it.

Windcave Payment On Hold Status, does not match (default Pending): Windcave reported a different amount, currency, merchant reference or transaction type than the order (for example, the cart was changed in another tab after the payment started), or the order already had a status set by someone else. The note lists the differences. The approved money can still be refunded from the order tab. Check the payment in Windcave Payline before shipping, and refund it if necessary.

Refunded Status (default Refunded): the payment was fully refunded or the authorisation was released through the extension.

If an approved payment arrives for an order in Cancelled Order Status, or a second approved payment arrives for an order or a cart that is already paid, the order is not changed. A note with the transaction ID asks you to refund it in Windcave Payline (or restore the cancelled order manually).

Notes are entries in the order History that the customer does not see.

VibeFox Windcave Payment Gateway tab

In Sales > Orders open an order paid with Windcave. At the bottom of the order page, next to History and Additional, the VibeFox Windcave Payment Gateway tab shows the Transaction ID, the Session ID, the Type / status with the environment, the Amount paid, the Auth code / card, the Capture transaction or a released authorisation, the Payment total / refunded, a Test mode (UAT) label for test payments, the capture button, the refund form and history, the Windcave sessions of this cart and the Windcave notes of the order. The tab is shown to users who have access to the extension.

Capture (Auth mode)

For an order in Windcave Payment On Hold Status with an authorisation that has not been captured or released yet, the tab shows Capture Windcave payment. Click it and confirm Capture the authorised amount through Windcave now? The authorised amount is captured, the order moves to Order Status After Payment and the capture transaction is shown in the tab. If Windcave does not accept the capture, the tab shows Windcave capture failed: with the reason, the reason is added to the notes and the order stays on hold. The capture needs the right to modify the extension and the credentials of the environment of the payment.

Refunds

In the VibeFox Windcave Payment Gateway tab enter the Amount (the amount not refunded yet is filled in), optionally a Reason (optional), and click Refund via Windcave. Confirm the question Refund this amount through Windcave? This cannot be undone. Full and partial refunds are supported. You need the right to modify the extension (set in System > Users > User Groups). Refunds are counted against the amount and currency Windcave approved, so after a mismatch you can refund up to what the customer actually paid, not the order total. A refund after a capture goes to the capture transaction. The refund is sent to the environment (UAT or production) and the account in which the payment was made, so the credentials of that environment must be saved. A successful refund is added to the refund history and the notes with the Windcave transaction ID. A full refund sets the order to Refunded Status without notifying the customer and without returning products to stock, like a manual status change. A partial refund does not change the status.

For an Auth payment that has not been captured, the button is Release authorisation (void) and only the full amount can be released. A partial amount gives an error asking you to refund the full amount or capture the payment first.

If Windcave declines the refund, the tab shows Windcave declined the refund: with the reason and no refund is recorded. If Windcave is still processing the refund, the tab shows Windcave has not confirmed the refund yet. See the order notes. and the refund is not recorded. Check the transaction in Windcave Payline: if it was approved, record the refund manually; otherwise try again. A repeated attempt of the same refund is not sent to Windcave twice.

Product returns in Sales > Returns do not send money back through Windcave. Refunds made in Windcave Payline are not reported to the store.

License key

The extension works with a VibeFox license key from vibefox.net. The license block License — VibeFox Windcave Payment Gateway is the first block on Extensions > Extensions > Payments > VibeFox Windcave Payment Gateway > 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-payment-windcave 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, Windcave 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. An admin user who is logged in to the admin in the same browser still sees the payment 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 payment 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: payments already started are still confirmed by the notification or when the customer returns, and captures and refunds work.

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

Windcave does not appear at checkout: check that the license is active, Enable/Disable is on and the current mode has both credentials: UAT API username and UAT API key in test mode, Production API username and Production API key in live mode. The settings page shows a warning when they are missing. Also check that the payment address is in the selected Geo Zone and that the order reaches the Total set in the settings.

The payment went through, but the order stays without a status: the extension could not get the result from Windcave yet. Look at the Log field on the extension page: errors are always logged, for example when the session could not be verified. Check that the credentials of the environment of the payment are saved and correct. The check is repeated when Windcave re-sends the notification (the extension answers payment could not be verified yet, retry later with an error code, so Windcave retries), when the customer clicks Check again and when the customer starts a new payment for the same cart. Your server must accept requests from Windcave to the Notification URL shown in the settings.

The notification answers order not found: the session was not created by this store, for example a session of another store that uses the same Windcave account. It is ignored.

Authentication failed in the log: the REST API username or key is wrong, or it belongs to the other environment. UAT credentials work only in test mode, production credentials only in live mode. PxPay keys do not work.

The customer sees that Windcave could not start the payment with the details of this order: Windcave rejected the session request, for example because of the currency or a payment method that is not enabled on your account. The exact reason is in the log.

The customer sees This payment method is not available. after Confirm Order: the checkout session no longer matches the order, or the payment method was turned off meanwhile. The customer reloads the checkout.

Order is in the review status after payment: read the notes in the VibeFox Windcave Payment Gateway tab. Either the payment is an Auth that waits for capture, or the paid amount, currency or merchant reference differed from the order. Capture, fulfil or refund the payment.

Test payments and live payments: UAT and production are kept apart. Each session is checked in the environment it was created in, and refunds and captures go to the environment of the payment, even if you switch Test mode later.

Refund fails with a message about the environment: the payment was made in UAT or production, and no credentials for that environment are saved. Enter them and try again.

Capture Windcave payment is missing in the order tab: the button is shown only for orders in Windcave Payment On Hold Status paid with Auth that have not been captured or released yet, only when the credentials of the payment's environment are saved, and only to users who may modify the extension.

Where to find details: errors and warnings are always written to the log; turn on Debug log to log the API requests and payment events as well.

For developers: before the Windcave session is created, the extension triggers the OpenCart event windcave_p_session_request with the session parameters and the order.

Uninstall

Go to Extensions > Extensions, choose the type Payments and click Uninstall (the red − button) next to VibeFox Windcave Payment Gateway. The license key and license status of this extension are always removed. OpenCart always removes its own settings of the extension: Enable/Disable, Sort Order, Geo Zone, Total and the order statuses of the Orders section, which return to their defaults on a re-install. The OpenCart event of the extension is removed too (on OpenCart 4 its events and its startup action, which lets the notification and the return of the customer through in maintenance mode). If Clean uninstall is on, the other settings (title, description, test mode, API credentials, transaction type, payment methods, logging) and the log are removed. If it is off, they are kept for a later re-install. The Windcave sessions, transactions and refunds are always kept, so orders paid before can still be refunded and captured after a re-install. Existing orders keep their payment notes.

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 Windcave Payment Gateway in the list of installed extensions, then Delete (the red bin button) to remove the uploaded package.

Windcave is a trademark of its respective owner. This extension is not affiliated with or endorsed by Windcave.