VibeFox Windcave for Adobe Commerce — Ayuda

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.

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 module. The payment methods you want to offer (cards, wallets and others) and the currencies of your orders 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 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-windcave-payment. Without Composer: unpack the ZIP file into app/code/Vibefox/WindcavePayment/, so that registration.php is directly in that folder.

2. Run bin/magento module:enable Vibefox_WindcavePayment 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 Windcave. 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. Set Test mode (UAT) to Yes, enter your UAT username and UAT API key, choose the Transaction type and the Payment methods, set Enable to Yes, click Save Config and place a test order. When you are ready, enter the production credentials, set Test mode (UAT) to No and click Save Config.

The module adds the Credit/Debit Card (Windcave) payment method to the Magento checkout. It is off after installation (Enable = No). The module uses the standard Magento order states and creates no order statuses of its own. It creates two tables, for the Windcave payment sessions and for the captures, voids and refunds. The return and notification URLs are sent with every payment session. Nothing has to be configured at Windcave.

Configuration

All settings are in Stores > Configuration > Sales > Payment Methods > Windcave, 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. Clean uninstall is read from the Default Config only. Save Config saves the whole 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 for the payment method (1 to 128 characters).), a Sort Order that is not a whole number (Sort order must be a whole number.), a Min Order Total or Max Order Total that is not a number of 0 or greater (Order total must be a number, 0 or greater.). Write amounts with a dot, for example 9.99.

The second row of the group always shows Notification URL is sent with each session; no dashboard webhook setup is needed. and the notification URL of the default store view (with a website selected in Scope, of the default store view of that website). It looks like https://your-store/wcpwindcavepaymentgateway/checkout/notify. Each payment session sends the URLs of the store view where the order was placed, automatically. While Enable is Yes, the row also shows TEST MODE — payments use Windcave UAT. or Payments use Windcave production., or Windcave is hidden until the username and API key of the selected environment are saved. when a credential of the current mode is missing.

General

Enable: shows or hides Windcave at checkout. It is shown only when the username and API key of the current mode are saved. Default: No.

Title: the payment method name customers see at checkout. It is also stored in the order. Default: Credit/Debit Card (Windcave). Required, at most 128 characters.

Description: shown in the payment method list at checkout, under the method when the customer selects it. Default: You will be redirected to the secure Windcave payment page to complete your payment.

Test mode (UAT): sends new payments to the Windcave UAT test environment (uat.windcave.com) with the UAT credentials. No real money is taken. While it is on, customers see TEST MODE — no real charges will be made. under the payment method. With No, payments go to production (sec.windcave.com) with the production credentials. Default: No.

Windcave REST API

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

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

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

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

Enter the REST API credentials issued by Windcave, not the PxPay keys. Production and UAT credentials can be saved side by side. Magento stores the API keys encrypted and shows only a mask (******) after saving: Masked value keeps the saved secret; clear the field to remove it. Type a new value to change a key; spaces at the start and end are removed. To delete a saved key, clear the field and click Save Config.

Sessions, captures, voids and refunds always use the credentials of the environment the payment was made in. A payment started in UAT is still checked and refunded in UAT after you switch to production, so keep those credentials saved while such orders are open.

Payment

Transaction type: how the payment is taken. Purchase charges immediately. Auth authorizes only; create a full native online Invoice to capture, or cancel the order to void. Default: Purchase.

Payment methods: the methods shown on the Windcave payment page: Cards, Account2Account, Apple Pay, Google Pay, PayPal, Alipay, WeChat Pay, UnionPay, Interac, humm. Use Ctrl or Cmd and click to select several. The methods must be enabled on your Windcave account. No selection means all payment methods enabled in the Windcave account. Default: Cards.

Advanced

Debug log: writes API requests and payment events to var/log/windcave_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 are always written, also while this is off. API keys, request bodies, card data and customer data are never logged. Default: No.

Clean uninstall: Removes settings, log and tagged cache; financial transaction history is always retained. When Yes, uninstalling the module with its data deletes the settings and the log (see Uninstall). The license key is always removed. Default: No.

Conditions

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

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

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

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

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

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

Checkout

At the payment step the customer chooses the payment method (by default Credit/Debit Card (Windcave)) and sees the description, the billing address and the note You will be redirected to Windcave to complete your payment. Windcave is offered for any order currency with a total above zero; the currency must be enabled on your Windcave account. After Place Order, Magento places the order in Pending Payment. No invoice is created and no order e-mail is sent yet.

