API XML Socket Interface

These messages are usually request/response pairs. The request message is usually initiated by POS system to make a request to EFTPOS terminal, and then being replied by the EFTPOS terminal in the format of response message. The response message uses the same format as the request message and includes a common field "Success" to indicate whether the request is successfully being processed by the EFTPOS terminal.

The acknowledge message will include the "success" field set to "1" and other message specific fields. It will look like the following:

<Message type="command type" id="application-specified ID" >
     <Success>1< /Success>
     ... message-specific fields ...
</Message>

<Message type="command type" id="application-specified ID">
     < Success>0</Success>
     <Reco>I2</Reco>
     <ResponseText>Unknown message type</ResponseText>
     ... other message-specific fields ...
</Message>

The EFTPOS terminal can only perform one operation at a time. Consequent request messages will be rejected if the previous request is still pending processing. An ACK or NACK response message indicates that the pending request has been processed completely.

Transaction (Request)

Notifies the EFTPOS terminal that the POS system wishes to initiate an EFTPOS transaction. The message data specifies the type of transaction and the amount to be processed.

Element Name	Description
type [Attribute]	Transaction
id [Attribute]	Id of the message. Will correspond to the Id of the message request.
Account	The merchant account which this transaction is to be process under. This parameter is only valid if multi-merchant capability is enabled. If this parameter is not present the default merchant account will be used.
AmountPurchase	Amount of Purchase. This parameter is only valid for purchase transactions.
AmountCashOut	The amount in dollars and cents of cash that the customer wishes to withdraw as part of this transaction. This parameter is only valid for purchase transactions. If this parameter is not present it will be assumed that no cash is to be withdrawn.
AmountRefund	The amount in dollars and cents to be refunded. This parameter is only valid for refund transactions.
CardNumber	The card number to use for a manual transaction
CardHolderName	The card holder name. Mandatory field for card not present entry (manual pan). If you do not wish to supply the name you can insert blank/empty data but the xml tags must be present.
CurrencyId	The identifier of the currency.
CurrencyRate	The currency rate.
EnableCurrencyConversion	If this value is 1. The currency conversion function is enabled for the transaction.
EnableCurrencyConversionPrompt	If this value is 1. The currency is prompted on the Pinpad screen for the customer to choose what currency they would like to pay in.
EnableTrainingMode	Enable to put EFTPOS in "Training Mode" which allows Payment Express Training Cards to be used in production environments. Values are 1 (Enabled) and 0 (Disabled).
ExpiryDate	The card expiry date in the YYMM format when doing a manual transaction.
MerchantReference	A free text field describing the transaction (order number etc). This is used inside the web reporting suite for tracking transactions.
ReceiptAutoPrint	If this value is 1 the receipt will be printed by the EFTPOS terminal. If this value is absent or any value other than 1 the POS system will be responsible for printing the receipt.
Track1	The manual entered track 1 data.
Track2	The manual entered track 2 data.
Track3	The manual entered track 3 data.
TxnType	The type of transaction to be processed. Allowed values are: Purchase Refund Balance MicrAuth Auth AuthTip AuthHospitality AuthTopup XtraCharge FlyBuy AuthFuel GCTop GCRefund Cash Deposit
TxnRef	Unique reference for the transaction. Used to match transaction requests with responses.

Example Data:


<Message type="Transaction" id="1234">
     <Account>1</Account> 
     <TxnType>Purchase</TxnType> 
     <TxnRef>TXN12345</TxnRef> 
     <AmountPurchase>19.95</AmountPurchase>
</Message>

Transaction (Response)

Once the transaction has been processed (or cancelled) a Transaction message will be sent back to the POS system, indicating the outcome of the transaction.

Element Name	Description
type [Attribute]	Transaction
id [Attribute]	Id of the message. Will correspond to the Id of the message request.
Account	The merchant account which this transaction is to be process under. This value will only be present if multi-merchant capability is enabled.
AccountType	The type of account selected by the customer. Possible values include: Cheque Saving Credit
AmountPurchase	The amount in dollars and cents of the purchase. This value will only be present if the transaction was a purchase transaction.
AmountCashOut	The amount in dollars and cents of cash that the customer wishes to withdraw as part of this transaction. This value will only be present if the transaction was a purchase transaction.
AmountRefund	The amount in dollars and cents to be refunded. This value will only be present if the transaction was a refund transaction.
AuthCode	Authorisation code from the bank
Authorized	If this value is 1 the transaction has processed successfully. If this value is 0 the transaction was declined or cancelled.
CardHolderName	The card holder name.
CardNumber	The card number
CardType	Type of card used to perform the transaction. Possible values include: EFTPOS Visa Mastercard
ExpiryDate	The card expiry date in the YYMM format.
MerchantId	The identifier of the merchant.
Reference	Reference code supplied by the acquirer and used to retrieve the original transaction data such as EOV transaction & tipping transactions.
Rid	The RID of the EMV transaction.
Pix	The PIX of the EMV transaction.
ReCo	Two-character response code that indicates the outcome of the transaction.
ResponseText	Text that indicates the outcome of the transaction.
Success	Indicates the success of a method call
SettleDate	Estimated date on which the funds will be cleared.
Stan	The System Trace Audit Number which identifies the transaction number processed through the merchant account.
TerminalId	The identifier of PINpad terminal.
TxnRef	Unique reference for this transaction. This is used inside the web reporting suite for tracking transactions.
TxnType	The type of transaction performed. This is the same as the TxnType passed in the transaction request.
TxnDateTime	Date of the transaction as reported by the EFTPOS network. The format is "YYYYMMDDhhmmss"

Example Data:

<Message type="Transaction" id="1234">
     <ReCo>00</ReCo>
     <ResponseText>ACCEPTED</ResponseText>
     <Success>1</Success> 
     <Account>1</Account>
     <TxnRef>TXN12345</TxnRef>
     <TxnType>Purchase</TxnType>
     <TxnDate>20060101</TxnDate>
     <TxnTime>120000</TxnTime>
     <SettleDate>20060102</SettleDate>
     <CardType>Visa</CardType> 
     <AmountPurchase>19.95</AmountPurchase>
     <AmountCashOut>0.00</AmountCashOut> 
