EFTPOS Tupelo

The Payment Express XML socket interface allows Point of Sale (POS) applications to integrate with Payment Express SCR Tupelo terminals to take payment in a card present attended environment.

This communication between POS and terminal is managed by the Payment Express SCR Controller software installed on a Windows or Linux machine. By default the XML interface will be installed and configured to listen locally i.e. 127.0.0.1 on port 2008.

The SCR Controller software will also manage the forwarding and receiving of encrypted messages between terminal and the Payment Express Host.

POS Certification

Below is a high-level overview of the solution in a typical EFTPOS merchant environment:

To begin integration using XML socket interface, you will need the following:

Getting Started

Component	Explanation
Development Hardware & Test Cards	A Tupelo terminal (e.g. IPP350) loaded with test keys can be provided along with suitable test cards. Please contact your Payment Express Account Manager or email our Sales team.
Development Account	Development access to the Payment Express Payline® web portal will be issued when you receive your development hardware and test cards. This will allow you to view all transactions processed via your development terminal.
SCR Controller Software	The SCR Controller software can be downloaded from here.
Development Support	Any integration questions can be directed at our development support team by emailing [email protected].

Component	Explanation
POS Environment	The SCR Controller supports the following versions of Microsoft Windows: Windows 10 (32-bit/64bit) Windows 8 (32-bit/64bit) Windows 7 (32-bit/64bit) Please ensure latest Service Pack updates have been installed. Due to the multitude of Linux distributions available, Payment Express cannot guarantee that the SCR Controller will be compatible for every single Linux distribution. Technically SCR Controller will work on virtually any Linuxbased system with x86, x64 or ARM family CPU. Please contact your technical contact lead at Payment Express or email [email protected] to validate compatibility. Please ensure the following information is provided: Linux Distribution, Init Script and CPU processor.
User Interface Management	The POS/operator dialogs need to be managed by POS application. Please contact Dev Support if your POS does not meet this requirement.
Receipt Printing	Printing of receipts can be managed by SCR Controller or POS application. EnablePrint setting in SCR Controller configuration file will need to be set accordingly. 1=SCR Controller Printing or 0=POS Printing.
Receipt Printer	A minimum of one receipt printer is required to process transactions. The majority of setups consist of one receipt printer per terminal and POS; however the solution can also be configured for shared network printing also. Before proceeding, please make sure a test page can be successfully printed. Payment Express stock and supply the Tysso PRP-188 USB receipt printers. To enquire about these printers, Please contact your Payment Express Sales Account Manager or call/email our Sales team (see appendix for contact details).
USB / Serial Port	One free USB or Serial port is required for the terminal. When requesting a terminal please ensure that the appropriate cables are requested for your desired connection type. Please note that external DC power will be used for the Serial option.

Firewall Considerations

The Payment Express SCR Tupelo solution requires access to our UAT host for testing and our SEC host for production/live traffic

The communication protocols used are HTTPS & TCP

Test

HTTPS Address: https://uat.paymentexpress.com/scr.aspx, Port: 443

TCP Address: uat.paymentexpress.com, Port: 65

Production

HTTPS Address: https://sec.paymentexpress.com/scr.aspx, Port: 443

TCP Address: scr.paymentexpress.com, Port: 65

Software Components

Filename	Type	Description
PxScrController	.exe	Payment Express SCR Controller software. The SCR Controller will be installed and run as a service if using Windows OS.
PXSCRCONTROLLER_CFG	.txt	The configurations file for the SCR Controller.
LOG	directory	Folder for all SCR Controller log files.
PXSCRCONTROLLER_*	.log	SCR Controller log files. The filename is prefixed with PXSCRCONTROLLER and appended with Machine Name, Date Stamp and Time Stamp.
dpseftxc	.exe	Standalone client to perform non-integrated transactions and functions.
dpseftx	.ocx	ActiveX Control. Only required for dpseftxc application & ActiveX integrations.
DpsEftTray		Standalone Tray application. Allows access to the config and maintenance control panels.
pxjview		Standalone Journal Viewer application. Allows access to past transaction history/receipt data.
uninst_scr		Uninstaller

