EFTPOS Host Initiated Transactions

Introduction

The Windcave Host Initiated Transaction (HIT) solution is a web facing HTTPS service that permits control of a payment transaction on a Windcave terminal.

There is no requirement of a direct physical connection between the Point of Sale (POS) application and the Windcave terminal. All required software is on the Windcave Terminal and Host. All messages are sent online via the internet to create an end-to-end cloud-based payment solution.

The terminal can be connected online to a modem or router directly. However if required the HIT enabled terminal can be connected to a POS’s PC as well to share the internet connection from the PC, in that case the POS’s PC needs to have the Windcave SCR Controller software installed. For further details please refer to Configurations.

The Windcave HIT sandbox is accessible online https://demo.windcave.com/SandboxPxHIT.aspx

Operation

The POS initiates a transaction request to Windcave by sending an HTTPS POST request as an XML message to the appropriate URL. See Endpoints & Firewall Considerations for a list of URLs.

Windcave responds to the request, either immediately or after a configurable timeout period of a few seconds; after receiving a response, the POS will continue to make Status requests until the Status response indicates that the transaction is Complete (Complete value is returned as “1”) in Result.

Status responses from Windcave may contain instructions for the POS to permit information to be displayed for the merchant (DL1, DL2) and enablement of buttons that may be used by the POS to interrupt the transaction or provide feedback for example signature capture.

Note: For any new integrations, the POS must handle the entry of new users. POS applications are typically used by many different customers.

As each customer has one or more HIT API users, a key part of POS development is ensuring that new user HIT API credentials can be easily added into the POS and that the development credentials are not hard coded in any way. Please ensure the API credentials configuration within the POS are also password protected or has some level of authorised access challenge.

Endpoints & Firewall Considerations

The POS can communicate with the Windcave Host using HTTPS on the addresses below. Please ensure that your network can accommodate this access.

Production: https://sec.windcave.com/hit/pos.aspx

Test: https://uat.windcave.com/hit/pos.aspx

The Windcave HIT terminal communicates with the Windcave Host using TCP on the addresses below. Please ensure that your network can accommodate this access.

Production: scr.windcave.com, port 65

Test: uatscr.windcave.com, port 65

Configurations

Outlined below are some of the configuration options available for HIT integrations:

Note: not all configurations are available for all payment terminal models, please contact the Sales team for options based on your configuration requirements.


Configuration	Description
Ethernet	The payment terminal connects directly to your network switch/router using Ethernet.
Wi-Fi	The payment terminal connects directly to your network via Wi-Fi.
Cellular	The payment terminal connects directly to the cellular network.
SCR Controller	The payment terminal connects to the POS PC via USB or DB9 serial communications, the Windcave SCR Controller software installed on the PC then uses the PC internet connection to communicate between the Windcave Host and payment terminal.

Paymark key set up (NZ Only)

Terminals using the Paymark key scheme must have their keys remotely injected before transacting. Please contact our support team for assistance.

Terminal configuration

The Windcave terminal should come with preconfigured network settings. If there are any connectivity issues that cannot be resolved, please contact Windcave Support staff

Initialisation

Once powered up, the device will go through an automatic boot-up and online logon process. Once completed & ready, PINpad will idle and display “EFTPOS” on the screen.

Logon

In order to prepare the terminal for processing transactions, the Logon message is used. A Logon uses the assigned merchant number and terminal ID to login to the banking switch. This is recommended but optional as the terminal will automatically log itself with the Windcave Host 10 seconds after connecting to the network. However if logon is required please do the following manual logon process. Press the “Menu” button on the PINpad, and select “LOGON”.

Transaction Flow

Message Specification

This section describes communication aspects of the HIT XML messages specification.

Transaction

To initiate a transaction the following SCR XML message specified needs to be posted to the HIT POS endpoint.

Transaction Request – Input Parameters