</Message>

When this message has been received, the transaction operation is complete and the POS system may continue with other operations. To recover a transaction after a power failure or POS crash, simply open a socket connection. The relevant Receipt and Transaction messages will be supplied automatically.

LastTransaction (Request)

Notifies the EFTPOS terminal that the POS system wishes to retrieve the last transaction.

Element Name	Description
type [Attribute]	LastTransaction
id [Attribute]	Id of the message. Will correspond to the Id of the message request.

Example Data:

Notifies the EFTPOS terminal that the POS system wishes to retrieve the last transaction.

When the last transaction retrieve has completed, the POS system will receive a LastTransaction message from the EFTPOS terminal.

LastTransaction (Response)

Received in response to a "get last transaction" request.

When this message has been received, the last transaction retrieve operation is complete and the POS system may continue with other operations.

Element Name	Description
type [Attribute]	LastTransaction
id [Attribute]	Id of the message. Will correspond to the Id of the message request.
Account	The merchant account which this transaction is to be process under. This value will only be present if multi-merchant capability is enabled.
AccountType	The type of account selected by the customer. Possible values include: Cheque Saving Credit
AmountPurchase	The amount in dollars and cents of the purchase. This value will only be present if the transaction was a purchase transaction.
AmountCashOut	The amount in dollars and cents of cash that the customer wishes to withdraw as part of this transaction. This value will only be present if the transaction was a purchase transaction.
AmountRefund	The amount in dollars and cents to be refunded. This value will only be present if the transaction was a refund transaction.
Authorized	If this value is 1 the transaction has processed successfully. If this value is 0 the transaction was declined or cancelled.
CardHolderName	The card holder name.
ExpiryDate	The card expiry date in the YYMM format when doing a manual transaction.
CardNumber	The card number to use for a manual transaction
CardType	Type of card used to perform the transaction. Possible values include: EFTPOS Visa Mastercard
MerchantId	The identifier of the merchant.
ReCo	Two-character response code that indicates the outcome of the transaction.
ResponseText	Text that indicates the outcome of the transaction.
Success	Indicates the success of a method call.
TxnRef	Unique reference for this transaction. This is used inside the web reporting suite for tracking transactions.
TxnType	The type of transaction performed. This is the same as the TxnType passed in the transaction request.
TxnDateTime	Date of the transaction as reported by the EFTPOS network. The format is "YYYYMMDDhhmmss"
SettleDate	Estimated date on which the funds will be cleared.
Stan	The System Trace Audit Number which identifies the transaction number processed through the merchant account.
TerminalId	The identifier of PINpad terminal.
Reference	Reference code supplied by the acquirer and used to retrieve the original transaction data such as EOV transaction & tipping transactions.
Rid	The RID of the EMV transaction.
Pix	The PIX of the EMV transaction.

Button (Request)

Notifies the EFTPOS terminal that the POS user has hit a button in response to a Display message.

This message takes only a single parameter, which specifies which button was pressed.

Element Name	Description
type [Attribute]	Button
id [Attribute]	Id of the message. Will correspond to the Id of the message request.
Button	Valid parameters: Yes: if "Yes" button is pressed. No: if "No" button is pressed. OK: if "OK" button is pressed. Cancel: if "Cancel" button is pressed. This parameter is case-insensitive.

Element Name	Description
type [Attribute]	Receipt
id [Attribute]	Id of the message. Will correspond to the Id of the message request.
Receipt	Receipt data. You will need to format so that each line only has 30 characters.

Example Data:

<Message type="Receipt" id="1234">
     <Receipt>
THE VENDOR 
1 MERCHANT LANE 
THE CITY 

*-----------EFTPOS-----------* 
TERMINAL 00000001    TRAN 000001 
TIME 01JAN 12:00      ACCT CREDIT 
VISA                       411111....1111 
AUTHORISATION 000001 EXP 12/10 
PURCHASE                      NZ$19.95 
TOTAL                            NZ$19.95 
           ACCEPTED 

*----------------------------*
</Receipt> 
</Message>

LastReceipt (Request)

Notifies the EFTPOS terminal that the POS system wishes to retrieve the last receipt.

When the last receipt retrieve has completed, the POS system will receive a LastReceipt message from the EFTPOS terminal.

Element Name	Description
type [Attribute]	LastReceipt
id [Attribute]	Id of the message. Will correspond to the Id of the message request.

Example Data:

When the last receipt retrieve has completed, the POS system will receive a LastReceipt message from the EFTPOS terminal.

LastReceipt (Response)

Received in response to a LastReceipt message request.

The EFTPOS terminal will send this message every time a receipt is to be printed, even if the terminal is responsible for printing the receipts.

Element Name	Description
type [Attribute]	LastReceipt
id [Attribute] Id of the message.	Will correspond to the Id of the message request.
Receipt	Receipt data. You will need to format so that each line only has 30 characters.
Success	Indicates the success of a method call.
ReCo	Two-character code indicating the outcome of the request.
ResponseText	A textual description of the outcome of the request.

Example Data:

<Message type="LastReceipt" id="1234">
     <Success>1</Success>
     <ReCo>97</ReCo>
     <ResponseText>Transaction Completed</ResponseText>
     <Receipt>
        THE VENDOR 
        1 MERCHANT LANE
        THE CITY 

        *-----------EFTPOS-----------* 
        TERMINAL 00000001    TRAN 000001 
        TIME 01JAN 12:00      ACCT CREDIT 
        VISA                       411111....1111 
        AUTHORISATION 000001 EXP 12/10 
        PURCHASE                      NZ$19.95 
        TOTAL                            NZ$19.95 
                     ACCEPTED 
        *----------------------------*
    </Receipt> 
</Message>

Cutover (Request)

Notifies the EFTPOS terminal that an end-of-day settlement should be performed. In multi-merchant setups, the merchant number must be supplied.

When the settlement cutover has completed, the POS system will receive a Settle message from the EFTPOS terminal.

