VibeFox Windcave for WooCommerce — Help

Requirements

WordPress: 6.0 or later.

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

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 plugin. The payment methods you want to offer (cards, wallets and others) must be enabled on your Windcave account.

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_windcave_payment_gateway folder to /wp-content/plugins/ by FTP.

2. Click Activate.

3. Open the settings: WooCommerce > Settings > Payments > Windcave > 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 your REST API username and key: the UAT credentials for test mode, the production credentials for live payments (see Configuration).

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

Configuration

All settings are on one page: WooCommerce > Settings > Payments > Windcave. 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. In the list of payment methods, Windcave is marked as needing setup until the current mode has both an API username and an API key. The plugin version is shown at the bottom of the page.

General

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

Title: the payment method name customers see at checkout. Default: Credit/Debit Card (Windcave).

Description: the text shown under the payment method at checkout. Default: You will be redirected to the secure Windcave payment page to complete your payment.

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.

Test mode: Use 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).

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 is put on hold, and you take the money with Capture Windcave payment in the order actions, 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. They must be enabled on your Windcave account. Leave the field empty to show every method enabled on the account. Default: Cards.

Advanced

Debug log: Log API requests and payment events. The log is in WooCommerce > Status > Logs, source wcp_windcave_payment_gateway. Errors and warnings are always logged; this option adds API requests and payment events. API keys, card data and customer personal data are masked. Default: off.

Clean uninstall: Delete the plugin settings and logs when the plugin is deleted. Payment data saved on orders (Windcave transaction IDs needed for refunds) is always kept. Default: off.

Notification URL

You do not need to set up a notification URL at Windcave. The plugin sends its return addresses and its notification address with every payment session. Windcave sends the notification (Fail-Proof Result Notification) to https://your-site/wc-api/windcave_p_notification/. Neither the customer's return nor the notification is signed by Windcave, so the plugin never trusts them on their own: it always reads the result of the session from the Windcave REST API with your credentials of the environment the session was created in.

Checkout

The customer chooses the payment method (by default Credit/Debit Card (Windcave)) and places the order. The plugin creates a Windcave payment session for the order total in the order currency and sends the customer to the Windcave Hosted Payment Page. The order number is sent as the merchant reference, together with the store language and the customer's name, e-mail, phone and billing and shipping addresses. In test mode the Checkout block shows Test mode: payments go to the Windcave UAT environment, no real money is taken. under the payment method.

After paying, the customer returns to the order received page of your store. The order is marked paid only after Windcave confirms it: the plugin asks the Windcave REST API for the result of the session, both when the customer returns and when the Windcave notification arrives. A per-order lock makes sure the payment is applied only once. If the result is not known yet, the order received page checks it once more and 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.

If the customer comes back without a completed payment, the checkout page (or the Pay for order page, if the attempt started there) 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 order 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.

The cart is not emptied and stock is not reduced before the customer pays. A customer can pay an unpaid order again, for example from the Pay for order page. A new attempt first checks the previous session: if it is already paid, no second payment is created; 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 sees a short message: that Windcave could not start the payment with the details of this order, or that the payment service is temporarily unavailable. The reason is added to the order notes. 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.

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

The plugin 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

Pending payment: the customer was sent to Windcave and has not paid yet, or Windcave has not confirmed the payment yet. If the customer cancels or the session expires, the order stays Pending payment and a note is added.

Processing or Completed: a Purchase payment was confirmed. WooCommerce sets Processing, or Completed for orders that need no shipping, as usual. The order note shows the amount, the Windcave transaction ID, the auth code, the card type with the masked card number and the environment (UAT or production). The transaction ID of the order is the Windcave transaction ID.

On hold (authorised): an Auth payment was approved but not captured yet. The order note explains how to capture or release it.

On hold (does not match): Windcave reported a different amount, currency, merchant reference or transaction type than the order (for example, the order was edited after the payment started). The note lists the differences. Check the payment in Windcave Payline before shipping, and refund it if necessary.

Failed: the payment was declined. The note shows the Windcave response text and code. The customer can try again.

If an approved payment arrives for a cancelled order, or a second approved payment arrives for an order 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).

Capture (Auth mode)

Open the order, choose Capture Windcave payment in the order actions and click the update button. The action appears only for an On hold order with an authorisation that has not been captured or released yet. The order total is captured, the capture is added to the order notes and the order moves on as a paid order (usually Processing). If Windcave does not accept the capture, the order screen shows Windcave capture failed: with the reason, and the reason is added to the order notes.

Refunds

Open the order, click Refund, enter the amount and click Refund via Windcave. Full and partial refunds are supported. 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 order notes with the Windcave transaction ID.

For an Auth payment that has not been captured, only a full refund is possible: it releases (voids) the authorisation. A partial amount gives an error asking you to refund the full amount or capture the payment first.

If Windcave declines the refund, WooCommerce shows Windcave declined the refund: with the reason and no refund is recorded. If Windcave is still processing the refund, WooCommerce 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. Refunds made in Windcave Payline are not reported to the store.

License key

The plugin works with a VibeFox license key from vibefox.net. The license block is at the top of WooCommerce > Settings > Payments > Windcave. 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, 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. 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, and refunds and captures work.

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

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 payment went through, but the order stays Pending payment: the plugin could not get the result from Windcave yet. Open the order notes: a note says when the session could not be verified and why. 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 plugin answers it with an error until the result can be verified, so Windcave retries) and when the customer opens the order received page. Your server must accept requests from Windcave to https://your-site/wc-api/windcave_p_notification/.

Authentication failed in the order notes or the log: the REST API username or key is wrong, or it belongs to the other environment. UAT credentials work only with 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 order notes and in the log.

Order is On hold after payment: read the order note. 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. Orders created by version 1.0 of the plugin use the environment of the old API URL setting.

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 actions: the action is shown only for On hold orders paid with Auth that have not been captured or released yet.

Where to find details: errors and warnings are always written to WooCommerce > Status > Logs, source wcp_windcave_payment_gateway. Turn on Debug log to log the API requests and payment events as well.

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 plugin options and the logs (log files, including rotated ones, and database log entries) are removed only if Clean uninstall was on. Otherwise they stay for a later re-install. Existing orders keep their payment notes and Windcave transaction IDs.

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