HTTP POST Request/ Response

Building an HTTPS POST request is a task you rarely have to do “by hand”. There are plenty of tools and libraries supporting you in the composition of HTTPS requests. Mostly, the required functionality for doing this task is contained in the standard set of libraries coming with the technological environment in which you develop your online store.

Since all of these libraries slightly differ in their usage, no general building process can be described. In order to illustrate the basic concepts, the following chapters will give examples showing how to build a valid HTTPS request in PHP and ASP. In general, the set of parameters you have to provide for building a valid HTTPS request in whatever technology is as follows:

📘

Please note, that the Gateway is using GSLB (Global Server Load Balancing) solution to route traffic to different locations.

By default, DNS returns IP address of a primary datacenter. This may change during planned maintenance or unplanned outage – in such case a different IP is returned, pointing to DR (disaster recovery) location. It is therefore critical, that you respect IP address and TTL returned by DNS. Please consider that while setting up firewalls, proxy whitelists etc.

Doing HTTP communication in PHP is mostly accomplished with the aid of cURL which is shipped both as library and command line tool. In newer PHP versions, cURL is already included as extension which has to be “activated”, thus making the cURL functionality available in any PHP script. While this is a rather straightforward task in case your Web server operates on Microsoft Windows, it might require to compile PHP on Unix/Linux machines. Therefore, you might consider to call the cURL command line tool from your PHP script instead of using the cURL extension. Both variants are considered in the following beginning with the usage of the cURL extension in PHP 5.2.4 running on a Windows machine.

Mostly, activating the cURL extension in PHP 5.2.4 simply requires to uncomment the following line in your php.ini configuration file:

;extension=php_curl.dl

📘

Please note that other PHP versions might require other actions in order to enable cURL support in PHP. Refer to your PHP documentation for more information.

After activating cURL, an HTTP request with the above parameters is set up with the following PHP statements:

<?php
// storing the SOAP message in a variable – note that the plain XML code
// is passed here as string for reasons of simplicity, however, it is 
// certainly a good practice to build the XML e.g. with DOM – furthermore, 
// when using special characters, you should make sure that the XML string 
// gets UTF-8 encoded (which is not done here):
$body = "<SOAP-ENV:Envelope ...>...</SOAP-ENV:Envelope>";
// initializing cURL with the IPG API URL:
$ch = curl_init("https://test.ipg-online.com/ipgapi/services");
// setting the request type to POST:
curl_setopt($ch, CURLOPT_POST, 1);
// setting the content type:
curl_setopt($ch, CURLOPT_HTTPHEADER, array("Content-Type: text/xml"));
// setting the authorization method to BASIC:
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
// supplying your credentials:
curl_setopt($ch, CURLOPT_USERPWD, "WS101._.007:myPW");
// filling the request body with your SOAP message:
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
...
?>

Setting the security options which are necessary for enabling TLS communication will be discussed in the next chapter extending the above script.

For the reasons described above, you might consider using the cURL command line tool instead of the extension. Using the tool does not require any PHP configuration efforts – your PHP script simply has to call the executable with a set of parameters. Since the security settings are postponed to the next chapter, the following script only shows how to set up the standard HTTP parameters, i.e. the script is extended with the TLS parameters in the next chapter.

<?php
// storing the SOAP message in a variable – note that you have to escape
// " and \n, since the latter makes the command line tool fail,
// furthermore note that the plain XML code is passed here as string 
// for reasons of simplicity, however, it is certainly a good practice
// to build the XML e.g. with DOM – finally, when using special 
// characters, you should make sure that the XML string gets UTF-8 encoded
// (which is not done here):
$body = "<SOAP-ENV:Envelope ...>...</SOAP-ENV:Envelope>";
// setting the path to the cURL command line tool – adapt this path to the
// path where you have saved the cURL binaries:
$path = "C:\curl\curl.exe";
// setting the IPG API URL:
$apiUrl = " https://test.ipg-online.com/ipgapi/services";
// setting the content type:
$contentType = " --header \"Content-Type: text/xml\"";
// setting the authorization method to BASIC and supplying
// your credentials:
$user = " --basic --user WS101._.007:myPW";
// setting the request body with your SOAP message – this automatically
// marks the request as POST:
$data = " --data \"".$body."\"".
...
?>

