This is a technical post provided as advice to server administrators having issues with the HSBC payment gateway system.

HSBC have recently updated the SSL certificates on their payment gateway system. However it seems they did not provide the intermediate certificates for the certificate authority they used. This leaves the job of updating the CA bundles up to HSBC’s clients. The following advice refers to resolving the issue on a Linux server.

Step 1 – Check the problem is definitely related to an SSL Certificate mismatch

To do this, it is best to simply request the main secure-epayment API via curl. Running the following command will suffice.

curl https://www.secure-epayments.apixml.hsbc.com

If this issue is present, you will likely see a message such as the one below. If you do not see this message or one similar, the issue is likely to be unrelated and we recommend you contact HSBC’s epayments support line to resolve the issue.

 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.

Step 2 – Update the CA bundle on your server

Obviously it is possible to remove the verification of the SSL certificate, but this is heavily not recommended due to potential negative security implications. To update the CA bundle file from the curl website, use the following commands. Note that may have to adjust to certs path mentioned to conform to the distribution and configuration of your operating system. Also, it is recommend to back up any existing ca-bundle file and any related configuration.

 cd /etc/pki/tls/certs/
 wget http://curl.haxx.se/ca/cacert.pem
 mv cacert.pem ca-bundle.crt

The file available from the CURL site shown above is generated weekly from the latest Mozilla certs, so should be reasonably up to date with all existing certificate authorities.

Step 3 – Test the CA bundle update has resolved the issue

This is merely a case of rerunning the curl command from step 1 mentioned previously. If the update has been successful you should now see the following response from HSBC (or similar) indicating a secure connection has been established.

 <?xml version="1.0" encoding="UTF-8"?>
 <EngineDocList>
  <EngineDoc>
   <MessageList>
    <MaxSev DataType="S32">6</MaxSev>
    <Message>
     <AdvisedAction DataType="S32">16</AdvisedAction>
     <Audience DataType="String">Merchant</Audience>
     <Component DataType="String">CcxXmlInput.A</Component>
     <ContextId DataType="String">CcxXmlInput</ContextId>
     <DataState DataType="S32">1</DataState>
     <FileLine DataType="S32">793</FileLine>
     <FileName DataType="String">CcxXmlInstance.cpp</FileName>
     <FileTime DataType="String">13:30:24Jul 14 2009</FileTime>
     <ResourceId DataType="S32">8</ResourceId>
     <Sev DataType="S32">6</Sev>
     <Text DataType="String">The HTTP method received is not valid.  Only POST is accepted.</Text>
    </Message>
   </MessageList>
  </EngineDoc>
 </EngineDocList>

Step 4 – Restart any dependant services

This step may or may not be required depending on your software and/or configuration. You may need to restart any services which are dependent on the updated CA bundle.

For example, the following commands are commonly used to restart the Apache 2 webserver.

/etc/init.d/apache2 restart

/etc/init.d/apache restart

/etc/init.d/httpd restart

I hope this article aids any server administrators currently experiencing issues due to the recent HSBC epayments SSL certificate update.

Feel free to discuss this issue further in the comments section below.

HSBC epayments issues relating to SSL certificate mismatches