Windcave Terminal Gateway
Windcave Terminal sends a sale from the till to a Windcave terminal. The customer pays on the terminal, and the till records the payment once Windcave confirms it.
This page starts at the till. Store admins: Set up Windcave Terminal covers the credentials, the WP Admin settings and how to check it worked.
Windcave Terminal needs WCPOS Pro 2.0 or later, and version 1.0 or later of the extension.
Test payments only: don't take a real customer's card on Windcave yet. Windcave approves every point-of-sale integration before it takes real payments, and hasn't approved this one yet. The extension hasn't been run on a physical Windcave terminal yet. Its payments and refunds have been tested against a stand-in for Windcave's HIT service, built from Windcave's documentation. Take a small UAT sale and refund it before you rely on it.What hasn't been tested
Take a card payment
With Open and close the register switched on, the till won't record a payment while the register is closed, and a card you've already taken would have to be refunded. See Registers for the setting.
- Press Checkout in the cart and tap the Windcave Terminal tile on the Payments tab. If your terminals ask for a signature, use the Legacy tab instead: see When the terminal asks a question.
- Look above the keypad. If you see Choose a terminal, tap the Station ID of the terminal at your counter: the name Windcave gives each terminal, such as
DOCS-STATION-1. If you see Terminal: and an ID, that's the one this till uses; press Change to pick another. The till remembers your choice. - To take part of the balance on the card, type the amount. The rest stays due for another payment.
- Press Send … to Windcave Terminal. The till shows On the terminal with four steps: Sent, On terminal, Approved and Captured, which means the money is taken.
- The customer taps, inserts or swipes the card on the terminal. When the payment is captured and nothing is left to pay, the receipt opens. If some is left, take it with another tile.