Property\[Attribute]	Required	Description
[user]	Yes	HIT Username provided by Windcave. Alphanumeric, from 1 to 32 characters in length. Please ensure this is securely configurable via the POS config.
[key]	Yes	HIT Key provided by Windcave. Alphanumeric, from 1 to 64 characters in length. Please ensure this is securely configurable via the POS config.
Station	Yes	Station Id unique to the terminal. Alphanumeric, from 1 to 32 characters. Please ensure this is securely configurable via the POS config.
Amount	Yes	Amount of transaction in D.CC format. Where D is dollar and C is cent value. Numeric and decimal point, from 1 to 13 digits.
AmountCash	No	Amount for cash out. Numeric and decimal point, from 1 to 13 digits.
Cur	Yes	Currency of the transaction. Alphanumeric, 3 characters only allowed.
TxnType	Yes	Transaction Type. Valid values: Purchase, Validate, Auth, Refund or Status. Please note for requesting the Complete transaction after an Auth transaction from the terminal please use our eCommerce API.
TxnRef	Yes	Set by POS to uniquely identify transactions. Alphanumeric, from 1 to 40 characters.
DeviceId	Yes	HIT POS identifier provided by POS. For example, a POS Lane Identifier etc. Alphanumeric, from 1 to 32 characters.
PosName	Yes	PosName – agreed between POS Vendor and Windcave. Alphanumeric, from 1 to 32 characters.
PosVersion	No	Version of POS. Supplied by POS to assist transaction recording and diagnosis. Alphanumeric, from 1 to 32 characters.
VendorId	Yes	The developer of the POS Application. This is agreed between Windcave and vendor. Alphanumeric from 1 to 32 characters in length.
MRef	No	Merchant text field. Alphanumeric, max 64 characters. Recommend to use, useful for reporting purposes.
UrlSuccess	No	Set the URL to receive a HTTP GET notification on approved card present payment
UrlFail	No	Set the URL to receive a HTTP GET notification on declined card present payment

<Scr action="doScrHIT" user="xxx" key="yyy">
    <Amount>1.05</Amount>
    <Cur>NZD</Cur>
    <TxnType>Purchase</TxnType>  
    <Station>1234567890</Station>  
    <TxnRef>123</TxnRef>  
    <DeviceId>Device 1</DeviceId>  
    <PosName>POS 1</PosName>  
    <PosVersion>Pos V1</PosVersion>
    <VendorId>PXVendor</VendorId>
    <MRef>My Reference</MRef>
</Scr>

Initial Transaction Status Response – Output Parameters

Property\[Attribute]	Description
TxnType	Transaction Type. Normally the HIT transaction response's TxnType value is as Status.
StatusId	Status of the current request.
TxnStatusId	Status ID related to current transaction.
Complete	If transaction is completed this field will be set to 1.
ReCo	Response Code indicating outcome. See below section Response codes for a detailed description of ReCo values
Tmo	Http Timeout in operation for the request.
TxnRef	TxnRef value for the original request and transaction.
DL1	Display Line 1. If not empty, the merchant display should display this on the uppermost lines.
DL2	Display Line 2. If not empty, the merchant display should display this on the lowermost line.
B1	Button1. If not blank, contains label for a button that permits the POS to interact with the transaction. The "en" attribute will be "1" if the button should be active and displayed.
B2	Button2. If not blank, contains label for a button that permits the POS to interact with the transaction. The "en" attribute will be "1" if the button should be active and displayed.

<Scr>
    <TxnType>Status</TxnType>
    <StatusId>3</StatusId>
    <TxnStatusId>2</TxnStatusId>
    <Complete>0</Complete>
    <ReCo/>
    <Tmo>20</Tmo>
    <TxnRef>123</TxnRef>
    <DL1>PRESENT/INSERT</DL1>
    <DL2> SWIPE CARD</DL2>
    <B1 en="0"/>
    <B2 en="1">CANCEL</B2>
</Scr>

Surcharge

A surcharge is a fee applied to recover the cost of accepting payment correlating to the cost of processing that payment. When payment is made using some scheme methods, merchants typically incur a fee per payment and this fee is typically a proportion of the total sale value.

Terminals can be configured with a surcharge functionality that allows merchants to add the surcharge amount on top of the original transaction amount based on the card processed.

If a surcharge is added to the transaction it will be included in the final transaction response, for HIT this is returned in the AmtS field.

The surcharge amount is configured on the Windcave host per card type (Visa, Mastercard, Amex etc) and account selected (CHQ,SAV,CRD) and can be set as a fixed amount or a percentage of the original transaction amount.

To enable surcharging on your terminals, please contact [email protected] and provide the serial number of the terminal(s), the card name and surcharge fee you would like applied for each card type you would like to apply a surcharge.

Tipping

Tipping allows merchants to offer their customers the ability to add a tip or gratuity amount on top of the original transaction amount.

If enabled on the terminal the customer will be prompted if they would like to add a tip to the transaction, if yes they will then be prompted to enter the amount they would like to tip. This amount is automatically added on top of the final transaction amount.

When a tip is added to a transaction, the AmtT field will be included in the final transaction response containing the tip amount.

To enable tipping on your terminals, please contact [email protected] and provide the serial number of the terminal(s) you would like this feature enabled on.

Status

Status Request

Request a Status for an active or historical transaction. Merchant POS should request this message shortly after the transaction is initiated as per transaction. The TxnRef must match the transaction the POS wants to do status check on.

Example Status:

<Scr action="doScrHIT" user="xxx" key="yyy">
    <Station>1234567890</Station>
    <TxnType>Status</TxnType>
    <TxnRef>123</TxnRef>
</Scr>

Status Response

During Processing

