The Payment Express Host Initiated Transaction (HIT) solution is a web facing HTTPS service that permits control of a payment transaction on a Payment Express terminal.
There is no requirement of a direct physical connection between the Point of Sale (POS) application and the Payment Express terminal. All required software is on the Payment Express Terminal and Host.
All messages are sent online via the internet to create an end-to-end cloud-based payment solution.
The terminal can be connected online to a modem or router directly. However if required the HIT enabled terminal can be connected to a POS's PC as well to share the internet connection from the PC, in that case the POS's PC needs to have an SCR Controller software installed. For further details see Configurations below.
The Payment Express HIT sandbox is accessible online https://demo.paymentexpress.com/SandboxPxHIT.aspx
A PDF version of this guide is available here
The POS initiates a transaction request to Payment Express by sending an HTTPS POST request as an XML message to the appropriate URL. See Endpoints and Firewall Considerations below for a list of URLs. Payment Express responds to the request, either immediately or after a configurable timeout period of a few seconds; after receiving a response, the POS will continue to make Status requests until the Status response indicates that the transaction is Complete (Complete value is returned as "1") in Result.
Status responses from Payment Express may contain instructions for the POS to permit information to be displayed for the merchant (DL1, DL2) and enablement of buttons that may be used by the POS to interrupt the transaction or provide feedback for example signature capture.
Note: For any new integrations, the POS must handle the entry of new users. POS applications are typically used by many different customers.
As each customer has one or more HIT API users, a key part of POS development is ensuring that new user HIT API credentials can be easily added into the POS and that the development credentials are not hard coded in any way. Please ensure the API credentials configuration within the POS are also password protected or has some level of authorised access challenge.
The POS can communicate with the Payment Host using HTTPS on the addresses below.
The Payment Express HIT terminal communicates with the Payment Express Host using TCP on the addresses below.
Please ensure that your network can accommodate this access.
HTTPS Address: https://uat.paymentexpress.com/pxmi3/pos.aspx, Port: 443
TCP Address: uat.paymentexpress.com, Port: 65
HTTPS Address: https://sec.paymentexpress.com/pxmi3/pos.aspx, Port: 443
TCP Address: scr.paymentexpress.com, Port: 65
Payment Express HIT terminals can be configured to connect directly to an external Internet connection; this allows merchants to remove all physical connection between their POS and the payment device; this option is available for both the iPP350 and the iWL250. No Payment Express software is required on the PC running the POS. However only the Payment Express key scheme is supported.
The iPP350 terminal is connected to an external network using three separate cables:
The customer must have a receipt printer and all receipt printing is controlled directly by the POS
The iWL25C terminal is connected for online connectivity to an external network (via a router or modem) using a standard Ethernet cable. The device must also have power to the base.
Both the iPP350 and the iWL250 can be connected directly to the merchant's POS. In order to run the HIT device, the merchant must download the SCRController software from the Payment Express website.
Payment Express and Paymark (NZ only) terminal key schemes are available.
The iPP350 is connected directly to the POS using one USB-A cable:
The customer must have a receipt printer. The HIT response will contain the receipt content which is required to be printed by the POS's own receipt printer.
The iWL25C terminal is connected directly to the POS using one USB-A cable. The device must also have power to the base.
All printing is handled directly by the terminal's on-board thermal printer.
The iPP350 can be connected directly to the MTM200.
The MTM200 includes a thermal printer and allows both Paymark and Payment Express key schemes to be used. The MTM200/iPP350 connection requires two separate cables:
All printing is handled by the MTM200's on-board thermal printer.
The iWL25C accepts SIM cards, this allows it to communicate using 3G.
No cable connection is required other than the standard power cable to the base. Only Payment Express keys can be used with this set up.
All printing is handled by the on-board thermal printer.
Terminals using the Paymark key scheme must have their keys remotely injected before transacting. Please contact our support team for assistance.
The Payment Express terminal should come with preconfigured network settings. If there are any connectivity issues that cannot be resolved, please contact Payment Express Support staff.
Once powered up, the device will go through an automatic boot-up and online logon process. Once completed & ready, PINpad will idle and display "EFTPOS" on the screen.
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. This is recommended but optional as the terminal will automatically log itself with the Payment Express Host 10 seconds after connecting to the network. However if logon is required please do the following manual logon process. Press the "Menu" button on the PINpad, and select "LOGON".
This section describes communication aspects of the HIT XML messages specification.
To initiate a transaction the following SCR XML message specified needs to be posted to the HIT POS endpoint.
| Property\[Attribute] | Required | Description |
|---|---|---|
| [user] | Yes | HIT Username provided by Payment Express. Alphanumeric, from 1 to 32 characters in length. Please ensure this is securely configurable via the POS config. |
| [key] | Yes | HIT Key provided by Payment Express. Alphanumeric, from 1 to 64 characters in length. Please ensure this is securely configurable via the POS config. |
| Station | Yes | Station Id unique to the terminal. Alphanumeric, from 1 to 32 characters. Please ensure this is securely configurable via the POS config. |
| Amount | Yes | Amount of transaction in D.CC format. Where D is dollar and C is cent value. Numeric and decimal point, from 1 to 13 digits. AmountCash No Amount for cash out. Numeric and decimal point, from 1 to 13 digits. Cur Yes Currency of the transaction. Alphanumeric, 3 characters only allowed. |
| TxnType | Yes | Transaction Type. Valid values: Purchase, Auth, Refund or Status. Please note for requesting the Complete transaction after an Auth transaction from the terminal please use our PxPost or WebService API. |
| TxnRef | Yes | Set by POS to uniquely identify transactions. Alphanumeric, from 1 to 40 characters. |
| DeviceId | Yes | HIT POS identifier provided by POS. For example, a POS Lane Identifier etc. Alphanumeric, from 1 to 32 characters. |
| PosName | Yes | PosName – agreed between POS Vendor and Payment Express. Alphanumeric, from 1 to 32 characters. |
| PosVersion | No | Version of POS. Supplied by POS to assist transaction recording and diagnosis. Alphanumeric, from 1 to 32 characters. |
| VendorId | Yes | The developer of the POS Application. This is agreed between Payment Express and vendor. Alphanumeric from 1 to 32 characters in length. |
| MRef | No | Merchant text field. Alphanumeric, max 64 characters. Recommend to use, useful for reporting purposes. |
| UrlSuccess | No | Set the URL to receive a HTTP GET FPRN on approved card present payment. Please see Fail-Proof Result Notification below for usage. |
| UrlFail | No | Set the URL to receive a HTTP GET notification on declined card present payment. Please see Fail-Proof Result Notification below for usage. |
| Property\[Attribute] | Description |
|---|---|
| TxnType | Transaction Type. Normally the HIT transaction response's TxnType value is as Status. |
| StatusId | Status of the current request. |
| TxnStatusId | Status ID related to current transaction. |
| Complete | If transaction is completed this field will be set to 1. |
| ReCo | Response Code indicating outcome. See 3 IntroductionResponse for a details description of ReCo values. |
| Tmo | Http Timeout in operation for the request. |
| TxnRef | TxnRef value for the original request and transaction. |
| DL1 | Display Line 1. If not empty, the merchant display should display this on the uppermost lines. |
| DL2 | Display Line 2. If not empty, the merchant display should display this on the lowermost line. |
| B1 | Button1. If not blank, contains label for a button that permits the POS to interact with the transaction. The "en" attribute will be "1" if the button should be active and displayed. |
| B2 | Button2. If not blank, contains label for a button that permits the POS to interact with the transaction. The "en" attribute will be "1" if the button should be active and displayed. |
Request a Status for an active or historical transaction. Merchant POS should request this message shortly after the transaction is initiated as per (see Transaction above). The TxnRef must match the transaction the POS wants to do status check on.
Example Status:
The POS interface should always show any DL1 and/or DL2 text from the Status response to match the terminal screen prompt text. Note in below example the DL1 display message is set to Processing.
Example Status Response:
A receipt message will be available to print as well as prompts and mandatory button options YES' and ‘NO'.
The POS should display the button options to the POS operator and a print button to print the physical merchant copy of the receipt for the customer to sign on. The POS system is required to accept or decline a signature transactions with the Yes or No button—please follow the messages for button requests in Buttons below.
Example Status Response (Signature prompted):
Please Note: It is important that the POS integration continues to request a status check until after the POS user appropriately handles the prompt on the POS and/or terminal and the final response contains the Complete tag value as 1. The HIT interface allows only one transaction to be fully completed at a time. A pending transaction completion will result in an "Existing Txn In Progress" error. This should be handled by sending the Status request for the TxnRef of the transaction until it reaches the Complete stage.
On completion of a transaction the Complete XML element will be set to 1. The result of the transaction will be populated inside the Result XML element. Below property elements are contained in the transaction response and Result XML element.
Example Final Status Response (Completed):
| Property | Description |
|---|---|
| TxnType | Transaction Type. Normally the HIT transaction response's TxnType value is as Status. |
| TxnRef | TxnRef value for the original request and transaction. |
| StatusId | Status of the current request Refer to the TxnStatusId and StatusId below for more information. |
| TxnStatusId | Status ID related to current transaction. |
| Complete | If transaction is completed this field will be set to 1. |
| RcptW | Receipt Width 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. |
| Rcpt | Actual EFTPOS receipt content that should be physically printed in case the POS handles the EFTPOS receipt printing. All receipt content should be printed to ensure financial data integrity. |
| Result | Encloses the final transaction results with specific transaction data fields. |
| AC | AuthCode. Up to 6 character authorisation code. |
| AP | Approved flag. "1" indicated approved (funds transfer or reserve); "0" indicated declined or not approved. |
| CN | Masked Card Number. |
| Complete | 1 indicates transaction session is completed. The POS should stop sending status requests |
| CT | Card Name e.g. Visa. |
| DS | Expected Settlement Date of Transaction. Format is yyyymmddhhmmss. |
| DS_TZ | TimeZone applied to the DS value. |
| DT | Date of Transaction. Returned in Timezone Format is yyyymmddhhmmss. |
| DT_TZ | TimeZone applied to DT value. |
| PIX | EMV specific data. |
| RID | EMV specific data . |
| RRN | Retrieval reference Number |
| ST | STAN. The System Trace Audit Number which identifies the transaction number processed through the merchant account. |
| TR | DpsTxnRef. Unique global transaction identifier generated by Payment Express and returned for every transaction. This value can be provided to support teams to identify transactions. |
| DBID | DpsBillingId is a card token generated by Payment Express. Token used to rebill the card for subscription or recurring based payments. Rebilling requests are sent via the PxPost or Webservice API. |
| RC | Response Code. See Response Codes below. |
| RT | Response Text. See Response Codes below. |
| RTT | Round Trip Time in Milliseconds – provides an indication of network health (between Payment Express and Payment Express Terminal). |
| AmtA | Amount value of the transaction in cents. |
POS is required to display appropriate buttons if B1 or B2 field in the XML response(s) is not blank. Once any button is clicked, the POS should then post appropriate button request to SCR endpoint.
Example Button Request
Example Button Response
| Property | Description |
|---|---|
| Station | Station Name of the Payment Express terminal being selected by the POS. |
| TxnType | For Button Request, the value should be UI for User Interface. |
| UiType | Bn |
| Name | B1 or B2. Depending on the button pressed. |
| Val | Value to be sent with the request for button press - CANCEL, YES, NO. |
| TxnRef | Transaction reference assigned by POS. This should be different for each transaction. |
Matched refunds initiated via HIT request To initiate a refund directly from the POS, the DpsTxnRef of the initial transaction must be included. The unique TxnRef is used separately as a reference to the refund and must be unique.
Example Matched Refund
To initiate a refund directly from the POS and authorise with a merchant refund card, the following example XML should be modified and sent. The DpsTxnRef tag does not need to be included, instead 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. The merchant refund card is setup by Payment Express. For extra security, it is expected the POS requires own authorization before requesting unmatched refund via the POS.
Example Unmatched Refund
The PxPost or Web Service eCommerce API can be used to process refunds with the matched DpsTxnRef of the given HIT transaction. For more information on PxPost and Web Service, please visit our website https://www.paymentexpress.com/developer-e-commerce-merchant-hosted-transaction-processing When using PxPost or Web Service to handle refunds, the HIT user and the eCommerce API user must be associated with the same Payment Express Group; for additional information please contact our Support team
In case the POS requires to request the last EFTPOS receipt content to print, the POS can send a request to receive the last transaction's receipt content with the most recent or last transaction's TxnRef. This can be requested to reprint the receipt when a printer and it's paper roll is available. Following are the request and response details specific to get the last receipt
Example Receipt Request
| Property | Required | Description |
|---|---|---|
| Station | Yes | Station Name of the Payment Express terminal being selected by the POS. |
| TxnType | Yes | For Receipt Request, the value should be Receipt. |
| TxnRef | Yes | The most recently processed transaction's transaction reference. |
| DuplicateFlag | No | An optional tag. If value 1: Includes a DUPLICATE RECEIPT text string on the receipt content. Otherwise 0 will not include the duplicate text string. |
| ReceiptType | Yes | 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 |
Example Receipt Response
| Property | Description |
|---|---|
| RcptW | Receipt Width 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. |
| Rcpt | Actual EFTPOS receipt content that should be physically printed in case the POS handles the EFTPOS receipt printing. All receipt content should be printed to ensure financial data integrity. |
Fail-Proof Result Notification (FPRN) is a service that provides additional assurance that the merchant website will receive a notification regarding the outcome of transactions completed via the Payment Express host. This service allows the merchant POS to stop checking for the status stage after the transaction is initiated and simply indicate finalisation of the transaction.
FPRN can be enabled by adding
As soon as the response result of TxnStatusId is 7 or 8, a background process on our cloud makes a HTTP GET request to the merchant-nominated success or failure URL. The URL must contain your own suitable query string parameters to identify the transaction reference, station ID etc appropriately on receiving the GET request from our cloud.
Depending on your architecture, the merchant hosted server may need to ensure it informs the POS of the GET request and subsequently performs a Status request to receive the final transaction outcome details (as shown above).
If the merchant web site is unreachable or returns any HTTP status code other than 200, 201, 302, 303, 404 or 502 the HTTP GET is retried up to a maximum of six times. It will give up immediately on receiving a 404 (page not found) HTTP status code or 502 (Bad Gateway) HTTP status code. A 500 HTTP status code, indicating a temporary problem at the client site, will cause a retry.
Please note if required, the POS can still perform the Status request after the transaction is initiated if the POS still wants to display the prompts on the POS screen for every stage of the transaction process.
To ensure that the web application is in the best position to acknowledge the outcome of every transaction, certain guidelines should be followed.
The merchant web application should not:
- Filter or base any conditional logic upon the originating IP address (this can vary)
- Depend upon receiving one and only one request for the success/fail URL from the Payment Express FPRN system (multiple requests may be sent). Note: The URL at which the merchant website will process FPRN requests must be exposed via standard internet ports i.e. port 80 or port 443 for SSL/TLS traffic. When specifying UrlSuccess and UrlFail values do not specify a non-standard port number within the URL.
Example Transaction Request with FPRN:
The Response Code value is a two character response used to indicate the transaction outcome.
| ReCo | Description |
|---|---|
| P4 | PosDeviceId is greater than 32 characters |
| P5 | PosDeviceId not matched |
| P7 | Invalid transaction type |
| P8 | Authentication error |
| P9 | Authentication error—Station Id mismatch |
| PA | Status request error |
| PB/PC | SCRHIT Init Session Error |
| PC | Existing Txn In progress — previous transaction was left in an incomplete state, ensure sending status request of the previous transaction and it's reference and status response is handled accordingly. |
| PD/PE/PF | SCRHIT Transmit Error — network connection issue, ensure the terminal has performed a Logon to the Payment Express HOST. |
| PG | Init Wait Timeout |
| PJ | TxnRef not matched |
| PK | SCRHIT not enabled |
| PL | Invalid input parameter |
| PM | Txn type not allowed |
| PO | Invalid Station Id |
| TQ | HIT Start Failed— connection lost, ensure the terminal has performed a Logon to the Payment Express HOST. |
The TxnStatusId is the Status ID related to the current transaction and terminal prompt. StatusId is the status of the current request.
| Id | Description |
|---|---|
| 1 | Idle |
| 2 | Present Or Insert Card |
| 3 | Select Account |
| 4 | Select App |
| 5 | Enter Pin |
| 6 | Processing |
| 7 | Verifying Signature 8 Display Result |
| Id | Description |
|---|---|
| 1 | Initiating |
| 2 | Transaction Started |
| 3 | Transaction Started |
| 4 | Processing |
| 5 | Authenticating |
| 6 | Transaction Completed |
The HIT request parameters are supplied as either XML elements or attributes. Some parameters are mandatory (must be included and non-blank), while others are optional.
| Name | Description |
|---|---|
| Amount | Amount of the transaction type. Decimal point is mandatory. |
| AmountCash | Amount of cash out required. Decimal point is mandatory. |
| EnableAddBillCard flag (optional) and BillingId (optional) | Set the EnableAddBillCard flag to 1 and POS supplies a unique BillingId that can be associated with card data for tokenizing a card and use for future automated rebilling or recurring payment via an eCommerce API (PxPost or WebService). BillingId has to be 1-32 characters in length. Otherwise the DpsBillingId (DBID) in the final transaction response can be used as a card token that is automatically generated by Payment Express. |
| Cur | Specifies the standard three letter Currency Code for the transaction. The standard currencies supported depends on the merchant's account configuration in the Payment Express system. |
| DeviceId | POS identifier provided by POS. For example, a POS Lane Identifier etc. Alphanumeric, from 1 to 32 characters. |
| EnableTip (optional) | If set to 1, enables prompting for a Tip (gratuity) in hospitality situations. Valid for Auth or Purchase transactions. |
| HttpTimeout (optional) | Timeout in seconds to be applied by Payment Express to HIT Client HTTP POST requests. If supplied, value must be between 10 and 60. |
| MRef (optional) | Merchant reference applied to the transaction. Mostly used for transaction reporting purposes. Up to 64 characters alphanumeric. |
| PosName | PosName – agreed between POS Vendor and Payment Express. |
| PosVersion | Version of POS. Supplied by POS to assist transaction recording and diagnosis. Alphanumeric characters between 1-32 characters. |
| Station | Station is the serial number value as a Station Name of the Payment Express terminal being selected by the POS. |
| TxnRef | Transaction reference assigned by POS. This should be unique for each Purchase, Auth or Refund transaction. |
| TxnType | The transaction type to be performed Purchase - Purchase Transaction Auth - Auth a card for certain amount Status - To receive the current status of the HIT terminal and HOST process Refund - To Refund a Purchase or Complete Transaction For more information please refer to Transaction Type Information. |
| TZ (optional) | Time zone to be applied to returned time values including times printed on receipt. If not supplied, the time zone configured by Payment Express for the terminal is applied. AEST - Australia Eastern Time (Sydney) AESTQL - Australia Eastern Time (Queensland) NZT - New Zealand Time UK GMT - UK Time US CST - United States Central Time US EST - United States Eastern Time US MST - United States Mountain time US PST - United States Pacific Time |
| Val | Value to be sent with the request for the button press - CANCEL, YES or NO. |
| VendorId | The developer of the POS Application. This is agreed between Payment Express and vendor. Alphanumeric from 1 to 32 characters in length. |
Any transactions processed via the Payment Express® HIT terminal can be monitored in real-time from any device with access to internet and a web browser. You can logon to the Payline® web portal at the address below using the username and password provided with your account.
Live transactions portal: https://sec.paymentexpress.com/pxmi3/logon
Test transactions portal: https://uat.paymentexpress.com/pxmi3/logon
In addition to monitoring transactions in real-time, the Payline® web portal can configured to download transaction reports, view invoices, view payments and also process manual transactions online.
For more information on Payline®, phone Payment Express® Sales on 0800 PAYMENT (729 6368) or email [email protected]
