HSBC payment API method (Version 0.1.0)

28 Aug

HSBC Corporation generates some tricky documents for their payment method. Hopefully they will update those as soon as possible. I had to cry “HELP HELP!” when I got their manual. 😦
I tried to contact with HSBC help desk a number of times but got more upset. Forum and blog’s also made me frustrated. I was just bouncing around them.

Here i am going to explain the total  process,
First of all, HSBC have two systems for their payment integration method  API and CPI. I solved my problem using API (Application Programmable Interface) method.
Currently API interfaces is available in – C, Java and XML.

I don’t know how dumb those guys, who developed this manual and why  they did not provide the primary elements like “POST Action URL”. After  tried several times i got from their help desk.

We have to follow these simple process to complete the API integration using XML :
Post URL: https://www.secure-epayments.apixml.hsbc.com

Step -1: Prepare an XML document  with  the payment information according to HSBC conversions.
Step-2: Send the XML document to HSBC server and retrieve  the reply instantly
Step-3: Check the status. If status is ‘A’ then consider it as a  successfull transaction.
Step-4: Update your store

Here is the  XML that I prepared to send HSBC server.

<EngineDocList>
<DocVersion DataType=”String”>1.0</DocVersion>
<EngineDoc>
<ContentType DataType=”String”>OrderFormDoc</ContentType>
<User>
<Name DataType=”String”>HSBC_USER_NAME</Name>
<Password DataType=”String”>HSBC_USER_PWD</Password>
<ClientId DataType=”S32″>HSBC_USER_ID</ClientId>
</User>
<Instructions>
<Pipeline DataType=”String”>Payment</Pipeline>
</Instructions>
<OrderFormDoc>
<Mode DataType=”String”>Y</Mode>
<Consumer>
<PaymentMech>
<Type DataType=”String”>CreditCard</Type>
<CreditCard>
<Number DataType=”String”>’ . $cradit_card_no .’</Number>
<Cvv2Val DataType=”String”>’ . $Cvv . ‘</Cvv2Val>
<Cvv2Indicator DataType=”String”>1</Cvv2Indicator>
<Expires DataType=”ExpirationDate”>’ . $exp .’</Expires>
</CreditCard>
</PaymentMech>
</Consumer>
<Transaction>
<Type DataType=”String”>PreAuth</Type>
<CurrentTotals>
<Totals>
<Total DataType=”Money” Currency=”826″>17</Total>
</Totals>
</CurrentTotals>
</Transaction>
</OrderFormDoc>
</EngineDoc>
</EngineDocList>

One important issue is, Total amount always multiplied by 100. For example, If we send amount £3530 then it will represent £35.30.

About Sand Box/Testing Mode:
Another one thing, HSBC has no SandBox. So there is not opportunity to practice except actual user account. 😦
For testing we have set <Mode DataType=”String”>Y</Mode> in XML document and for Live Transaction we have to set <Mode DataType=”String”>P</Mode>

I used CURL to send the XML to HSBC network. See the following example:

<?php
$ch = curl_init();
$url = ‘https://www.secure-epayments.apixml.hsbc.com’;
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_HEADER, 0);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $xml_data_will_go_here);
ob_start();
$data = curl_exec($ch);
curl_close ($ch);
ob_end_clean();
?>

The return XML will available in ‘$data’ variable. There is a XML node ‘ TransactionStatus’ in return XML file from where we can determine the status of the last operation .

Now see the status of payment.