The POS interface should always show any DL1 and/or DL2 text from the Status response to match the terminal screen prompt text. Note in below example the DL1 display message is set to Processing.

Example Status Response:

<Scr>
    <TxnType>Status</TxnType>
    <StatusId>4</StatusId>
    <TxnStatusId>5</TxnStatusId>
    <Complete>0</Complete>
    <ReCo/>
    <Tmo>20</Tmo>
    <TxnRef>123</TxnRef>
    <DL1>PROCESSING</DL1>
    <DL2/>
    <B1 en="0"/>
    <B2 en="0"/>
</Scr>

Signature Stage

A receipt message will be available to print as well as prompts and mandatory button options ‘YES’ and ‘NO’.

The POS should display the button options to the POS operator and a print button to print the physical merchant copy of the receipt for the customer to sign on. The POS system is required to accept or decline a signature transactions with the Yes or No button—please follow the messages for button request in Buttons.

Example Status Response (Signature prompted):

<Scr>
    <TxnType>Status</TxnType>
    <TxnRef>123</TxnRef>
    <StatusId>4</StatusId>
    <TxnStatusId>7</TxnStatusId>
    <Complete>0</Complete>
    <RcptW>30</RcptW>
    <Rcpt>                              *-----------EFTPOS-----------*27 Mar 18 13:35         CREDITSWIPE VISA       CARD    476173******0010AUTHORISATION           025211REFERENCE               029017PURCHASE       NZD1.08TOTAL                  NZD1.08       APPROVED    PLEASE SIGN BELOW       *----------------------------*    MERCHANT COPY   PLEASE RETAIN  FOR YOUR RECORDS</Rcpt>
    <ReCo></ReCo>
    <Tmo>20</Tmo>
    <TxnRef>123</TxnRef>
    <DL1>SIGNATURE OK?</DL1>
    <DL2>YES/NO</DL2>
    <B1 en="1">YES</B1>
    <B2 en="1">NO</B2>
</Scr>

Please Note: It is important that the POS integration continues to request a status check until after the POS user appropriately handles the prompt on the POS and/or terminal and the final response contains the Complete tag value as 1. The HIT interface allows only one transaction to be fully completed at a time. A pending transaction completion will result in an “Existing Txn In Progress” error. This should be handled by sending the Status request for the TxnRef of the transaction until it reaches the Complete stage.

Final Status Response on completion of Transaction

On completion of a transaction the Complete XML element will be set to 1. The result of the transaction will be populated inside the Result XML element. Below property elements are contained in the transaction response and Result XML element.

Property	Description
TxnType	Transaction Type. Normally the HIT transaction response's TxnType value is as Status.
TxnRef	TxnRef value for the original request and transaction.
StatusId	Status of the current request Refer to the TxnStatusId and StatusId below for more information.
TxnStatusId	Status ID related to current transaction.
Complete	If transaction is completed this field will be set to 1.
RcptW	Receipt Width specifies the maximum character limit per receipt content's line. A terminal's account is setup with a default receipt width character length. The fixed character limit can be used to center justify the receipt content per line to get the standard receipt format.
Rcpt	Actual EFTPOS receipt content that should be physically printed in case the POS handles the EFTPOS receipt printing. All receipt content should be printed to ensure financial data integrity.
Result	Encloses the final transaction results with specific transaction data fields.
AC	AuthCode. Up to 6 character authorisation code.
AP	Approved flag. "1" indicated approved (funds transfer or reserve); "0" indicated declined or not approved.
CN	Masked Card Number.
Complete	1 indicates transaction session is completed. The POS should stop sending status requests
CT	Card Name e.g. Visa.
DS	Expected Settlement Date of Transaction. Format is yyyymmddhhmmss.
DS_TZ	TimeZone applied to the DS value.
DT	Date of Transaction. Returned in Timezone Format is yyyymmddhhmmss.
DT_TZ	TimeZone applied to DT value.
PIX	EMV specific data.
RID	EMV specific data .
RRN	Retrieval reference Number
ST	STAN. The System Trace Audit Number which identifies the transaction number processed through the merchant account.
TR	DpsTxnRef. Unique global transaction identifier generated by Windcave and returned for every transaction. This value can be provided to support teams to identify transactions.
DBID	DpsBillingId is a card token generated by Windcave. Token used to rebill the card for subscription or recurring based payments. Rebilling requests are sent via the eCommerce API.
RC	Response Code. See Response codes below.
RT	Response Text. See Response codes below.
RTT	Round Trip Time in Milliseconds – provides an indication of network health (between the Windcave cloud and Windcave Terminal).
AmtA	Amount value of the transaction in cents.
AmtS	Amount value of the surcharge in cents, if Surcharge is configured on the terminal account and applied.
AmtT	Amount value of the Tip or Gratuity in cents, if Tipping is enabled on the terminal account and set via the terminal when initiating the transaction.
AmtC	Amount value of the cash out in cents, if cashout is enabled on the terminal account and set via the terminal when initiating the transaction.
MID	Merchant ID for the terminal account, only parsed and recorded if required.
TID	Terminal account ID for the terminal account, only parsed and recorded if required.
AutoSig
CaStan

