Payment Engine Troubleshooting

1. Receive the error java.net.ConnectException: Connection refused: connect in the browser when submitting a payment.

2. Receive the error javax.net.ssl.SSLHandshakeException: java.security.cert.CertificateException: Couldn't find trusted certificate in the browser when submitting a payment.

3. Receive the error org.xml.sax.SAXParseException: The value of attribute "message" must not contain the '<' character in the browser when submitting a payment.

4. When starting the payment engine, it shuts down with the following error in the DOS screen: Error! The payment engine failed to bind to the listening port. Please determine if the port is already in use before proceeding. Shutting down... The pelog.txt file contains java.net.BindException: Address already in use: JVM_Bind.

5. When starting the payment engine, it shuts down and contains the following error in the pelog.txt: Error reading keystore file, ensure the file exists and configured properly...shutting down. java.io.FileNotFoundException: C:\bea\c2gdomain\applications\Click2GovXX\PaymentEngine\pe.jks (The system cannot find the file specified)

6. The payment engine log file, pelog.txt contains the error java.io.IOException: Keystore was tampered with, or password was incorrect

7. When submitting a payment, it returns with the following error: An error occurred while processing this transaction: java.io.FileNotFoundException: C:\bea\c2gdomain\applications\Click2GovX\PaymentEngine\pe.key (The system cannot find the file specified)

8. When submitting a payment, receive the following error in the browser: An error occurred while processing this transaction: com.hteinc.util.HTEException: An error has occurred while processing your payment. Please contact the system administrator

9. When submitting a payment, receive the following error in the browser: An error occurred while processing this transaction: java.lang.SecurityException: User does not have sufficient privilege to access the requested service

10. When submitting a payment, receive the following error in the browser: An error occurred while processing this transaction: com.hteinc.payment.domain.HTEPaymentParameterException: The tender account number entered is not listed in the test merchant configuration in use. Please contact the system administrator.

11. The console Pre-Batch, Post-Batch, and Settlement date listings are not displaying any data. What's wrong?

12. When clients use a proxy server to dispatch Click2Gov requests, Payment Engine needs the following:

1. The ConnectException may occur for a variety of reasons:
   • The payment engine is not running. Verify the engine is running, and that the client has not started the payment engine, then signed off of the windows account (they must remain signed-in, but can lock the console).

   • The payment engine is running, but the web application and payment engine are not configured to use the same port number.

     Check the PortNumber parameter for the Authorization servlet in the \bea\c2gdomain\applications\Click2GovXX\web\WEB-INF\web.xml file and verify it is configured to connect to the port number the payment engine is listening on. To determine the port number the payment engine is listening on, type status in the DOS window where the payment engine is running and press Enter, or look in the \bea\c2gdomain\applications\Click2GovXX\PaymentEngine\ccpProxy.properties at the Application.PortNumber entry.

