# 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[​](#features "Direkter Link zu 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[​](#how-it-works "Direkter Link zu 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[​](#setup "Direkter Link zu Setup") 1 ### Install Windcave Terminal for WooCommerce Download the **plugin zip asset** (not the GitHub source-code zip) from the [GitHub releases page](https://github.com/wcpos/windcave-terminal-for-woocommerce/releases). 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](https://www.windcave.com/merchant-attended-developer-hit). 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 Hinweis 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[​](#settings "Direkter Link zu 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[​](#usage "Direkter Link zu Usage") ### Processing Payments[​](#processing-payments "Direkter Link zu 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[​](#payment-controls "Direkter Link zu 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[​](#receipts "Direkter Link zu Receipts") Terminal receipt text, when Windcave returns it, is saved as a **private order note** in WooCommerce. ## Refunds[​](#refunds "Direkter Link zu 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[​](#logs-and-support-bundle "Direkter Link zu 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[​](#requirements "Direkter Link zu 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[​](#scope-and-limitations "Direkter Link zu 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[​](#troubleshooting "Direkter Link zu Troubleshooting") ### Common Issues[​](#common-issues "Direkter Link zu 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[​](#getting-help "Direkter Link zu Getting Help") * Send the **support bundle** from the gateway settings screen with the **order number** * Visit the [GitHub repository](https://github.com/wcpos/windcave-terminal-for-woocommerce) to report issues * Contact Windcave support for account, credentials, and hardware questions