- Windcave Terminal — the tile, outlined once tapped.
- Station IDs under Choose a terminal — tap the one at your counter. Once this till has one, this row shows Terminal: and its ID, with Change.
- To pay — the amount for this payment. Type a smaller one to take part of the balance on the card.
- Full balance — puts the whole amount still due back in To pay.
- Send … to Windcave Terminal — starts the payment on the terminal. It's dimmed until a terminal is chosen.
- Legacy — the other payment tab, for gateways with their own payment page. Use it when your terminal asks for a signature.
Details, under the four steps, opens a log of the payment, with the Station it went to. There's no tip, surcharge or cash-out on the terminal.
When the terminal asks a question
A terminal can stop and ask something, such as whether the customer's signature matches. In this version the Payments tab doesn't show those questions. The Legacy tab does:
- Open the Legacy tab and choose Windcave Terminal. See The Legacy Tab.
- Start the payment there. It takes the whole order in one payment.
- When the terminal asks, the payment page shows the question with the terminal's own buttons, such as YES and NO. Press the answer.
Cancel a payment
Press Cancel on terminal before the customer pays. This works only while the terminal itself is offering CANCEL. If it isn't, the till says The terminal is not offering cancel right now. Cancel on the terminal.
A cancel is a request. If the card was already read, the payment can still go through: the till shows Cancelling — waiting for the terminal to confirm, keeps checking and shows the result. Wait for it before you take payment another way.
If the till can't get an answer, it offers Release this payment. Released doesn't mean cancelled: press it only once a manager has checked the Windcave portal and found no approved payment for the order. The order can then be paid another way, and the store keeps checking the terminal.
If something goes wrong
When the customer may have paid
In these two cases the card may already be charged. A manager checks the Windcave portal first, where the sale is listed under the order number.
Could not confirm the terminal result. Check Windcave before taking payment again. The till asked again for a payment it had already sent, and Windcave's answer was unclear. Take the payment again only once a manager has looked for the sale in the portal and found none.
Payment failed: The terminal confirmed a different amount. The terminal approved an amount other than the one the till sent, so the till didn't record it, but the card may be charged. Don't take another payment: ask a manager to find the sale in the portal under the order number and compare the amount the terminal took with the order.
Other messages
Payment failed: Card declined
Press Try again to send it to the terminal again, or Choose another way to pay with another tile.
The terminal is still finishing an earlier transaction
The Station is busy with another payment. Complete or cancel it on the terminal, then press Try again.
The payment fails straight after it was sent
The extension waits 30 seconds for Windcave to register a new payment. If Windcave still has no record of it by then, the extension counts it as not sent and the payment fails. Check the terminal is switched on and online, and that its Station ID is in the settings, then press Try again.
The terminal asks a question and the till keeps waiting
The Payments tab doesn't show the terminal's questions, so it waits until the payment ends. Press Cancel on terminal, or cancel on the terminal, then take the payment on the Legacy tab. See When the terminal asks a question.
Timed out — payment cancelled
No one paid within 5 minutes. Check the terminal, then press Try again.
The Windcave Terminal tile is greyed out or missing
Under the tiles, the till says why. See When a tile can't be used for every reason.
- In use by order #… — the Station is busy with another order's payment. Finish or cancel that one, or press Change and pick another Station.
- Needs a connection — the till is offline. A terminal payment goes through your store, so take another kind of payment or wait for the connection.
- No tile at all — the gateway is missing its HIT username, HIT key or Station IDs, or isn't switched on in WCPOS. A manager checks the setup.
Refund a Windcave payment
A refund goes back through Windcave to the Station that took the sale, for the full amount or part of it.
- In the POS, open the order's refund. See Refunds.
- Choose Refund to Windcave Terminal and press Process Refund.
- Your store waits up to 20 seconds for Windcave's answer, then adds the result to the order notes.
A refund in WP Admin, with WooCommerce's Refund … via Windcave Terminal button, works the same way.
If a refund stays pending, check it in the Windcave portal before you refund again.
A refund stays pending
Windcave didn't answer within 20 seconds, or approved a different amount from the one asked for. Your store doesn't retry it. Find the refund in the Windcave portal: if it went through, the customer has their money; if it didn't, refund again.
A sale taken with version 0.1 won't refund
The refund stops with Configure a default Station in POS settings before refunding this sale. Version 0.1 of the extension didn't record which Station took the sale, so version 1.0 refunds it on a store-wide default Station. Tills now pick their own Station under Settings > Card readers, and WCPOS 2.0 has no store-wide default yet. Refund the sale in the Windcave portal or on the terminal, then record it in WooCommerce with Refund … manually.
Set up Windcave Terminal
An administrator does this once per store in WP Admin, then picks a Station on each till. Your store reaches each terminal through Windcave over the internet, so there's nothing to pair, and any till can use any of your terminals.
Requirements
You need HIT credentials, a HIT username and a HIT key, and the Station ID of each terminal. Windcave issues all of them; WP Admin can't look them up or create them. Contact Windcave and ask for UAT HIT credentials and the Station ID of each terminal, or use Windcave's Integration Requirements form for a development account. UAT and production each get their own username and key, and Windcave issues a Vendor ID once they certify the integration.
Install the extension
Open WP Admin > POS > Settings > Extensions, find Windcave Terminal for WooCommerce, install it and activate it. You need version 1.0 or later; version 0.1 is for WCPOS before 2.0. See Extensions.
You can also upload the plugin zip (not the source-code zip) from the GitHub releases page under Plugins > Add Plugin > Upload Plugin.
Without WCPOS Pro 2.0, WP Admin shows Windcave Terminal requires WooCommerce POS Pro 2.0 or newer. and the gateway isn't added. Activation is refused on PHP older than 7.4, or without the DOM extension: ask your host to enable php-xml.
Enter your HIT credentials
Go to WP Admin > WooCommerce > Settings > Payments and open Windcave Terminal.

- Environment — leave it on UAT (testing), the default. Production is for after Windcave certifies the integration, with production credentials.
- HIT username — from Windcave, for the environment you chose.
- HIT key — from Windcave. Once saved, the field stays blank: leave it blank to keep the saved key.
- Station IDs — one per line, one for each terminal. Windcave issues them; they aren't found automatically.
- Vendor ID — leave it empty until Windcave issues one.
- POS name — what your POS is called at Windcave.
WCPOSby default.
Below them, Result notifications (FPRN) is optional. With it ticked, Windcave also tells your store when a result is ready, as a backup to the till's own checks. Your site must be reachable from the internet for it to work.
Click Save changes.
Switch it on in WCPOS
Go to WP Admin > POS > Settings > Checkout, find Windcave Terminal in the Gateways table and switch Enabled on. That screen saves as you go; there's no Save button.
Leave Enable/Disable on the WooCommerce settings page off. The POS uses the gateway once Enabled is on here, whether that box is ticked or not. See Checkout Settings.