Basic Communication

Each individual message sent to or received from the SCR Controller should be formatted as follows.

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

Each individual message sent to or received from the SCR Controller should be formatted as follows.

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 SCR Controller 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 messages. This attribute is optional but strongly recommended. When the POS software specifies an id in a Message sent to the SCR Controller, 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.

Unsolicited Messages

These messages are usually sent from SCR Controller to POS system. An unsolicited message may or may not be associated with a request message. It is usually used by SCR Controller to display information on the POS system’s screen or prompt for user input from POS system.

It will also be used for notifying the status changes of SCR Controller and/or terminal. Depending on the type of unsolicited message the POS system may need to take actions upon receipt of the message. This is important in situations where the POS system is shutdown or has crashed in the middle of a transaction, and the SCR Controller is awaiting feedback from the POS. The POS application must be able to reconnect immediately to the XML listener upon restart to resume the process.

Status

This is an unsolicited message that tells the POS system that the status of terminal has changed e.g. terminal is disconnected.

This message contains the information of the EFTPOS terminal status.

The message is identical to the GetStatus Response Message apart from the type attribute being Status instead of GetStatus.

Display

This is an unsolicited message that tells the POS system to display dialog/buttons to the POS operator.

An unsolicited message may be associated to a request message or not.

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

Below is the description of fields and example message.

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

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 dialog.
Text2	This is the message display line 2 of the dialog.
Button	Data from Track3 of the card.
Button1	Indicates the success of a method call.
Button2	Two-character code indicating the outcome.
Button3	A textual description of the outcome.
Beep	If present and set to 1 the POS should beep to indicate that it requires user input.

        <Message type="Display" id="1234"> 
            <Text1>SIGNATURE OK Y/N</Text1> 
            <Text2></Text2> 
            <Button1>Yes</Button1> 
            <Button2>No</Button2>  
            <Button3></Button3>  
            <Beep>1</Beep>
        </Message>

ClearDisplay

This is an unsolicited message that Notifies the POS system that it should remove any dialogs/buttons that it was asked to display.

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

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

Normal Messages

These messages are usually request/response pairs. The request message is usually initiated by POS system to make a request to the SCR Controller and then being replied by the SCR Controller 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 SCR Controller and terminal.

The acknowledge message will include the "success" element 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" element set to "0" and two other elements "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 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.

Functions

Logon

In order to prepare the terminal for processing transactions, the Logon message is used.

A Logon uses the assigned merchant number and terminal ID to login to the banking switch. Logon functionality is mandatory.

A manual merchant Logon can also be used as a manual trigger to restart online processing after a period of offline processing and to manually trigger a configuration download from the Payment Express host (if there are changes).

Logon Request Message

Element Name	Description
type [Attribute]	Logon
Id [Attribute]	Example: Id of the message. Will correspond to the Id of the message response.

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

Logon Response Message

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.
ResponseText	A textual description of the outcome.

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

Transaction

Notifies the terminal that the POS system wishes to initiate a transaction.

The message data specifies the type of transaction and the amount to be processed.

Transaction Request Message

Element Name	Description
type [Attribute]	Transaction
Id [Attribute]	Id of the message. Will correspond to the Id of the message response.
Account	The merchant account which this transaction is to be process under. If this parameter is not present the default merchant account will be used.
AmountAuth	The amount in dollars and cents for Purchase transaction. This parameter is only valid for Auth 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.
AmountPurchase	The amount in dollars and cents for Purchase transaction. This parameter is only valid for Purchase transactions.
AmountRefund	The amount in dollars and cents to be refunded. This parameter is only valid for Refund transactions.
DpsTxnRef	Unique transaction identifier returned for every transaction. Required input for Refund transactions or Complete transactions.
MerchantReference	A free text field describing the transaction (order number etc). The merchant reference is stored against this transaction and is made available in Payment Express Payline® web portal and reports.
TxnType	The type of transaction to be processed. Standard allowed values are: Purchase, Auth, Refund.
TxnRef	Unique reference for the transaction. Used to match transaction requests with responses.

        <Message type="Transaction" id="1234"> 
            <TxnType>Purchase</TxnType>  
            <MerchantReference>order12345</MerchantReference>  
            <TxnRef>txnref12345</TxnRef>  
            <AmountPurchase>19.95</AmountPurchase> 
            <AmountCashOut>0.00</AmountCashOut>
        </Message>

