Skip to main content
  Sign in

Quick Steps

Labels

UTG

Universal Transaction Gateway

ART10191

Unable to Process Transactions

MID

POS

Still Have Questions? Submit a Request

Or Call (888) 857-9751.

Or Call (888) 276-2108.

General Universal Transaction Gateway Communication Troubleshooting

Timothy Hughes
  • Updated

Description: There are many different communication lines that are open during a transaction and regardless of the make, model, or communication method; the Universal Transaction Gateway (UTG) handles all PIN Pad hardware devices with the same workflow.  

 

Depending on when an "error" or "issue" is encountered, this changes the scope of troubleshooting you need to perform. This article reviews the UTG Processing Flow and the types of issues that can be encountered in each step. 

flow.jpg

  1. The Interface sends a message with an API Terminal ID (API TID), indicating it is ready to process a customer's payment and to wake the hardware device of capture.
  2. The UTG receives the wake-up message and forwards the wake-up request to the Hardware Device (or UTG Stub), and activates the requested PIN Pad assigned to that API TID.
  3. The PIN Pad collects the customer's payment details and performs any other requested functions regarding the sale.
  4. The device forwards the information to the UTG (Or UTG Stub) and then it is forwarded to Lighthouse Transaction Manager (LTM).
  5. Lighthouse Transaction Manager (LTM) forwards this request to the properties processor who then sends back an approved or declined response to Lighthouse Transaction Manager (LTM), who subsequently sends the response back to the UTG, Interface, and PIN device.

Types of Issues found on line 1 (Interface to UTG) 

Issues and errors on this line indicate that the Interface can't send data to the Universal Transaction Gateway. This is typically due to either Invalid configuration between the Interface and Universal Transaction Gateway, or local Networking issues. 

  • Invalid configuration of the Interface software.
  • Invalid configuration of the Universal Transaction Gateway.
  • Universal Transaction Gateway Service or Stand Alone is not running.
  • Network Permission or User Policy Changes.

Types of Issues found on line 2 - 3 (UTG to UTG Stub or PIN-Device) 

Issues on this line typically indicate information regarding device/terminal setup has changed or is blocked, and the UTG cannot reach the device. Errors that occur during this step will return a Shift4 Error Text and Code and should be searchable in our Knowledge Base. 

  • Invalid configuration of the Device Hardware, Windows OS, UTG Stub, or Universal Transaction Gateway.
  • UTG Stub Service or Stand Alone is not running.
  • Network Permission or User Policy Changes.
  • Bad device cables or faulty USB, Serial, or Ethernet Ports.
  • Faulty hardware devices

Types of Issues found on line 4 (UTG to LTM)

Issues on this line typically indicate we cannot reach Lighthouse Transaction Manager (LTM). This is most typically caused by a lack of internet or privileges on the local network. Errors that occur during this step will return a Shift4 Error Text and Code and should be searchable in our Knowledge Base. 

  • Merchant Internet connection Is down or limited.
  • Invalid device hardware encryption in use.
  • Outbound Network Permission or Policy Changes.
  • Invalid hardware configuration in Lighthouse Transaction Manager (LTM).
  • Invalid Shift4 Merchant Account operation or configuration.

Types of Issues found on line 5 (LTM to Processor)

Issues on this line typically indicate we cannot reach the processor or are running into a particular issue with the card or card type in question. (You should identify if this only affects one or all card processing.)

Processing Tests should be performed in Lighthouse Transaction Manager to validate if this is an issue at the processor level, or if this is an issue with how the transaction is being sent. Processor issues should return Error texts that are searchable in our Knowledge Base. If nothing is found, the processor should be brought in to define the error being received. 

  • Merchant processor network is unavailable or under maintenance.
  • Invalid merchant account operation or configuration. 
  • The merchant processing account was closed or frozen by the processor.

 

Error Codes 

Error Codes are identifiers for known issues and limitations, but from time to time you will run into issues that do not provide error codes or context. Should you run into these issues, there is a step-by-step process to diagnosing the issue outlined below

For known error conditions, our Knowledge Base should be the first stop for troubleshooting.

  1. Try and identify any unique verbiage or numerical error code within the supplied error message.
  2. Search our Knowledge Base for an existing article covering your error.
    • Do not search for words like "The, a, or error," and do not use full sentences. Stick to searching for a single unique word or numerical code. This provides more tailored results.
      • If you have located an article that is in reference to your issue, follow that article to work on the issue.
      • If encountering an undocumented error, we will need to identify where the transaction is running into a problem; see the sections below this one to define the issue.

UTG Interface Communication Troubleshooting

Undefined Issue With Processing:

In any situation where you are unable to identify the issue and are troubleshooting the inability to process transactions, follow the process outlined below to diagnose on which line the communication is failing.

It would be best if you started the UTG in Stand-Alone Mode. This is a diagnostic feature of the UTG software. You will need to stop the current instance of the Universal Transaction Gateway (UTG) services by following, Starting/Stopping a service in Windows including UTG Service, UTG Stub, and Shift4 Bridge.  Once stopped, startup the UTG as Stand-Alone Mode. Refer to Start or Stop Stand-Alone Mode for UTG. 