Element Name	Description
type [Attribute]	Cutover
id [Attribute]	Id of the message. Will correspond to the Id of the message response.
Account	The merchant account on which to perform the settlement cutover. This parameter is only valid if multi-merchant capability is enabled. If this parameter is not present the default merchant account will be used.

Example Data:


<Message type="Cutover" id="1234">
     <Account>1</Account>
</Message>

Notifies the POS system that a settlement operation has completed. The message data specifies whether the cutover was successful or not.

When this message has been received, the settlement operation is complete and the POS system may continue with other operations.

Element Name	Description
type	Settle
id [Attribute]	Id of the message. Will correspond to the Id of the message request.
ReCo	Two-character code indicating the outcome of the settlement.
Success	If this value is 1 the settlement request has processed successfully. If this value is 0 the settlement request was declined.
ResponseText	A textual description of the outcome of the settlement.
Account	The merchant account which this transaction is to be process under. This value will only be present if multi-merchant capability is enabled.

Example Data:

<Message type="Cutover" id="1234">
     <Success>1</Success>
     <ReCo>97</ReCo>
     <ResponseText>Transaction Completed</ResponseText>
     <Account>1</Account>
</Message>

Settlement Enquiry (Request)

Notifies the EFTPOS terminal that a settlement enquiry operation should be performed. A receipt will be printed containing a breakdown of transactions that have been or can be settled for the given date. In multi-merchant setups the merchant number must be supplied.

When the settlement enquiry has completed the POS system will receive an Enquiry message from the EFTPOS terminal.

Element Name	Description
type	Enquiry
id [Attribute]	Id of the message. Will correspond to the Id of the message response.
Account	The merchant account on which to perform the settlement cutover. This parameter is only valid if multi-merchant capability is enabled. If this parameter is not present the default merchant account will be used.
SettleDate	The date upon which the enquiry operation should be run in yyyymmdd format.

Example Data:

<Message type="Enquiry" id="1234">
     <Account>1</Account>
     <SettleDate>20090315</SettleDate>
</Message>

Settlement Enquiry (Response)

Notifies the POS system that a enquiry operation has completed. The message data specifies whether the enquiry was successful or not.

When this message has been received, the enquiry operation is complete and the POS system may continue with other operations. test

Element Name	Description
type	Settle id [Attribute] Id of the message. Will correspond to the Id of the message request.
ReCo	Two-character code indicating the outcome of the settlement enquiry.
Success	If this value is 1 the settlement enquiry request has processed successfully. If this value is the settlement enquiry request was declined.
ResponseText	A textual description of the outcome of the settlement enquiry.
Account	The merchant account which this operation was processed under. This value will only be present if multi-merchant capability is enabled

Example Data:

<Message type="Enquiry" id="1234">
     <Success>1</Success>
     <ReCo>97</ReCo>
     <ResponseText>Transaction Completed</ResponseText>
     <Account>1</Account>
</Message>

SubTotal (Request)

This feature can be used to keep track of shift totals without effecting the financial settlement. A running total of purchase and refund transactions is kept by the Eftpos client. This running total can be accessed by setting the message type 'SubTotal'. This will cause a Reciept event where the purchase and refund totals since the last 'SubTotal' or 'Cutover' was performed will be printed. The shift totals will be cleared.

When the SubTotal enquiry has completed the POS system will receive an SubTotal message from the EFTPOS terminal.

Element Name	Description
type	SubTotal
id [Attribute]	Id of the message. Will correspond to the Id of the message response.
Account	The merchant account on which to perform the SubTotal Enquiry. This parameter is only valid if multi-merchant capability is enabled. If this parameter is not present the default merchant account will be used.

Example Data:

<Message type="SubTotal" id="1234">
     <Account>1</Account>
</Message>

SubTotal (Response)

Notifies the POS system that a SubTotal operation has completed. The message data specifies whether the enquiry was successful or not.

When this message has been received, the enquiry operation is complete and the POS system may continue with other operations.

Element Name	Description
type	SubTotal
id [Attribute]	Id of the message. Will correspond to the Id of the message request.
ReCo	Two-character code indicating the outcome of the settlement enquiry.
Success	If this value is 1 the SubTotal request has processed successfully. If this value is 0 the SubTotal request was declined.
ResponseText	A textual description of the outcome of the settlement enquiry.
Account	The merchant account which this operation was processed under. This value will only be present if multi-merchant capability is enabled.

Example Data:

<Message type="SubTotal" id="1234">
     <Success>1</Success>
     <ReCo>90</ReCo>
     <ResponseText>READY TO SETTLE</ResponseText>
     <Account>1</Account>
</Message>

Logon (Request)

Notifies the EFTPOS terminal that the system wished to perform a manual logon to the EFTPOS network

Example Data:

<Message type="Logon" id="1234">
     <Account>1</Account>
</Message>

When the manual logon has completed, the POS system will receive a Logon message. The message data specifies whether the cutover was successful or not.

Logon (Response)

Notifies the POS system that the EFTPOS terminal has completed its logon.

Element Name	Description
type [Attribute]	Logon
id [Attribute]	Id of the message. Will correspond to the Id of the message request.
ReCo	Two-character code indicating the outcome of the settlement.
ResponseText	A textual description of the outcome of the settlement.
Account	The merchant account which this transaction is to be process under. This value will only be present if multi-merchant capability is enabled.

Example Data:

<Message type="Logon" id="1234">
     <ReCo>00</ReCo>
     <ResponseText>ACCEPTED</ResponseText>
     <Account>1</Account>
</Message>

When this message has been received, the logon operation is complete and the POS system may continue with other operations.

ReadCard (Request)

Notifies the EFTPOS 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 may be partially obscured. Please see the section below for more information.

Element Name	Description
type [Attribute]	ReadCard
id [Attribute]	Id of the message. Will correspond to the Id of the message request.
Text1	The first line of text to be displayed on the EFTPOS terminal.
Text2	The second line of text to be displayed on the EFTPOS terminal.
EnableBackLight	If present and set to 1 the EFTPOS terminal should turn back light on.

Example Data:

<Message type="ReadCard" id="1234">
     <Text1>Swipe Customer Card</Text1>
     <Text2></Text2>
     <EnableBackLight>1</EnableBackLight>
