# 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](#setup) covers the credentials, the WP Admin settings and how to check it worked.

Pro Feature

Windcave Terminal needs [WCPOS Pro](/getting-started/pro-license.md) 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[​](#take-payment "Direct link to 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](/manage-store/stores/register-settings.md#one-register) 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](#terminal-questions).
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](/img/2.x/payment/gateways/windcave-terminal/en/tablet-light-regular--wc-4-till-tile.png)123456

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[​](#terminal-questions "Direct link to 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](/sell/take-payment/legacy-tab.md).
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[​](#cancel "Direct link to 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[​](#goes-wrong "Direct link to If something goes wrong")

### When the customer may have paid[​](#may-have-paid "Direct link to 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[​](#other-messages "Direct link to 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](#terminal-questions).

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](/settings/checkout/payment-methods.md#unavailable-tiles) 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](#setup).

## Refund a Windcave payment[​](#refunds "Direct link to 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](/sell/refunds.md).
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[​](#setup "Direct link to 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[​](#requirements "Direct link to 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](https://www.windcave.com/merchant-attended-developer-hit) 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[​](#install "Direct link to 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](/manage-store/add-ons.md#installing-an-extension).

You can also upload the **plugin zip** (not the source-code zip) from the [GitHub releases page](https://github.com/wcpos/windcave-terminal-for-woocommerce/releases) 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[​](#credentials "Direct link to 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](/img/2.x/payment/gateways/windcave-terminal/en/desktop-light-regular--wc-1-hit-settings.png)123456

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[​](#enable "Direct link to 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](/settings/checkout.md#enabling-a-gateway).

![WP Admin, POS Settings, Checkout: two rows of the Gateways table, Vipps MobilePay switched on and Windcave Terminal switched off](/img/2.x/payment/gateways/windcave-terminal/en/desktop-light-regular--wc-2-pos-checkout-gateways.png)12

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[​](#till-terminal "Direct link to 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](/hardware/card-readers.md#smart-readers).

### Check it worked[​](#check "Direct link to 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[​](#upgrade "Direct link to 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](#refunds).

## Settings reference[​](#settings "Direct link to 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[​](#logs-and-support-bundle "Direct link to 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](/img/2.x/payment/gateways/windcave-terminal/en/desktop-light-regular--wc-3-status-support-bundle.png)123

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[​](#scope-and-limitations "Direct link to 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[​](#related-documentation "Direct link to Related Documentation")

* [Card readers](/hardware/card-readers.md)
* [The Legacy Tab](/sell/take-payment/legacy-tab.md)
* [Refunds](/sell/refunds.md)
* [Checkout Settings](/settings/checkout.md)
* [Report an issue on GitHub](https://github.com/wcpos/windcave-terminal-for-woocommerce/issues). For your account, credentials and terminals, contact Windcave.

[Card readersPick the Station each till pays with](/hardware/card-readers.md)

[Checkout SettingsTurn gateways on for the POS](/settings/checkout.md)

[All GatewaysThe other card terminals WCPOS works with](/settings/checkout/payment-gateways.md)