- Windcave Terminal — the extension's row in the Gateways table.
- Enabled — the switch beside the gateway ID; switch it on. The till shows the Windcave Terminal tile once it reloads.
Choose each till's Station
On each till, open Settings > Card readers. Every Station ID you entered is listed as a reader under Smart readers, all marked Online: the extension doesn't ask Windcave whether a terminal is switched on. Press Use this reader on the Station at that counter; its row shows Selected. The cashier can still press Change at checkout.
With only one Station there's nothing to choose: it's already Selected on every till. See Choose a smart reader.
Check it worked
- Back on the Windcave Terminal settings page, the line under the settings reads
uat: HIT credentials configured (not verified).It means the username and key are saved, not that Windcave accepted them.HIT credentials missing.means one is empty. - On a till, reload the POS and press Checkout. The Windcave Terminal tile is among the ways to pay. Tap it: your Station IDs appear above the keypad, under Choose a terminal or as Terminal: and the one this till uses.
- Take a small sale on a UAT terminal, then refund it. There's no test-connection button: this first sale is what checks the credentials and the Station ID.
Upgrading from version 0.1
- Update WCPOS, WCPOS Pro and the app to 2.0 first, then the extension.
- A payment in progress during the upgrade carries over. Nothing is charged twice.
- A payment that 0.1 set aside carries over if its order is still unpaid. Otherwise the order gets a note: Windcave TxnRef … was set aside before the 1.0.0 upgrade and is no longer followed automatically. Check that payment in the Windcave portal: if it was approved, refund it there or record it on the order by hand.
- These 0.1 settings are gone: Default Station ID, Lock terminal selection, Checkout logs and Log level. Tills now choose their Station under Settings > Card readers.
- Set aside is gone too, and terminal receipt text is no longer added to the order as a private note.
- Refunding a sale taken by 0.1: see Refund a Windcave payment.
Settings reference
On WP Admin > WooCommerce > Settings > Payments > Windcave Terminal:
| Setting | What it does |
|---|---|
| Enable/Disable | Offers the gateway on your online store's checkout. Leave it off; the POS has its own switch under POS > Settings > Checkout |
| Title | The tile's name at the till. Defaults to Windcave Terminal |
| Description | Defaults to Pay in person on the Windcave terminal. |
| Environment | UAT (testing) (default) or Production. Each has its own HIT credentials; production needs Windcave certification. A payment started in one environment is always checked in that one |
| HIT username | Issued by Windcave, for the environment you chose |
| HIT key | Issued by Windcave. Never shown once saved; leave it blank to keep it |
| Station IDs | One per line, one per terminal. Duplicates are dropped |
| Vendor ID | Agreed with Windcave during certification. Leave it empty until then |
| POS name | The name your POS goes by at Windcave. Defaults to WCPOS |
| Result notifications (FPRN) | Windcave also tells your store when a result is ready, as a backup to the till's checks. Off by default |
Logs and support bundle
At the foot of the settings page are the support bundle, the credentials line and a link to the logs.

- Credentials line —
HIT credentials missing.on this store, which isn't set up. Yours should readHIT credentials configured (not verified). - View logs — opens
WooCommerce > Status > Logs, sourcewindcave-terminal. - Download support bundle — a file for WCPOS support.
The logs record each request to Windcave and its reply, with the HIT key and card numbers masked.
When a payment goes wrong, click Download support bundle and send the file to WCPOS support with the order number. WCPOS Pro adds this button: the bundle covers every POS payment provider on your site, with secrets and card numbers removed.
What it doesn't do
- Real payments, until Windcave certifies the integration.
- Tips, surcharges, cash-out, or authorising now and capturing later.
- Answering the terminal's questions on the Payments tab. Use the Legacy tab.
- Finding terminals on its own: you type in each Station ID.
- Checking the HIT credentials before the first payment.
How it works, for developers
The gateway uses Windcave HIT (Host Initiated Transaction) over HTTPS: uat.windcave.com for UAT and sec.windcave.com for production. Each terminal is addressed by its Station ID.
A payment sends a Purchase for the amount on the till, with Order # and the order number as the merchant reference, then WCPOS Pro checks its status until it completes. If the till asks again, the extension first queries the same transaction reference rather than starting another Purchase. A Purchase that Windcave hasn't registered within 30 seconds counts as not sent.
With Result notifications (FPRN) on, each Purchase asks Windcave to call your store's WCPOS payments webhook, wp-json/wcpos/v2/payments/webhook with provider=windcave and the transaction reference. The call is only a hint: the store then asks Windcave for the result itself.
A refund is a HIT matched Refund against the original Windcave transaction, for the amount you enter. The store checks its status every 2 seconds for up to 20 seconds.
Related Documentation
- Card readers
- The Legacy Tab
- Refunds
- Checkout Settings
- Report an issue on GitHub. For your account, credentials and terminals, contact Windcave.