Once open, check the Global Status of the UTG Standalone to identify if the issue is occurring between the Local Network or The Shift4 Datacenter.

The Global Status section gives you detailed information regarding the UTG’s communication status to the Shift4 data center and the UTG’s offline procedures. This section is enabled by default and is highlighted green on the UTG Stand Alone.

01.png

When starting the UTG Stand Alone, a message of WaitKeyPage, Connection Needed no connection, KeyPage Required KeyPage not available, Offline Key Okay, KeyPage not available, or No Failures will display in this section. Wait a few minutes, and the status should change to one of the following.

 

Ready No Failures

02.png

 

Once the UTG is able to establish a connection to the data center, the message will change to “Ready No Failures” If the message shows 'Ready," you should quickly scan to see if another section of the Stand Alone is highlighted in RED. 

Errors on RED lines should be searched in our knowledge base. 

Common Examples:

  • [Thread Name] Halted Terminated - The assigned IP and TCP\IP Port can't be reached on the network.
    • Possible IP network schema change or misconfiguration. The UTG, PC, and  Interface network assignment configuration should be reviewed for discrepancies.
  • [Thread Name] WASD Listen Socket Bind Failed - The assigned TCP\IP Port is already bound or blocked on the network.
  • [Thread Name] Listen Bind Failed WSAEADDRNOTAVAIL -  The assigned IP is already bound or blocked on the network.
        • If it responds while the PC is off, this means another PC on the network stole this PC's IP assignment. IT will need to resolve Network IP Reservations to ensure this is uniquely assigned to the UTG PC.
        • If no response, turn the PC back on and try another Ping Test to ensure the IP is allowed to communicate on the network. Again if failing the property IT will need to be involved to validate the IP is unrestricted on the network.

If encountering an undocumented error we will need to diagnose the line of communication in question. 

Pick One:

  1. I can process with the UTG Stand Alone Open
    • You should identify if this only required a restart or if the UTG Service may be blocked by Window's permissions.
    • If you are able to process after starting the service, the UTG may just have needed to be refreshed.
  1. I am now encountering an Error Condition.
    • Search the error condition in our Knowledge Base for issue resolution.
  1. I still can't process with the UTG Stand Alone open. 
    • Typically if the UTG Standalone shows no errors or conditions but transaction processing is not occurring, this could be due to a misconfiguration of the Interface software or device hardware.
    • You should get the Interface provider conferenced in so we can review the setup and communication details between the two systems.
    • Hardware should only be reviewed if this is only occurring after card insert or swipe. If activation isn't occurring, the API TID assignment in the interface should be reviewed.

Offline

03.png

If an error occurred during connection, the UTG would go into an Offline state. Typically Offline means the UTG is experiencing an issue communicating inbound\outbound to the Shift4 Datacenter. So details regarding the network\internet should be reviewed.

  1. Validate the property has Internet Service. 
    • Validate this by opening a website that is not in the browser(s) history or is not commonly visited. (EX: purple.com)
    • If no connection, reach out to the Internet Service Provider (ISP) or IT department to diagnose internet connectivity.
  1. Check the Servers assigned IP Address to ensure this has not changed or been reassigned.
    • You can validate the previously configured IP Address by accessing the UTG Tune-Up in read-only mode from the Stand Alone screen.

Shift4_UniversalTransactionGateway_Header.jpg

    • This IP detail will be configured in the Express Tab details or assigned to the API Interface config directly. 
    • You can validate the computer's IP Address assignment by performing an ipconfig in windows. How To Run ipconfig To Check For A Static IP Address.
    • If the value configured in the UTG doesn't match what the PC shows in its network settings, the IP has changed and should be reverted back to the previous IP by IT to restore communication.
      • This setup can be reconfigured for the new IP schema if needed; however, you will need to inform your Point of Sale (POS) or Property Management Software (PMS) provider to update the system with this new IP Address detail. In addition, if you are using communication converters such as the Shift4 Bridge, you will need to update this detail as well.
  1. Validate the TCP\IP Ports 26880 and 26881 are open on the network firewall (Outbound.)
    • The Shift4 Probe can be run to test these ports on the network.
    •  Navigate to:
      • Start > All Programs > Shift4 Payments > S4 Probe
      • Start > All Apps > Shift4 Payments > S4 Probe
    • Once open run the probe using Normal Route and select Test.
    • The S4 Probe will scan the network, and If the probe shows failure at the end of this scan, IT will need to add exceptions to the network firewall\router to allow communication for outbound communication on these ports.
    • Scans can be as quick as 5 minutes to as slow as 20 minutes, depending on the network connection state.
  1. Validate the UTG is listed as a service exception within the Windows Firewall and Anti-Virus\Malware.
  1. Should you still be having issues after this step please contact the Shift4 Support Department so the setup and connection details can be reviewed.

PIN Pad Troubleshooting

Issue: Nothing Happens