Transaction Response Message

Element Name	Description
type [Attribute]	Transaction
Id [Attribute]	Id of the message. Will correspond to the Id of the message response.
AccountType	The type of account selected by the customer. Possible values include: Cheque Saving Credit
AmountAuth	The amount in dollars and cents for an Auth transaction. This parameter is only valid for Auth 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.
AmountPurchase	Total Amount of purchase. This parameter is only valid for Refund transactions.
AmountRefund	The amount in dollars and cents to be refunded. This parameter is only valid for Refund transactions.
AmountSurcharge	The additional amount charged by the merchant in dollars and cents added to the Purchase Amount.
AmountTip	The additional amount in dollars and cents added to the Purchase Amount for Tipping/Gratuity.
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 (masked).
CardType	Type of card used to perform the transaction.
DpsBillingId	The unique Card Token ID generated by Payment Express when adding a card, used for recurring billing.
DpsTxnRef	Unique transaction identifier returned for every transaction.
ExpiryDate	The card expiry date in the YYMM format.
MerchantId	The identifier of the merchant.
MerchantReference	A free text field describing the transaction (order number etc). The merchant reference is stored against this transaction and is made available in Payment Express Payline® web portal and reports.
Rid	The RID of the EMV transaction (only applicable if EMV card is used).
Pix	The Pix of the EMV transaction (only applicable if EMV card is used).
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.
TxnDateTime	Date of the transaction as reported by the EFTPOS network. The format is "YYYYMMDDhhmmss"
TxnType	The type of transaction to be processed. In this case it would be Purchase.
TxnRef	Unique reference for the transaction. Used to match transaction requests with responses.

        <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>
            <AmountCashOut>0.00</AmountCashOut> 
            <AmountPurchase>0.00</AmountPurchase>
			<DpsBillingId>12343567890123</DpsBillingId>
            ... 
        </Message>

Tokenisation & Rebilling

For tokenisation you must store the DpsBillingId from the Setup Phase of the secure card reader Transaction Response Message, then use one of the eCommerce APIs to perform the rebilling phase transactions, such as PxPost.

Auth-Completion

Overview

Payment Express supports Auth/Completion.

An "Auth" transaction verifies that funds are available for the requested card and amount and reserves the specified amount.

A "Completion" transaction is sent at a later date to cause funds transfer for the previously authorised amount, or a smaller amount if the total original value is no longer required.

This transaction set is useful when the merchant needs to ensure that funds up to a certain limit are available but the actual total amount is not yet known or goods or services have not yet been delivered.

Operation

1) Authorization

In the Transaction Request Message, set TxnType to "Auth" for the amount to be authorised.

The Auth response contains a DpsTxnRef.

The funds are not transferred from the cardholder account.

2) Completion

After a successful Authorization transaction, but within 7 days maximum, a completion transaction must be sent containing the DpsTxnRef returned by the "Auth" transaction.

A Completion cannot be performed via the secure card reader, it must be processed via one of the eCommerce APIs, such as PxPost.

Please see the Auth-Completion process via PxPost for more information.

Refunds

There are different methods for performing refunds from the terminal.

The customer's card must be present in all cases and if it is a standalone refund then a Merchant Refund Card will be required for authorisation.

To enable refunds and obtain a merchant refund card, please contact [email protected].

Matched Refund Transaction Request Message

Matched refunds are a refund directly from the POS, the DpsTxnRef of the initial transaction must be included.