The module then creates a Windcave payment session and sends the customer to the Windcave Hosted Payment Page. The session has the order total in the order currency with the decimals of that currency, the Magento order number as the merchant reference, the language of the store view, the selected payment methods and the customer's name, e-mail, phone, billing address and shipping address (none for virtual orders). Card data is entered only on the Windcave page.

Windcave reports the result twice: the customer's browser comes back to the store, and Windcave sends its notification to the notification URL. Neither is signed by Windcave, so the module never trusts them on their own: it reads the session from the Windcave REST API with the credentials of the environment the session was created in, and checks the session ID, transaction ID and type, amount, currency and merchant reference. A lock per cart makes sure the payment is applied only once. The results are handled even when Enable is No, the test mode was switched or the license is not active.

After a Purchase is confirmed, Magento creates the invoice with the Windcave transaction as the transaction ID, the order moves to Processing and the order e-mail is sent. The customer sees the standard order success page. After an approved authorisation the order e-mail is sent and the customer sees a Windcave payment status page with Windcave authorization approved. The store will capture your payment. If the result is not known yet, the page shows Waiting for Windcave payment confirmation. with a Check again link. The order is confirmed as soon as the notification arrives. A customer who comes back in another browser lands on the home page.

If the payment was declined, cancelled or expired, the order is cancelled (the stock goes back), the cart is restored and the customer is back in the cart with Windcave payment was declined or canceled. You can try again. The customer can pay again or choose another payment method. If the customer opens the payment again for the same order and the earlier Windcave page was not used yet, the same page is opened again instead of a new session.

If the payment cannot be started, the customer is back in the cart with Windcave payment could not be started. Check the previous payment before retrying. When Windcave clearly refused the session, or the module or the credentials of the current mode were not active, the order is cancelled and the cart is restored. Without an active license the customer sees This payment method is not available. Please choose another one. instead. When Windcave did not answer (timeout, server error, unexpected answer), the order stays in Pending Payment for your review and no new session is started for that cart. The customer never got a Windcave page for it, so you can cancel such an order, and Magento cancels it after the Pending Payment Order Lifetime.

Magento cancels orders that stay in Pending Payment longer than the Pending Payment Order Lifetime (Stores > Configuration > Sales > Sales > Orders Cron Settings). Authorised orders are in Processing and are not affected. If Windcave approves a payment after the order was cancelled, the order is not re-opened and a note asks you to reconcile the payment in Windcave Payline. If the module refuses to cancel an order during this cron run (for example a payment that needs review), the order is left as it is, the reason is written to the log, and the other expired orders are still cancelled.

The module works with the standard Magento checkout. It has no subscriptions or recurring payments, no saved cards, no card fields on your site, 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. Windcave 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 Windcave, but no result has arrived yet. There is no invoice.

Processing (authorised): an Authorization only payment was approved. The order has the authorisation transaction and no invoice yet, with the note Windcave authorization approved; no charge or invoice yet. Capture the full amount with a native online Invoice, or cancel to void.

Processing (paid): a Purchase was confirmed, or an authorisation was captured. The invoice has the Windcave transaction as the transaction ID. The note shows the amount and the transaction, for example Windcave purchase approved through API verification: 25.50 NZD, transaction …

On Hold: Windcave approved a transaction that does not match the order (amount, currency, merchant reference, session or transaction type). No invoice is created. The note lists the differences and the money actually taken and asks for a manual review or refund in Windcave Payline.

Canceled: the payment was declined, cancelled or expired, the session was refused, the order was cancelled in Magento (an authorisation is then voided) or by the Pending Payment Order Lifetime cron.

Closed: the payment was fully refunded with credit memos.

A paid order is never changed by a later result. If a second approved payment arrives for a cart that is already paid or authorised, nothing is invoiced again. A note with the transaction ID asks you to review and refund it in Windcave Payline. The notes are order comments that the customer does not see.

Windcave payment information

On the admin order page (Sales > Orders > View) the payment information shows the payment method title and, for each payment attempt, a line Windcave attempt #… with the session ID, environment, transaction type, status, transaction ID, capture ID, amount, auth code and masked card, and for each capture, void or refund a line Windcave operation #… with the kind, the Windcave transaction ID, the X-ID, the amount and the status. It is shown also when the module is disabled. The customer sees only the payment method title.

Capture (Authorization only)