The issue of having nothing occurring after a processing request does not provide much detail in terms of troubleshooting. To diagnose where the disconnection is or to try to get to a workable error condition, you should do the following:

  • Test a transaction in the interface advising of the steps you are taking. Also, determine if the interface has a specific button/option to enable the card reader.
  • If prompting, after making a special/different selection, see if the card will go through. If an error should present itself, you can then reference the Knowledge Base on the error received.
  • If failing to validate the device state in the UTG Stand Alone or UTG Stub Stand Alone, a guide to reviewing the Stand Alone applications can be found here: Reading The UTG (v2) Stand Alone.
    • If the device status shows Idle/Waiting on the UTG Stand Alone or if the UTG Stub Stand Alone shows Process, find out if the device will respond to commands from the Universal Transaction Gateway.
    • If yes, then it is likely that the interface is not making the correct API call to the UTG software for device activation. 
      • The interface provider should be contacted to validate that you have PIN Pads enabled on your terminal and validate that you have the appropriate API Terminal ID (API TID) assigned in your software for device activation.
    • If another state in Stand Alone, the device could be configured improperly or disconnected.

Issue: Freezing

Lock-ups and freezing typically do not result in error codes and are mostly the result of software compatibility issues and very rarely hardware failure. To diagnose what should be done review the following steps:

 Identify if the PIN pad is freezing or the interface screen is freezing.

  1. If the freeze is occurring on the interface, try to finish the transaction on the device. Sometimes, the interface has no identifying information on the screen, it may be necessary to wait for card details from the device that appears frozen when it is actually listening. If still frozen after card input, get the interface involved to research why your system is freezing.
  2. If the freeze is occurring on the PIN Pad, test a transaction, noting the steps being taken. Identify after what action on the device the freeze is occurring (e.g., Amount OK, swipe/dip/contactless, PIN entry, Signature Capture, etc.) or if it is only affecting a particular card type (e.g., debit/credit, VS, AX, MC, NS, etc.) and try the following:
    1. Update the Universal Transaction Gateway. See How to Manually Update the Universal Transaction Gateway (UTG).
    2. Update device firmware and forms to clear out any possible bad files or to apply newer compatibility patches.
    3. Check the physical device connectors, as sometimes a loose or damaged cable can cause freezing to occur. It should be noted that cabling is different, based on the type of device and the communication method in use. So you may have to check multiple cords, depending on the setup.

Issue: Hardware Functions

If all of the previous have failed, we may need to consider this a hardware issue.

Hardware issues can be broken down into two categories: functionality issues and defects.

Functionality issues can be described as the inability to perform certain functions such as manual entry, EMV, or contactless. Typically, most functionality issues can be resolved by enabling and disabling a setting. It is just a matter of knowing where this can be enabled. Other times, this can be achieved through updating the device and UTG software.

  • Update the Universal Transaction Gateway. See How to Manually Update the Universal Transaction Gateway (UTG).
  • Update device firmware and forms to clear out any possible bad files or to apply newer compatibility patches. 
  • To update the device firmware or forms, see Updating Ingenico Telium Device Firmware & Forms or Updating Verifone MX Device Firmware & Forms.
  • To validate if something is an enabled feature see the below: 
    • Enable Manual Entry: This is controlled within the Universal Transaction Gateway device thread.
    • Enable Contactless: This is controlled within The Universal Transaction Gateway device thread.
    • Enable EMV: This is controlled within Lighthouse Transaction Manager.
    • Enable Debit/Credit Selection: This is controlled within Lighthouse Transaction Manager.
    • Signature Capture: This NOT a setting that Shift4 controls. The interface making the request to the UTG sends a set of API options to determine if a signature is needed for this transaction. If changes are needed to this capture process, then the interface should be contacted to see if this can be changed on the device wake request.

Defects tend to prevent the device from moving past a certain state or prevent input to the device. Examples include:

  • Power issues
  • Boot looping
  • Pen/stylus not registering on the screen

While there is little Shift4 can do for a true defect, such as screen failure, we can diagnose if it is the device, cables, or the PC experiencing the issue. To diagnose if something is truly defective, we should perform the following:

  1. Check the device cables for any loose connections or frayed and torn wires. Oftentimes, devices that do not get enough power to function can prevent the device from loading or booting up properly. If available, the cables from a working terminal should be swapped to validate the cabling is not the issue.
  2. If you have a spare, or another working terminal to swap with, swap this device (without cables) with the spare one and identify if the issue follows the device or if it remains at the terminal.
  • If remaining at the terminal, this indicates that the local COM or USB port on the host PC could be bad. You should try changing this with another available port. (If dealing with an Ethernet device, change the network port it's connected to).
  • If the issue follows the device, this is reflecting that the device has something wrong with its hardware and should be replaced. 

Ethernet Note: Due to each device having unique IP addresses, it is possible that if swapping, you will need to reassign the device IP address in the UTG TuneUp to perform this test. 

EMV Note: Due to each device having a unique device serial number, you will need to reassign the device serial numbers in Lighthouse Transaction Manager to perform this test. 

Top