</Message>

ReadCard (Response)

Notifies the EFTPOS 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 may be partially obscured. Please see the section below for more information.

Element Name	Description
type [Attribute]	ReadCard
id [Attribute]	Id of the message. Will correspond to the Id of the message request.
Track1	Data from ISO 7813 Track 1 on the card.
Track2	Data from ISO 7813 Track 2 on the card
Track3	Data from ISO 7813 Track 3 on the card
Success	If this value is 1 the read card request has processed successfully. If this value is 0 the read card request was declined.
ReCo	Two-character code indicating the outcome of the request.
ResponseText	A textual description of the outcome of the request.

Example Data:

<Message type="ReadCard" id="1234">
     <Success>1</Success>
     <ReCo>97</ReCo>
     <ResponseText>Transaction Completed</ResponseText>
     <Track1>%B4111111111111111^PUBLIC/JOHN Q./MR^1012201?</Track1>
     <Track2>;4111111111111111=1012201?</Track2>
     <Track3></Track3>
</Message>

Input Properties

Parameter	Required	Description
EnableBackLight	No	Enhances the backlight brightness of the Pinpad display.
InputMask	No	Character to mask plain text input data such as a password. Length is 1 character such as "*".
KeyMask	No	Key Map Enabled Keys. Used when entering data from Pinpad keypad. Length can include up to 4 Hex numbers and can include values such as "1FF8" for all numbers key on the pinpad "6006" means only F1 F2 F3 Cancel Clear and Enter key are allowed and "FFF8" means 0-9 Cancel Clear and Enter key are allowed. Keymaps available are - F1 Bit 0 F2 Bit 1 F3 Bit 2 0 Bit 3 1 Bit 4 2 Bit 5 3 Bit 6 4 Bit 7 5 Bit 8 6 Bit 9 7 Bit 10 8 Bit 11 9 Bit 12 Cancel Bit13 Clear Bit 14 Enter Bit 15
EnterMode	No	Set the pinpad input mode it can be single Pinpad key input or multiple key combination string key input The maximum string length is 9. Values are - 1 - single Key input mode 2 - String keys input mode
MaxLength	No	Set the maximum data length of the EnterMode mode. Values are 0 - 9
DisplayLine1	No	Line 1 of the display on the Pinpad screen
DisplayLine2	No	Line 2 of the display on the Pinpad screen

Example Data:

<Message type="EnterDataEvent" id="1234">
     <EnableBackLight >1</EnableBackLight>
     <InputMask>*</InputMask >
     <KeyMask>FFF819</KeyMask >
     <EnterMode></EnterMode>
     <MaxLength></MaxLength>
     <DisplayLine1>87</DisplayLine1>
     <DisplayLine1></DisplayLine1>
</Message>

EnterData (Response)

Fires when the call to DoEnterData is completed.

Parameter	Description
Success	Indicates the success of a method call.
Result	Informs what keys were pressed during the EnterData method call. Will include character or string of characters if multiple buttons were pushed. A = Cancel key B = Clear key C = Enter key D = F1 key E = F2 key F = F3 key

Example Data:

<Message type="EnterData" id="1234">
     <Account>1</Account>
     <Success>1</Success>
     <ReCo>00</ReCo>
     <ResponseText>1</ResponseText>
     <Result>1000</Result>
</Message>

PinpadDisplay (Request)

This call is used to display temporary messages on the Pinpad for a certain amount of time.

Input Properties

Parameter	Required	Description
DisplayLine1	Optional	Line 1 of the display on the Pinpad screen
DisplayLine2	Optional	Line 2 of the display on the Pinpad screen
EnableBackLight	Optional	Enhances the backlight brightness of the Pinpad display.
DisplayTimeout	Optional	Sets display timeout length. The default timeout is 3 seconds

Example Data:

<Message type="PinpadDisplay" id="1234">
     <DisplayLine1>52</DisplayLine1>
     <DisplayLine2></DisplayLine2>
     <EnableBackLight>1</EnableBackLight>
     <DisplayTimeout>5</DisplayTimeout>
</Message>

SetIdlePrompt (Request)

This call is used to display the Idle message of the Pinpad. The default is "EFTPOS", which can be changed by using theDisplayLine1 & DisplayLine2 input properties.

Input Properties

Parameter	Required	Description
DisplayLine1	Optional	Line 1 of the display on the Pinpad screen
DisplayLine2	Optional	Line 2 of the display on the Pinpad screen

Example Data:

<Message type="IdlePrompt" id="1234">
     <DisplayLine1>Swipe Staff</DisplayLine1>
     <DisplayLine2>Card</DisplayLine2>
</Message>

EditTender (Request)

EFTPOS Support for Tipping and Hospitality.

The event EditTenderEvent is fired when the command completes.

Input Properties

Parameter	Required	Description
DpsTxnRef	Yes	The DpsTxnRef value returned by a successful DoAuthorize reequest.
TxnType	Yes	Tip:Tipping transaction. Hospitality: Hospitality transaction.
Amount	Yes	The original Amount used for the DoAuthorize request.
Amount2	Yes	The new amount to be charged (Original amount plus the value of the Tip).
MerchantReference	Yes	Optional Details (max 64 character alphanumeric) of operator altering the value of the transaction.

Example Data:

<Message type="EditTender" id="1234">
     <Account>1</Account>
     <DpsTxnRef>0000000001</DpsTxnRef>
     <TxnType>Tip</TxnType>
     <Amount>10.00</Amount>
     <Amount2>12.00</Amount2>
</Message>

EditTender (Response)

Output Properties

Input Properties

Parameter	Description
Success	True (1) - Tender successfully changed
False	(0) - Tender not changed
ReCo	00 - Accepted F4 - Tip limit exceeded E2 - Transaction not found
ResponseText	Response Text associated with the response code of the transaction

Parameter	Required	Description
Account	No	The merchant account which this transaction is to be process under. This value will only be present if multi-merchant capability is enabled.

Example Data:

<Message type="TipSettlement" id="1234">
     <Account>1</Account>
</Message>

TipSettlement (Response)

Notifies the POS system that a tip settlement operation has completed