There are multiple ways of building an HTTP request in ASP. However, in the following, the usage of WinHTTP 5.1 is described as it ships with Windows Server 2003 and Windows XP SP2. Furthermore, only a few lines of code are required in order to set up a valid HTTP request. Note that the following code fragment is written in JavaScript. Using VB Script instead does not fundamentally change the shown statements.

<%@ language="javascript"%>
<html>...<body>
<%
// storing the SOAP message in a variable – note that the plain XML code
// is passed here as string for reasons of simplicity, however, it is 
// certainly a good practice to build the XML e.g. with DOM – furthermore, 
// when using special characters, you should make sure that the XML string 
// gets UTF-8 encoded (which is not done here):
var body = "<SOAP-ENV:Envelope ...>...</SOAP-ENV:Envelope>";
// constructing the request object:
var request = Server.createObject("WinHttp.WinHttpRequest.5.1");
// initializing the request object with the HTTP method POST
// and the IPG API URL:
request.open("POST", "https://test.ipg-online.com/ipgapi/services");
// setting the content type:
request.setRequestHeader("Content-Type", "text/xml");
// setting the credentials:
request.setCredentials("WS10036000750._.1001", "testinger", 0);
...
%>
</body></html>

📘

Note that the above script is extended in the next chapter by setting the security options which are required for establishing the TLS channel.

The actual communication with the Web Service API takes place when sending the HTTPS request and waiting for a response. Again, how this is done depends on the technology you are using. Most HTTP libraries fully cover the underlying communication details and reduce this process to a single operation call returning the HTTP response as result object. In any case, the parameters which are required for successfully performing an HTTP POST request over
TLS and receiving the response (carrying a 200 HTTP status code) have been described in the previous two chapters. Setting invalid or incorrect parameters results in the web server running the Web Service API to return a standard HTTP error code in the HTTP header of the response or sending an TLS failure. Their meanings can be found in any HTTP/TLS guide.

📘

Please note, that only TLS secured communication over standard HTTPS TCP port 443 is accepted.

However, there is one important exception: In case the HTTP parameters you have provided are correct, but the Web Service has failed to process your transaction due to an incorrect value contained in the SOAP request message (e.g. an invalid credit card number), a SOAP exception is thrown and transferred in the body of an HTTP response carrying the error code 500. Details about the exception cause are provided in the SOAP fault message which is described in the context of the next chapter. In order to complete the PHP and ASP scripts, built gradually in the previous chapters, the following two chapters will provide the statements necessary for doing an HTTP call using these technologies.

Again, the distinction between the PHP cURL extension and the cURL command line tool is made in the following:

The PHP script using the cURL extension is finally completed by doing the call with the statements shown below. Note that the HTTP call returns a SOAP response or fault message in the HTTP response body.

<?php
...
// telling cURL to return the HTTP response body as operation result
// value when calling curl_exec:
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
// calling cURL and saving the SOAP response message in a variable which
// contains a string like "<SOAP-ENV:Envelope ...>...</SOAP-ENV:Envelope>":
$result = curl_exec($ch);
// closing cURL:
curl_close($ch);
?>

Doing the HTTP call with the cURL command line tool simply requires completing the command line statement and executing the external tool. However, reading the HTTP response is more complicated as the PHP exec command saves each line returned by an external program as one element of an array. Concatenating all elements of that array results in the SOAP response or fault message which has been returned in the HTTP response body. The following statements handle the HTTP call and complete the script:

<?php
...
// saving the whole command in one variable:
$curl = $path.
$data.
$contentType.
$user.
$serverCert.
$clientCert.
$clientKey.
$keyPW.
$apiUrl;
// preparing the array containing the lines returned by the cURL
// command line tool:
$returnArray = array();
// performing the HTTP call by executing the cURL command line tool:
exec($curl, $returnArray);
// preparing a variable taking the complete result:
$result = "";
// concatenating the different lines returned by the cURL command
// line tool – this result in the variable $result carrying the entire
// SOAP response message as string:
foreach($returnArray as $item)
$result = $result.$item;
?>

Doing the actual HTTP call with WinHTTP in ASP is limited to one simple operation call taking the SOAP request XML as a parameter. After successfully performing the request a SOAP response or fault message is returned which can be retrieved as a string by accessing the request object’s responseText property. How such a SOAP response message looks like is described in the next chapter. The following statements complete the ASP script:

<%@ language="javascript"%>
<html>...<body>
<%
...
// doing the HTTP call with the SOAP request message as input:
request.send(body);
// saving the SOAP response message in a string variable:
var response = request.responseText;
%>
</body></html>