Open the order (it is in Processing), click Invoice, keep all items, choose Capture Online and click Submit Invoice. The full authorised amount is captured through Windcave and the invoice is created. Partial capture is not possible: Windcave requires the full authorization for capture/void and a valid amount/currency. To release the authorisation, cancel the order with Cancel; the full amount is voided. Uncaptured authorisations expire at Windcave after some days, so capture them in time.

Refunds

Open the Invoices tab of the order, open the invoice, click Credit Memo and then Refund. The refund is sent to Windcave in the order currency, to the capture transaction after a capture or to the purchase transaction, in the environment and account of the payment. For currencies without decimals (JPY, KRW, CLP and others) Magento keeps the order total with cents, while Windcave took a whole amount: each credit memo refunds the whole-unit difference of the refunded totals, and the credit memo that refunds the rest of the order refunds exactly what is left of the payment, so a full refund always matches the Windcave payment. Full and partial refunds are supported, up to the amount Windcave actually took (Refund exceeds the remaining Windcave payment.). A full refund closes the order. Refund Offline on the order page records a refund in Magento without sending money back.

If Windcave declines the refund, Magento shows Windcave declined the operation. A new attempt will use a new X-ID. and the credit memo is not created. If Windcave does not confirm it (timeout or server error), Magento shows Windcave has not confirmed the operation. Retry the same amount with its stored X-ID, or reconcile in Payline. and the credit memo is not created. Retry the same amount: Windcave recognises the X-ID and does not refund twice. A different amount or another kind of operation is refused until the unconfirmed one is reconciled. Refunds made in Windcave Payline are not reported to the store: create a credit memo with Refund Offline for them.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — Windcave is the first row of the Windcave group in Stores > Configuration > Sales > Payment Methods, 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-windcave 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, Windcave 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 This payment method is not available. Please choose another one. 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, and captures, voids and refunds work.

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

Windcave does not appear at checkout: check that the license is active and Enable is Yes for the website of the store, and that the current mode has both credentials: UAT username and UAT API key in test mode, Production username and Production API key in production. The second row of the group shows a warning when they are missing. Check Payment from Applicable Countries and Payment from Specific Countries against the customer's billing address, and Min Order Total and Max Order Total. An order total of zero is not offered.

The payment went through, but the order stays Pending Payment: the module could not get the result from Windcave yet. Errors are always written to the log: look at the Log field, for example for Windcave session verification failed. Check that the credentials of the environment of the payment are saved and correct, and that your server accepts requests from Windcave to the notification URL shown in the settings. The check is repeated when Windcave re-sends the notification, when the customer clicks Check again and when the customer opens the payment again.

Answers of the notification URL: Invalid session ID (400) and Unknown session (404) mean the session was not created by this store, for example a session of another store that uses the same Windcave account; it is ignored. Busy or Verification unavailable (503) mean that the order was being confirmed by another request at the same moment or the Windcave API could not be reached; Windcave retries later. Requests other than GET and POST get Method not allowed (405).

Results 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.

Authentication errors 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 production. PxPay keys do not work.

The customer is back in the cart with Windcave payment could not be started: Windcave refused the session (for example a currency or a payment method that is not enabled on your account), the credentials of the current mode are missing or the module was disabled; the order of that attempt is cancelled. If Windcave did not answer, the order stays in Pending Payment: check the log and the session in Windcave Payline, then cancel the order.

The order is On Hold after payment: read the order notes. The paid amount, currency, merchant reference or transaction type differed from the order. Check the transaction in Windcave Payline, then fulfil the order or refund the payment there.

Capture or refund fails with No API credentials are saved for the original Windcave environment: the payment was made in UAT or production, and no credentials for that environment are saved. Enter them and try again.

Capture fails with Windcave requires the full authorization for capture/void and a valid amount/currency: only the full authorised amount can be captured, in the order currency (for currencies without decimals, rounded to whole units like the authorisation). Invoice all items of the order.

There is no Refund button on the credit memo: open the credit memo from the invoice, not from the order page. An order without an invoice (an uncaptured authorisation, an order On Hold) cannot be refunded online: cancel it to void an authorisation, or refund the payment in Windcave Payline.

For developers: the session request can be changed before it is sent with the Magento event windcave_p_session_request (the request parameters and the order).

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_WindcavePayment. It removes the data and the code.

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

The license key and license status are always removed. If Clean uninstall is Yes, the settings and the log are removed too. If it is No, the settings are kept for a re-install. The Windcave sessions, captures, voids and refunds are always kept, so orders paid before can still be captured and refunded after a re-install. Existing orders keep their invoices, payment notes and transaction IDs.

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