Output Properties

Parameter	Description
Success	True (1) - Tender successfully changed
False	(0) - Tender not changed
ReCo	00 - Accepted F4 - Tip limit exceeded E2 - Transaction not found
ResponseText	Response Text associated with the response code of the transaction
Account	The merchant account which this transaction is to be process under. This value will only be present if multi-merchant capability is enabled.

Example Data:

<Message type="TipSettlement" id="1234">
     <Success>1</Success>
     <ReCo>00</ReCo>
     <ResponseText>Accepted</ResponseText>
     <Account>1</Account>
</Message>

EovSettlement (Request)

Notifies the EFTPOS terminal to upload and settle any pending EOV transactions.

Input Properties

Parameter	Required	Description
Account	No	The merchant account which this operation is to be process under. This value will only be present if multi-merchant capability is enabled.

Example Data:

<Message type="EovSettlement" id="1234">
     <Account>1</Account>
</Message>

EovSettlement (Response)

Notifies the POS system that an EOV settlement operation has completed

Output Properties

Parameter	Description
Success	If this value is 1 the EOV settlement request has processed successfully. If this value is 0 the EOV settlement request was declined.
ReCo	Two-character code indicating the outcome of the EOV settlement
ResponseText	A textual description of the outcome of the EOV settlement.
Account	The merchant account which this transaction is to be process under. This value will only be present if multi-merchant capability is enabled.

Example Data:

<Message type="EovSettlement" id="1234">
     <Success>1</Success>
     <ReCo>00</ReCo>
     <ResponseText>Accepted</ResponseText>
     <Account>1</Account>
</Message>

GetStatus (Request)

Requests a list of EFTPOS settings. This may be useful for advanced exception handling.

Example Data:

<Message type="GetStatus" id="1234">
</Message>

GetStatus (Response)

Returns current EFTPOS settings to the POS.

Output Properties

Parameter	Description
Ready	The terminal is ready to start online or offline transaction.
Description	Returns a meaningful description of the current eftpos state. eg: 'Ready' 'EFTPOS OFFLINE' 'Link Failure'
ReadyPinPad	Returns the state of the pinpad: 0 - Offline 1 - Ready
ReadyLink	Returns the state of the connection to DPS: 0 - Offline 1 - Connected
EovEnabled	returns a value that indicates if EFTPOS can go into offline mode. 0 - Offline transactions not allowed 1 - Offline transactions allowed
EovOffline	Indicates if EFTPOS is currently operating in offline mode: 0 - Processing online 1 - Processing offline
Interface	Shows the relevant properties of a potential connection to DPS. Address: The address the interface will try to connect to. eg eft6.paymentexpress.com Port: The port to connect to at the address. Enabled: Indicated if the Interface is turned on. 1 - True 0 - False Ready: Indicates if the interface has a successful connection. 1 - True 0 - False Gprs: Indicates if the interface connects using a GPRS modem. 1 - True 0 - False RTTExceeded:Uplink Round trip time exceeded. 1 - True 0 - False
PinPadInfo	Port: The COM Port the pinpad is connected to. SerNum: The pinpads serial number. SwVer: The Software verion of the pinpad.
HostId	The host the EFTPOS will attempt to connect to.
TxnTimeout	The length of time before a transaction will timeout in seconds. Defatult 30 seconds.
SessionKeyIntervalType	Session Key Interval type. Method used for changing Session Keys. 0 - Time Period (minutes) 1 - Transaction Count 2 - Terminal Default (24 Hours) regardless of Transaction Count 3 - Time Period and Transaction Count
Catid	The assigned Terminal Id
Caid	The assigned Merchant Number
Aiic	Acquiring Institution identifier Code
ReversalPresent	There is a pending reversal. If in offline mode this cannont be cleared untill eftpos comes back online.
PrinterName	Currently set printer name. Used by the EFTPOS software to identify the reciept printer.
FirstEovTxnTime	Time the first offline transaction was processed. Field will be empty if no offline transactions present.
TxnRef	Last transaction txnRef from POS client.
IsOffline
LastTxnStan	The stan provided for the last transaction.
LoggedOn	0 - Not logged on. 1 - Logged on
Stan	Current stan
LastReCo	Response code for the last transaction.
LastTxnType	0 - Null 1 - Transaction 2 - Logon 3 - Reversal 4 - SettlementEnquiry5 - SettlementCutover 6 - EMVEFileUpdate 7 - ReadCard 7 - Advice 9 - TcuInit 10 - RKIInit
EMVAppList	Supported EMV application list.
EMVBinRange	Supported EMV card Bin range.
EnableEOV	1 - Offline transactions allowed 0 - Offline transactinos not allowed.
EovMaxTransactions	Maximum allowed offline transactions.
EovMaxDuration	Maximum amount of time the merchant is allowed to process transactions in offline mode.
EovTotalAmount	Total amount allowed to be processed for all transactions while in offline mode.
EovTxnCount	Number of stored offline transactions.
DailyRefundLimit	Maximum allowed value of total refunds per day.
RefundTotal	Daily refund processed total.
EnableCashOnCredit	0 - Cashout not allowed for credit cards. 1 - Cashout allowed for credit cards.
EovForceLoggedOff	Terminal enters a logged off state and invokes EOV processing for the next 30 minutes. The terminal is not to perform its 10 minute auto logons during this period. Normal auto logon processing resumes after 30 minutes.
CurrencySymbol	Text repesentation of default currency eg:NZD
EnableTip	Indicates if TxnType 'Tip' is allowed 0 - Not alloewd 1 - Allowed
HospitalityAllowed	Indicates if TxnType 'Hospitality' is allowed 0 - Not alloewd 1 - Allowed
EnableManualPan	Indicates if manual card number entry is allowed. 1 - Allowed 0 - Not allowed
EnableEMV	Indicates if EMV is enabled. 1 - Allowed 0 - Not allowed Stan2 CscProcessing
Kvc	TSEK KVC code for Terminal storage encrypt key KvcTMK
EnableRefundPreAuth	Check merchant refund card in pre-auth message under Payment Express key scheme.
EnableMultiMerchant	Multiple merchant numbers can be configured to be used on a single pinpad. This feature would only be turned on if it is intended to use. 0 - Feature is turned off (Default). 1 - Feature is turned on.