Example Final Status Response (Completed):

<Scr>
    <TxnType>Status</TxnType>
    <TxnRef>123</TxnRef>
    <StatusId>6</StatusId>
    <TxnStatusId>8</TxnStatusId>
    <Complete>1</Complete>
    <RcptW>30</RcptW>
    <Rcpt>                              *-----------EFTPOS-----------*27 Mar 18 13:13         CHEQUESWIPE VISA                    CARD          411111******1111AUTHORISATION           000289REFERENCE               029013PURCHASE               NZD1.00TOTAL                  NZD1.00                                         APPROVED                                                  PIN VERIFIED                                       *---------------------------*        CUSTOMER COPY                                               PLEASE RETAIN                FOR YOUR RECORDS</Rcpt>
    <Result>
        <AC>000289</AC>
        <AP>1</AP>
        <CN>411111******1111</CN>
        <CT>Visa</CT>
        <CH>VISA TEST CARD/</CH>
        <DT>20180327131306</DT>
        <DT_TZ>NZT</DT_TZ>
        <DS>20180327180000</DS>
        <DS_TZ>NZT</DS_TZ>
        <PIX></PIX>
        <RID></RID>
        <RRN></RRN>
        <ST>788359</ST>
        <TR>0000000100e1a6f9</TR>
        <DBID>0000010001128730</DBID>
        <RC>00</RC>
        <RT></RT>
        <RTT>4050</RTT>
        <AmtA>100</AmtA>
        <AmtS>0</AmtS>
        <AmtT>0</AmtT>
        <AmtC>0</AmtC>
        <MID>10000000</MID>
        <TID>10000648</TID>
        <AutoSig>0</AutoSig>
        <CaStan>47228</CaStan>
    </Result>
    <ReCo></ReCo>
    <Tmo>20</Tmo>
    <TxnRef></TxnRef>
    <DL1>APPROVED</DL1>
    <DL2></DL2>
    <B1 en="0"></B1>
    <B2 en="0"></B2>
</Scr>

Buttons

POS is required to display appropriate buttons if B1 or B2 field in the XML response(s) is not blank. Once any button is clicked, the POS should then post appropriate button request to SCR endpoint.

Property	Description
Station	Station Name of the Windcave terminal being selected by the POS.
TxnType	For Button Request, the value should be UI for User Interface.
UiType	Bn
Name	B1 or B2. Depending on the button pressed.
Val	Value to be sent with the request for button press - CANCEL, YES, NO.
TxnRef	Transaction reference assigned by POS. This should be different for each transaction.

Button Request XML

Example Button Request

<Scr action="doScrHIT" user="xxx" key="yyy">
    <Station>1234567890</Station>
    <TxnType>UI</TxnType>
    <UiType>Bn</UiType>
    <Name>B1</Name>
    <Val>YES</Val>
    <TxnRef>12345678</TxnRef>
</Scr>

Button Response XML

Example Button Response

<Scr>
    <TxnType>UI</TxnType>
    <TxnRef>12345678</TxnRef>
    <Success>1</Success>
    <RC></RC>
</Scr>

Refunds

Matched refunds initiated via HIT request

To initiate a refund directly from the POS, the DpsTxnRef of the initial transaction must be included. The unique TxnRef is used separately as a reference to the refund and must be unique.

Button Response XML

Example Matched Refund:

<Scr action="doScrHIT" user="xxx" key="yyy">
    <Amount>76.00</Amount>
    <Cur>NZD</Cur>
    <TxnType>Refund</TxnType>
    <Station>1234567890</Station>
    <TxnRef>987</TxnRef>
    <DpsTxnRef>0000005400911209</DpsTxnRef>
    <DeviceId>1234567890</DeviceId>
    <PosName>POS 1</PosName>
    <PosVersion>Pos V1</PosVersion>
    <VendorId>DPSVendor</VendorId>
    <MRef>My Reference</MRef>
</Scr>

Unmatched refunds with refund card

To initiate a refund directly from the POS and authorise with a merchant refund card, the following example XML should be modified and sent. The DpsTxnRef tag does not need to be included, instead for authorization the terminal will prompt for the merchant’s refund card to be swiped and PIN entered before the customer presents their card for the refund. The merchant refund card is setup by Windcave. For extra security, it is expected the POS requires own authorization before requesting unmatched refund via the POS

Button Response XML

Example Unmatched Refund:

