HSBC API Integration

HSBC have two ways for their payment gateway integration. They are API (Application Programmable Interface) and CPI (Card Payment Interface).The XML API interface does not require the installation of any software provided by HSBC. It was developed as a “Platform Independent Solution”. Choosing the API for card processing means accepting responsibility for meeting all relevant industry card processing standards (e.g. card data security, brand logo usage, data retention) i.e. complying with the PCI DSS standards.

I’ve been working on integrating HSBC’s payment API system with our client’s web site. I faced lots of issues due to lack of proper documentation provided from HSBC .They do provide lots of documents but they are not comprehensive enough and they do miss some key points in the document.

We wanted to implement the HSBC CPI but HSBC provide only 32 bit dll which is an issue as we have a 64 bit app. We spoke with HSBC Technical support and they said they will upgrading to 64bit dll in the future and that they do not support .net development only C Java and com objects. Moreover the CPI document clearly states that the CPI service is not designed for use within a call centre environment, or equivalent. The customer must enter the details themselves in order for you to comply with the terms and conditions of the service.
So anyways after hours of hard work I did manage to implement the API.

I’ll explain the steps involved in API integration

· Gather necessary card and user details from the end user.

· Create a correctly formatted “data document” and populate it with relevant data according to their API.

· Post the XML document to HSBC’s XML API

· Post URL:

· The HSBC API server performs all the necessary calculations and returns the resulting XML document through the same connection.

· Capture the response from HSBC.

To check whether the transaction was successful or not there is a “TransactionStatus” attribute in response from HSBC.
The possible transaction status is as follows:

A = Approved (Transaction was processed and accepted by the authoriser, but is not yet marked as ready for settlement)

C = Captured (Transaction is ready for settlement)

D = Declined (Transaction was declined by the authoriser and it is unlikely that it would receive voice approval. This is also known as a hard decline.)

R = Referred (Transaction was declined by the authoriser, but it might receive voice approval. This is also known as a soft decline.)

V = Voided (Transaction has been voided.)
Depending on the transaction status you can respond at your end.

Some key points are as follows:
For Test transactions set “Mode” attribute to “Y”and for live transactions set “Mode” attripute to “P”.
The “Total” field specifies the amount to be charged. The total must be specified in terms of the smallest unit for that Currency. For a UK Sterling transaction all money amounts must be specified in pence. As an Example for £35.56 it should be like “3556”.
That’s all from me for now.

In my next post I’ll be detailing about the implementation of Payer Authentication Services(PAS) which allows us to participate in Verified by Visa and MasterCard SecureCode programs (via a separate interface / integration) to benefit from the schemes’ protection when processing Internet transactions.

By James Ellins