The refund amount can be any amount up to the original transaction amount.

The unique TxnRef is used separately as a reference to the refund and must be unique.

The customer's card must be present in order to perfom the refund transaction from the terminal.

        <Message type="Transaction" id="1234"> 
            <TxnType>Refund</TxnType>  
            <MerchantReference>refund12345</MerchantReference>  
            <TxnRef>txnref12345</TxnRef> 
            <DpsTxnRef>10b0001f00c09fa1</DpsTxnRef>
            <AmountRefund>19.95</AmountRefund> 
        </Message>

Unmatched Refund Transaction Request Message

To initiate a refund directly from the POS you will need to authorise with a merchant refund card. The merchant refund card is setup by Payment Express.

For authorization the terminal will prompt for the merchant's refund card to be swiped and PIN entered before the customer presents their card for the refund.

For extra security, it is expected the POS requires own authorization before requesting unmatched refund via the POS.

        <Message type="Transaction" id="1234"> 
            <TxnType>Refund</TxnType>  
            <MerchantReference>order12345</MerchantReference>  
            <TxnRef>txnref12345</TxnRef>  
            <AmountRefund>19.95</AmountRefund> 
        </Message>

Surcharge

A surcharge is an additional charge, payment or fee that is added to the cost of a good or service.

Using the surcharge functionality we can add an addtional surcharge amount on top of the original amount of the transaction.

If a surcharge amount is added to the transaction, then the Transaction Response message will contain the AmountSurcharge field.

The surcharge amount is not set in the Transaction Request, it is configured on the host as a set amount value or a percentage of the original transaction amount.

To apply a surcharge per transaction, please contact [email protected] and provide the account details such as terminal IDs, Card Name and Fee to be applied for each card you accept and wish to apply a surcharge amount for all transactions.

Tipping

Tipping refers to an optional additional gratuity amount that is added on top of the original amount of the transaction.

The tip amount is not set in the Transaction Request, if an amount for gratuity is to be added to the transaction, it will be entered on the terminal directly.

If a tip amount is added to the transaction, then the Transaction Response message will contain the AmountTip field.

To enable the optional Tipping/Gratuity entry for transactions, please contact [email protected] to enable the feature.

EnterData

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

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

All display prompts are configured by PX. Please contact Dev Support if you wish to utilise this function for a specific use case.

EnterData Request Message

Element Name	Description
type [Attribute]	EnterData
Id [Attribute]	Id of the message. Will correspond to the Id of the message response.
DisplayLine1	Prompt Id number e.g. 411 "Enter Cash-out Amount". Configured by PX.
Param1	Optional Parameter 1 (e.g. If PromptId = 105 describes a fuel pumping prompt "Use pump ", the optional parameter might provide the number "1")
Param2	Optional Parameter 2. As for optional parameter 1
Timeout	Optional timeout value in seconds

        <Message type="EnterData" id="1504241246"> 
            <DisplayLine1>411</DisplayLine1> 
        </Message>

EnterData Response Message

Element Name	Description
type [Attribute]	EnterData
Id [Attribute]	Id of the message. Echoes Id of the request message.
Success	Indicates whether request was successfully processed by SCR controller
ReCo	Two-character response code that indicates the outcome of the request. See SCR Serial Message Specification for the list of possible values.
ResponseText	Text that indicates the outcome of the request
Result	The data string or button code entered by the customer.

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

The Result element contains the data entered by the customer using the terminal. In the above example the customer entered 1234.

This can then be used for a POS function or another PX XML API function such as Purchase/Cash-Out.

LastTransaction

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

LastTransaction Request Message

Element Name	Description
type [Attribute]	LastTransaction
Id [Attribute]	Example: Id of the message. Will correspond to the Id of the message response.

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

LastTransaction Response Message

Same as Transaction Response Message.

GetReceipt

Notifies the terminal that the POS system wishes to retrieve a particular receipt for a specified TxnRef.

When the receipt retrieval has completed, the POS system will receive a GetReceipt response message from the terminal.