Example Data:

<Message type="GetStatus" id="1234">
    <Ready>1</Ready>
    <Description>Ready</Description>
    <ReadyPinPad>1</ReadyPinPad>
    <ReadyLink>1</ReadyLink>
    <EovEnabled>1</EovEnabled>
    <EovOffline>0</EovOffline>
    <UplinkDetails>
        <UplinkDetails>
            <Interface>
                <Name>EFT6</Name>
                <Address>eft6.paymentexpress.com</Address>
                <Port>61</Port>
                <Enabled>1</Enabled>
                <Ready>1</Ready>
                <Gprs>0</Gprs>
                <RTTExceeded>0</RTTExceeded>
            </Interface>
            <Interface>
                 <Name>GPRS</Name>
                 <Address>192.168.2.102</Address>
                 <Port>61</Port>
                 <Enabled>1</Enabled>
                 <Ready>1</Ready>
                 <Gprs>1</Gprs>
                 <RTTExceeded>0</RTTExceeded>
            </Interface>
        </UplinkDetails>
        <Terminal>
             <PinPadInfo>
                 <Port>12</Port>
                 <SerNum>211549306</SerNum>
                 <SwVer>SC5xx 2.100 1191</SwVer>
            </PinPadInfo>
            <HostId>997</HostId>
            <TxnTimeout>30</TxnTimeout>
            <SessionKeyIntervalType></SessionKeyIntervalType>
            <Catid>00905339</Catid>
            <Caid>10009053039</Caid>
            <Aiic>00000000000</Aiic>
            <ReversalPresent>0</ReversalPresent>
            <PrinterName>Receipt</PrinterName>
            <FirstEovTxnTime></FirstEovTxnTime>
            <TxnRef>MI202E6B7E2E3236</TxnRef>
            <IsOffline>0</IsOffline>
            <LastTxnStan>14</LastTxnStan>
            <LoggedOn>1</LoggedOn>
            <Stan>15</Stan>
            <LastReCo>08</LastReCo>
            <LastTxnType>1</LastTxnType>
            <EMVAppList></EMVAppList>
            <EMVBinRange></EMVBinRange>
            <EnableEOV>0</EnableEOV>
            <EovMaxTransactions>0</EovMaxTransactions>
            <EovMaxDuration>0</EovMaxDuration>
            <EovTotalAmount>0</EovTotalAmount>
            <EovTxnCount>0</EovTxnCount>
            <DailyRefundLimit>999999</DailyRefundLimit>
            <RefundTotal>0.00</RefundTotal>
            <EnableCashOnCredit>1</EnableCashOnCredit>
            <EovForceLoggedOff>0</EovForceLoggedOff>
            <CurrencySymbol>NZD</CurrencySymbol>
            <EnableTip>0</EnableTip>
            <HospitalityAllowed>0</HospitalityAllowed>
            <EnableManualPan>1</EnableManualPan>
            <EnableEMV>1</EnableEMV>
            <Stan2>1</Stan2>
            <CscProcessing>0</CscProcessing>
            <KvcTSEK></KvcTSEK>
            <KvcTMK>B3D4AF</KvcTMK>
            <EnableRefundPreAuth>0</EnableRefundPreAuth>
            <EnableMultiMerchant>0</EnableMultiMerchant>
        </Terminal>
    </UplinkDetails>
</Message>

PrintPendingReceipt (Request)

Prints the pending Tip or hospitality receipt. PrintPendingReceiptevent will fire when after this call has been completed.OutputReceiptEvent event will fire if there is any receipt available.

Input Properties

Parameter	Required	Description
TxnType	Yes	Values are "Tip" or "Hospitality"
DpsTxnRef	Yes	The unique identifier of the Tipping or Hospitality transaction. For Tipping & Hospitality this is a combination of ther TerminalId & the Stan number.
EnablePrintReceipt	Yes	Set to true (1) to print receipt or false (0) to capture and print via the POS

Example Data:

<Message type="PendingReceipt" id="1234">
     <Account>1</Account>
     <ReceiptAutoPrint>1</ReceiptAutoPrint>
     <DpsTxnRef>0000000001</DpsTxnRef>
     <TxnType>Tip</TxnType>
</Message>

PrintPendingReceipt (Response)

Received in response to a PrintPendingReceipt request.

Output Properties

Parameter	Description
Success	Indicates the success of a method call.
ReCo	2 character response code.
ResponseText	Response Text associated with the response code of the transaction.

Example Data:


<Message type="PendingReceipt" id="1234">
     <Success>1</Success>
     <ReCo>97</ReCo>
     <ResponseText>Transaction Completed</ResponseText>
     <Receipt>
         THE VENDOR
         1 MERCHANT LANE
         THE CITY
         
         *-----------EFTPOS-----------*
         TERMINAL 00000001    TRAN 000001
         TIME 01JAN 12:00      ACCT CREDIT
         VISA                       411111....1111
         AUTHORISATION 000001 EXP 12/10
         PURCHASE                      NZ$19.95
         TOTAL                            NZ$19.95
                     ACCEPTED
         *----------------------------*
     </Receipt>
</Message>

Unsolicited Messages

These messages are usually sent from EFTPOS terminal to POS system. An unsolicited message may be associated to a request message or not. It is usually used by EFTPOS terminal to display information on the POS system's screen or ask user input from POS system. It also will be used for notifying the status changes of EFTPOS terminal. Depending on the type of unsolicited messages, the POS system may need to take actions upon the messages.

Display (Response)

Notifies the POS system that a message needs to be shown to the POS user.

The data inside this message indicates the message to be displayed, and whether there are any buttons that should also be displayed.

Output Properties

