Troubleshooting

Overview of common errors & explanations

In the following section you can find an overview of common error messages and their possible explanations below (marked in italic).

Merchant Exceptions

1. Empty Message

<detail>
    XML is not wellformed: Premature end of message. 
</detail>

You have sent an absolutely empty message. The message contains neither a soap message nor an IPG API message or any other characters in the http body.

2. Message can't be interpreted

<detail>
    XML is not wellformed: Content is not allowed in prolog. 
</detail>

The message can’t be interpreted as an XML message.

3. End tags are missing

<detail>
    XML is not wellformed: 
    XML document structures must start and end within the same entity. 
</detail>
<detail>
    XML is not wellformed: 
    The element type "SOAP-ENV:Body" must be terminated  
    by the matching end-tag "&lt;/SOAP-ENV:Body&gt;". 
</detail>

Error Message 1: The message starts like an XML message but the end tag of the first open tag is missing.
Error Message 2: To an open internal tag (not the top level tag) the end tag is missing. In this example the end tag </SOAP-ENV:Body> is missing.

4. Not an (correct) XML message

<detail>
    XML is not wellformed: 
    Element type "irgend" must be followed by either attribute specifications, "&gt;" or "/&gt;". 
</detail>

The message isn’t an XML message or a correct XML message. A “>” character is missing for the tag irgend.

5. Value isn't enclosed

<detail>
    XML is not wellformed: 
    Open quote is expected for attribute "xmlns:ns3" 
    associated with an element type "ns3:IPGApiOrderRequest".
</detail>

The value of one attribute isn’t enclosed in quotation marks. In IPG API attributes are only used for the name spaces.

6. Name space “ipgapi” isn’t declared

<detail>
    XML is not wellformed: 
    The prefix "ipgapi" for element "ipgapi:IPGApiOrderRequest" 
    is not bound.
</detail>

To declare a name space use the xmlns prefix. In this case you should take xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi" as attribute in the top level tag of the IPG API message (IPGApiOrderRequest or IPGApiActionRequest).

7. Prefix written in xmln instead of xmlns

<detail>
    XML is not wellformed: 
    The prefix "xmln" for attribute "xmln:ns2" associated 
    with an element type "ns3:IPGApiOrderRequest" is not bound.
</detail>

To declare an own name space, only the predefined name space xmlns allowed. In this case the prefix is written as xmln and not as xmlns.

8. No or incorrectly declared name space(s)

<detail>
    XML is not wellformed: 
    Unable to create envelope from given source 
    because the namespace was not recognized
</detail>

The message could be interpreted as an XML message and the enclosing soap message is correct, but the including IPG API message in the soap body has no name spaces or the name spaces are not declared correctly. The correct name spaces are described in the xsd.

9. Processing instruction not allowed

<detail>
    XML is not wellformed: 
    The processing instruction target matching "[xX][mM][lL]" 
    is not allowed.
</detail>

The whole message must be a correct XML message so that the including IPG API message must not contains the xml declaration .

10. Unexpected characters

<detail>
    Unexpected characters before XML declaration 
</detail>

The XML must start with “<?xml”. Please check, if you send an empty line or another white space character in front of the xml and remove them.

11. XML is not SOAP

<detail>
    XML is not a SOAP message: 
    Unable to create envelope from given source 
    because the root element is not named "Envelope" 
</detail>

The message seems to be a correct XML message but only soap messages are accepted. This message must be enclosed by a soap message.

12. SOAP body tag missing

<detail>
    XML is not a valid SOAP message: 
    Error with the determination of the type. 
    Probably the envelope part is not correct.
</detail>

The soap body tag is missing.

13. Empty SOAP body

<detail>
    Source object passed to ''{0}'' has no contents. 
</detail>

The soap body is empty. The including IPG API message is missing.

14. Tag has no namespace

