Windcave Terminal Gateway

The Windcave Terminal gateway lets you take in-person card payments on a Windcave terminal through Windcave HIT. Payments are started from WCPOS and completed on the terminal, with confirmation written back to the WooCommerce order.

New in 0.1.0 — pending Windcave certification

0.1.0 is the first release. Windcave requires QA certification of an integration before it is used in production, and this integration is not yet certified. Use it with Windcave UAT (test) credentials until certification is complete. The Vendor ID is issued by Windcave during certification.

Features

Cloud HIT Connection

Connect through Windcave's cloud HIT service with one Station ID per terminal and no local pairing

Terminal Prompts on Screen

Follow the terminal's prompts and buttons from the payment panel, including YES/NO for signature verification and CANCEL

Verified Completion

Orders complete only after the payment reference, amount, environment, order total, and currency are checked

Set a Payment Aside

After a timeout, set the pending payment aside and carry on while a background check follows it up

Result Notifications

Enable optional result notifications (FPRN) so Windcave can notify your site as a backup to polling

How It Works

The gateway uses Windcave HIT (Host Initiated Transaction) over HTTPS. Environment selects the UAT or production endpoint, and each terminal is addressed by its Windcave-issued Station ID.

Starting a payment sends the full order total and currency to the terminal. The payment page polls Windcave every 1.5 seconds, mirroring the terminal's prompts and available buttons. Optional Result notifications (FPRN) let Windcave notify the site as a backup to polling.

Setup

1

Install Windcave Terminal for WooCommerce

Download the plugin zip asset (not the GitHub source-code zip) from the GitHub releases page. Upload it via Plugins > Add New > Upload Plugin and activate it with WooCommerce installed and active.

Activation requires PHP 7.4+ and the PHP DOM extension (php-xml). If either is missing, activation is refused with a message.

2

Get HIT credentials from Windcave

Ask Windcave for a HIT username, a HIT key, and one Station ID per terminal. Request a development account through Windcave's Integration Requirements form.

UAT and production credentials are separate. Use UAT credentials while this integration is awaiting certification.

3

Configure the gateway

1. Go to WP Admin > WooCommerce > Settings > Payments and open Windcave Terminal
2. Set Environment to UAT (testing) (the default). Production is for use after Windcave certification with production credentials
3. Enter the HIT username and HIT key issued by Windcave
4. Enter your Station IDs, one per line
5. (Optional) Set a Default Station ID. Enable Lock terminal selection to always use that default and prevent cashiers from changing it
6. Leave Vendor ID empty until Windcave issues one during certification
7. Save your settings

4

Turn on result notifications (optional)

Enable Result notifications (FPRN) and save to ask Windcave to notify your site when a transaction result is ready. This is a backup to polling.

5

Enable in WCPOS

1. Go to WP Admin > POS > Settings > Checkout
2. Find the Windcave Terminal gateway and enable it for the POS
3. Save your settings

nota

The Enable/Disable checkbox on the WooCommerce settings screen controls the online store checkout only. WCPOS uses this gateway once it is configured, whether or not that box is ticked.

Settings reference

Setting	What it does
Enable/Disable	Enables the gateway for online store checkout. POS enablement is controlled under POS > Settings > Checkout
Title	The checkout label; defaults to Windcave Terminal
Description	The checkout description; defaults to Pay in person on the Windcave terminal.
Environment	UAT (testing) (default) or Production. Each uses separate HIT credentials; production requires Windcave certification
HIT username	The HIT username issued by Windcave for the selected environment
HIT key	The HIT key issued by Windcave for the selected environment
Station IDs	One Windcave-issued Station ID per line, one for each terminal
Default Station ID	The preselected Station, also used when no Station is selected
Lock terminal selection	Always uses the default Station so cashiers cannot change it. Only takes effect when a default is set
Vendor ID	Issued by Windcave during certification. Leave empty until Windcave provides it
POS name	The name sent to Windcave to identify the POS; defaults to WCPOS
Result notifications (FPRN)	Asks Windcave to notify the site when a transaction result is ready, as a backup to polling. Off by default
Checkout logs	Shows log tools on the payment panel. Off by default
Log level	Off, Errors only, or Debug. Defaults to Debug, logging requests and responses with keys and card data masked
Support	Provides Download support bundle and a link to view logs in WooCommerce > Status > Logs