<Scr action="doScrHIT" user="xxx" key="yyy">
    <Amount>76.00</Amount>
    <Cur>NZD</Cur>
    <TxnType>Refund</TxnType>
    <Station>1234567890</Station>
    <TxnRef>987</TxnRef>
    <DeviceId>1234567890</DeviceId>
    <PosName>POS 1</PosName>
    <PosVersion>Pos V1</PosVersion>
    <VendorId>DPSVendor</VendorId>
    <MRef>My Reference</MRef>
</Scr>

Matched Refunds via Ecommerce solution

The PxPost or Web Service eCommerce API can be used to process refunds with the matched DpsTxnRef of the given HIT transaction. For more information on PxPost and Web Service, please visit our website

https://www.windcave.com/merchant-ecommerce-merchant-hosted.html

When using PxPost or Web Service to handle refunds, the HIT user and the eCommerce API user must be associated with the same Windcave Group; for additional information please contact our Support team.

Receipt

In case the POS requires to request the last EFTPOS receipt content to print, the POS can send a request to receive the last transaction’s receipt content with the most recent or last transaction’s TxnRef. This can be requested to reprint the receipt when a printer and its paper roll is available. Following are the request and response details specific to get the last receipt.

Receipt Request XML

Example Receipt Request

Receipt Request XML Fields

Property	Required	Description
Station	Yes	Station Name of the Windcave terminal being selected by the POS.
TxnType	Yes	For Receipt Request, the value should be Receipt.
TxnRef	Yes	The most recently processed transaction's transaction reference.
DuplicateFlag	No	An optional tag. If value 1: Includes a DUPLICATE RECEIPT text string on the receipt content. Otherwise 0 will not include the duplicate text string.
ReceiptType	Yes	A flag indicating the receipt content type to receive. Valid Values: 1 = Merchant Copy of receipt with a signature placeholder (only for signature transaction) 2 = Customer Copy of receipt 3 = Merchant Copy of receipt

<Scr action="doScrHIT" user="xxx" key="yyy">
    <Station>4012345678</Station>
    <TxnType>Receipt</TxnType>
    <TxnRef>12345</TxnRef>
    <DuplicateFlag>0</DuplicateFlag>
    <ReceiptType>2</ReceiptType>
</Scr>

Receipt Response XML

Example Receipt Response

Receipt Response XML Fields

Property	Description
RcptW	Receipt Width specifies the maximum character limit per receipt content's line. A terminal's account is setup with a default receipt width character length. The fixed character limit can be used to center justify the receipt content per line to get the standard receipt format.
Rcpt	Actual EFTPOS receipt content that should be physically printed in case the POS handles the EFTPOS receipt printing. All receipt content should be printed to ensure financial data integrity.

<Scr>
    <TxnRef>12345</TxnRef>
    <TxnType>Receipt</TxnType>
    <RcptW>30</RcptW>
    <Rcpt>                              *-----------EFTPOS-----------*18 Apr 18 11:06         CHEQUESWIPE VISA                    CARD          499999******9103AUTHORISATION           011498REFERENCE               009451PURCHASE               AUD1.00TOTAL                  AUD1.00                                         APPROVED                                                  PIN VERIFIED                                       *----------------------------*        CUSTOMER COPY                                               PLEASE RETAIN                FOR YOUR RECORDS</Rcpt>
</Scr>

EnterData

Notifies the terminal that the POS system wants to collect data entered using the terminal keypad.

This function is useful for capturing data using the terminal when the POS application cannot, for example the EnterData command could be used if cash-out amount needs to be entered on terminal.

All display prompts are configured by Windcave. Please contact [email protected] and provide the serial number of the terminal(s) you would like this feature enabled on.

EnterData Request XML

Example EnterData Request

EnterData Request XML Fields

Property	Description
Station	Station Name of the Windcave terminal being selected by the POS.
TxnType	For EnterData Request, the value should be EnterData.
CmdSeq	Command sequence number for pairing requests and responses. Can be set to any numerical value.
PromptId	Prompt Id number e.g. 411 "Enter Cash-out Amount". Configured by Windcave.
Timeout	Optional timeout value in seconds.

<Scr action="doScrHIT" user="xxx" key="yyy">
	<Station>4012345678</Station>
	<TxnType>EnterData</TxnType>
	<CmdSeq>100</CmdSeq>
	<PromptId>901</PromptId>
	<Timeout>20</Timeout>
</Scr>

EnterData Response XML

Example EnterData Response

EnterData Response XML Fields

Property	Description
TxnType	For EnterData Request, the value should be EnterData.
CmdSeq	Command sequence number for pairing requests and responses. Can be set to any numerical value.
RC	Two-character response code that indicates the outcome of the request.
Result	The data string or button code entered by the customer.

<Scr>
	<TxnType>EnterData</TxnType>
	<CmdSeq>100</CmdSeq>
	<RC>00</RC>
	<Result>1234</Result>