Element Name	Description
type [Attribute]	Display
id [Attribute]	Id of the message. Will correspond to the Id of the message request.
Text1	This is the message display line 1 of the EFTPOS dialogs.
Text2	This is the message display line 2 of the EFTPOS dialogs.
Button	Yes No Ok Cancel. Describes which buttons should be available to the POS application.
Button1	The text for first button.
Button2	The text for second button.
Button3	The text for third button.
Beep	If present and set to 1 the POS should beep to indicate that it requires user input. If buttons are to be displayed the POS system must allow for the buttons to be pressed. When any such button is pressed the POS should send a Button message to the EFTPOS terminal. In general these messages are used to convey information that would normally be displayed on the operator's screen on a standalone EFTPOS terminal.

Example Data:

<Message type="Display" id="1234">
    <Text1>SIGNATURE OK Y/N</Text1>
    <Button1>Yes</Button>
    <Button2>No</Button> 
</Message>

ClearDisplay (Response)

Notifies the POS system that it should remove any message that it was asked to display.

When the POS receives this message it should remove any message that the EFTPOS terminal has asked it to display. If such messages are displayed in a separate pop-up window, this window may be hidden.

Element Name	Description
type [Attribute]	ClearDisplay
id [Attribute]	Id of the message. Will correspond to the Id of the message request.

Example Data:

<Message type="ClearDisplay" id="1234" ></Message>

Status (Response)

Notifies the POS system that the status of terminal has changed. This message contains the information of the EFTPOS terminal status.

Element Name	Description
type [Attribute]	Progress
id [Attribute]	Id of the message. Will correspond to the Id of the message request.
Ready	Indicates the status of the terminal.
Description	Describes the status of the terminal. For example a Ready value of '1' and a desciption of 'EFTPOS OFFLINE' indicates that the terminal may be capable of processing transactions in EOV mode.

Example Data:

<Message type="Status" id="1234"> 
     <Ready>0</Ready> 
     <Description>Offline</Description> 
</Message>

Element Details & Configuration

Element Descriptions

Account (input) Datatype: Int Max 1 Bytes

The merchant account which this transaction is to be process under. This parameter is only valid if multi-merchant capability is enabled. If this parameter is not present, the default merchant account will be used.

AmountPurchase (input) Datatype: BSTR Max 13 Bytes

Set the amount to be charged or refunded (depending on the TxnType). Format is d.cc (d=dollars, c=cents). Max amount is 99999.99

AmountCashOut (input) Datatype: BSTR Max 13 Bytes

Set the "Cashout" amount. Format is d.cc (d=dollars, c=cents). If no cash out is to be made, this property must be empty (blank).

AmountRefund (input) Datatype: BSTR Max 13 Bytes

The amount, in dollars and cents, to be refunded. This parameter is only valid for refund transactions.is to be made, this property must be empty (blank).

AuthCode (input) Datatype: BSTR Max 22 bytes

Authorisation code returned by the Bank for approved transactions.

The value can be numeric or alpha-numeric.

Button (input) Datatype: BSTR Max 6 Bytes

Value will be the dialog button that needs selecting. Valid parameters: Yes, No, OK, Cancel. This parameter is case-insensitive.

Button1 (input) Datatype: BSTR Max 6 Bytes

The text for first button.

Button2 (input) Datatype: BSTR Max 6 Bytes

The text for the second button.

Button3 (input) Datatype: BSTR Max 6 Bytes

The text for the third button.

Beep (input) Datatype: BOOL Max 1 Bytes

If present and set to 1, the POS should beep to indicate that it requires user input.

CardType (output) Datatype: BSTR

The card type used for the transaction. Note that the list may be expanded as support for new cards is added. The CardName format is to capitalize the first letter with remaining letters in lowercase.

CardType	Description
Eftpos	Eftpos Cards
VISA	VISA Cards
DINERS	DINERS Cards
AMEX	AMEX Cards
MCARD	MasterCard
CurrencyId (input) Datatype:	LONG The currency to use for Dynamic Currency Conversion.

Currency Id	Currency Name
36	Australian Dollar
242	Fijian Dollar
250	French Franc
280	Deutschemark
344	Hong Kong Dollars
548	Vanuatu Vatu
554	New Zealand Dollar
598	PNG Kina
702	Singapore Dollar
776	Tonga Pa'anga
840	US Dollar
882	Samoa Tala
826	Pound Sterling
756	Swiss Franc
710	South African Rand
978	Euro
458	Malaysian Ringgit
414	Kuwaiti Dinar
392	Japanese Yen
124	Canadian Dollar
90	Solomon Islands Dollar

CurrencyRate (input) Datatype:BSTR

The rate of the foreign currency against the home currency.

DateTimeTransaction (output) Datatype: BSTR

Indicates when the transaction was processed. HHMMSS format.

DpsTxnRef (output) Datatype: BSTR Max 16 bytes

For future use. Returned for every transaction. If the transaction was approved, DpsTxnRef can be used as input to a Refund or Completion transaction for other Payment Express products. Used to specify a transaction for refund without supplying the original card number and expiry date. The DpsTxnRef value returned by the original approved Auth transaction must be supplied also when doing a complete transaction.

EftStatus (output) Datatype: LONG

Reserved

EnableBackLight (output) Datatype: BOOL

If present and set to 1, the EFTPOS terminal should turn back light on.

Ready (output) Datatype: BOOL

Indicates whether the terminal is ready or not. If the value is 1, the terminal is ready for processing request. If the value is 0, the terminal is in an error status and may require manual intervention.

ReceiptAutoPrint (output) Datatype: BOOL

If this value is 1, the receipt will be printed by the EFTPOS terminal. If this value is absent, or any value other than 1, the POS system will be responsible for printing the receipt.

Receipt (output) Datatype: BSTR

Receipt of the transaction that can be printed out for the customer.

DIRECT PAYMENT SOLUTIONS
DIRECT PAYMENT
SOLUTIONS - TEST

*-----------EFTPOS-----------*
TERMINAL 00905302  TRAN 000321
TIME  10JUN 15:17  ACCT CHEQUE
                             503871....7361
PURCHASE                       NZ$1.00
TOTAL                             NZ$1.00
         INCORRECT PIN
             DECLINED
*-------------------------------*

Reco (output) Datatype: BSTR Max 2 Bytes

The client application should not interpret the Response Code property contents - it is provided as informational only. TheAuthorizedIf this value is 1, the transaction has processed successfully. If this value is 0, the transaction was declined or cancelled.