There is no connection-test button: credentials and Station IDs are checked when the first payment runs.

Usage

Processing Payments

1. Add Items: Add products to your cart in the POS
2. Select Gateway: Choose Windcave Terminal as the payment method
3. Choose Terminal: Select a Station, or use the locked default. Selection is required when there are two or more Stations and no default
4. Start Payment: Click Start Terminal Payment to send the order total to the terminal
5. Follow Prompts: The terminal's prompts and available buttons appear on screen, including YES/NO for signature verification and CANCEL when offered
6. Automatic Completion: After approval and verification, the order completes and the POS goes to the receipt

Payment Controls

• Start Terminal Payment: Send a new payment request to the selected Station
• Cancel Terminal Payment: Presses the terminal's CANCEL button when the terminal offers it. Otherwise, cancel on the terminal or set the payment aside when that option appears
• Set payment aside: Appears after the 5-minute timeout. It leaves the attempt to a 10-minute background check so you can take payment another way; it does not cancel the payment at Windcave
• Reloading the page: Resumes a payment already in progress

Receipts

Terminal receipt text, when Windcave returns it, is saved as a private order note in WooCommerce.

Refunds

Refunds from WooCommerce are not supported in 0.1.0. Refund in the Windcave portal (Payline) or on the terminal, then record the refund in WooCommerce manually.

Logs and support bundle

Find logs in WooCommerce > Status > Logs, under source windcave-terminal. The log level defaults to Debug, recording Windcave requests and responses with keys and card data masked.

Click Download support bundle on the gateway settings screen to download a .json file, and send it with the order number. It contains environment details, settings with the HIT key and username masked, payment attempts from up to 20 recent orders with receipts removed, and the last 1,000 lines from the two newest log files; log lines may include terminal receipt text with card numbers masked.

If WooCommerce uses the database log handler, the bundle contains no log lines. Export logs from WooCommerce > Status > Logs instead.

Enable Checkout logs to show log tools on the payment panel.

Requirements

Windcave Account: HIT username, HIT key, and a Station ID per terminal; production use requires Windcave certification

Compatible Hardware: A Windcave terminal using HIT

WCPOS: Pro version required for POS checkout

Server: WordPress 5.2+, WooCommerce, and PHP 7.4+ with the DOM extension (php-xml)

Currency: A two-decimal currency

Stable Connection: Reliable internet connection for API communication

Scope & Limitations

Certification required

This integration is not yet certified by Windcave. Use UAT credentials until Windcave QA certification is complete; do not use it in production before certification.

• Refunds from WooCommerce are not supported in 0.1.0
• Tips, surcharge, and cash-out are not supported
• Only two-decimal currencies are supported
• The terminal is charged the full order total; paying only part of an order on the terminal is not supported
• Station IDs are entered by hand; terminals are not discovered automatically
• The gateway is built for the POS. On the online store, it only works on the order-pay page

Troubleshooting

Common Issues

Activation is refused: PHP DOM extension (php-xml) required

• The server is missing the PHP DOM extension
• Ask your host to enable php-xml. Activation also requires PHP 7.4+

No Station IDs configured

• The Station IDs setting is empty
• Add the Station IDs issued by Windcave in the gateway settings, one per line, and save

Windcave HIT credentials are not configured

• The HIT username or HIT key is empty
• Enter both in the gateway settings and save. Make sure Environment matches those credentials

The terminal is still finishing an earlier transaction

• An earlier transaction is still in progress on that Station
• Complete or cancel it on the terminal, then try again

Windcave has no record of this transaction

• Windcave still has no record after the initial 30-second grace period
• Start the payment again

Windcave approved a payment but it could not be applied

• The approved result did not pass the checks needed to complete this order
• Check the Windcave portal and order notes before charging again

This payment was started in a different environment

• Environment was changed while the payment was in progress
• Switch back to the environment where the payment started, or check the Windcave portal

Getting Help

• Send the support bundle from the gateway settings screen with the order number
• Visit the GitHub repository to report issues
• Contact Windcave support for account, credentials, and hardware questions