2. The SSLHandshakeException may occur for a variety of reasons:
   • The path and\or file name is incorrect in the web app hte.cfg entry PaymentInterface.TrustStore.

     Verify the drive letter is correct, as well as the path and file name. By default, the file should be configured as [InstallDriveLetter]:\bea\c2gdomain\common\pekeys.jks

   • The file pointed to by the PaymentInterface.TrustStore above does not exist.

     The pekeys.jks file is created the first time the C2GKeyTool.bat utility is run. The batch file can be found in \bea\c2gdomain\applications\Click2GovXX\PaymentEngine.

   • The password in the web app hte.cfg entry PaymentInterface.KeyStorePwd is incorrect. Verify the password matches the password used to create the keystore.

     From a DOS prompt, change directory to the common directory and use the keytool to access the keystore

     cd \bea\c2gdomain\common #Comment: You may need to change drive letters first \bea\jdk141_0x\bin\keytool -list -keystore pekeys.jks #Comment: Need to replace 'x' in jdk141_0x # with version installed (i.e. jdk141_05) You will be prompted for a password. Verify the password in the hte.cfg file is correct.

   • The pekeys.jks exists, but the certificate containing the public key for the payment engine is not in the keystore.

     You need to verify the certificate is in the trusted store. Because the certificate is a private certificate and not signed by a recognized CA, we must instruct the web application to trust the certificate using a trust store. It is possible the payment engine's public key and certificate were not added into the web server's trust store. To check this:

     From a DOS prompt, change directory to the common directory and use the keytool to access the keystore

     cd \bea\c2gdomain\common #Comment: You may need to change drive letters first \bea\jdk141_0x\bin\keytool -list -keystore pekeys.jks #Comment: Need to replace 'x' in jdk141_0x # with version installed (i.e. jdk141_05) You will be prompted for a password. After supplying the password, the keytool will list all certificates currently in the keystore. For example,
     
     Next, we need to list the contents of the payment engine's keystore. From a DOS prompt, change directory to the payment engine directory and use the keytool to access the keystore cd \bea\c2gdomain\applications\Click2GovXX\PaymentEngine #Comment: You may need to change drive letters first # Replace 'XX' in Click2GovXX with appropriate app \bea\jdk141_0x\bin\keytool -list -keystore pe.jks #Comment: Need to replace 'x' in jdk141_0x # with version installed (i.e. jdk141_05) You will be prompted for a password. After supplying the password, the keytool will list all certificates currently in the keystore. For example,
     
     Compare the two listings. Verify the certificate from the payment engine listing is contained in the web application common trust store listing. If it is not, the recommended course of action is to delete the pe.jks from the payment engine directory and run the C2GKeyTool.bat from the Payment Engine directory again.

   • You have more than one web application installed that uses a new payment engine, but the web applications are configured to point to different common keystores.

     If you have two or more web apps installed, say BP and CX, that use the new payment engine, they must be configured to point to the same common trusted keystore. This means the hte.cfg files in the cfg directories must refer to the same keystore, [DriveLetter]:\bea\c2gdomain\common\pekeys.jks. If they do not refer to the same keystore, only one application will function correctly because only one keystore can be loaded in the single Java Virtual Machine in which all the web applications run under.

3. The SAXParseException received when submitting a payment typically occurs for the following reasons:
   • Verify the schema documents are in the schema folder.

     The schema documents HTEPayments.xsd and HTEPaymentsTypes.xsd should be located in the directory \bea\c2gdomain\applications\Click2GovXX\web\schema.

   • The ccpProxy.properties in the PaymentEngine directory is not configured correctly. The entry should contain the url where the schema document HTEPayments.xsd is located.

     The entry Application.XML.Validation.Source should look like

     Application.XML.Validation.Source=http(s)://localhost/Click2GovXX/schema/HTEPayments.xsd
   • The Application.XML.Validation.Source entry in the ccpProxy.properties file is not configured for the correct protocol (http or https).

     Verify the schema document can be retrieved using a web browser. Take the url from the Application.XML.Validation.Source entry. If it comes up in the browser and it is configured to use https, you will need to update the Java cacerts file.

     The cacerts file that ships with BEA does not contain the Verisign class 3 public primary root certificate. Download a version that does here. You will need to replace the existing copy in \bea\jdk141_0x\jre\lib\security. After replacing it, you'll need to restart the payment engine for the change to take affect.

4. The BindException that occurs when the payment engine fails to bind to the listening port occurs when the port is already in use.

   To determine if the port is already in use, open a DOS shell and run the netstat command:

   netstat -a | more Look for an entry where the Local Address contains the port number the payment engine is configured to use and the State is LISTENING. If you find an entry in the netstat listing, the port is already in use.

   If the port is in use, wait a few minutes and try starting the payment engine again. Because of the way TCP is designed, it is possible the port is no longer in use but has not been completely shut down. If after a few minutes it is still in use, it will probably be necessary to configure the payment engine and web application to use a different port number.

5. The payment engine will shutdown if it cannot read the Java keystore that contains its SSL encryption information. Verify the Application.KeyStore.Name points to the location of the pe.jks and verify the file exists.

6. If the payment engine is configured with an incorrect keystore password, it will result in an IOException when it starts.

   Verify the Application.KeyStore.Password contains the correct password.

7. This message is received when the payment engine is not configured to correctly locate its encryption key, by default named pe.key and kept in the payment engine directory.

   Verify the Key entry in the file \bea\c2gdomain\applications\Click2GovXX\PaymentEngine\hte.cfg contains the correct path to the encryption file. Also verify the key file exists. If the file does not exist, run the batch file genencryptkey.bat in the PaymentEngine directory. If a change is made, you must restart the payment engine.

