API Request/Response Messages
Building a SOAP Request Message
After building your transaction in XML, a SOAP request message describing the Web Service operation call, you wish to perform, has to be created. That means while the XML-encoded transaction you have established as described in the previous chapter represents the operation argument, the SOAP request message encodes the actual operation call.
Building such a SOAP request message is a rather straightforward task. The complete SOAP message wrapping the XML-Sale-transaction looks as follows:
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header />
<SOAP-ENV:Body>
<ipgapi:IPGApiOrderRequest
xmlns:v1="http://ipg-online.com/ipgapi/schemas/v1"
xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi">
<v1:Transaction>
<v1:CreditCardTxType>
<v1:Type>sale</v1:Type>
</v1:CreditCardTxType>
<v1:CreditCardData>
<v1:CardNumber>4111********1111</v1:CardNumber>
<v1:ExpMonth>12</v1:ExpMonth>
<v1:ExpYear>27</v1:ExpYear>
</v1:CreditCardData>
<v1:Payment>
<v1:ChargeTotal>19.00</v1:ChargeTotal>
<v1:Currency>978</v1:Currency>
</v1:Payment>
</v1:Transaction>
</ipgapi:IPGApiOrderRequest>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
In short, the SOAP request message contains a SOAP envelope consisting of a header and a body. While no specific header entries are required for calling the Web Service, the SOAP body takes the transaction XML document as sub element as shown above.
Please note, that there are no further requirements for transactions of a type other than Sale. That means the general format of the SOAP request message regardless of the actual transaction type is as follows:
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header />
<SOAP-ENV:Body>
<ipgapi:IPGApiOrderRequest
xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi"
xmlns:v1="http://ipg-online.com/ipgapi/schemas/v1">
<v1:Transaction>
<!-- transaction content -->
</v1:Transaction>
</ipgapi:IPGApiOrderRequest>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Finally, you may have noticed that there are no specific entries describing which Web Service operation to call. In fact, the Gateway automatically maps the ipgapi:IPGApiOrderRequest element to the corresponding Web Service operation.
Reading the SOAP Response Message
The SOAP response message may be understood as the Web Service operation result. Hence, processing the SOAP request message may have either resulted in a SOAP response message in the success case (i.e. the return parameter) or a SOAP fault message in case of a failure (i.e. the thrown exception). Both SOAP message types are contained in the body of the HTTP response message.
SOAP Response Message
A SOAP response message is received as the result to the credit card processor (started by the Gateway) having approved your transaction. It always has the following scheme:
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header />
<SOAP-ENV:Body>
<ipgapi:IPGApiOrderResponse
xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi">
<!-- transaction result -->
</ipgapi:IPGApiOrderResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
If you have send an Action, you get an ipgapi:IPGApiActionResponse.
Again, no headers are defined. The SOAP body contains the actual transaction result contained in the ipgapi:IPGApiOrderResponse or ipgapi:IPGApiOrderRequest element. Its sub elements and their meanings are presented in the next chapter. However, in order to provide a quick example, an approved Sale transaction is wrapped in a SOAP message similar to the following example:
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header />
<SOAP-ENV:Body>
<ipgapi:IPGApiOrderResponse
xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi">
<ipgapi:CommercialServiceProvider>
BNLP
</ipgapi:CommercialServiceProvider>
<ipgapi:TransactionTime>
1192111687392
</ipgapi:TransactionTime>
<ipgapi:ProcessorReferenceNumber>
3105
</ipgapi:ProcessorReferenceNumber>
<ipgapi:ProcessorResponseMessage>
Function performed error-free
</ipgapi:ProcessorResponseMessage>
<ipgapi:ErrorMessage />
<ipgapi:OrderId>
62e3b5df-2911-4e89-8356-1e49302b1807
</ipgapi:OrderId>
<ipgapi:ApprovalCode>
Y:440368:0000057177:PPXM:0043364291
</ipgapi:ApprovalCode>
<ipgapi:AVSResponse>PPX</ipgapi:AVSResponse>
<ipgapi:TDate>1192140473</ipgapi:TDate>
<ipgapi:TransactionResult>
APPROVED
</ipgapi:TransactionResult>
<ipgapi:TerminalID>123456</ipgapi:TerminalID>
<ipgapi:ProcessorResponseCode>
00
</ipgapi:ProcessorResponseCode>
<ipgapi:ProcessorApprovalCode>
440368
</ipgapi:ProcessorApprovalCode>
<ipgapi:ProcessorReceiptNumber>
4291
</ipgapi:ProcessorReceiptNumber>
<ipgapi:ProcessorTraceNumber>
004336
</ipgapi:ProcessorTraceNumber>
</ipgapi:IPGApiOrderResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
SOAP Fault Message
In general, a SOAP fault message returned by the Web Service API has the following format:
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header />
<SOAP-ENV:Body>
<SOAP-ENV:Fault>
<faultcode>SOAP-ENV:Client</faultcode>
<faultstring xml:lang="en-US">
<!-- fault message -->
</faultstring>
<detail>
<!-- fault message -->
</detail>
</SOAP-ENV:Fault>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Basically, the faultstring element carries the fault type. According to the fault type, the other elements are set. Note that not all of the above shown elements have to occur within the SOAP-ENV:Fault element. Which elements exist for which fault type is described in the upcoming sections.
SOAP-ENV:Server
Internal Exception
In general, this fault type indicates that the Web Service has failed to process your transaction due to an internal system error.
If you receive this as response, please contact our support team to resolve the problem.
An InternalException always looks like the example below:
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header />
<SOAP-ENV:Body>
<SOAP-ENV:Fault>
<faultcode>SOAP-ENV:Server</faultcode>
<faultstring xml:lang="en-US">
unexpected error
</faultstring>
</SOAP-ENV:Fault>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
The SOAP fault message elements – relative to the SOAP-ENV:Envelope/SOAP-ENV:Body/SOAPENV:Fault element – are set as follows:
| Path/Name | XML Schema type | Description |
|---|---|---|
faultcode | xs:string | This element is always set to SOAP-ENV:Server, indicating that the fault cause is due to the system underlying the API having failed. |
faultstring | xs:string | This element always carries the following fault string: unexpected error |
SOAP-ENV:Client
MerchantException
This fault type occurs if the Gateway can trace back the error to your store having passed incorrect information.
This may have one of the following reasons:
- Your store is registered as being closed. In case you will receive this information despite your
store being registered as open, please contact support. - The store ID / user ID combination you have provided for HTTPS authorization is syntactically
incorrect. - The XML does not match the schema.
A MerchantException always looks as shown below:
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header />
<SOAP-ENV:Body>
<SOAP-ENV:Fault>
<faultcode>SOAP-ENV:Client</faultcode>
<faultstring xml:lang="en-US">
MerchantException
</faultstring>
<detail>
<!-- detailed explanation. -->
</detail>
</SOAP-ENV:Fault>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
The SOAP fault message elements – relative to the SOAP-ENV:Envelope/SOAP-ENV:Body/SOAPENV:Fault element – are set as follows:
| Path/Name | XML Schema type | Description |
|---|---|---|
faultcode | xs:string | This element is always set to SOAP-ENV:Client |
faultstring | xs:string | This element is always set to MerchantException |
detail/reason | xs:string | Minimum one reason |
See section Troubleshooting: Merchant Exceptions for detailed analysis of errors.(!)
Processing Exception
A fault of this type is raised whenever the Gateway has detected an error while processing your transaction.
The difference to the other fault types is that the transaction passed the check against the xsd.
A ProcessingException always looks as shown below:
<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header />
<SOAP-ENV:Body>
<SOAP-ENV:Fault>
<faultcode>SOAP-ENV:Client</faultcode>
<faultstring xml:lang="en-US">
ProcessingException: Processing the request
resulted in an error - see SOAP details for more
information
</faultstring>
<detail>
<ipgapi:IPGApiOrderResponse
xmlns:ipgapi="https://ipg-online.com/ipgapi/schemes/ipgapi">
<ipgapi:CommercialServiceProvider>
BNLP
</ipgapi:CommercialServiceProvider>
<ipgapi:TransactionTime>
1192111156423
</ipgapi:TransactionTime>
<ipgapi:ProcessorReferenceNumber />
<ipgapi:ProcessorResponseMessage>
Card expiry date exceeded
</ipgapi:ProcessorResponseMessage>
<ipgapi:ErrorMessage>
SGS-000033: Card expiry date exceeded
</ipgapi:ErrorMessage>
<ipgapi:OrderId>
62e3b5df-2911-4e89-8356-1e49302b1807
</ipgapi:OrderId>
<ipgapi:ApprovalCode />
<ipgapi:AVSResponse />
<ipgapi:TDate>1192139943</ipgapi:TDate>
<ipgapi:TransactionResult>
FAILED
</ipgapi:TransactionResult>
<ipgapi:TerminalID>123456</ipgapi:TerminalID>
<ipgapi:ProcessorResponseCode/>
<ipgapi:ProcessorApprovalCode />
<ipgapi:ProcessorReceiptNumber />
<ipgapi:ProcessorTraceNumber />
</ipgapi:IPGApiOrderResponse>
</detail>
</SOAP-ENV:Fault>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
The SOAP fault message elements – relative to the SOAP-ENV:Envelope/SOAP-ENV:Body/SOAPENV:Fault element – are set as described below:
| Path/Name | XML Schema type | Description |
|---|---|---|
faultcode | xs:string | This element is always set to SOAP-ENV:Client, indicating that the fault cause is likely to be found in invalid transaction data having been passed. |
faultstring | xs:string | This element always carries the following fault string: ProcessingException |
detail/ ipgapi:IPGApiOrderResponse | Composite element | This element contains the error. Since there are numerous causes for raising such an exception, the next chapter will give an overview by explaining the data contained in this element. |
See section Troubleshooting: Processing Exceptions
Updated about 2 months ago