(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.

That’s all to complate HSBC payment method. But only for proper documentation I had to suffer.

And I  thanks  MR. Paul who gave me support to do the experiment for his Finest Teddy Bear website.

Hope this post will help all of you guys.

Update September 7, 2009
Check my HSBC Paymen Class to make implement in easy way. I have implemented it with PASS(payer authentication service specification) validation.

Advertisements

182 Responses to “HSBC payment API method (Version 0.1.0)”

  1. S Ward October 5, 2007 at 2:09 pm #

    Hi There,
    Man HSBC are so hard to deal with… I like the look of your code and can see how it will work for me but you wouldn’t happen to know where i could locate a classic ASP sample to produce the same results?

    Thanks

  2. Rubel October 21, 2007 at 8:13 am #

    Hi Ward,
    Actually you have to follow the process. Ya, I used PHP here to describe it but u can use it in asp. Try to send XML to server and then u will get the return xml.

    You can use XML http request to send the xml by JavaScript.
    🙂

  3. Joe Richards November 29, 2007 at 1:55 am #

    Hello
    I am about to embark on this project of API integtation with HSBC and their half-arsed guide has done nothing but ignite hatred inside me HSBC. Anyhow – your post here has really helped me get my head around it – if only to see someone else had the same reaction to the stupid 20 page list of unnecessary xml data examples — why would I ever want to send the shipping address to HSBC?

    So yeah thanks.. I am using PHP so I will be trying your methods as I begin testing.

    Best wishes

    Joe

  4. Rubel November 29, 2007 at 4:38 am #

    They providing some bullshit documents. This is really hard to implement HSBC after reading their docs.

    To make your life easy contact the HSBC help desk and aslo read their PAS doc.

    Thnx

  5. Pankaj Kaushik December 11, 2007 at 11:13 am #

    Complain No.2711747413

    HSBC provide a loan to me and singned an ECS form so that they can get EMI directly from my bank. But due to lack of proper documentation they did not submit mandate form in my bank. My Bank retruned their ECS and debited my account against ECS charges when they first time hit my account.

    In order to sort out this problem I issued them PDCs they assured me as they have received PDCs no further ECS request will be sent to my bank.

    But after a lot of telephonic compalins they are still hiting my account against ECS as well as by depositing cheques.

    They are getting EMIs on time but every time I am suffering with a loss as my bank regularly debiting my account against ECS return charges.

    Really HSBC is able to manage things in order. They make my life a hell.

    No recevied any responsible response form them.

    Pankaj Kaushik

  6. Rubel December 11, 2007 at 11:26 am #

    HI Pankaj Kaushik,
    I used secure-epayments@hsbc.com address to communicate with them.

    You can try with it. My be they will reply you.
    😉

  7. sriarun December 12, 2007 at 6:44 am #

    hi rubel….

    i tried u’r code for hsbc api integration in my site….

    it’s generating response….but giving some message that

    Insufficient permissions to perform requested operation…

    i am unable to identify why this is coming and also i am failed to get the Transaction status…

    could you please help me to get it out…

    thanks,
    sri

  8. Rubel December 12, 2007 at 6:57 am #

    Hi sri,
    Check Name, Password and Client id carefully in xml. And please add customer billing address to fulfill the XML.

    🙂

  9. sriarun December 13, 2007 at 8:17 am #

    hi rubel,
    thanks a lot.now it’s working fine.but when i will get response in xml format message is getting repeated 10 times in message list.

    can you tell me what could be the reason for that..

    thanks,
    sri 🙂

  10. Rubel December 13, 2007 at 8:40 am #

    Well,
    If you are getting any error message you can trace it from error code. You will get all error code in Reference Docs in HSBC Manual.

    Try to make the xml following all convention of API overview.

  11. sriarun December 13, 2007 at 9:27 am #

    Yes i m trying to say that

    2
    —–

    in the above tags i m getting this sort of thing repeatedly,

    48
    Administrator
    CcxFraudShield

    FraudShield
    3
    1776
    CcxProcessFraudRules.cpp
    20:20:59Nov 6 2006
    1043

    2
    Rule 'Hot Billing Address 5.9/2' from strategy 'UK CNP' owned by StrategyOwnerId '1' for a transaction for client '23594' could not be evaluated : Key 'BillToStreet1' was not found in the document. The action taken is: '0'.

    for this i m not getting the reason…..

  12. sriarun December 13, 2007 at 9:35 am #

    theres is a big list of error codes in hsbc manual that we need to use or store…
    like 1 for Approved
    50 for Declined…
    what are the list of codes are neccessarily to be considered for orders…

  13. Rubel December 13, 2007 at 5:35 pm #

    Hi Sriarun,
    If the XML you are sending is not well formatted then HSBC will send the error report. So follow the API direction to generate XML with proper DATATYPE. For Solo and MasterCard include ISSUE NO and START DATE.

    Thank you

  14. sriarun December 14, 2007 at 1:10 pm #

    Hi Rubel,

    do we need to have SSL3.0 or TLS 1.0 technologies to be installed in our system…

  15. Rubel December 14, 2007 at 3:01 pm #

    I actually I used CURL (PHP library) to send XML. It was working fine except SSL. HSBC document says to have SSL.

    But when you want to do PAS validation then SSL I must.

  16. sriarun December 15, 2007 at 6:38 am #

    hi,

    after confirm page do we directly generate xml…?

    if it is like that, how the customer will enter his own creditcard number….

    and payment mech type is CreditCard or other wise need to specify type related to the card like (Visa,Solo like that)….?

  17. Rubel December 15, 2007 at 3:25 pm #

    No. After getting the payment detail like Card No, Expire Date you have to generate the XML and then it send to HSBC network following all convension of API & PAS docs.

  18. sriarun December 18, 2007 at 7:18 am #

    okay.we will get the response in xml .how we will get that into an array to check the status…

  19. asokanstar December 18, 2007 at 8:32 am #

    hi,
    i used

    price = ‘0.0003’;
    status = ‘Y’

    but i got the return value for ‘F” only.

    why its happend ?

  20. Rubel December 18, 2007 at 10:05 am #

    Hello Sri,
    To get the status you have to process the xml.. I processed as string. You can use explode() function if you are using PHP

    HI asokanstar,
    Actually we can’t use floating point for price. See the API overview documents to get the idea.
    Suppose if you want to send $00.05 the you have to assign $5

    Thank you buddies

  21. sriarun December 19, 2007 at 5:43 am #

    hi rubel,

    the what you have given is worked already,but now it’s not returning any response…

  22. sriarun December 19, 2007 at 5:58 am #

    1.0

    OrderFormDoc

    userid
    password
    clientid

    Payment

    P

    CreditCard

    4111111111111111
    123
    1
    12/07

    London
    UK
    Test
    Test
    41 Bickersteth Road
    SW17 9SH
    London

    1
    PR123
    100
    100
    2
    Sample Product 1
    SAMPLEPROD1

    PreAuth

    1

    i ve given this sort of code …..

    $ch = curl_init();
    if (!$ch) {
    die(“Couldn’t initialize a cURL handle”);
    } else {
    echo ‘curl handle initialized’;
    }
    $url = “https://www.secure-epayments.apixml.hsbc.com”;
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_HEADER, 1);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
    curl_setopt($ch, CURLOPT_POST, 1);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $XML_data);
    $ret = curl_setopt($ch,CURLOPT_SSL_VERIFYHOST, false);
    $ret = curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
    curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_ANY);

    // execute
    echo $ret = curl_exec($ch);
    previously it’s generated some response ….
    now, the server is not getting respond for this…can any one tell me the reason …?

  23. sriarun December 19, 2007 at 7:15 am #

    i m getting error as — Couldn’t resolve host http://www.secure-epayments.apixml.hsbc.com‘.

    is it the problem at remote side or it is related to the xml code that i am supplying ….?

  24. Rubel December 19, 2007 at 6:47 pm #

    Can you check your curl library. Is it working fine or see the spelling mistake. This payment get way is working fine in my 3 websites.

    If you have any problem with xml follow this one.

    <?xml version="1.0" encoding="UTF-8"?>
    <EngineDocList>
    <DocVersion>1.0</DocVersion>
    <EngineDoc>
    <ContentType>OrderFormDoc</ContentType>
    <User>
    <Name>XML_store</Name>
    <Password>xml</Password>
    <ClientId DataType="S32">208</ClientId>
    </User>
    <Instructions>
    <Pipeline>PaymentNoFraud</Pipeline>
    </Instructions>
    <OrderFormDoc>
    <Mode>Y</Mode>
    <Comments/>
    <Consumer>
    <Email/>
    <PaymentMech>
    <CreditCard>
    <Number>4111111111111111</Number>
    <Expires DataType="ExpirationDate" Locale="840">01/04</Expires>
    </CreditCard>
    </PaymentMech>
    <BillTo>
    <Location>
    <TelVoice/>
    <TelFax/>
    <Address>
    <Name>PTS Auth Test (Level I w/AVS)</Name>
    <Street1>Metric</Street1>
    <Street2/>
    <City>Austin</City>
    <StateProv>TX</StateProv>
    <PostalCode>78758</PostalCode>
    <Country>840</Country>
    <Company/>
    </Address>
    </Location>
    </BillTo>
    </Consumer>
    <Transaction>
    <Type>Auth</Type>
    <CurrentTotals>
    <Totals>
    <Total DataType="Money" Currency="840">180000</Total>
    </Totals>
    </CurrentTotals>
    </Transaction>
    </OrderFormDoc>
    </EngineDoc>
    </EngineDocList>

  25. sriarun December 22, 2007 at 9:20 am #

    Hi Rubel,

    if the payment type is PaymentNoFraud, it’s not dislaying any sort of error message other wise if i specified it as Payment it’s giving the fraud information such as AVS mismatch…(even though i have specified valid address).

    if i m specifying payment type as PaymentNoFraud,
    —————
    HTTP/1.1 200 OK Server: CCE_XMLIC/1.0 Connection: close Content-Type: text/xml Content-Length: 4207 1.0 OrderFormDoc 476c07b2-fd96-3002-002a-0003ba9a87ff PaymentNoFraud
    London UK Test Test SW17 9SH London 41 Bickersteth Road
    1 345 11/08 4111111111111111 Sample Product 1 PR123 1 75 SAMPLEPROD1 2 75 CreditCard 1198315082380 476c07b2-fd97-3002-002a-0003ba9a87ff 476c07b2-fd97-3002-002a-0003ba9a87ff Y 282679 1 Approved. 1 Approved 1 7 23 476c07b2-fd98-3002-002a-0003ba9a87ff 4 7 1 PreAuth 282679 1 Approved. 1198315082380 Y 476c07b2-fd97-3002-002a-0003ba9a87ff 476c07b2-fd98-3002-002a-0003ba9a87ff A UK09452611GBP 23594 UK09452611GBP 23594 username password 1198315082374 1198315082702
    ————–
    i getting response as above ….. how can i get this in an array to save order details to database

  26. Rubel December 23, 2007 at 7:58 am #

    If you set farud. It means you allow credit and debit card both. After getting the response it depends on you how you will process the xml.

  27. theo singer January 5, 2008 at 11:48 pm #

    dont touch hsbc they are crap. If you do it will cost you dear and you will regret it.

  28. Rubel January 7, 2008 at 3:45 am #

    😀 😀 …

  29. Kras January 11, 2008 at 4:11 am #

    I’m getting response message like

    16
    Merchant
    Director
    Director
    3
    876
    CcxInput.cpp
    19:43:05Nov 6 2006
    7
    6
    Insufficient permissions to perform requested operation.

    I’m using curl. User, pass and client id are correct. Customer billing address is filled. Any suggests?

  30. Kras January 11, 2008 at 6:33 am #

    Never mind 🙂 I found problem they have test and real API URLs
    test URL https://www.uat.apixml.netq.hsbc.com
    real URL https://www.secure-epayments.apixml.hsbc.com

  31. Rubel January 11, 2008 at 8:47 am #

    @Kras
    This message means HSBC network got invalide user name and password .

    🙂 🙂
    Thank you

  32. lucas January 15, 2008 at 9:38 pm #

    Hi everyone. Im just implementing this as we speak and need to be live aspa! Its great to find a good thread with recent responses. My thoughts are the same as above.

    One question, do they have a test / sandbox url? soooo silly that you have to find this info off the web.

  33. Rubel January 16, 2008 at 4:30 am #

    To test your payment you have to set payment mode to ‘Y’

  34. Karim January 16, 2008 at 11:28 am #

    Hi Rubel
    You have a wonderful article , actually I used it as a reference
    but I have a problem that is say

    Insufficient permissions to perform requested operation.

    I didn’t got my Username , Password and ClientID from the bank yet, so I want to know
    is there any Data that I can test with or I have to ask the Stupid bank for it??

  35. Rubel January 17, 2008 at 4:18 am #

    Ya Mate. You have to collect it from your bank. 😦

    So far i know HSBC has no sandbox type process so that you can test it with out having an account. And for each test tranjection they will create a order in their mail order panel.

    So you have to collect it. 🙂

  36. Ziko January 22, 2008 at 2:16 am #

    Would u please tell me What exactly i will get if i send XML file like u write in ur article to The HSBC URL.

    1- and What type of data will it return ?? XML file , POST data, or Array

    if it return something like that “where the start end element”
    ********************************
    1.0

    OrderFormDoc
    4794500d-5065-3001-002a-0003bac00fc9

    Payment

    6

    16
    Merchant
    Director
    Director
    3
    876
    CcxInput.cpp
    19:43:05Nov 6 2006
    7
    6
    Insufficient permissions to perform requested operation.

    01/08
    1111111111111111

    EMC-3843006-4075629
    Y

    7

    29

    Auth

    12345
    User
    pass

    1200918335861
    1200918335872
    *********************************

    2- Would u please explain what is the first lines , from “1.0” TO “Insufficient permissions …..”

    please if u have sample module for this API , send to me at mail

    Thank you in advanced

  37. Rubel January 22, 2008 at 8:55 am #

    @Ziko

    You will get a XML with all response information. It seems that user name and password is not valid.

    You need a well formed xml with all valid information.

    🙂

  38. sriarun January 29, 2008 at 11:03 am #

    Hi Rubel,

    can you plz tell me how can make a hsbc api request so that i can get any of the following list -{ 2,3,502,1069,2055 } of error codes in my response.

    Regards,
    Sri 🙂

  39. Rubel January 29, 2008 at 11:29 am #

    H Sriarun,
    How are you.. I remember i gave you a sample xml file. Actually i got this XML document form HSBC help desk( See 14th comments).

    First you have to generate a xml with your shopping cart information. Then you have to send this xml as a post back request to HSBC network.

    I used CURL to do this operation. If you are using PHP you can use my source code given here.

    Then you will get a replay with a xml Document. You have to phrase the document and you will get status of your request.

    Then you can confirm be about your tranjection

    I think you have a PDF document about PAS referance. There you get see description of your error codes.

    Thank you

  40. sriarun January 30, 2008 at 8:11 am #

    hi rubel,

    thanks for providing the information.Now i m successfully getting xml response and i m able to parse that and storing orders based on error codes….

    Now i want to know in which senario i can get these list -{ 2,3,502,1069,2055 } of error codes.

    In pdf they specified some info for each error code…

    Inorder to get that error code what fraud information i can send …?

    regards,
    sri.

  41. Ziko February 6, 2008 at 9:09 am #

    Hello guys
    anyone know how to deal with “3D Secure” in HSBC API ?
    and if HSBC API not support this , What happen if Customer buy with Card require 3D Secure
    Thank you

    Notes:
    3D Secure is a new technical standard developed by Visa and MasterCard to further secure CNP transactions over the Internet.

    MasterCard brand their system as ‘MasterCard SecureCode’ and Visa call theirs ‘Verified by Visa’. (Maestro cards will also be supported through the MasterCard service from the 31st July 2007).

    3D Secure creates what is called a ‘trust chain’ throughout the transaction, shifting the liability for fraud from the merchant to the issuer under a range of conditions. Customers are requested to either enter their pre registered PIN code or to register for the service. If the customer chooses not to register for 3D secure the merchant will still be eligible for chargeback protection.

  42. Mamun Murtaza Sheriff February 20, 2008 at 7:52 am #

    When I send request, I get reply with bellow information. Please check what is the problem how to trap that the transaction was processed or not?

    1.0 OrderFormDoc 47bb1329-9c4a-3002-002a-0003ba9a87ff PaymentNoFraud 6 16 Merchant Director Director 3 876 CcxInput.cpp 19:43:05Nov 6 2006 7 6 Insufficient permissions to perform requested operation.
    Austin 840 PTS Auth Test (Level I w/AVS) 78758 TX Metric
    01/04 4111111111111111 Y 180000 Auth 208 XML_store xml 1203491091702 1203491091712

  43. Rubel February 20, 2008 at 9:00 am #

    @Mamun Murtaza Sheriff

    Check the NAME and PASSWORD you used in XML document.

    For test you need to set the payment mode to “Y” and use the Credit Card No given in the HSBC document. This credit card is valid for test operation…

    🙂

  44. Vincent February 21, 2008 at 6:12 am #

    great work rubel. Can you please give the code for parsing the XML reply m8.

    cheers

  45. Vincent February 21, 2008 at 6:16 am #

    Hi rubel,

    How can we make the XML to a readable format m8

    Kind Regards
    Vincent

  46. Vincent February 27, 2008 at 11:29 am #

    Hi mate,

    HSBC sent me 2 XML files. I dont know what they BOTH are for.
    preauth payment example.xml and auth payment example.xml

    According to you Rubel there is only ONE xml file that we need to post to the HSBC site, rt m8. Your example is like the second file I got from HSBC mate.

    Thanks
    Vincent

  47. sriarun March 4, 2008 at 9:07 am #

    Hi Rubel,

    i have to integrate payerauthenticationcode in hsbc api…..

    just i need help to send xml for payerauthentication and then to hsbc….

    Regards,
    Sri.

  48. Rajapandian March 11, 2008 at 11:52 am #

    Hi Rubel,

    Any body can provide sample xml file . because i tried with above xml’s but it always shows Insufficient permissions to perform requested operation.

    Thanks in advance.
    Rajapandian

  49. Rajapandian March 11, 2008 at 11:52 am #

    Hi all,

    Any body can provide sample xml file . because i tried with above xml’s but it always shows Insufficient permissions to perform requested operation.

    Thanks in advance.
    Rajapandian

  50. Rubel March 11, 2008 at 12:22 pm #

    Hi Friends,
    The above xml I used is directly sent from HSBC help desk. Well here i have past the code that is already using in one of my website.
    NB: Before use this code you have to put orginal Name, Password,ClientId that you got from HSBC bank.

    Thank you.

    $ch = curl_init();
    $url = ‘https://www.secure-epayments.apixml.hsbc.com’;
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_HEADER, 0);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
    $vars ='<?xml version="1.0" encoding="UTF-8"?’ . ‘>
    <EngineDocList>
    <DocVersion DataType="String">1.0</DocVersion>
    <EngineDoc>
    <ContentType DataType="String">OrderFormDoc</ContentType>
    <User>
    <Name DataType="String">UserName</Name>
    <Password DataType="String">Password</Password>
    <ClientId DataType="S32">Client ID</ClientId>
    </User>
    <Instructions>
    <Pipeline DataType="String">PaymentNoFraud</Pipeline>
    </Instructions>
    <OrderFormDoc>
    <Id DataType="String" >Order id. ‘</Id>
    <Mode DataType="String">P</Mode>
    <Consumer>
    <PaymentMech>
    <CreditCard>
    <Number DataType="String">’ . $cradit_card_no .'</Number>
    <Expires DataType="ExpirationDate">’ . $exp .'</Expires>
    ‘ . $issue_node . ‘
    </CreditCard>
    <BillTo>
    <Location>
    <TelVoice/>
    <TelFax/>
    <Address>
    <Name DataType="String"> ‘ . $order[‘txtName’] . ‘</Name>
    <Street1 DataType="String">’ . $order[‘txtAdd1’] . ‘</Street1>
    <Street2 DataType="String">’ . $order[‘txtAdd1’] . ‘</Street2>
    <City DataType="String" >’ . $order[‘txtCity’] . ‘</City>
    <StateProv DataType="String" >’ . $order[‘txtCounty’] . ‘</StateProv>
    <PostalCode DataType="String">’ . $order[‘txtZip’] . ‘</PostalCode>
    <Country DataType="String">’ . $country . ‘</Country>
    <Company DataType="String" />
    </Address>
    </Location>
    </BillTo>
    </PaymentMech>
    </Consumer>
    <Transaction>
    <Type DataType="String">Auth</Type>
    <CurrentTotals>
    <Totals>
    <Total DataType="Money" Currency="826">’ . $price2 . ‘</Total>
    </Totals>
    </CurrentTotals>
    </Transaction>
    </OrderFormDoc>
    </EngineDoc>
    </EngineDocList>’;
    curl_setopt($ch, CURLOPT_POST, 1);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $vars);

    ob_start();
    $data = curl_exec($ch);
    curl_close ($ch);
    ob_end_clean();
    // Unblock This code for Dubugging
    /*echo "Xml sent -> <textarea>";
    echo htmlspecialchars($vars);
    echo "</textarea>";
    echo "Xml returned from hsbc -> <textarea>";
    echo htmlspecialchars($data);
    echo "</textarea>";
    exit;*/

  51. Jason March 12, 2008 at 12:37 pm #

    I am currently developing an application against the hellish HSBC payment gateway. Looking for information on the web to clarify the rubbish in the documentation supplied by HSBC I put the following search terms into Google:
    “HSBC secure ePayment XML document format”. Your blog gets top ranking in Google, it is concise and simple to follow. The solution provided works – in minutes! I suggest that you contact HSBC and offer to rewrite their documentation for them – for a VERY large fee 🙂

    Thank you.

  52. Rubel March 12, 2008 at 2:20 pm #

    @Jason

    Thanks mate.

    I also passed a horrible time when worked with HSBC Payment.

    I thanks Mr.Paul, Who allowed me to do a small research on HSBC payment.

    I wrote this post only for those people who are facing this terrible situation like me… This is really out of description.

    Rubel

  53. Mike Savage March 17, 2008 at 7:44 pm #

    Hi there, can some tell me if you have to state the card type in the ‘CreditCard’ XML node? If you do what are the values for certain cards like VISA, Maestro, etc, etc… I can’t find the documentation anywhere????

  54. Mike Savage March 17, 2008 at 7:48 pm #

    It’s okay… HSBC FINALLY sent me the API Heirachy Doc!!!

  55. Rubel March 18, 2008 at 4:24 am #

    🙂

  56. Mike Savage March 19, 2008 at 1:25 pm #

    This article has saved my life and made something so complicated so very easy! Thank you, thank you, thank you. However I do have one question. What is the best method in PHP to iterate through the returned XML (which has the variable $data above)? As once we have the XML I need to determine what happens next depending on the outcome (if the payment is processed or rejected) as I wish to display the ‘The card failed compliancy checks.’ to the user if something has gone wrong. Once again You Rock for writing this article!

  57. Ziko April 2, 2008 at 9:29 pm #

    Dear ,
    do u have any sample for send
    HSBC Secure ePayments Card Processing
    “payer authentication service specification (PAS)”

    How can i use it ? i’m ready setup the HSBC API while send to HSBC data and get the respond

    soif u nkow or have good guide how to send (PAS) or use it please send to me
    p.s. i have HSBC doc about (PAS) it is not helper
    Thank you

  58. Rubel April 3, 2008 at 5:56 am #

    I did not implement it. I hope any body who started with it. Will reply here to help all of us.

    🙂

  59. Becky April 3, 2008 at 3:38 pm #

    Dear Rubel

    I eventually got what I consider as “Good Response ” from the server, I can even see that it is approved, but the big question is, how do I get to read the response to be able to generate user friendly responses?

    Well am using the API not the PAS

  60. Rubel April 3, 2008 at 3:48 pm #

    Well, You are receiving an XML data as a response if you are using API in XML.. Now you have parse the xml file to get the values. Actually it’s up to you how do you like to parse it. I did it in a very simple way. And It is working fine.

    // Language Name : PHP
    // I have call my the function with the tag name

    $TransactionStatus = $this->get_value_by_tag_Name( $data, ‘<TransactionStatus DataType="String">’, ‘</TransactionStatus>’);

    //Body of the function
    function get_value_by_tag_Name( $data, $s_tag, $e_tag) // collect data beteween to tag
    {
    //
    $s = strpos( $data,$s_tag) + strlen( $s_tag);
    $e = strlen( $data);
    $data= substr($data, $s, $e);

    //
    $s = 0;
    $e = strpos( $data,$e_tag);
    $data= substr($data, $s, $e);
    $data= substr($data, $s, $e);

    //
    return $data;
    }

  61. Becky April 8, 2008 at 11:16 am #

    Rubel,

    Thank you very much for your response.

    You have been of help

  62. itsjame April 16, 2008 at 7:59 pm #

    hi can any one tell me how to work with e-PAS HSBC..when i am sending the xml to e-PAS server
    it going to server…
    but when Reading the xml it is showing error
    [Fatal Error] :1:1: Content is not allowed in prolog.

  63. Rima April 18, 2008 at 5:41 am #

    “payer authentication service specification (PAS)”

    How can i use it ? I have implemented HSBC API.

  64. Ziko April 23, 2008 at 2:12 pm #

    Hello,
    yes please we need to know how to use
    payer authentication service specification (PAS)
    i have create HSBC API to call the HSBC server and send XML and recive XML
    but i don’t know more about PAS
    so please if anyone know send to me or to this blog
    Thank you

  65. Josh April 28, 2008 at 9:25 am #

    Thank you for putting this together Rubel – a very useful resource.

    I’ve got the API to work but i am having an issue with billing details. the transaction is completed successfully but the billing name is blank. I am sending a properly formatted XML doc according to their specs with the billing name and address but nothing shows when i check the order on HSBC’s server.

    Thanks!

  66. Josh April 29, 2008 at 10:25 am #

    I’ve fixed it now – thanks again for the help Rubel.

  67. rubel April 29, 2008 at 10:52 am #

    Hi,
    You are welcome

    Soon i am going to share about 3D (PAS) installation of HSBC.

    Thanks All
    Keep in touch.

  68. Mansi May 2, 2008 at 11:11 am #

    Hello Rubel,

    Can you please now help all of us for implementing PAS with API. We are despirately waiting for your valuable reply. Thanks in advance for your help.

  69. TC May 8, 2008 at 5:36 pm #

    I’m having the same problem Josh had – the billing name not appearing in the HSBC VT. How did you get round this?

  70. Josh May 20, 2008 at 10:11 am #

    Hi TC,

    I had a slight error in the XML regarding the PaymentMech tag. I had the bilto inside it which was wrong. Hope you have the same problem.

    I am now having another problem. Everything works fine in test mode but when i put it into production mode it returns an error.

    1067
    System error.

    Any ideas?

  71. TC May 20, 2008 at 6:30 pm #

    Josh, I could kiss you 🙂

    That’s exactly the mistake I made. All works perfectly now!

    By way of returning the favour, I believe your problem is with the ISO code for the country. Despite the documentation (ahem) stating this is a 3-char ISO string (which it is in a roundabout way), it is NOT “GBR” for the UK as you’d expect, but “826” (UN/ISO numeric rather than the expected ISO 3-alpha).

    A full list can be found here: http://www.unc.edu/~rowlett/units/codes/country.htm

    Hope this solves your problem!

    Cheers, TC

  72. Lee May 28, 2008 at 10:25 am #

    Doeds anyone know the URL that the PAS data must be POSTed to?

    Thanks in advance.

  73. TC May 29, 2008 at 2:36 pm #

    just checked back here and my previous post has disappeared?! Anyway, if you haven’t sorted it by now, I believe the problem is with the country code, should be ‘826’ for UK, not ‘GBR’.

  74. Rubel May 29, 2008 at 3:52 pm #

    @TC,
    I am extremity sorry if accidentally it happened. I just deleted some auto generated comments form my comments list.

    I am sorry again. Please mail me ( reazulk@gmail.com) if I can do anything
    Rubel

  75. Lee June 9, 2008 at 3:29 pm #

    Hello Everyone,

    Given the number of problems people have integrating with the HSBC XML API I thought I would share my imlementation of some simple C# classes that make working with the system much easier from any .NET language. You can find these on my blog at http://lmdavies.blogspot.com/2008/06/as-per-my-last-post-i-have-now-made.html

    I have also recently impleneted the PAS service which is a bit less elegant due to the fact taht the POST to the PAS server must originate from the clients browserr (and can’t be done out of bound by your own server). If people want I can write up a blog post about this also.

    Cheers everyone.

  76. rubel June 9, 2008 at 4:21 pm #

    hi Lee,
    Thnx for sharing your knowledge here.

    Thnx

  77. black knight June 30, 2008 at 12:57 pm #

    hi im just new here,so i need to have an account on the hsbc control panel?how could i get an account for that? is that the merchant account?how to register…is anybody could help me?

    thanks

  78. black knight June 30, 2008 at 1:17 pm #

    hi guyz,
    i just used CURL to send the XML and this is what I got:

    curl handle initialized

    HTTP/1.1 200 OK
    Date: Mon, 30 Jun 2008 12:09:59 GMT
    Server: Apache/2.2.6 (Fedora)
    Last-Modified: Mon, 30 Jun 2008 08:59:48 GMT
    ETag: “5ad530-427-7b462900”
    Accept-Ranges: bytes
    Content-Length: 1063
    Connection: close
    Content-Type: text/xml

    1.0

    OrderFormDoc

    XML_store
    xml
    208

    PaymentNoFraud

    P

    4111111111111111
    01/04

    PTS Auth Test (Level I w/AVS) Metric Austin TX 78758 840

    Auth

    180000

    can anybody tell me what this response mean? i dont even get that Insufficient permissions to perform requested operation…how to get that username, password, client thing?can anybody help me…rubel…

    thanks…

  79. black knight June 30, 2008 at 3:55 pm #

    hi guys,
    just want to ask on how u guys did have account for the HSBC including the username, password and client id?do i need to regiseter on the HSBC Secure ePayments?

    thans for any help…

  80. Rubel June 30, 2008 at 4:14 pm #

    Hi Nice to meet you.

    Here is the email address(secure-epayments@hsbc.com) of HSBC help desk. Send a mail to him. Most probably his name is “MR. ROY”.

    Put the subject “NEED URGENT HELP”.

    Thank you.

  81. Tooks July 11, 2008 at 9:59 am #

    Hi, Thanks for sharing i’ve found reading through this page very useful.

    I’m having a similar problem to josh further up the page in that i seem to be recieving alot of 1067 “System Error” error codes. The confusing thing is that this is an intermitant problem where some orders are approved fine but some are returning with the error code 1067.

    Unfortunately its not due to due to the ISO currency string as we’re using the correct 826 numeric string. but these errors are far to frequent to be normal. for example if we had 10 orders 5 would be approved and 5 would be a system error.

    does anyone know why the system error actually means? as you know the HSBC API documentation is a pile of hourse manure

    Thanks a lot!

  82. atomicguava July 22, 2008 at 11:52 am #

    For Switch or Maestro, the XML node name for the Issue Number is ‘IssueNum’, and should be a child of the ‘CreditCard’ node.

  83. Steve July 25, 2008 at 12:50 pm #

    Hi folks,

    Any advance on the 3D Secure implementation with HSBC? Need to get this sorted asap.

    Thanks,

    Steve

  84. johnpeter July 29, 2008 at 9:11 am #

    Hi,

    I have problem with HSBC Payment. Some orders failed for AVS check even it has the correct address. The orders considered as “Fraud Review”.

    Any one can help me.

    Thanks in advance.

    John Peter

  85. Gaz Copnall July 30, 2008 at 12:24 am #

    Hello,

    We have been using HSBC secure epayments with the help of this web site over the past few months, so I’d like to thank you for your help.

    I have one question though, when we post the user details to HSBC there is a problem with the country field. 90% of our customers is from the UK, but for example this is a typical result inside the epayments control panel (please note this is not real data!:

    Name: Joe Bloggs
    Company:
    Phone: 01326561131
    Address Line 1: 67 Loe Valley Hill
    Address Line 2 :
    Address Line 3 :
    City: Helston
    State/Province: Cornwall – GB
    Zip/Postal Code: TR13 8UR
    Country: United States (code 840)
    Email:

    Now you can see the obvious problem here with the country being united states, when it should be UK (or GB maybe). The guys that work on my site were stuck at this point, orders are being processed, but I want it working as it should.

    The guys mentioned if there was a table of codes available for each country? Is this what they need to make it work properly? Seems odd how the country is being abbreviated in the State/County section. Any ideas? Thanks

  86. Rubel July 30, 2008 at 6:32 am #

    Thnx for your comments and i am happy as my blog could help you…

    HSBC provide a REFERENCE Documents where you can get all these information.

    For your help temporarily i am uploading this file in my server. Please download it.
    Reference Document

  87. Pete M August 5, 2008 at 6:23 pm #

    I’ve given up with the CPI and have decided to go with the API. With the help of this blog I’ve been able to make good progress ad am getting a good respose from my XML.

    What I really need now is a sample form to capture the credit card data (preferably for the UK). Would anyone be able to share this with me?

    Thanks, Pete

  88. Matt August 6, 2008 at 10:24 pm #

    Hi guys, the info on this page has helped me out no end and i can confirm that HSBC are still as shite as they were at the start if this thread. Its taken my client 3 weeks to finally get his username, password and client Id after not being sent it by HSBC.

    Anyway, my question is: the format of the client id HSBC have provided for my customer is UK11111111GBP? This is clearly not a S32 DataType so is the client id the 11111111 section or is the actually DataType a string?

    Any help will stop me pulling out my hair!
    Cheers,
    Matt

  89. Rubel August 7, 2008 at 4:49 am #

    @Matt
    UK111111111GBP This is not your client id.. A ClientId should be 5 digit integer no….

  90. Matt August 7, 2008 at 1:11 pm #

    Yes this has been my argument with HSBC for the last 3 weeks. Every discussion i have had with them or email/letter they have sent clearly says… ClientId = UK111111111GBP. The fact that this is actually the ClientAlias and not the ClientId make a hell of a difference when you come to try to use the system.
    Managed to get a decent response today and have round out my customers actual ClientId (which as you rightly say, is a 5 digit number)

    I think the lesson here is, ignore anything the HSBC tell you and just use the information found within this massive thread. Invaluable!

  91. Rubel August 7, 2008 at 4:37 pm #

    some time i got strange about the HELP desk of HSBC….

    Event they don’t have a simple example code of their payment implementation.. they are really dumb..

  92. Rasel Ahmed August 13, 2008 at 12:56 pm #

    Fine your example is nice..and very helpful….Can you help me to develop a HSBC online payment using JAVA API

  93. Rasel Ahmed August 20, 2008 at 9:25 am #

    Hello when I click in your site(Reference Document link) it…..give message that…….file is not in server…….that is I can’t download the Reference Documents.

  94. Rubel August 20, 2008 at 10:12 am #

    @ Rasel Ahmed
    Please Check it now.. Sorry for the inconvenience

  95. michel August 20, 2008 at 4:16 pm #

    Hello Mr Rubel,

    Im new with HSBC api integration, Just wanna ask about the filling of the card details, Am I the one to create interface of the Card details like cardholdername, expiry date etc. Or it is built in on the hsbc secure payment using api integration?

  96. Rasel Ahmed August 21, 2008 at 10:52 am #

    Hi, Rubel…Thanks a lot for your greate help. Can u tell me that is there any different XML tag line for Auth and PreAuth transection except transection ?
    and is must for Auth or PreAuth transection?
    And what is the meaning of Cvv2Val ?

  97. michel August 21, 2008 at 1:11 pm #

    hi , how to generate xml in php?

  98. Rubel August 21, 2008 at 3:23 pm #

    @ Rasel Ahmed
    Please read HSBC API docs to generate the XML.

    @michel
    To create the XML for HSBC Payment just put the xml in a variable following the proper format and pass it to HSBC net work.

    For more information about XML see these links
    http://w3schools.com/xml/default.asp
    http://www.php.net/header

  99. Steve August 27, 2008 at 9:06 am #

    Anybody had any luck with implementing HSBC’s PAS?

  100. Suba August 28, 2008 at 4:52 am #

    Hi, Your article helped me a lot.Thanks.When i run your code with my account details from HSBC. I got some notice that

    “Key ‘ShipToStreet1’ was not found in the document”
    “Key ‘CustomerEmail’ was not found in the document”
    “Key ‘IPAddress’ was not found in the document”

    For the shipping and billing details. So can you tell me the xml tagnames and format to insert these details please.

    Thanks in advance

  101. Anton Gerassimov September 11, 2008 at 7:26 pm #

    Hi guys, just a little tip for the dreaded

    Insufficient permissions to perform requested operation

    If you or your client have been given ClientID in this format: UK11111111GBP – this is NOT the ClientID

    BUT if you log in to the admin site they provide you with:

    Testing: https://www.uat.store.netq.hsbc.com
    Live: https://www.secure-epayments.hsbc.com

    The ACTUAL Client ID is displayed in the header of the page and it is a 5 digit number!

  102. Devid September 15, 2008 at 12:22 pm #

    Hello All,
    Would u please send me the full document you use for HSBC API
    i need the one you use and latest document , which will help me to deal with my Code
    i don’t need to send HSBC mail , if anyone can send it info@pixelshouse.com

    info at pixelshouse.com

    Thank you

  103. Sy September 29, 2008 at 10:32 pm #

    Hi Rubel,

    You are a legend! Thanks so much for all the time you’ve spent helping with this.

    2 questions:

    Could you explain the difference between these?
    1) Payment
    2) PaymentNoFraud

    Also, in your two example XML posts from your live websites that there is:

    P

    and the other has:

    Y

    What’s the difference?

    Many thanks again.

  104. Rubel October 6, 2008 at 8:05 pm #

    @Sy

    Qty-1: What do you mean.

    Qty-2:
    Y -> Test Payment/Sandbox
    P -> Production mode..

  105. evilsee November 6, 2008 at 2:03 pm #

    Sy – Payment is more secure than Paymentnofraud.

    Paymentnofraud seems to mean – take the payment but do not do fraud checks, try doing a transaction with a fake ccv number, will probably go through, do the same but with the pipeline set to Payment and it will give an error.

    Btw in order to make use of this, the Mode must be set to production(p) and not testing (Y)

    E.

  106. evilsee November 6, 2008 at 2:06 pm #

    Just to add to the collective,

    I was not sure when to use Issue Number or Startdate, I know its only used for debits cards, but not all debit cards have both values.

    I called the help desk and wa

  107. evilsee November 6, 2008 at 2:09 pm #

    Just to add to the collective,

    I was not sure when to use Issue Number or Startdate, I know its only used for debits cards, but not all debit cards have both values.

    I called the help desk and was told over the phone that both fields are optional and then received andemail from hsbc supprt telling me that both are required.

    I called back and spoke to a ‘more senior’ consultant and was told the following ‘Capture all the details as they appear on the card’

    So basically you need to tell your clients to enter all details that are applicable, if they enter an Issue Number and not a start Date then only send the Issue Number through in the XML, or they enter both then send both in your XML.

    e

  108. Rubel November 7, 2008 at 7:09 am #

    @Evilsee

    This Issue number and Start date for Solo, Maestro type code. So you can keep it optional. So if the customer enter this information only then allow this inputs in your XML

  109. Deba December 11, 2008 at 6:30 am #

    PAS server URL for POST is https://www.ccpa.hsbc.com/ccpa

  110. Luke Yates January 8, 2009 at 1:51 pm #

    Hi,

    I am currently *trying* to integrate the HSBC API with classic ASP.

    I have been sent various integration guides and reference sheets etc. Having read through them all (repeatedly!) I found that they contradicted each other in a number of places, as well as managing to explain absolutely nothing useful and confuse me completely!

    When I rang HSBC I was told that there was no test mode, no method of testing, and no example files available! Useless B***ards!

    As mentioned above in the earlier postings, the documentation just instills hatred and anger toward HSBC!

  111. Josh January 15, 2009 at 2:44 pm #

    Hello, I’m still getting a lot of 1067 errors which is incredibly frustrating. I’ve had no joy with HSBC support who have just sent example XML.

    The problem is as Tooks described earlier, sometimes the order goes through other times i get a 1067. What does this error mean (system error as the documentation says isn’t very helpful) and what causes it?

    any ideas?

    Thanks,

    Josh

  112. wunpac January 23, 2009 at 1:05 am #

    Hi there,

    Very insightful and helpful site. Rubel I commend your efforts to help beleaguered HSBC Secure Epayments customers (like myself). You would think a massive worldwide bank would be able to provide decent, accurate documentation for its products. Alas it falls to its customers to help each other to navigate the mind field of problems, poor/inaccurate information and plain incompetence.

    The issue of 3D secure has been mentioned a few times above, but as far as I’m aware remains has not been addressed. My HSBC bank manager tells me that 3D secure will be a requirement as from the end of Jan 09′. From this date transactions will not be processed and fines will be issued to merchants who continue to accept MasterCard payments but who do not use 3D secure. Can you Rubel, or any readers of this blog enlighten us on how to integrate 3D secure using the XML API.

    Any helpful information or insights will be, I’m sure, appreciated by many thousands of baffled Epayments customers who read or stumble across this blog.

  113. Alek January 27, 2009 at 11:38 am #

    I had a lot of troubles with 3D Secure by myself, hope that below will save you guys some troubles:

    $received_data[‘cardexpiryyear’].$received_data[‘cardexpirymonth’],
    CardholderPan => $received_data[‘cardnumber’],
    CcpaClientId => ‘UK11111111GBP01’,
    CurrencyExponent => 2,
    PurchaseAmount => POUND.$received_data[‘thetotal’],
    PurchaseAmountRaw => $_SESSION[‘total_minor’],
    PurchaseCurrency => 826,
    PurchaseDesc => ‘T’,
    ResultUrl => ‘https://’.$_SERVER[‘HTTP_HOST’].$_SERVER[‘REQUEST_URI’].’?step=2′,
    );
    // display form for confirmation
    $smarty = new smarty_wrapper();
    $smarty->assign(‘card’, $card);
    $smarty->display(‘page/cart_components/payment_verification.tpl’);
    } else {
    unset($_SESSION[‘return_post’]);
    header(‘Location: thankyou.php’);
    }
    exit;
    break;

    // answer from PAS server
    case 2:
    $return_post = array();

    $hsbc_api = new logic__hsbc_api();
    $hsbc_api->client_id = ‘11111’;
    $hsbc_api->login = ‘login’;
    $hsbc_api->password = ‘pass’;

    // analyze PAS response
    switch ($received_data[‘CcpaResultsCode’]) {
    // AUTHENTICATION SUCCESFUL – proceed to API
    case 0:
    $hsbc_api->PayerSecurityLevel = 2;
    $hsbc_api->PayerAuthenticationCode = $received_data[‘CAVV’];
    // note that it MUST be encoded (without encoding ‘+’ will transform to ‘ ‘)
    $hsbc_api->PayerTxnId = urlencode($received_data[‘XID’]);
    $hsbc_api->CardholderPresentCode = 13;
    break;
    case 1:
    $hsbc_api->PayerSecurityLevel = 5;
    $hsbc_api->CardholderPresentCode = 13;
    break;
    case 2:
    $hsbc_api->PayerSecurityLevel = 1;
    $hsbc_api->CardholderPresentCode = 13;
    break;
    case 3:
    $hsbc_api->PayerSecurityLevel = 6;
    $hsbc_api->PayerAuthenticationCode = $received_data[‘CAVV’];
    $hsbc_api->PayerTxnId = $received_data[‘XID’];
    $hsbc_api->CardholderPresentCode = 13;
    break;
    case 4:
    $hsbc_api->PayerSecurityLevel = 4;
    $return_post[‘warnings’][] = ‘Transaction completed, but it was unable to make 3-D Secure Authentication’;
    break;
    case 5:
    case 6:
    $return_post[‘errors’][] = ‘Failed to authenticate credit card. Please provide alternative card or choose different payment type’;
    break;
    case 7:
    case 8:
    case 9:
    case 10:
    $hsbc_api->PayerSecurityLevel = 4;
    $return_post[‘warnings’][] = ‘Transaction completed, but it was unable to make 3-D Secure Authentication’;
    break;
    case 11:
    $return_post[‘errors’][] = ‘Provided card validation data incorrect. Please correct’;
    break;
    case 12:
    $hsbc_api->PayerSecurityLevel = 2;
    $hsbc_api->PayerAuthenticationCode = $received_data[‘CAVV’];
    $hsbc_api->PayerTxnId = $received_data[‘XID’];
    $hsbc_api->CardholderPresentCode = 13;
    break;
    case 14:
    $hsbc_api->CardholderPresentCode = 7;
    $return_post[‘warnings’][] = ‘Transaction completed, but it was unable to make 3-D Secure Authentication’;
    break;
    }
    $return_post[‘warnings’][] = “[CcpaResultCode: {$received_data[‘CcpaResultsCode’]}]”;

    // if PAS response correct proceed with API
    if (empty($return_post[‘errors’])) {
    $hsbc_api->send_auth_request();
    // if there are errors go back to previous step
    if ($hsbc_api->analyze_response()) {
    $return_url = ‘thankyou.php’;
    $return_post[‘warnings’][] = ‘Transaction completed using 3-D Secure Authentication’;
    // if there are errors go back to previous step
    } else {
    $return_url = ‘payment.php’;
    $return_post[‘errors’] = $hsbc_api->errors;
    }
    }
    $return_url = URL_ROOT.$return_url;

    $_SESSION[‘return_post’] = $return_post;
    header(‘Location:’.$return_url);
    exit;
    break;
    }
    ?>

    • Paresh August 13, 2009 at 9:18 am #

      Hi

      Can any body help me?
      I am trying to implement HSBC 3-D Secure. i have the existing normal HSBC payment. What do i need to post extra for transection to be 3D-secure, because i am not getting intended responce for eg. CAVV or authentication protocol.
      Or Do i need separate marchant account for 3D-secure?

      I ll be very greatfull if somebody can help me.

      Thanks in advance.

    • Paresh August 19, 2009 at 7:38 am #

      Thank you, but i really cant understand the full process(steps) i found HSBC’s pdf document confusing, and form where from will i get this info

      CardholderPan => $received_data[‘cardnumber’],
      CcpaClientId => ‘UK11111111GBP01′,
      CurrencyExponent => 2,

      and do i have to send this above information first, and then do i have to send info about order and all??

      I am reallly confused.
      Please Help.

  114. Rubel January 28, 2009 at 7:47 am #

    @Alek
    Thank you buddy for your contribution…

  115. arpit February 11, 2009 at 1:00 pm #

    Really a nice stuff man, got very much help from your blog, you must get chance to work in hsbc..lol

    well i have created xml and also i m working with php. but how it will give response me in xml, i m not getting any xml response, how do i check it?

    need help

    thanks,,,,,in advance.
    god bless u.

  116. arpit February 12, 2009 at 11:14 am #

    i am still getting errors, no output at all….

    when i prints the $data it gives me following output.

    1.0 OrderFormDoc 499320ef-eadf-3002-002a-0003ba9a87ff PaymentNoFraud 6 16 Merchant Director Director 3 902 CcxInput.cpp 14:32:10Oct 13 2007 7 6 Insufficient permissions to perform requested operation.
    Austin 840 PTS Auth Test (Level I w/AVS) 78758 TX Metric
    12/12 4111111111111111 Y 100 Auth clientid userid pass 1234437039467 1234437039476

    i have passed my correct userid, clientid and password instead of this, but still it says “Insufficient permissions to perform requested operation.”

    can you please tell me what should i do?
    thanks in advance.

  117. arpit February 12, 2009 at 11:17 am #

    my code is

    <?php
    $xml = <<<XML

    1.0

    OrderFormDoc

    uname
    pass
    clientid

    PaymentNoFraud

    Y

    4111111111111111
    12/12

    PTS Auth Test (Level I w/AVS)
    Metric

    Austin
    TX
    78758
    840

    Auth

    100

    XML;
    $ch = curl_init();
    // $url = “https://www.uat.apixml.netq.hsbc.com”;
    $url = “https://www.secure-epayments.apixml.hsbc.com”;
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_HEADER, 0);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
    curl_setopt($ch, CURLOPT_POST, 1);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $xml);
    ob_start();
    $data = curl_exec($ch);
    curl_close ($ch);
    ob_end_clean();

    print_r($data);
    ?>

    please note: i am inserting my correct hsbc userid, clientid and password instead of the input of xml which i have put.

    thanks in advance..
    need help please…
    i m stucked..

  118. arpit February 12, 2009 at 11:29 am #

    more detailed info
    in my code
    HSBC_USER_NAME
    HSBC_USER_PWD
    HSBC_USER_ID

    i m putting my hsbc user id instead of HSBC_USER_NAME, my password instead of HSBC_USER_PWD and my hsbc client id instead of HSBC_USER_ID

    please help me.
    thanks a lot

  119. Ziko February 18, 2009 at 11:11 pm #

    Thank you Rubel and Alek, very helpful blog, and very helpful message @Alek

    i have small problem
    i need to send German char like
    1- gewählten
    2- über

    must i send the XML in UTF8 or i can send it in charset=iso-8859-1
    and what about if my website use charset=iso-8859-1

    Thanks

  120. mike April 1, 2009 at 9:57 pm #

    Just when i thought it couldn’t get any harder (worldpay), along came hsbc, the cpi documentation should be recycled (an instructions manual with no instructions, might aswell be developer notes). I gave up!

    The api was much easier to get to grips with alas the documentation was a thumbs down and customer serice is like talking to a useless documentation vending machine (that eats your change)!

    Thanks for your post it includes all the info i need short and quick!

  121. hi May 5, 2009 at 2:56 pm #

    guys i keep getting the result code 11 in the PAS result, any ideas ?

    11 . Data submitted or configured in the CCPA has failed validation checks.

    i realy cant see any error in my post

  122. Pons July 18, 2009 at 10:21 am #

    HI everybody,
    I am already using the HSBC API and would like to add the PAS. Is it a proxyweb kind of call (my server calling PAS server) or is it a browser POST direct to PAS and therfore a Javascript application to read their response??

  123. ron July 29, 2009 at 5:28 pm #

    @hi
    did you add the 01 to the end of yr CccpaClientId uk11111111111gbp number. -should be uk111111111gbp01.
    this is required, and is only mentioned once somewhere in the ‘very’ small print of the guides
    i struggled a bit but now got the PAS working, just the AVS to finish…

    • Paresh August 19, 2009 at 9:38 am #

      Thank you, but i really cant understand the full process(steps) i found HSBC’s pdf document confusing, and from where will i get this info

      CcpaClientId => ‘UK11111111GBP01′,

      you have began your code from this:

      $received_data[‘cardexpiryyear’].$received_data[‘cardexpirymonth’],
      CardholderPan => $received_data[‘cardnumber’],
      CcpaClientId => ‘UK11111111GBP01′,
      CurrencyExponent => 2,
      PurchaseAmount => POUND.$received_data[‘thetotal’],
      PurchaseAmountRaw => $_SESSION[‘total_minor’],
      PurchaseCurrency => 826,
      PurchaseDesc => ‘T’,
      ResultUrl => ‘https://’.$_SERVER[‘HTTP_HOST’].$_SERVER[‘REQUEST_URI’].’?step=2′,
      );

      will i get all this info when customer submits after adding card info.?

      and do i have to send this above information first, and then do i have to send info about order and all??

      i am totally new to this.

      I am reallly confused.
      Please Help.

  124. Jon August 20, 2009 at 10:23 am #

    This page has been 100 x more useful than all the HSBC document. Big thanks to everyone who has posted help here.

    I thought it would be good to post a few of my observations from setting this up on our systems.

    1) Insufficient permissions to perform requested operation.

    THIS IS VERY MISLEADING it seems to be a catch all error code for a number of issues. Very unfriendly and wasted a lot of my time chasing some of these bugs.

    2) Check your XML first.

    One silly mistake I made was not to always check my XML when there was a problem. For those of you new to XML the easiest way to do this is to capture your XML and save it to a file hsbc.xml then open this in IE (or any other browser/program that will test xml). If everything is fine it will show all the fields, otherwise it will highlight any problems. Any problems with the XML will cause the error message in point 1.

    3) HSBC email support.

    I’ve found our email support from HSBC to be not bad, a bit basic but gave me the info needed get round the current problem. Then again we got our branch manager involved who would phone up and hassle them, if you can always try and get branch staff to shout at their tech staff if they are not helpful 😉

    4) Testing, 123…

    Mode Y is their testing mode,

    Once finally getting a reasonable response from the server it was full of these….

    AdvisedAction – 48
    Audience – Administrator
    Component – CcxFraudShield
    ContextId – FraudShield
    DataState – 3
    FileLine – 1776
    FileName – CcxProcessFraudRules.cpp
    FileTime – 14:36:08Oct 13 2007
    ResourceId – 1043
    Sev – 2
    Text – Rule ‘Non UK Billing/Card 5.9/5’ from strategy ‘UK CNP’ owned by StrategyOwnerId ‘1’ for a transaction for client ‘9941’ could not be evaluated : Key ” was not found in the document. The action taken is: ‘0’.

    HSBC said…

    The messages you receive stem from the fact that ‘these fields’ [no reference to which fields!!] are not present in the XML document.
    The system does not contact the card issuing bank during test phase,hence it is not able to provide values for Address or CVV2 checks.
    These messages are just for your information and they do not create an impediment for the transaction. Once you start processing ‘Live’ transactions these messages would not be present in the response XML.

    Despite this being a test and failing as a test should….. I was amazed when our account department phoned me up and said “What on earth have you been doing?”. All the successful test amounts had shown up on our account, they had pages of 1p transactions from my playing around trying to find out what the above errors meant. They all showed up as ‘Captured’.

    5) In summary.

    I think the HSBC API is actually not that hard to set up, it’s just that the documentation, error messages and server responses are rubbish. Also the lack of a real test environment does not help. We are due to go live in a few weeks and I’m still not 100% sure that it will all work or what to expect as a good valid responce from the server.

    If anyone can post up here what XML to expect back from the HSBC server for a successful transaction with no problems that might help a few people, me included.

    • peter October 11, 2011 at 3:29 am #

      Hi,
      I set the Mode=”P” on the real URL:”https://www.secure-epayments.apixml.hsbc.com”, And I used Visa CreditCard , I input the Cvv2Val ,Expires ,Number into the request XML. Also ,I used the real ClientId ,Name ,Password .

      unfortunately, The response XML display as follow:

      6

      16
      Merchant
      Director
      Director
      3
      993
      CcxInput.cpp
      00:31:10Jan 28 2011
      7
      6

      Insufficient permissions to perform requested operation.

      What can I do ,help me

      • peter October 11, 2011 at 3:30 am #

        Thank you very much

  125. Rubel August 20, 2009 at 11:00 am #

    Thnx Jon

  126. Deepak kaushik September 24, 2009 at 10:36 am #

    This is code is very good to integrate hsbc payment gatways

    Thanks

  127. Deepak kaushik September 24, 2009 at 1:45 pm #

    This is code is very good to integrate hsbc payment gatways .

    Thanks

  128. Deepak kaushik September 24, 2009 at 1:49 pm #

    i am use your code which you mention
    the ouput is:

    6

    16
    Merchant
    CcxXmlInput.A
    System
    1
    766
    CcxXmlInstance.cpp
    14:55:53Oct 13 2007
    3
    6
    Unable to locate 'DocVersion' in 'CcaVariantMap01'.

    what is it mein.

  129. soumik October 7, 2009 at 7:48 pm #

    hi,
    as noted by someone in this thread earlier, i am also getting the result code 11 in the PAS result when i do a form submit to send the merchant http post. However if i do curl to https://www.ccpa.hsbc.com/ccpa with the same set of values urlencoded, i get the right response code.
    The merchant http post looks like the following

    [CardExpiration] => 1009
    [CardholderPan] => xxxxxxxxx0006
    [CcpaClientId] => UK34xxxx31GBP01
    [CurrencyExponent] => 2
    [PurchaseAmount] => £31.89
    [PurchaseAmountRaw] => 3189
    [PurchaseCurrency] => 826
    [ResultUrl] => …..

    Is it the pound symbol which is making the difference? Can anyone give me any hint of what is going wrong when i submit the data through a form? I have been really stuck with this for the last two days and would be immensely grateful to you.

    Thanks
    Soumik

  130. Rubel October 8, 2009 at 6:02 am #

    Finally I have create a HSBC Payment Class. I have put all to gather here(API + PASS).

    You can download it.. It’s pretty easy
    HSBC Payment Class

  131. soumik October 8, 2009 at 5:34 pm #

    @Rubel
    Many thanks.

  132. Udana October 20, 2009 at 1:18 pm #

    Thank you Very much .. This Thread realy helped me lot…

    why cant we test AVS in Test mode (Y) ?

  133. Rubel October 20, 2009 at 2:17 pm #

    You can run PAS on test mode

  134. Udana October 21, 2009 at 4:32 am #

    yes i can run PAS in test mode. But i can’t run AVS in test mode. why is that?

  135. Rubel October 21, 2009 at 4:41 am #

    No Idea. It might be for their owen security. lolz

  136. Udana October 21, 2009 at 5:11 am #

    ya , what ever thank you very much for this thread.
    I did all with PAS and AVS . Thanks to all who posts comments here..

  137. Udana November 17, 2009 at 7:47 am #

    I have a problem.
    we send them PAS responce with the pre auth request.
    we send them PayerTxnId as “wkzGChOIhEGRtjbvehl+eIubR2M=” as this.
    there error message is :
    PayerTxnId ‘wkzGChOIhEGRtjbvehl eIubR2M=’ is not in a valid base64 encoding.
    “+” sign has replaced with a space. This issue comes only when there’s a “+” sign in there pas responce.

    I can’t figure out the issue. I feel when we post the request through CURL this happens.

    any Idea?

  138. ashish December 18, 2009 at 11:54 am #

    i am not able to connec twith secure payment gate way and not getting any response anybody can help me

  139. Ziggy January 27, 2010 at 8:35 pm #

    You sir are a star… multiply amount by 100?!?!?!?!?!?!?!?! WTF?!?!?!?!?!?!? stupid hsbc and their lack of documentation… what a steaming pile of ****

  140. lin February 1, 2010 at 3:19 pm #

    hi,

    what will i do with ccparesultscode 3?

    Please help me with that.

    Thanks.

  141. Yanni February 8, 2010 at 12:05 pm #

    Anything extra we need to do to implement the 3D -Secure code ?

  142. Abrett February 10, 2010 at 4:05 am #

    I have been trying to implement the HSBC API and CPI solution for two of my clients. THE API documentation is pathetic , too much information thrown at you without a single word that means anything. As for 3D secure , that is a pain in the a**. I had sent an email to the helpdesk, surprisingly I got help from a person named Ashvin.
    I didn’t expect those people to help me ,but it came a a surprise,anybody who has any issues , I would suggest you speak to that person , at least he is the only one who talks some sense. you can get a lot of help regarding 3D secure and API. I had some of my questions on the CPI Integration, as it wa giving me some problems in ASP.net and IIS 6.0. This guy is some Senior Integrator there,but good one if you want to make any sense of the guides….but don’t expect too much …haha these guys have their support boundaries…

  143. char March 10, 2010 at 11:34 am #

    Hi,

    I have made PAS successfully processing but I cannot extract XID and CAVV..

    Can anybody help me?

    thanks.

  144. Phill March 11, 2010 at 9:08 am #

    I have developed both API and CPI ecommerce website and cant believe the lack of support that HSBC provide. Further more HSBC systems are very unstable and are prone to general failure such as payment will fail to be processed or their internal web pages will fail to load. My advice is go for PayPal they actually provide documentation and flexible options for integration. As for the documentation; it has been written as a schematic blueprint by someone who dost care about any practical service development, probably someone with too much higher education real industrial experience. I have 60 web ecommerce customers and now strongly advise them to not use HSBC. But to be fare there are a number of solutions out there such as SagePay who are just as bad when it comes to service… one day they will realise that they have competition and actualy become customer firendly.

  145. Kashif Murtaza April 18, 2010 at 12:12 am #

    Hi There,
    is there complete documentation about “Verified By Visa and Maestro Securecode Integration” for HSBC using php.
    Best Regards
    Kashif Murtaza

  146. Nishad April 21, 2010 at 1:12 pm #

    Hello,
    Could you please give me a test debit card details for tesing debit card payments.
    How will I send Card holder Name and Address of Billing to HSBC.

    Thanks in advance for help..

    Regards
    Nishad Aliyar

    • Rubel April 29, 2010 at 9:51 am #

      Number = 4055011111111111
      Cvv2Val = 345

  147. Nishad April 30, 2010 at 5:04 am #

    Hi Rubel

    Thanx for you help, I got the card details from HSBC..
    I have implemented HSBC payment system using this class and its working fine in test environment for both credit card and Debit card.
    But when I try to make this live , I got an error like this.

    For Payer Authentication with PayerSecurityLevel=2 or PayerSecurityLevel=6 PayerAuthenticationCode must be present.

    Could you please clarify the reason for this error?
    Whether needed to make any settings in my bank account to support live transactions?

    Regards
    Nishad Aliyar

    • Mark Constantine May 27, 2011 at 2:53 pm #

      I had the same issue and the way i solved this was the remove the DataType=”String” just in the xml payer sections.

      Weird, but seemed to do the trick.

  148. Dave June 15, 2010 at 9:58 am #

    Hey there,
    Just wanted to say thanks for posting this.

    HSBC docs suck big time and I was doubtful I’d get my project finished (client is with HSBC) on time while messing around with them
    Your code helped me get started and my payment portal is up and running.

    So big thanks for posting!

  149. Rubel June 15, 2010 at 1:25 pm #

    😀

  150. Mydaya October 16, 2010 at 4:59 pm #

    Hi Rubel !

    Thank you very much for your hard work ! I think I would die without your post !
    Little by little, I managed to have less and less errors, however, it doesn’t seem to work ;__;

    So I would like to know some things :
    1. Is it impossible to use a debit card ? Because I have just this type of card so I can’t run tests if there is no possibility.
    2. I have same errors of some people who post there : Insufficient permissions to perform requested operation. (so I haven’t TransactionStatus) However I check and check again : I can connect to the HSBC account with the logins gived so they don’t seem to be the problem. For the moment, I give the logins to the xml without encoding them. Is that the problem ? How can I do that ? Or is there others reasons to fail ?

    I’m gonna be kill by my boss so I just continue to try until monday =__=
    Thanks in advance if you can help me !

    Mydaya

    • Mydaya October 16, 2010 at 5:05 pm #

      Sorry I forgot one more question :

      3. Is it possible to run test on local with the testing modes ?

      Thanks,
      Mydaya

      • Rubel October 16, 2010 at 6:48 pm #

        To implement HSBC payment you must have a valid account account and better not to use local host for testing.

  151. Dale Wilson January 20, 2011 at 3:21 pm #

    After reading your documents and blogs I have now successfully got the HSBC PAS/API working, however when I test out several of my own credit cards/debit cards I always get a response code of ‘Approved’ but some of my cards have 3d-secure accounts so shouldnt I be asked for a cardholders password somewhere? or have i misunderstood?

  152. deepak February 2, 2011 at 7:12 am #

    Nice post,

    Please tell me one thing while using the API it is required to have ssl on our site, or we can post the request from any http page, or it is necessary to have https to send the request????

    • Rubel March 11, 2011 at 12:50 pm #

      you can implement in Non Secure page.

  153. sky cards February 5, 2011 at 4:26 pm #

    Will try this in pho now and let you know my results

  154. deepak March 11, 2011 at 8:23 am #

    Hi,

    Thanks for you post, it helps me a lot, but i m getting some errors like

    1) Rule ‘Invalid Billing Post Code/12’ from strategy ‘UK CNP’ owned by StrategyOwnerId ‘1’ for a transaction for client ‘37268’ could not be evaluated : Key ‘BillToPostalCode’ was not found in the document. The action taken is: ‘0’.

    2) Rule ‘Invalid Billing City/11’ from strategy ‘UK CNP’ owned by StrategyOwnerId ‘1’ for a transaction for client ‘37268’ could not be evaluated : Key ‘BillToCity’ was not found in the document. The action taken is: ‘0’.

    and few more like this.

    can u give me the full XML document so that i can accomplish this task

  155. Farukh March 28, 2011 at 4:50 pm #

    Need Help:
    System was down so got this from HSBC:
    “The SSL certificate on API had to be renewed due to which merchants having any old certificates on their server are facing a problem. The old certificates on their server are not able to trust our new certificates.”
    Any information on how to add the new certificate,
    Thank

  156. Nestor Sulu June 25, 2011 at 3:07 am #

    Besides poor documentation, you can add the CPI is totally outdated. We do the Microsoft way, and in 2011 they only have a sample for classic ASP and C code… but not ASP.NET (and forget MVC!) and not C#… it was very hard to find out how to code it, and yes, helpdesk is not help :), after too much effort and time invested we are closer to have it working (we hope so).

  157. peter September 28, 2011 at 1:04 pm #

    Hi,
    1. If the card used to make a purchase is a Maestro or Solo card, the IssueNum and StartDate fields must be specified, and the Expires should also be specified ?

    2.When I set Transaction Type is Auth or PreAuth ,The Expires and Number must be specified ?

    3.When I set Transaction Type is Auth or PreAuth, and The consume card is Maestro and Solo card , the card information such as :Expires ,Number, IssueNum, StartDate must all be Specified?

    4.Can HSBC’s payment API support Debit Card Consume?Does Solo,Maestro stand for debit card ?

    5. What the difference between Auth and PreAuth?

    Please help me !

    I am puzzled by this .

    • Malinda March 8, 2012 at 3:27 am #

      If you can send me the code you use. I can help you.

  158. Malinda January 12, 2012 at 8:13 am #

    I sorted out that HSBC 3d secure integration Now It’s work fine 🙂 if you have anything regarding HSBC 3d secure implementation with the secure API feel free to drop me a mail (malindar11@gmail.com) 🙂

  159. JageshMK February 10, 2012 at 5:48 am #

    hi can you explain how to use this xml code in magento

    • Rubel June 7, 2013 at 6:13 am #

      I have explained the basic process of the API. This XML is not related to Magento XML. Create a new Payment method in Magento and use this XML to pass data in HSBC server.

  160. Dss April 16, 2012 at 7:26 pm #

    Hurray! HSBC has announced they are dropping this crap API and switching to RealEx’s API system.

  161. b.koteswara rao June 7, 2012 at 5:32 pm #

    sir. hsbc credit card is retuned due address not properly enquired. please send my hose address.b. koteswara rao . plot no 15 and 16 brundavan colony .kamalanagar. vansthalipuram hyderabad.

  162. sainul August 29, 2012 at 2:45 pm #

    Can any one tell me the problem

    6

    16
    Merchant
    CcxXmlInput.A
    CcxXmlInput
    1
    793
    CcxXmlInstance.cpp
    13:30:24Jul 14 2009
    8
    6
    The HTTP method received is not valid. Only POST is accepted.

  163. asian massage December 3, 2012 at 9:52 pm #

    A lot of fantastic material composed here you really should be a
    fulltime blog writer doubtlessly? ! ?

  164. 8tracks.com December 8, 2012 at 8:47 am #

    Its like you learn my thoughts! You appear to grasp so much approximately this, such as you wrote the guide in it or something.

    I feel that you could do with some percent to force the message home a bit, but other than that, this is wonderful
    blog. An excellent read. I’ll certainly be back.

  165. haarausfall bei katzen im kopf December 21, 2012 at 8:46 pm #

    Hello there! This post could not be written any better!
    Reading this post reminds me of my previous room
    mate! He always kept talking about this. I will forward this write-up to him.
    Pretty sure he will have a good read. Thanks for sharing!

  166. Staci February 15, 2013 at 1:55 pm #

    Terrific post however , I was wanting to know if you could write a litte more on this
    subject? I’d be very grateful if you could elaborate a little bit more. Cheers!

  167. management articles May 31, 2013 at 3:50 am #

    whoah this blog is wonderful i really like reading
    your articles. Keep up the great work! You realize,
    a lot of individuals are searching around for this info, you can aid them greatly.

  168. www.fiql.com June 2, 2013 at 8:19 pm #

    Hello! I could have sworn I’ve been to this blog before but after browsing through some of the articles I realized it’s
    new to me. Nonetheless, I’m definitely happy I found it and I’ll be bookmarking it and checking back often!

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: