Host Initiated Transactions

The Payment Express HIT API facilitates communication between the merchant Point of Sale and a payment terminal. As all communications route via the Payment Express host, no direct connection is required between the merchant’s POS and the payment terminal.

Download as PDF | HIT Sandbox

Getting started.

Outfitted with an array of connectivity options, the Ingenico payment terminals support 3G, Wi-Fi, RJ-45, and USB connections depending on the terminal.

Connectivity options
Device 3G Wi-Fi RJ-45 USB

Now that you have established a connection between your terminal and the outside world, perform a logon or a Purchase transaction via the standalone menu on the PINpad. If the terminal displays an Approval message, you are ready to start development. If your terminal times out or if HOST CONN ERR is displayed on the screen, there is some problem with your network. Please check connectivity using another device, if you are unable to resolve the issue, please contact our support team.

You should have Payment Express HIT API credentials already, if you do not have credentials please contact our support team and provide the serial number of the payment terminal.

Transaction flow.

To initiate a transaction, well-formed XML must be sent to the PX Host endpoint.

The PX Host then communicates directly with the terminal and returns an XML response to your POS. During the initial phases of POS development, it is advised that developers utilize the Payment Express HIT Sandbox. The Sandbox will assist with understanding the basic flow of the API.

Payment Express will update the display on the payment terminal and will send a response back to your POS.

Looking at the response XML, you will notice the “Complete” tag is currently set to 0, until this Boolean value is equal to 1, your POS should continue to send Status checks. Additionally you will also note that the DL1 and DL2 tags contain the state of the transaction in a human friendly format, these should be displayed on your POS screen to keep the operator informed of the transaction progress.

On completion of the transaction, “Complete” will be set to 1 and a final response will be provided by Payment Express containing all relevant transaction data.


At certain stages of the payment process, the POS operator may wish to CANCEL the transaction or provide either a YES/NO response to the payment terminal. The XML response should be parsed and if B1 or B2 is enabled, the POS operator should be able to send a button response back to the PX Host. The Name and Val are both pulled from the most recent XML response.


A matched refund can be initiated directly from the POS

Alternatively you can perform a matched refund using another Payment Express online payment API.

To assist with troubleshooting, it is highly recommended that comprehensive logging of all XML requests and responses be performed.

Transaction inputs.
XML tag Required? Description
Station Yes 10 digit ID found on the back of the terminal. An IPP350 will start 40XXXXXXXX and an IWL250 will start 41XXXXXXXX
Amount Yes The monetary value of the transaction
Cur Yes A valid ISO 4217 currency code
TxnType Yes One of:
TxnRef Yes A unique identifier for each and every transaction
DeviceId Yes An alphanumeric identifier with a maximum length of 32 characters. This is used to identify the device or till being used and should be unique to the device and not the transaction
PosName Yes The name of POS agreed with Payment Express
PosVersion No The version number of the POS. This is alphanumeric with a maximum size of 32 characters.
VendorId Yes The name of the developing organization responsible for the POS. This is alphanumeric with a maximum size of 32 characters.
MRef No Merchant text field used for reporting purposes. This is alphanumeric with a maximum size of 64 characters.
EnableAddBillCard No Will generate a reference to the card that can be used for subsequent rebilling. To enable set value to 1.