EFTPOS XML Socket Interface

The Payment Express EFTPOS socket interface allows Point of Service (POS) applications to communicate with a Payment Express EFTPOS terminals across a local area network.

Requirements/Downloads:

Sample Code - C++ Sample available ActiveX Control Interface XML Socket Interface Tray Monitor - File Format Specification EFTPOS Service Configuration Settings Test Scripts to use before certification Test Card Information EFTPOS Response Codes - Non Bank Codes Test account. Apply online at https://www.paymentexpress.com/pxmi/apply FAQs Merchant FAQs Developer FAQs

Basic Communication

Each individual message sent to or from the terminal will look like the following:

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

The same message format is used for messages in both directions.

Each Message item has two attributes. The first attribute, type, specifies the type of data that is present in the message. The EFTPOS terminal and the POS software must examine the type of each message, and take the appropriate action.

The second attribute, id, is used to track associated commands. This attribute is optional. When the POS software specifies an id in a Message sent to the EFTPOS terminal, all corresponding Messages sent in return will contain the same id value. This is particularly useful when an operation causes multiple Messages to be sent back to the POS software.

Any line breaks inside the message data will be encoded to single-byte format, i.e. The line break is encoded as '0x0A'.

All messages will be encoded into ASCII format.

Using XML Interface

• Message Types

Normal Messages
• Transaction (Request)
• Transaction (Response)
• Cutover/Settlement (Request)
• Cutover/Settlement (Response)
• Logon (Request)
• Logon (Response)
• LastReceipt (Request)
• LastReceipt (Response)
• LastTransaction (Request)
• LastTransaction (Response)
• Receipt (Response)
• Button (Button Request)
• ReadCard - loyalty cards (Request)
• ReadCard - loyalty cards (Response)
• Enter & Display Data - Fuel (Request)
• Enter & Display Data - Fuel (Response)
• Tipping, Hospitality & Fuel (Request)
• Tipping, Hospitality & Fuel (Response)
• Display Pinpad Temporary Messages (Request)
• Set Pinpad Idle Prompt (Request)
• Print Pending Receipt (Request)
• Print Pending Receipt (Response)

Unsolicited Messages
• Display (Response)
• Status (Response)
• ClearDisplay (Response)

• ResponseCodes
• Element Descriptions
• XML Listener Configuration

EFTPOS Environments

• Cheque Verification
• Fuel Transactions

Message Types

Messages are divided into two main categories: normal messages and unsolicited messages.

Normal Messages

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>

The error (NACK) message will include the “success” field set to “0” and other two fields “Reco” and “ResponseText” to specify the error details. It will look like the following:

< 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 or Refund
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
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	If this value is 1, the transaction has processed successfully. If this value is 0, the transaction was declined or cancelled.
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.

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:

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

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.
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	If this value is 1, the transaction has processed successfully. If this value is 0, the transaction was declined or cancelled.
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.

Example Data:

<Message type="LastTransaction" 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>

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.

The id attribute for this message MUST match the id attribute of the Display message that caused the button to be shown. The POS system will not receive any response to this message.

Example Data:

<Message type="Button" id="1234">
<Button>Yes</Button>
</Message>

Receipt (Response)

Notifies the POS system that a receipt is to be printed. This message contains a digital copy of the data that would be printed on the receipt.

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]	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:

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

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	If this value is 1, the request has processed successfully. If this value is 0, the 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="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 request.
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>

Cutover (Response)

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 [Attribute]	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 logon request has processed successfully. If this value is 0, the logon 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>

Logon (Request)

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

Element Name	Description
type [Attribute]	Logon
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.

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>Track1>%B4111111111111111^PUBLIC/JOHN Q./MR^1012201?</Track1>
<Track2>;4111111111111111=1012201?</Track2>
<Track3></Track3>
</Message>

The information returned in this message contains the raw data from the ISO 7813 magnetic strip on the card. This data includes the start sentinel and end sentinel characters for each track.

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

EnterData (Request)

This function is used for displaying additional message prompts on the pinpad and receiving keystrokes pressed on the pinpad back to the POS application. Plain Text can be masked as well to be displayed on the Pinpad. This function is mainly used with vending and fuel POS. The event EnterDataEvent is fired when the command completes.

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 Bit 13 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 the DisplayLine1 & 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

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

Example Data:

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

TipSettlement (Request)

Notifies the EFTPOS terminal to finalize the pending tipping transaction.

Input Properties

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>

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.

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" />

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.

Example Data:

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

Element Descriptions

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.

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

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).

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).

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

The text for first button.

The text for the second button.

The text for the third button.

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

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

The currency to use for Dynamic Currency Conversion.

Currency Id	Currency Name
036	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
090	Solomon Islands Dollar

The rate of the foreign currency against the home currency.

Indicates when the transaction was processed. HHMMSS format.

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 DPS 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.

Reserved

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

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.

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 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
*-------------------------------*

The client application should not interpret the Response Code property contents - it is provided as informational only. The Authorized property determines if the the transaction was successful or not.

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.

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.

Indicates success or failure of a method call.

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

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

Capture track 1 data with the magnetic strip

Capture track 2 data with the magnetic strip

Capture track 3 data with the magnetic strip

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

Unique transaction reference 1-16 alphanumeric character.

 

Value	Description
Purchase	Purchase - Funds are transferred immediately.
Refund	Refund - Funds transferred immediately.

XML Listener (PxEftXML.exe)

The configuration file will be in your installation directory and the file is named 'PXEFTXML_CFG.TXT'. It is in XML format and the elements and default settings are displayed below.

<Server>

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.

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 and DisplayLine2 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