</Scr>

PinpadDisplay

Notifies the terminal that the POS system wants to display a prompt on the terminal screen.

This function is useful for displaying prompts for customers/staff when the POS application cannot, for example the PinpadDisplay XML command could be used to prompt that the table selected is currently in use.

All display prompts are configured by Windcave. Please contact [email protected] and provide the serial number of the terminal(s) you would like this feature enabled on.

PinpadDisplay Request XML

Example PinpadDisplay Request

PinpadDisplay Request XML Fields

Property	Description
Station	Station Name of the Windcave terminal being selected by the POS.
TxnType	For PinpadDisplay Request, the value should be PinpadDisplay.
CmdSeq	Command sequence number for pairing requests and responses. Can be set to any numerical value.
PromptId	Prompt Id number e.g. 409 “Table %s In Use”. Configured by Windcave.
Param1	Optional Parameter 1 (e.g. If PromptId = 409 describes a prompt “Table %s In Use”. The optional parameter replaces %s with the number “12”)
Param2	Optional Parameter 2. As for optional parameter 1
Timeout	Optional timeout value in seconds.

<Scr action="doScrHIT" user="xxx" key="yyy">
	<Station>4012345678</Station>
	<TxnType>PinpadDisplay</TxnType>
	<CmdSeq>100</CmdSeq>
	<PromptId>409</PromptId>
	<Param1>12</Param1>
	<Param2>$10</Param2>
	<Timeout>20</Timeout>
</Scr>

PinpadDisplay Response XML

Example PinpadDisplay Response

PinpadDisplay Response XML Fields

Property	Description
TxnType	For PinpadDisplay Request, the value should be PinpadDisplay.
CmdSeq	Command sequence number for pairing requests and responses. Can be set to any numerical value.
RC	Two-character response code that indicates the outcome of the request.

<Scr>
	<TxnType>PinpadDisplay</TxnType>
	<CmdSeq>100</CmdSeq>
	<RC>00</RC>
</Scr>

ReadCard

Notifies the terminal that the POS system wishes to read the track data from a card.

This call should only be made to retrieve the track data from loyalty cards and other non-payment cards.

The data returned from attempting to read a payment card will be masked for security reasons.

If you require the full track data from a particular non-payment card or cards, please contact [email protected] to enable on your profile (see appendix for contact details).

You will need to provide the BIN range (first 6 digits) of the card for identification.

ReadCard Request XML

Example ReadCard Request

ReadCard Request XML Fields

Property	Description
Station	Station Name of the Windcave terminal being selected by the POS.
TxnType	For ReadCard Request, the value should be ReadCard.
TxnRef	Set by POS to uniquely identify transactions. Alphanumeric from 1 to 40 characters.

<Scr action="doScrHIT" user="xxx" key="yyy">
	<Station>4012345678</Station>
	<TxnType>ReadCard</TxnType>
	<TxnRef>123</TxnRef>
</Scr>

ReadCard Response XML

Example ReadCard Response

ReadCard Response XML Fields

Property	Description
TxnType	Transaction Type. Normally the HIT transaction response's TxnType value is as Status.
TxnRef	TxnRef value for the original request and transaction.
StatusId	Status of the current request.
TxnStatusId	Status ID related to current transaction.
Complete	If transaction is completed this field will be set to 1.
ReCo	Response Code indicating outcome. See below section Response codes for a detailed description of ReCo values
Tmo	Http Timeout in operation for the request.
CardType	Card ID stored in Windcave database
CardBin	The first six digits of the card number
CardHolderName	Name on the card
CardData	Track2 Data or Track2 equivalent read from the card. This data will be masked with * characters if the card is a PCI card
ClessCardUID	Unique card identifier for the type of card presented. Returned in hex format. If the card is not contactless then this field will be blank
CardIssuerName	Name of the card Issuer
PrivateCardData	Returns special tags specific to the card type. Please contact Windcave to set up configuration to retrieve this data which must not be PCI data. Eg. Can contain loyalty card data.
Track1Data	Data from Track1 of the card.

<Scr>
    <TxnType>Status</TxnType>
    <TxnRef>123</TxnRef>
    <StatusId>6</StatusId>
    <TxnStatusId>2</TxnStatusId>
    <Complete>1</Complete>
    <ReCo>00</ReCo>
    <Tmo>20</Tmo>
    <Result>
        <CardType>3</CardType>
        <CardBin>541333</CardBin>
        <CardHolderName>John Doe</CardHolderName>
        <CardData>541333******0028=*51*201**********</CardData>
        <ClessCardUID></ClessCardUID>
        <CardIssuerName>MasterCard</CardIssuerName>
        <PrivateCardData></PrivateCardData>
        <Track1Data></Track1Data>
    </Result>
