Integration and Connection

Technical connectivity options

A terminal is normally connected to some kind of transport layer (host connector) which is responsible to transport the messages from terminal to to a web server in front of Fiserv's gateway.

In this SSL communication, a client- and a server-certificate is used. The web-server will only accept the connection, if the used client-certificate is signed by trusted instance. The common name (CN) in the certificate identifies the
instance which sends the transaction. the gateway will check, whether the store given in the transaction belongs to this instance and routes the transaction to the Backend Switch. The response of the authorization system will be returned to the client as a response to the HTTPS request.

📘

There multiple way for terminals to integrate with our NEXO interface.

Integration options vary from:

• the connection between owner of the host,
• the key exchange process and,
• the used terminal management system (TMS) that is used for parameterization.

All of them can either be managed by fiserv, 3rd party provider or terminal vendor itself.

Terminals connect via a terminal server (at client side) to the Gateway's: host to host connectivity

• Agnostic development of the client server application
• A failover to the backup side will be controlled by the Gateway. The customer doesn't need to care about this.
• Makes best use of existing fault tolerant network infrastructure on Gateway side.

Terminals connect via Fiserv's inhouse connector 'Datawire'

• Certified interface between terminals and our gateway
• No need to install client certificates.
  The terminal technically connects to the infrastructure of Datawire
• Simple registration process for each combination of Store ID, Merchant and Terminal ID

Terminals connect directly to the Gateway (test-only)

• Terminal directly accesses the Gateway's web-server
• Client level certificate generated per store
• ONLY allowed for initial tests

Communication protocol

Transport layer

Transport layer of the authorization processing via NEXO will be implemented as a REST service. The terminal will initiate communications by sending POST HTTPS requests to Fiserv.

The transport layer between the terminal (host) and the Gateway will be implemented with the below characteristics:

• The interface to the gateway is via a REST service, which will be available through
  HTTPS.
• Connections will be opened by terminal (host)
• The request must be a POST HTTP request (HTTP 1.1), with the message (an
  NEXO XML request message) in the HTTP body.
• The gateway will send the corresponding NEXO XML response message in the body part
  of HTTPS response.
• All message types will use the same URL. (of course URLs for test will vary)
• Once a request was sent, the connection must stay open until the response is
  received or a timeout occurs.
• It is not allowed to send other messages through the same connection, while a
  response is still outstanding. This also applies to diagnostic messages.
• If there is a failure during communication, then the connection must be closed and not re-used. This applies only to errors on the transport level.
  Failed or declined transactions do not require to close the connection. Also a reject message is not a ‘failure during communication’ and the connection may be used again.
• After the response is received, the connection can be used for further requests.
• It is possible to open several connections in parallel to process multiple transactions at the same time (one through each connection).
• HTTP status codes are not used to indicate success or failure of processing. This is always done using NEXO messages.
• The implementation uses NEXO Acquirer Protocol v6
• Content-type should be "application/xml; charset=UTF-8”
• A HTTP status code different from 2xx is returned for communication errors,
  after which the connection is no longer usable.

Connection pool/handling

On the client side we recommend a connection pool to avoid overhead for connection setup. Connections in the pool could be kept alive using the diagnostic message or simply closed when idle for a too long period.
A background task should clean up unused connections.

The maximum allowed number of parallel connections should be bigger than tps_ x avgTime**.
_tps = expected number of transactions per second and
**avgTime = average execution time for a transaction (request + response)

Certificate

Our company will supply a client certificate to use for client-authentication when the ssl connection is set up. There are different certificates for test and production environments.
The provided Java KeyStore (jks) certificate needs to be used for the encryption (e.g.
with java -Djavax.net.ssl.trustStore=./complete-ipg-truststore.jks)

Please use the following URL for your tests: https://test3.ipg-online.com/epas/v1
The URLs to fiserv's and other (higher) test and productive environments vary.

Timers

For the integration with physical terminals, web shops or integrated cash registers the timeouts of all systems involved in the solution need to be synchronized. The timeout windows for the "consumer devices" need to be longer than the timeouts of the "backend switches".

(Diagramm: simplied system view of timeouts)