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 call/email our Sales team (see section 6 for contact details) to arrange.
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 our website: https://www.paymentexpress.com/support-software
Development Support Any integration questions can be directed at our development support team by emailing devsupport@paymentexpress.com.
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 devsupport@paymentexpress.com 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.

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.

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

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:

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:

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.

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.

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 Namem Description
type [Attribute] Transaction
Id [Attribute] Id of the message. Will correspond to the Id of the message response.
AmountPurchase Amount of Purchase.
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.
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 & Refund.
TxnRef Unique reference for the transaction. Used to match transaction requests with responses.

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
AmountPurchase Amount of Purchase.
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.
AuthCode Authorisation code from the bank. If this value is 1 the transaction has processed successfully. If this value is 0 the transaction was declined or cancelled.
Authorized
CardHolderName The card holder name.
CardNumber The card number (masked).
CardType Type of card used to perform the transaction.
ExpiryDate The card expiry date in the YYMM format.
MerchantId The identifier of the merchant.
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"
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. In this case it would be Purchase.
TxnRef Unique reference for the transaction. Used to match transaction requests with responses.

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

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.

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.

LastTransaction Response Message

Same as Transaction Response 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.

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.

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.

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.

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.

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.

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.

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.

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.

ClearDisplay

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

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.

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

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.

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.