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.

Downloads/Guides

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

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

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.

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

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>

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

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 0, 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>

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


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>

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 - SettlementEnquiry
5 - 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  
KvcTSEK KVC code for Terminal storage encrypt key.
KvcTMK  
EnableRefundPreAuth Check merchant refund card in pre-auth message under DPS 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.

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

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.

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

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