<detail>
    Included XML is not a valid IPG API message: 
    unsupported top level {namespace}tag "irgendwas" in the soap body. Only one of [ 
    {http://ipg-online.com/ipgapi/schemas/ipgapi}IPGApiActionRequest, 
    {http://ipg-online.com/ipgapi/schemas/ipgapi}IPGApiOrderRequest 
    ] allowed.
</detail>

The first tag in the including IPG API message must be one of IPGApiActionRequest or IPGApiOrderRequest tag and not the tag irgendwas. In this case this tag has no namespace.

15. Wrong name space

<detail>
    Included XML is not a valid IPG API message: 
    unsupported top level {namespace}tag 
    "{http://firstdata.de/ipgapi/schemas/ipgapi}IPGApiOrderRequest" in the soap body. Only one of 
    [ 
    {http://ipg-online.com/ipgapi/schemas/ipgapi}IPGApiActionRequest, 
    {http://ipg-online.com/ipgapi/schemas/ipgapi}IPGApiOrderRequest 
    ] allowed.
</detail>

The top level tag of the included IPG API message no allowed tag. In this case the name space is wrong.

16. Value does not match with declaration in XSD

<detail>
    cvc-pattern-valid: 
    Value '1.234' is not facet-valid with respect to pattern 
    '([1-9]([0-9]{0,12}))?[0-9](\.[0-9]{1,2})?' for type
    '#AnonType_ChargeTotalAmount'
    cvc-type.3.1.3: 
    The value '1.234' of element 'ns3:ChargeTotal' is not valid.
</detail>

The value of a tag does not correspond with the declaration in the xsd. The value has three decimal places but the xsd only allows two.

17. Invalid content

<detail>
    cvc-complex-type.2.4.a: 
    Invalid content was found starting with element 'ns2:ExpYear'. 
    One of '{"http://ipg-online.com/ipgapi/schemas/v1":ExpMonth}' 
    is expected.
</detail>

The occurrences of the tags must be corresponding to the xsd. We recommend to use the tags in the same sequence as they are declared in the xsd. In this case the tag ExpMonth is expected and not ExpYear.

Processing Exceptions

1. Wrong combination of values

<detail>
    <ipgapi:IPGApiOrderResponse 
        xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi">
        <ipgapi:CommercialServiceProvider />
        <ipgapi:TransactionTime>1233656751183</ipgapi:TransactionTime>
        <ipgapi:ProcessorReferenceNumber />
        <ipgapi:ProcessorResponseMessage />
        <ipgapi:ErrorMessage>
            SGS-C: 000003: 
            illegal combination of values for the 3DSecure: 
            (VerificationResponse, PayerAuthenticationResponse, 
            PayerAuthenticationCode) N Y null
        </ipgapi:ErrorMessage>
        <ipgapi:OrderId />
        <ipgapi:ApprovalCode />
        <ipgapi:AVSResponse />
        <ipgapi:TDate />
        <ipgapi:TransactionResult>FAILED</ipgapi:TransactionResult>
        <ipgapi:TerminalID />
        <ipgapi:ProcessorResponseCode />
        <ipgapi:ProcessorApprovalCode />
        <ipgapi:ProcessorReceiptNumber />
        <ipgapi:ProcessorTraceNumber />
    </ipgapi:IPGApiOrderResponse>
</detail>

The combination of the three values VerificationResponse, PayerAuthenticationResponse and AuthenticationValue for 3-D Secure version 1 is wrong.

Allowed combinations are:

Verification-ResponsePayer-Authentication-ResponseAuthenticationValueIPG 3dsecure response codeComments
nullnullnulln/aTransaction will be passed to auth
system without any 3dsecure
information
No MC ECI, Visa ECI = 7
Nnullnull7Cardholder not enrolled
No MC ECI, Visa ECI = 7
NNnull7Cardholder not enrolled
No MC ECI, Visa ECI = 7
Unullnull5Unable to authenticate (DS not
accessible)
No MC ECI, Visa ECI = 7
YAnull4Attempt (ACS cannot tell result of
authentication)
MC ECI = 1, Visa ECI = 6
YAx4Attempt (ACS cannot tell result of
authentication)
MC ECI = 1, Visa ECI = 6
YUnull6Unable to authenticate (ACS not
accessible)
No MC ECI, Visa ECI = 7
YYnull2Auth Success (no CAAV / UCAF)
MC ECI = 2, Visa ECI = 5
YYx1Auth Success
MC ECI = 2, Visa ECI = 5
YNnull3Auth Failure (Signature verification
incorrect) - IPG declines the transaction
( "N:-5101:3D Secure authentication
failed" )
No MC or Visa ECI

Other combinations not listed above will be declined by IPG with a IPG 3dsecure response code of 8 and "N:-5100:Invalid 3D Secure values". XID (created by MPI before sending Verification request) needs to be set for VISA transactions. The payer authentication code x means, that the value is not null.

2. Unsupported transaction

<detail>
    <ipgapi:IPGApiOrderResponse 
        xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi">
        <ipgapi:CommercialServiceProvider />
        <ipgapi:TransactionTime>1233659493267</ipgapi:TransactionTime>
        <ipgapi:ProcessorReferenceNumber />
        <ipgapi:ProcessorResponseMessage />
        <ipgapi:ErrorMessage>
            SGS-005002: 
            The merchant is not setup to support the requested service.
        </ipgapi:ErrorMessage>
        <ipgapi:OrderId>
            IPGAPI-REQUEST-9c555d62-3850-4726-8589-5a2444c98c5d
        </ipgapi:OrderId>
        <ipgapi:ApprovalCode />
        <ipgapi:AVSResponse />
        <ipgapi:TDate />
        <ipgapi:TransactionResult>FAILED</ipgapi:TransactionResult>
        <ipgapi:TerminalID />
        <ipgapi:ProcessorResponseCode />
        <ipgapi:ProcessorApprovalCode />
        <ipgapi:ProcessorReceiptNumber />
        <ipgapi:ProcessorTraceNumber />
    </ipgapi:IPGApiOrderResponse>
</detail>

This is an example with a German Direct Debit transaction, which is not supported for the merchant. If you should receive this result for a transaction type which is included in your agreement, please contact our technical support team.

3. Further transactions blocked with same data

<detail>
    <ipgapi:IPGApiOrderResponse 
        xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi">
        <ipgapi:CommercialServiceProvider />
        <ipgapi:TransactionTime>1233656752933</ipgapi:TransactionTime>
        <ipgapi:ProcessorReferenceNumber />
        <ipgapi:ProcessorResponseMessage />
        <ipgapi:ErrorMessage>
            SGS-005005: Duplicate transaction.
        </ipgapi:ErrorMessage>
        <ipgapi:OrderId>
            IPGAPI-REQUEST-29351d8e-2634-4725-9d93-91b83704e00d
        </ipgapi:OrderId>
        <ipgapi:ApprovalCode />
        <ipgapi:AVSResponse />
        <ipgapi:TDate />
        <ipgapi:TransactionResult>FRAUD</ipgapi:TransactionResult>
        <ipgapi:TerminalID />
        <ipgapi:ProcessorResponseCode />
        <ipgapi:ProcessorApprovalCode />
        <ipgapi:ProcessorReceiptNumber />
        <ipgapi:ProcessorTraceNumber />
    </ipgapi:IPGApiOrderResponse>
</detail>

After a transaction further transactions with the same data blocked are for a configurable time span. See User Guide Virtual Terminal for details about the fraud settings.

4. Unallowed currency

<detail>
    <ipgapi:IPGApiOrderResponse 
        xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi">
        <ipgapi:CommercialServiceProvider />
        <ipgapi:TransactionTime>1233656752308</ipgapi:TransactionTime>
        <ipgapi:ProcessorReferenceNumber />
        <ipgapi:ProcessorResponseMessage />
        <ipgapi:ErrorMessage>
            SGS-005009: 
            The currency is not allowed for this terminal.
        </ipgapi:ErrorMessage>
        <ipgapi:OrderId>
            IPGAPI-REQUEST-a58f6631-eb71-49c8-bbca-23fff53252fc
        </ipgapi:OrderId>
        <ipgapi:ApprovalCode />
        <ipgapi:AVSResponse />
        <ipgapi:TDate />
        <ipgapi:TransactionResult>FAILED</ipgapi:TransactionResult>
        <ipgapi:TerminalID />
        <ipgapi:ProcessorResponseCode />
        <ipgapi:ProcessorApprovalCode />
        <ipgapi:ProcessorReceiptNumber />
        <ipgapi:ProcessorTraceNumber />
    </ipgapi:IPGApiOrderResponse>
</detail>

This is an example with US Dollar, which is no allowed currency for this store.

5. Insufficient number of Terminal IDs

<detail>
    <ipgapi:IPGApiOrderResponse 
        xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi">
        <ipgapi:CommercialServiceProvider />
        <ipgapi:TransactionTime>1234346305732</ipgapi:TransactionTime>
        <ipgapi:ProcessorReferenceNumber />
        <ipgapi:ProcessorResponseMessage />
        <ipgapi:ErrorMessage>
            SGS-032000: Unknown processor error occured.
        </ipgapi:ErrorMessage>
        <ipgapi:OrderId>
            IPGAPI-REQUEST-b3223ee5-156b-4d22-bc3f-910709d59202
        </ipgapi:OrderId>
        <ipgapi:ApprovalCode />
        <ipgapi:AVSResponse />
        <ipgapi:TDate>1234346284</ipgapi:TDate>
        <ipgapi:TransactionResult>DECLINED</ipgapi:TransactionResult>
        <ipgapi:TerminalID />
        <ipgapi:ProcessorResponseCode />
        <ipgapi:ProcessorApprovalCode />
        <ipgapi:ProcessorReceiptNumber />
        <ipgapi:ProcessorTraceNumber />
    </ipgapi:IPGApiOrderResponse>
</detail>

If your transactions are normally executed, one possible explanation is that the number of Terminal IDs assigned to your store are not sufficient for your transaction volume. Please contact our Sales team to order further Terminal IDs for load balancing.

Login error messages when using cURL

1. Keystore and password do not fit

* About to connect() to test.ipg-online.com port 443 (#0)
* Trying 217.73.32.55... connected
* Connected to test.ipg-online.com (217.73.32.55) port 443 (#0)
* unable to set private key file: 'C:\API\config\WS120666668._.1.key' type PEM
* Closing connection #0
curl: (58) unable to set private key file: 'C:\API\config\WS120666668._.1.key' type PEM

Please check if you used the right keystore and password. Check if you used the WS._.1.pem file. If you append .cer to the file name you can open the certificate with a double click. The certificate must be exposed for your store. Please remove the extension .cer after the check.

2. Truststore certificate is wrong

* SSL certificate problem, verify that the CA cert is OK. Details:
error:14090086:SSL routines:SSL3_GET_SERVER_CERTIFICATE:certificate verify failed
* Closing connection #0
curl: (60) SSL certificate problem, verify that the CA cert is OK. Details:
error:14090086:SSL routines:SSL3_GET_SERVER_CERTIFICATE:certificate verify failed
More details here: http://curl.haxx.se/docs/sslcerts.html

📘

cURL performs SSL certificate verification by default, using a "bundle" of Certificate Authority (CA) public keys (CA certs).

The default bundle is named curl-ca-bundle.crt; you can specify an alternate file using the --cacert option. If this HTTPS server uses a certificate signed by a CA represented in the bundle, the certificate verification probably failed due to a problem with the certificate (it might be expired, or the name might not match the domain name in the URL). If you'd like to turn off curl's verification of the certificate, use the -k (or --insecure) option.

Please verify the trustore: Open the file tlstrust.pem and check that one of them matched the root of the server certificate of the Gateway.

3. Wrong password or user

<html>
    <head>
        <title>Apache Tomcat/5.5.20 - Error report</title>
        <style>
<!--
H1 {font-family:Tahoma,Arial,sans-serif;color:white;background-color:#525D76;font-size:22px;} 
H2 {font-family:Tahoma,Arial,sans-serif;color:white;background-color:#525D76;font-size:16px;} 
H3 {font-family:Tahoma,Arial,sans-serif;color:white;background-color:#525D76;font-size:14px;} 
BODY {font-family:Tahoma,Arial,sans-serif;color:black;background-color:white;} 
B {font-family:Tahoma,Arial,sans-serif;color:white;background-color:#525D76;} 
P {font-family:Tahoma,Arial,sans-serif;background:white;color:black;font-size:12px;}
A {color : black;}
A.name {color : black;}
HR {color : #525D76;}
        -->
    </style> 
  </head>
  <body>
    <h1>HTTP Status 401 - </h1>
    <HR size="1" noshade="noshade">
    <p><b>type</b> Status report</p><p><b>message</b> 
        <u></u></p><p><b>description</b>  
        <u>This request requires HTTP authentication ().</u></p>
    <HR size="1" noshade="noshade">
    <h3>Apache Tomcat/5.5.20</h3>
  </body>
</html>

Your certificates are OK and accepted but your password or your user is wrong.

Login error messages when using the Java Client

1. java.ioException: Keystore was tampered with, or password was incorrect

Explanation:

Your keystore password doesn’t fit to the keystore or the truststore password to the truststore. You can check the password with the keytool which is a component of the JDK. You can find it in the bin directory of the JDK. For testing the password call

c:\Programme\Java\jdk1.6.0_07\bin\keytool.exe -list -v -keystore <your keystore or truststore> -storepass <your keystore or truststore password>

2. javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: No trusted certificate found

Explanation:

Your truststore is wrong. You can inspect your truststore with keytool, a component of the JDK. Call:

c:\Programme\Java\jdk1.6.0_07\bin\keytool.exe -list -v -keystore <your truststore> -storepass <your truststore password>

and you must find the issuer Equifax:

OU=Equifax Secure Certificate Authority, O=Equifax, C=US in the output. Check the MD5 and SHA1 values too.

<html>
    <head>
        <title>Apache Tomcat/5.5.20 - Error report</title>
        <style><!--H1 {font-family:Tahoma,Arial,sans-serif;color:white;background-color:#525D76;font-size:22px;} H2 {font-family:Tahoma,Arial,sans-serif;color:white;background-color:#525D76;font-size:16px;} H3 {font-family:Tahoma,Arial,sans-serif;color:white;background-color:#525D76;font-size:14px;} BODY {font-family:Tahoma,Arial,sans-serif;color:black;background-color:white;} B {font-family:Tahoma,Arial,sans-serif;color:white;background-color:#525D76;} P {font-family:Tahoma,Arial,sans-serif;background:white;color:black;font-size:12px;}A {color : black;}A.name {color : black;}HR {color : #525D76;}--></style>
    </head>
    <body>
        <h1>HTTP Status 401 -</h1>
        <HR size="1" noshade="noshade">
        <p>
            <b>type</b>
            Status report
        </p>
        <p>
            <b>message</b>
            <u></u>  
        </p>
        <p>
            <b>description</b>
            <u>This request requires HTTP authentication ().</u>
        </p>
        <HR size="1" noshade="noshade">
        <h3>Apache Tomcat/5.5.20</h3>
    </body>
</html>

Explanation: Your user id or password is wrong.