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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

Logon (Request)

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

Example Data:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

GetStatus (Request)

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

Example Data:

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:

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:

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:

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:

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:

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:

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.

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)

Fuel Transactions (Reserved)

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

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