GetReceipt Request Message

Element Name	Description
type [Attribute]	GetReceipt
id [Attribute]	TxnRef of the message. Will correspond to the id of the message response.
ReceiptType	A flag indicating the receipt content type to receive. Valid Values: 1 = Merchant Copy of receipt with a signature placeholder (only for signature transaction) 2 = Customer Copy of receipt 3 = Merchant Copy of receipt

        <Message type="GetReceipt" id="1234">
            <ReceiptType>1</ReceiptType>
        </Message>

GetReceipt Response Message

Element Name	Description
type [Attribute]	GetReceipt
id [Attribute]	TxnRef of the message. Will correspond to the id of the message request.
ReCo	The Response Code indicating the outcome of the request.
ResponseText	The text response indicating the outcome of the request.
Receipt	The raw receipt text data.
IsSeparate	Flag indicating if is last transaction receipt or separate receipt.
ReceiptWidth	Specifies the maximum character limit per receipt content's line. A terminal's account is setup with a default receipt width character length. The fixed character limit can be used to center justify the receipt content per line to get the standard receipt format.
ReceiptType	Integer indicating which ReceiptType was requested.

        <Message type="GetReceipt" id="1234">
            <Success>1</Success>
            <ReCo>00</ReCo>
            <ResponseText>ACCEPTED</ResponseText>
            <Receipt>...</Receipt>
            <IsSeparate>1</IsSeparate>
            <ReceiptWidth>27</ReceiptWidth>
            <ReceiptType>1</ReceiptType>
        </Message>

LastReceipt

Notifies the 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 terminal.

LastReceipt Request Message

Element Name	Description
type [Attribute]	LastReceipt
Id [Attribute]	Example: Id of the message. Will correspond to the Id of the message response.

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

LastReceipt Response Message

Element Name	Description
type [Attribute]	Button
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.
ResponseText	A textual description of the outcome.
IsSeparate	Flag indicating if is last transaction receipt or separate receipt.
ReceiptWidth	Specifies the maximum character limit per receipt content's line. A terminal's account is setup with a default receipt width character length. The fixed character limit can be used to center justify the receipt content per line to get the standard receipt format.
ReceiptType	Integer indicating which ReceiptType was requested.

        <Message type="LastReceipt" id="1234">
            <Success>1</Success>
            <ReCo>97</ReCo>
            <ResponseText>Transaction Completed</ResponseText>
            <Receipt> ...</Receipt>
            <IsSeparate>0</IsSeparate>
            <ReceiptWidth>27</ReceiptWidth>
            <ReceiptType>2</ReceiptType>
        </Message>

Button

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

Button Request Message

Element Name	Description
type [Attribute]	Button
Id [Attribute]	Id of the message. Will correspond to the Id of the message response.
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.

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

Button Response Message

Element Name	Description
type [Attribute]	Button
Id [Attribute]	Id of the message. Will correspond to the Id of the message request.
ReCo	Two-character code indicating the outcome.
ResponseText	A textual description of the outcome.

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

ReadCard

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

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

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

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

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

ReadCard Request Message

Element Name	Description
type [Attribute]	ReadCard
Id [Attribute]	Example: Id of the message. Will correspond to the Id of the message response.

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

ReadCard Response Message

Element Name	Description
type [Attribute]	ReadCard
Id [Attribute]	Id of the message. Will correspond to the Id of the message request.
Track1	Data from Track1 of the card.
Track2	Data from Track2 of the card.
Track3	Data from Track3 of the card.
Success	Indicates the success of a method call.
ReCo	Two-character code indicating the outcome.
ResponseText	A textual description of the outcome.

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

GetStatus

Requests terminal status & settings. This is a useful tool for exception handling.

GetStatus Request Message

Element Name	Description
type [Attribute]	ReadCard
Id [Attribute]	Example: Id of the message. Will correspond to the Id of the message response.

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

GetStatus Response Message