</Scr>

Fail-Proof Result Notification (FPRN)

Fail-proof result notification (FPRN) is a service that provides additional assurance that the merchant website will receive notification regarding the outcome of transactions completed via the Windcave host. This service allows merchant POS to stop checking for the status stage after the transaction is initiated and simply indicate finalization of the transaction.

FPRN can be enabled by adding <UrlSuccess> and <UrlFail> parameters in the request. Notification will be sent by Windcave host once the transaction is finalised. Windcave host will only send FPRN notification when the response result of TxnStatusId is 7 – Verifying Signature and 8 – Display Result. However, it is recommended to display a user-friendly prompt such as “Transaction in progress— Please refer to terminal" on the screen of POS. The only case that the POS would still have to display prompts/buttons is when the terminal must require user selection (TxnStatusId = 7) for approving signature with mandatory button options ‘YES’ and ‘NO’.

As soon as the response result of TxnStatusId is 7 or 8, a background process at Windcave makes an HTTP GET request to the merchant-nominated success or failure URL. If the merchant web site is unreachable or returns any HTTP status code other than 200, 201, 302, 303, 404 or 502 the HTTP GET is retried up to a maximum of six times. It will give up immediately on receiving a 404 (page not found) HTTP status code or 502 (Bad Gateway) HTTP status code. A 500 HTTP status code, indicating a temporary problem at the client site, will cause a retry.

Please note that merchant POS would still have to perform the status request after the transaction is initiated if they want to update prompts for every stage on the screen of POS.

To ensure that the web application is in the best position to acknowledge the outcome of every transaction, certain guidelines should be followed.

The merchant web application should not:
- Filter or base any conditional logic upon the originating IP address (this can vary)
- Depend upon receiving one and only one request for the success/fail URL from the Windcave FPRN system (multiple requests may be sent). Note: The URL at which the merchant website will process FPRN requests must be exposed via standard Internet ports i.e. port 80 or port 443 for SSL/TLS traffic. When specifying UrlSuccess and UrlFail values do not specify a non-standard port number within the URL.

N.B. The URL at which the merchant website will process FPRN requests must be exposed via standard internet ports i.e. port 80 or port 443 for SSL/TLS traffic. When specifying UrlSuccess and UrlFail values do not specify a non-standard port number within the URL.

Example Transaction Request with FPRN:

<Scr action="doScrHIT" user="xxx" key="yyy">
    <Amount>1.05</Amount>
    <Cur>NZD</Cur>
    <TxnType>Purchase</TxnType>
    <Station>1234567890</Station>
    <TxnRef>123</TxnRef>
    <DeviceId>Device 1</DeviceId>
    <PosName>POS 1</PosName>
    <PosVersion>Pos V1</PosVersion>
    <VendorId>PXVendor</VendorId>
    <MRef>My Reference</MRef>
    <UrlSuccess>https://InsertHostedWebHookURL?txnRef=12345&amp;station=1234567890</UrlSuccess>
    <UrlFail>https://InsertHostedWebHookURL?txnRef=12345&amp;station=1234567890</UrlFail>
</Scr>

Fail-Proof Result Notification Transaction Flow

Response Codes

The Response Code value is a two character response used to indicate the transaction outcome.

ReCo	Description
P4	PosDeviceId is greater than 32 characters
P5	PosDeviceId not matched
P7	Invalid transaction type
P8	Authentication error
P9	Authentication error—Station Id mismatch
PA	Status request error
PB/PC	SCRHIT Init Session Error
PC	Existing Txn In progress — previous transaction was left in an incomplete state, ensure sending status request of the previous transaction and it's reference and status response is handled accordingly.
PD/PE/PF	SCRHIT Transmit Error — network connection issue, ensure the terminal has performed a Logon to the Windcave HOST.
PG	Init Wait Timeout
PJ	TxnRef not matched
PK	SCRHIT not enabled
PL	Invalid input parameter
PM	Txn type not allowed
PO	Invalid Station Id
TQ	HIT Start Failed— connection lost, ensure the terminal has performed a Logon to the Windcave HOST.

TxnStatusId and StatusId

The TxnStatusId is the Status ID related to the current transaction and terminal prompt. StatusId is the status of the current request.

TxnStatusId

Id	Description
1	Idle
2	Present Or Insert Card
3	Select Account
4	Select App
5	Enter Pin
6	Processing
7	Verifying Signature
8	Display Result

StatusId

Id	Description
1	Initiating
2	Transaction Started
3	Transaction Started
4	Processing
5	Authenticating
6	Transaction Completed

Parameters

The HIT request parameters are supplied as either XML elements or attributes. Some parameters are mandatory (must be included and non-blank), while others are optional.