ResponseText (output) Datatype: BSTR Max 20 Bytes

The Response Text is associated with ResponseCode. For successful transactions this is usually Approved and for unsuccessful transactions this can be a number of texts depending on why the transaction declined. For example it could be Card Expired, Declined, Invalid Card, REFER TO CARD ISSUER, DO NOT HONOUR. All acquirers have their own response texts and should be displayed for better understanding of why the transaction got declined.

SettleDate (output) Datatype: BSTR Max 8 bytes

Indicates Date of settlement (when money will be deposited in Merchant bank account) if this is supported by the Acquirer, otherwise contains the date the transaction was processed in YYYYMMDD format.

Success (output) Datatype: Boolean true/false

Indicates success or failure of a method call.

Text1 (input) Datatype: BSTR

The first line of text to be displayed on the EFTPOS terminal.

Text2 (input) Datatype: BSTR

The second line of text to be displayed on the EFTPOS terminal.

Track1 (input) Datatype: BSTR

Capture track 1 data with the magnetic strip

Track2 (input) Datatype: BSTR

Capture track 2 data with the magnetic strip

Track2 (input) Datatype: BSTR

Capture track 3 data with the magnetic strip

TxnDateTime (output) Datatype: BSTR Max 14 bytes

Date of the transaction, as reported by the EFTPOS network. The format is "YYYYMMDDhhmmss"

TxnRef (input/output) Datatype: BSTR Max 16 Bytes

Unique transaction reference 1-16 alphanumeric character.

TxnType (input) Datatype: BSTR

Value	Description
Purchase	Purchase - Funds are transferred immediately.
Refund	Refund - Funds transferred immediately.
XML	Listener (dpseftxifxp.exe) The configuration file will be in your installation directory and the file is named 'dpseftxifxp_cfg.txt'. It is in XML format and the elements and default settings are displayed below.

Value	Description
Purchase	Purchase - Funds are transferred immediately.
Refund	Refund - Funds transferred immediately.
XML	Listener (dpseftxifxp.exe) The configuration file will be in your installation directory and the file is named 'dpseftxifxp_cfg.txt'. It is in XML format and the elements and default settings are displayed below.

Setting	Description
Port	TCP/IP port the XML Listner application should open for connection & communication with your client application. For Flash/AS 2.0 the port will need to be greater than or equal to 1024. Default: 63.
EnableTestMode	Set to true (1) to enable test mode which will give a simulated Pinpad environment for testing. Set to false (0) to use a real Pinpad device in a live environment. Default: 0.

EFTPOS Environments

Cheque Verification

A Cheque Verify transaction allows the merchant to authorise a cheque, to verify that funds are available to honour the cheque.

Using Cheque Verification entails setting TxnType to Cheque, setting the Amount property to the value of the Cheque and setting the Track2 property to include the Cheque number.

The format of the cheque number should include a space between the branch number and account number, account number and cheque serial number.

For example Track2 = "1234 12345678 999123".

To use Cheque Verification, you will need your merchant number enabled for it at the banking network. You will also need to set the EnableCheque property in PXPP_CFG.txt to true (1)

<EnableCheque>1</EnableCheque>

Fuel Transactions (Reserved)

To enable Fuel capability you will need to set the EnableFuelDispensing property in PXPP_CFG.txt to true (1)

<EnableFuelDispensing>1</EnableFuelDispensing>

Fuel transactions include authorisation and completion (financial advice) type transactions. To start your Fuel transaction you should call the Transaction method with the TxnType set to Fuel. A prompt will allow you to Select Pump Number and then display the amount with PUMP X READY TO DISPENSE UP TO $50.00 or PUMP X READY FOR DELIVERY if the authorisation amount is greater than $50.00. Normal account selection and pin entry will follow.

Transaction message response will give you a DpsTxnRef in the response to be used for the corresponding completion.

Once the Fuel transaction needs to be completed. You call EditTender method with the DpsTxnRef stored from the 1st transaction with the Amount (original amount) and Amount2 (final completed amount) fields and TxnType set to Fuel again.

EnterData can be used for Pinpad to display more Fuel message prompts. Customers can also interact with these messages by using the Pinpad keys. The EnterDataEvent will fire with the response of what keys were pressed.

EnterData can use the message prompts shown below by entering the corresponding IDs into DisplayLine1 andDisplayLine2 properties when using the function.

PinPadDisplay can be used to set temporary messages on the pinpad, which will expire after a certain amount of time set when calling the function. This method can be used in conjuction with the message prompts below as well.

Message Prompt Lookup Tables

ID	Message Prompt
55	SELECT PUMP AND
56	PUSH ENTER
57	REQUIRE RECEIPT
58	YES OR NO
59	LOAD USER ID
60	AND ENTER
61	LOAD CONTRACT NO
62	LOAD FLEET NO
63	LOAD VEHICLE NO
64	LOAD DRIVER NO
65	LOAD EMPLOYEE NO
66	LOAD PLANT NO
67	LOAD ODOMETER
68	LOAD ENGINE HRS
69	LOAD ODO ENG HRS
70	LOAD PRESET
71	GO TO PUMP
72	AND TAKE FUEL
73	WRONG SYSTEM
74	WRONG NETWORK
75	SYSTEM NOT READY
76	EXPIRED CARD
77	BAD CARD
78	CARD NOT ALLOWED
79	INVALID
80	IDENTIFIER
81	CARD ALREADY
82	IN USE
83	DOLLAR LIMIT
84	REACHED
85	INVALID PUMP
86	NUMBER
87	PUMP OFF LINE
88	PUMP IN USE
89	PUMP IN ERROR
90	PUMP UNAVAILABLE
91	RESTRICTED TIME
92	RESTRICTED FUEL
92	INVALID ENTRY
93	ODO ENTRY
94	OUT OF RANGE
95	PRINTER NOT
96	WORKING
97	PRINTER OUT OF
98	PAPER
99	NO RECEIPT TO
100	PRINT
101	NOT ACCEPTED
104	INSERT CARD
105	PRINTING
106	SWIPE CARD
107	PLEASE WAIT