Element Name	Description
type [Attribute]	GetStatus
Id [Attribute]	Id of the message. Will correspond to the Id of the message request.
Ready	1 if Ready to process transactions otherwise 0 .
Description	Text description for Ready element e.g. "Ready" or "PINpad Offline".
ReadyPinPad	1 if PINpad/Terminal is connected otherwise 0.
ReadyLink	1 if Interfaces/Links are connected otherwise 0.
EovEnabled	1 if EOV (Electronic Offline Voucher Mode) feature is enabled, otherwise 0.
EovOffline	1 if terminal is in EOV mode, otherwise 0 if terminal is online.
EovLimitExceeded	1 if terminal has exceeded EOV limits and cannot process any further transactions offline, otherwise 0.
UplinkDetails	Interface (link) connection details
Interface	Interface (one per interface).
Name	Interface Name (e.g. UAT_HTTPS).
Type	Connection Type (HTTPS or TCP).
Address	Endpoint Address (e.g. https://uat.paymentexpress.com/scr.aspx).
Port	Endpoint Port (e.g. 443)
Priority	Interface priority. The higher the number, the higher the priority.
Enabled	1 if interface is enabled, otherwise 0 if disabled.
Ready	1 if interface is ready (connected), otherwise 0 if not ready (disconnected).
Nii	Only valid for Paymark NZ configurations. 541 for UAT and 001 for Production.
Terminal	Terminal (PINpad) details
PinPadInfo
Port
Port	the terminal is connected on (e.g. COM3).
SerNum	Serial Number of the terminal. Unique per terminal.
SwVer	Firmware version running on the terminal (e.g. SCRIPP350 v1.3.7.2).
LoggedOn	1 if Terminal is logged on to the Payment Express Host, otherwise 0.
IsOffline	1 if Terminal is offline, otherwise 0.
EovTxnCount	Amount of EOV transactions stored (pending upload).
EovForceLoggedOff
CurrencySymbol	Currently set and used by terminal (e.g. USD).
Catid	Terminal ID set and used by the terminal
Caid	Merchant ID set and used by the terminal
Nii	Only valid for Paymark NZ configurations. 541 for UAT and 001 for Production.
MasterKeyKvc
StorageKeyKvc
ScrDeviceId	DeviceId set and used by terminal. Set in SCR Controller config file or by using the Configuration Function.
ReversalPresent	Amount of Reversal messages stored (pending upload).
Capabilities	List of terminal capabilities enabled.
PaDssVersion	PCI PA-DSS version.
LogonString	Only valid for Paymark NZ configurations. Unique logon string for identification.
AppVersion	PX SCR Controller version used.

        <Message type="GetStatus" id="1234">
            <Ready>1</Ready> 
            <Description>Ready</Description> 
            <ReadyPinPad>1</ReadyPinPad> 
            <ReadyLink>1</ReadyLink> 
            <EovEnabled>1</EovEnabled> 
            <EovOffline>0</EovOffline> 
            <EovLimitExceeded>0</EovLimitExceeded> 
            <UplinkDetails> 
            <Interface> 
                <Name>UAT_HTTPS</Name> 
                <Type>HTTP</Type> 
                <Address>https://uat.paymentexpress.com/scr.aspx</Address> <Port>443</Port> 
                <Priority>12</Priority> 
                <Enabled>1</Enabled> 
                <Ready>1</Ready> 
                <Nii></Nii> 
            </Interface> 
            <Interface> 
                <Name>UAT_TCP</Name> 
                <Type>TCP</Type> 
                <Address>uat.paymentexpress.com</Address> 
                <Port>65</Port> 
                <Priority>11</Priority> 
                <Enabled>1</Enabled> 
                <Ready>1</Ready> 
                <Nii></Nii> 
            </Interface> 
            </UplinkDetails> 
            <Terminal> 
            <PinPadInfo> 
            <Port>COM3</Port> 
            <SerNum>1102261473</SerNum> 
            <SwVer>SCRIPP350 v1.3.7.2</SwVer> </PinPadInfo> 
            <LoggedOn>1</LoggedOn> 
            <IsOffline>0</IsOffline> 
            <EnableEOV>1</EnableEOV> 
            <EovTxnCount>0</EovTxnCount> 
            <EovForceLoggedOff>0</EovForceLoggedOff> 
            <CurrencySymbol>USD</CurrencySymbol> 
            <Catid>55667788</Catid> 
            <Caid>11223344</Caid> 
            <Nii>1</Nii> 
            <MasterKeyKvc>000000</MasterKeyKvc> 
            <StorageKeyKvc>000000</StorageKeyKvc> 
            <ScrDeviceId>ETSL12345</ScrDeviceId> 
            <ReversalPresent>0</ReversalPresent> 
            <Capabilities>Auth=1,Balance=0,Cheque=0,MultiMerchant=0,EnableDcc=0,Tipping=0,Hospitality=0,Enable Eov=1,EnableFlyBuy=0,EnableFuelDispensing=0,Topup=0,EMVLibTest=0,Void=1,Deposit=0,EmvContactle ss=1</Capabilities> 
            <PaDssVersion>PA-DSS V1.269</PaDssVersion> 
            <LogonString></LogonString> 
            <AppVersion>PXSCRCONTROLLER 3.0.17.0-t3</AppVersion>
            </Terminal>
        </Message>

Hot-Swap

Hot-Swap allows merchants to replace an old/faulty terminal with a new/working terminal without contacting Payment Express.

Once connected, the terminal will automatically download the correct configurations from the Payment Express host.

To implement Hot-Swap, every till/workstation must be uniquely identified so that corresponding terminal profile can be applied.

This unique identifier string is communicated to SCR controller as POS device ID with the "Configuration" message described below:

Configuration Request Message

Element Name	Description
type [Attribute]	Configuration
Id [Attribute]	Id of the message. Will correspond to the Id of the message response.
ScrDeviceId	POS Device ID, ASCII 1 to 32 printable ASCII characters 0x20 to 0x7D (hex) are allowed.

        <Message type="Configuration" id="1504055462"> 
            <ScrDeviceId>9100000001-1725</ScrDeviceId>
        </Message>

Configuration Response Message

Element Name	Description
type [Attribute]	Configuration
Id [Attribute]	Id of the message. Echoes Id of the request message.
Success	Indicates whether request was successfully processed by SCR controller
ReCo	Two-character response code that indicates the outcome of the request. See SCR Serial Message Specification for the list of possible values.
ResponseText	Text that indicates the outcome of the request

        <Message type="Configuration" id="1504055462"> 
            <Success>1</Success> 
            <ReCo>00</ReCo> 
            <ResponseText>ACCEPTED</ResponseText>
        </Message>

Please note: There is no need to send the configuration function every time – once received SCR controller saves the parameters in configuration file and applies them in the subsequent initialisations.

Moreover, this message puts SCR controller in an initialisation state so that other requests couldn’t be processed until the initialisation completes.

Element Details & Configuration

Element Name	Datatype	Description
Account (input)	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)	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)	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)	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)	BSTR Max 22 bytes	Authorisation code returned by the Bank for approved transactions. The value can be numeric or alpha-numeric.
Button (input)	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)	BSTR Max 6 Bytes	The text for first button.
Button2 (input)	BSTR Max 6 Bytes	The text for the second button.
Button3 (input)	BSTR Max 6 Bytes	The text for the third button.
Beep (input)	BOOL Max 1 Bytes	If present and set to 1, the POS should beep to indicate that it requires user input.
CurrencyId (input)	LONG	The currency to use for Dynamic Currency Conversion only. Otherwise you are not required to use this input field. Below is the table of currencies. If you are unsure of the currency required, please consult [email protected].
CardType (output)	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

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

POS Certification

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

Pre-POS Certification Check

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

Please contact the Sales and Implementation team.

Book Certification

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

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

Certification

Payment Express QA will commence POS Certification on the scheduled date.

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

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

POS Bug Fixes

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

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

Certification Results

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