Name	Description
Amount	Amount of the transaction type. Decimal point is mandatory.
AmountCash	Amount of cash out required. Decimal point is mandatory.
EnableAddBillCard flag (optional) and BillingId (optional)	Set the EnableAddBillCard flag to 1 and POS supplies a unique BillingId that can be associated with card data for tokenizing a card and use for future automated rebilling or recurring payment via an eCommerce API (PxPost or WebService). BillingId has to be 1-32 characters in length. Otherwise the DpsBillingId (DBID) in the final transaction response can be used as a card token that is automatically generated by Windcave.
Cur	Specifies the standard three letter Currency Code for the transaction. The standard currencies supported depends on the merchant's account configuration in the Windcave system.
DeviceId	POS identifier provided by POS. For example, a POS Lane Identifier etc. Alphanumeric, from 1 to 32 characters.
EnableTip (optional)	If set to 1, enables prompting for a Tip (gratuity) in hospitality situations. Valid for Auth or Purchase transactions.
HttpTimeout (optional)	Timeout in seconds to be applied by Windcave to HIT Client HTTP POST requests. If supplied, value must be between 10 and 60.
MRef (optional)	Merchant reference applied to the transaction. Mostly used for transaction reporting purposes. Up to 64 characters alphanumeric.
PosName	PosName – agreed between POS Vendor and Windcave.
PosVersion	Version of POS. Supplied by POS to assist transaction recording and diagnosis. Alphanumeric characters between 1-32 characters.
Station	Station is the serial number value as a Station Name of the Windcave terminal being selected by the POS.
TxnRef	Transaction reference assigned by POS. This should be unique for each Purchase, Auth or Refund transaction.
TxnType	The transaction type to be performed Purchase - Purchase Transaction Validate - Validate to simply validate card is valid with the acquirer or bank Auth - Auth a card for certain amount to hold funds Status - To receive the current status of the HIT terminal and HOST process Refund - To Refund a Purchase or Complete Transaction For more information please refer to Transaction Type Information.
TZ (optional)	Time zone to be applied to returned time values including times printed on receipt. If not supplied, the time zone configured by Windcave for the terminal is applied. AEST - Australia Eastern Time (Sydney) AESTQL - Australia Eastern Time (Queensland) NZT - New Zealand Time UK GMT - UK Time US CST - United States Central Time US EST - United States Eastern Time US MST - United States Mountain time US PST - United States Pacific Time
Val	Value to be sent with the request for the button press - CANCEL, YES or NO.
VendorId	The developer of the POS Application. This is agreed between Windcave and vendor. Alphanumeric from 1 to 32 characters in length.

Payline

Any transactions processed via the Windcave® HIT terminal can be monitored in real-time from any device with access to internet and a web browser.

You can logon to the Payline® web portal at the address below using the username and password provided with your account.

Live transactions portal: https://sec.windcave.com/pxmi3/logon

Test transactions portal: https://uat.windcave.com/pxmi3/logon

In addition to monitoring transactions in real-time, the Payline® web portal can configured to download transaction reports, view invoices, view payments and also process manual transactions online.

For more information on Payline®, phone Windcave® Sales on 0800 PAYMENT (729 6368) or email [email protected]

Pay at Table

Pay at Counter vs Pay at Table

Pay at Counter is your traditional integration method where by customers will approach the counter where a POS machine is located and the merchant will initiate payment from the POS machine directly.

Pay at Table functionality allows merchants to initiate the payment process at the customers table by entering a unique staff code into the Windcave HIT terminal directly.

Pay at Counter vs Pay at Table

For further information on how to integrate HIT Pay at Table functionality into your POS system please contact one of the Windcave Sales team at [email protected] or call using one of the region specific phone numbers located on our contact page: https://www.windcave.com/contact

POS Certification

All POS integrations must be officially certified by Windcave QA before the solution can be used in production.

Below is the overview of the stages involved in the POS Certification.

Pre-POS Certification Check

Before submitting your POS for certification, you will need to complete the standard test scripts included with the Windcave Certification Request document.

Please contact the Sales and Implementation team.

Book Certification

Once your POS has passed the test scripts and you believe your POS is ready for certification please complete the first section of the above document and then contact QA or your Windcave project manager directly.

It is very important that you book your POS in for certification. Please note that we strongly recommend booking this well in advance to avoid disappointment.

Certification

Windcave QA will commence POS Certification on the scheduled date.

POS application and any supporting software or hardware must be provided by the scheduled date.

Please note that during this time our analysts may have questions and may need to contact POS technical/developer contact.

POS Bug Fixes

Any bugs found during Certification will be escalated back to POS developer to provide fix.

If time required to provide fix elapses Certification window then a new Certification (Round #2) window may need to be booked.

Certification Results

A Certification Report will be provided upon completion of the Certification process. This is proof that your POS has been officially certified by Windcave and is ready for production use.