Skip to main content
Version: 2.x

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.

Pro Feature

Windcave Terminal needs WCPOS Pro 2.0 or later, and version 1.0 or later of the extension.

Not certified by Windcave yet

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.

What hasn't been tested

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.

Take a card payment​

Open the register first

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.

  1. 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.
  2. 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.
  3. To take part of the balance on the card, type the amount. The rest stays due for another payment.
  4. 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.
  5. 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.
Checkout on the Payments tab for a $45.00 sale: the Windcave Terminal tile selected, two Station IDs under Choose a terminal, Full balance under them, and the button Send $45.00 to Windcave Terminal, dimmed until a terminal is chosen
  1. Windcave Terminal — the tile, outlined once tapped.
  2. 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.
  3. To pay — the amount for this payment. Type a smaller one to take part of the balance on the card.
  4. Full balance — puts the whole amount still due back in To pay.
  5. Send … to Windcave Terminal — starts the payment on the terminal. It's dimmed until a terminal is chosen.
  6. 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:

  1. Open the Legacy tab and choose Windcave Terminal. See The Legacy Tab.
  2. Start the payment there. It takes the whole order in one payment.
  3. 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​

Don't take the payment again

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.

  1. In the POS, open the order's refund. See Refunds.
  2. Choose Refund to Windcave Terminal and press Process Refund.
  3. 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.

Windcave Account: HIT credentials, and one Station ID per terminal. UAT credentials until Windcave certifies the integration
Terminal: A Windcave terminal that takes HIT payments
WCPOS: WCPOS Pro 2.0 or later, and version 1.0 or later of the extension
Server: WooCommerce, and PHP 7.4 or newer with the DOM extension (php-xml)

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.

WP Admin, Windcave Terminal settings: Environment UAT (testing), empty HIT username, HIT key, Station IDs and Vendor ID, and POS name WCPOS
  1. Environment — leave it on UAT (testing), the default. Production is for after Windcave certifies the integration, with production credentials.
  2. HIT username — from Windcave, for the environment you chose.
  3. HIT key — from Windcave. Once saved, the field stays blank: leave it blank to keep the saved key.
  4. Station IDs — one per line, one for each terminal. Windcave issues them; they aren't found automatically.
  5. Vendor ID — leave it empty until Windcave issues one.
  6. POS name — what your POS is called at Windcave. WCPOS by 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.

WP Admin, POS Settings, Checkout: two rows of the Gateways table, Vipps MobilePay switched on and Windcave Terminal switched off
  1. Windcave Terminal — the extension's row in the Gateways table.
  2. 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​

  1. 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.
  2. 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.
  3. 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:

SettingWhat it does
Enable/DisableOffers the gateway on your online store's checkout. Leave it off; the POS has its own switch under POS > Settings > Checkout
TitleThe tile's name at the till. Defaults to Windcave Terminal
DescriptionDefaults to Pay in person on the Windcave terminal.
EnvironmentUAT (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 usernameIssued by Windcave, for the environment you chose
HIT keyIssued by Windcave. Never shown once saved; leave it blank to keep it
Station IDsOne per line, one per terminal. Duplicates are dropped
Vendor IDAgreed with Windcave during certification. Leave it empty until then
POS nameThe 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.

WP Admin, foot of the Windcave Terminal settings on a store not set up yet: Support bundle with its Download support bundle button, the line uat: HIT credentials missing, and View logs
  1. Credentials line — HIT credentials missing. on this store, which isn't set up. Yours should read HIT credentials configured (not verified).
  2. View logs — opens WooCommerce > Status > Logs, source windcave-terminal.
  3. 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.