8. This message is often caused when the payment and\or web application are not configured with the same merchant information. Another indicator is the following message in the pelog.txt file: com.hteinc.payment.domain.HTEMerchantConfig.checkPermission.

   To resolve this issue, check that the web application's hte.cfg file is configured to use a merchant entry in that is listed in the payment engine's Merchants.xml file. To check this, open the web application's \bea\c2gdomain\applications\Click2GovXX\cfg\hte.cfg file to determine the PaymentInterface.MerchantId value. Next, open the \bea\c2gdomain\applications\Click2GovXX\PaymentEngine\xml\Merchants.xml file and verify the merchant id listed in the hte.cfg exists in the Merchants.xml.

   For more information, see merchant configuration documentation for more information.

9. This message is often caused when the payment and\or web application are not configured with the correct merchant access user id and\or password.

   To resolve this issue, check that the web application's hte.cfg file is configured to use a merchant user id and pasword listed in a <ServiceAccess> in the Merchants.xml file. To check this, open the web application's \bea\c2gdomain\applications\Click2GovXX\cfg\hte.cfg file to determine the PaymentInterface.MerchantUid and PaymentInterface.MerchantPwd values. Next, open the \bea\c2gdomain\applications\Click2GovXX\PaymentEngine\xml\Merchants.xml file and verify a <ServiceAccess> exists for the merchant account that is to be used, and it is configured with the same user id and password as specified in the hte.cfg file.

   For more information, see merchant configuration documentation.

10. This message is caused when the merchant configuration in use is configured for testing, but the credit card entered by the user is not listed as a <TestTender> in the Merchants.xml file.

    To resolve this issue, open the Merchants.xml file in the PaymentEngine's xml directory and verify the <Merchant> configuration in use contains a <TestTender> with the credit card number the user is testing with. If it is not listed, create a new <TestTender> with the card number and restart the payment engine.

    For more information, see merchant configuration documentation.

11. If the batch reports aren't displaying any data, the most likely problem is a configuration issue. The report data is retrieved using stored procedures K1APII01, K1APII02, and K1APII03
    • Verify the procedures are registered. They should be registered in HTEGPL or HTEPGM depending if they are Naviline clients. Use the SQL: SELECT * FROM SYSROUTINE WHERE SPECIFIC_NAME LIKE 'K1APII%'
    • Verify the procedures are registered to READ SQL. Use the above SQL, then check the column SQL_DATA_ACCESS. If the column is listed as CONTAINS, the registration programs K1CSP and K1CSP1 need to be sent again, compiled and run.
    • Verify the library C2GXXPMT is contained in the HT005AP entry for the application.

      Each application should have an entry added to HT005AP with the AppCode being the 'K' code for the application. The library C2GXXPMT should be in the list.

      Verify the AppCode entry in the hte.cfg in the web application cfg folder uses the K code.

12. Using Notepad, open Vitalnet.bat or Verisign.bat, and append the following lines right after the java launcher command (java.exe):
    -DproxySet=true -Dhttps.proxyHost=[proxy_host_ip_address] -Dhttps.proxyPort=443
    Example:
    
    call setpath.bat
    java -DproxySet=true -Dhttps.proxyHost=123.456.789.0 -Dhttps.proxyPort=443 -Djava.protocol.handler.pkgs=com.sun.net.ssl.internal.www.protocol -Dcom.hteinc.application.properties=ccpProxy.properties -Dcom.hteinc.processor.properties=vitalnet.properties -Dcom.hteinc.payment.factory=com.hteinc.payment.domain.vitalnet.HTEVitalNetPaymentServiceFactory -classpath .\class;.\jar\jnet.jar;.\jar\jcert.jar;.\jar\jsse.jar;.\jar\jt400.jar;.\jar\sax.jar;.\jar\dom.jar;.\jar\xercesImpl.jar;.\jar\jaxp-api.jar;.\jar\mail.jar;.\jar\mailapi.jar;.\jar\activation.jar; com.hteinc.payment.HTEPaymentEngine