Secure ePayments Card ProcessingCPI Integration Guide

Version 1.0

“COPYRIGHT. HSBC HOLDINGS PLC 2003.All rights reserved. No part of this publication may be reproduced, stored in a retrieval system,or transmitted, on any form or by any means, electronic, mechanical, photocopying, recording,or otherwise, without the prior written permission of HSBC Bank plc”

ContentsAudience 1

About this guide 1

Introduction 2

Background 2

Verified by Visa and MasterCard 2SecureCode Support

Address Verification Service 2

CPI integration software requirements 3

Testing the integration 3

Secure ePayments 4high level flow

Integration 5

Pre-Integration tasks 5

Integration requirements 5

CPI Hash Key 5

Implementing OrderHashes 5

Multi-currency 6

Merchant / CPI data exchange 6

Generating the merchant POST 6

Billing / delivery information 7

Handling the CPI return POST 7

Appendix A 8

Glossary 8

Appendix B 9

POST specifications 9

The merchant POST 9

Merchant security and order details 9-11

Billing information 12

Delivery information 13

CPI returned POST 14-15

CPI Returned OrderHash 15

CpiResultsCode breakdown 16

Appendix C 17

Example code 17

Java code sample 17

C code sample 18

Sample HTML form code 19

CGI code sample 20

Appendix D 21

OrderHash Generation 21

Appendix E 22

Currency codes 22

Appendix F 23

Country codes 23

Appendix G 24

Supported encryption technologies 24

Appendix H 25

Store administrator tool 25

Index of Figures

Figure 1 Secure ePayments 4high level flow outline

Index of Tables

Table 1 Merchant security 9-11and order details

Table 2 Billing information 12

Table 3 Delivery information 13

Table 4 CPI returned POST – 14obligatory returned fields

Table 5 CPI return POST – 14optionally returned fields

Table 6 CpiResultsCode values 16

Table 7 Currency Codes 22

Audience

This document is intended for use by:

• merchants integrating the HSBCCardholder Payment Interface (CPI)

• merchants’ web development partners(third party integrators)

About This Guide

This guide is designed to provide our Internetmerchants details of the integration process oftheir storefront(s) with the HSBC CPI.It contains a description of the process,along with detailed coding examples tosimplify integration.

Note: A working knowledge of HTML andscripting/programming languages is required to integratethe HSBC CPI service and understand this document.

1

Introduction

2

Background

This guide describes the requirements toallow Secure ePayments to processtransactions in real-time via the CardholderPayment Interface (CPI).

Secure ePayments has been designed tointegrate with a merchant store via theHSBC CPI to provide a securecheckout environment.

The CPI is an HTML-based integration.The service allows both standard HTMLpages and secure (SSL) HTML pages to callSecure ePayments.

To enhance security of transactionalinformation, Secure ePayments employs thehighest levels of encryption for connections,and utilises encoded check values(OrderHashes – see page 5 for a detaileddescription) designed to preventdata tampering.

Secure ePayment provides a secure CPIcheckout solution to:

• present payment pages to cardholders,requesting card details (and optionallybilling/delivery information –see page 7for more information)

• submit transactions for real-time processing• present order confirmations• return cardholders to the merchant store

The CPI interfaces with the HSBC paymentengine to perform payment authorisation, inaddition to enabling the Payer AuthenticationSystem (PAS) to provide cardholderauthentication via the Verified by Visa andMasterCard® SecureCode™ technologies.

The CPI also interfaces with the AddressVerification Service (AVS) to further assist indetection of potential fraudulent transactions.

Verified byVisa and MasterCardSecureCode support

The CPI supports the Verified by Visa(3-D Secure) and MasterCard SecureCode(UCAF) technologies.

Merchant stores will have been pre-configuredwith merchant participation status forthese schemes.

Address Verification Service

The Address Verification Service (AVS)verifies whether the billing street address andpostcode supplied by a customer at an onlinestore match corresponding data on recordat the card issuing authority.

The CPI forwards the billing street addressand postcode data to the card-issuingauthority, where this information is comparedagainst database information for that customer.The card issuing authority then returns anindustry standard AVS check result.

An authorisation does not fail because of anAVS address or postcode mismatch.

Address verification forms part of HSBC’sfraud detection system and can automaticallyplace a transaction in a Review state. If thisoccurs the merchant can still accept the order,however, they may wish to contact thecardholder for further verification checks.

Note: Some addresses, such as military, BFPO addressesor non-UK addresses can be in a number of differentformats. Consequently, such addresses might not beverified by AVS. In addition to this some card types donot participate with this service for example Corporateor Purchasing cards.

For more information, please refer to the ‘SecureePayments Card Processing Risk Management Guide.’

CPI integration software requirements

The merchant POST (as detailed on page 9)and the CPI return POST (page 14) bothrequire HTTP1.1/SSL connections to beestablished with the secure HSBC CPI server.

The C library is supported on thefollowing platforms:

• HP-UX 11.0 and 11.2• Sun Solaris 2.7 and 2.8• Windows 2000The Java API supports Java Virtual Machine1.2.2 on the platforms listed below. In addition,Java 1.3 is supported under the 1.2.2 compileron the same platforms:

• HP-UX 11.0 and 11.2• Sun Solaris 2.7 and 2.8• Microsoft Windows NT 4.0 and

Windows 2000

Testing the integration

A merchant is required to have an HSBC cardprocessing Internet merchant accountin order to use Secure ePayments prior toaccessing the CPI for testing.

3

Secure ePayments high level flow

Figure 1 Secure ePayments high level flow outline

Notes:

POST 1 is the merchant POST and contains the configuration and order details; see Appendix B for a detaileddescription of the data required in this POST.

POST 2 is the CPI returned POST and contains the results of the authorisation request; see Appendix B for a detaileddescription of the data this POST contains.

POST 2 is sent from the Secure ePayments Server to the CpiDirectResultUrl to the merchant specified in POST 1.

In the last stage, the customer is returned from the Secure ePayments Server to the CpiReturnUrl to the merchantspecified in POST 1.

An optionally supplied session identifier will be returned, allowing the merchant to associate the cardholder with the order.

4

Cardholder has completed shoppingat the merchant site and has selected‘buy now’ or the equivalent option.

The merchant site displays theorder confirmation screen to the

cardholder and inserts theOrderHash in POST 1.

OrderHash and POST 1contents verified

CPI screens displayed, cardholderpayment/address information

collected. Authorisation(Verified by Visa/MasterCard

Secure Code) attempted.

Transaction authorisation occurs.The results of the authorisationare sent back to the merchant

web site in POST 2.

Transaction confirmation screendisplayed to the cardholder.

Cardholder redirected back to themerchant site when ‘Close’ selected.

The merchant site employs anoptional CGI program to handle

the returned data.

Cardholder returned to themerchant web site.

Merchant website Secure ePayments

POST 1

POST 2

IntegrationPre-Integration tasks

Prior to integration of a merchant web serverwith the CPI service, merchants are stronglyencouraged to examine the potential impact ofthe integration upon their systems.

For example, merchants will have to:

• identify integration points within theircurrent web server architecture

• determine required software updates 1• assess potential security impacts• examine current contingency plans

for possible modification

Notes:

The above list is for guidance only and is not meantto be comprehensive.

1 Software updates/amendments must be performedat a Merchants’ own risk, HSBC cannot be heldliable for any problems/impacts associated withinstalling/updating third party software.

Integration requirements

Merchants are required to have completedthe application for card processing throughHSBC, and have in their possession thefollowing information:

• merchant User ID(sent by email or letter)

• Client Alias / Store ID number(sent by email or letter)

• CPI Hash Key (sent by letter)• password (provided by the merchant

to HSBC during initial sales process).

Note:

Merchants will have received a ‘Customer verificationregistration form’ with their initial set-up documentation.It is very important that this form has been completed andreturned to HSBC. If this form is not returned correctly,a merchant will not be eligible for telephone supportfrom HSBC.

CPI Hash Key

A merchant will have received, by letter, a copyof the CPI Hash Key (shared secret) relatingto Secure ePayments.

It is important that this informationremains confidential.

The CPI requires that the merchant usea small software library to generate aMessage Authentication Code (MAC) usingthe order information, this MAC is knownas an OrderHash.

The CPI Hash Key is an essential piece ofthe MAC process, and must be located in asecure (not externally accessible) location inthe merchant’s web site.

Implementing OrderHashes

The OrderHash is created with a single librarycall (which is available in either C or Java –for supported platforms see page 3).

A list of (string) data is sent, with the CPI HashKey, to the library and a resultant OrderHashis returned.

The order information and the generatedOrderHash are then submitted to the CPIserver. The CPI then attempts authenticationof the supplied OrderHash, to verify theintegrity of the order data received.

A detailed example of OrderHash generationis given in Appendix D.

5

Multi currency

A merchant has the option of acceptingpayments in other currencies than UKSterling. Each currency option will besupplied with a corresponding shared secret.For example, a merchant accepting UKSterling, US Dollars and Euros would beprovided three shared secrets.

Each shared secret is currency specific. Creatingan OrderHash using the UK Sterling secretwhen submitted a US Dollar transaction willcause a validation error on the CPI server –the transaction will be rejected.

It is the merchant’s responsibility, as detailedpreviously, to keep all shared secrets confidential,and in secure locations within their websites.

Merchant / CPI data exchange

Information between the merchant’s websiteand CPI is transmitted via a secure POST(HTTPS) operation. The merchant websiteand the CPI are required to generate anOrderHash to help ensure the validity ofthe data being transmitted.

The merchant website and the CPI perform thefollowing steps to generate and validate data.

• The merchant’s website collects data aboutan order and information necessary forprocessing the order with the CPI and thePayment Engine. Billing and deliveryinformation is optional.

• The website calls a program that generatesan OrderHash value based on the data tobe submitted to the CPI. (Sample programsare shown in Appendix C – Java codeexample on page 17 and C code exampleon page 18.)

• The website sends the OrderHash valueand all other applicable information to theCPI via a secure POST operation.

• As the CPI validates the input, itgenerates its own OrderHash value. Ifthe submitted OrderHash value does notmatch the generated value, the order isimmediately rejected.

• After the CPI has processed the order,it generates a new OrderHash value basedon the return fields. The OrderHash valueand other return fields are returned to themerchant via another secure POST.

• The merchant’s website should generate anew OrderHash value based on the returndata to confirm the validity of the data.(The returned OrderHash value must beexcluded when generating the confirmationOrderHash value.) The website shouldreject the order if the return OrderHashvalues do not match.

Generating the merchant POST

The merchant submits all order information,including the signed hash, to the CPI usinga secure (SSL) POST.

The POST can contain three types of data:

• merchant security and order details• billing information• delivery information

Merchant security and order details arecompulsory (the OrderHash is includedin this category).

6

Billing / delivery information

Merchants may wish to collect thecardholder’s personal details themselves (forfuture use), or they may already have thedetails ‘on file’ (for example, if a cardholderhas previously registered with a store).

Consequently, a merchant will have decided,during the sales process, if they want theCPI to gather the cardholder’s billing anddelivery information.

If the CPI is configured for payment detailsonly, the merchant must decide whether toPOST all, or none, of the billing and deliveryinformation in their possession.

HSBC actively maintains a complex list offraud rules for assisting in determination ofpotential fraudulent transactions.

A number of these rules may involve the useof the Address Verification Service (AVS)response. If no billing / shipping informationhas been provided through the merchantPOST, and if the CPI has been configured notto collect such information, then AVS checkscannot occur, and this may impede theautomated detection of potential fraud.

It is therefore highly recommended thatthe merchant submit billing and deliveryinformation via the merchant POST if theyhave opted to collect such informationthemselves.

Note: If one billing field is submitted, then all requiredbilling fields must also be submitted. The same appliesfor delivery fields; if one field is submitted, all otherrequired fields must also be submitted.

Full details of the data that can be submitted via themerchant POST (field name, usage, and restrictions) aregiven in Appendix B.

Handling the CPI return POST

After Secure ePayments has processed anauthorisation request, the outcome of thetransaction is returned to the merchant toenable, for example, automatic orderfulfilment. (See Figure 1 on page 4 to viewwhen this process occurs – POST 2).

The authorisation result will be returned tothe URL (CpiDirectResultUrl) supplied in theoriginal POST.

If the store is designed to automaticallyprocess the return POST, a CGI program(or equivalent handler) must be able to acceptthe case-sensitive data returned by the CPI.Full details of the returned data are given inAppendix C.

Once the storefront has received theauthorisation decision, Secure ePaymentswill present the order confirmation screento the cardholder. When the customer thenpresses ‘close’ to leave the service, they areredirected to a page designated by themerchant (the CpiReturnUrl designated inthe original POST).

7

Appendix AGlossary

AVSAddress Verification Service. A service usedto verify that the billing street address andpostcode supplied by the cardholder, matchthe data on record at the card issuing bank.Benefits of using AVS include enhancedfraud protection.

CPICardholder Payment Interface. The HSBCsecure environment, integrated with amerchant website, for accepting cardholderinformation and returning authorisationresults to the merchant.

HTMLHyperText Mark-up Language. Platformindependent language for specifying content,formatting and links between web pages.

PASPayer Authentication System. HSBC processingsystem for ‘Verified By Visa’ and ‘MasterCardSecureCode’ that integrates into merchantstorefront applications via the CPI, and isused to authenticate cardholders.

MasterCard SecureCodeMasterCard’s security service for cardholderauthentication during a purchase transactionin e-commerce environments.

SSLSecure Socket Layer. An industry standardsecurity protocol that provides securetransmission of private information sentover the Internet. The protocol providesdata encryption, server authentication,message integrity, and client authenticationfor TCP/IP connections.

Transmission Control Protocol/InternetProtocol (TCP/IP)A protocol for communication betweencomputers, used as a standard fortransmitting data over networks and asthe basis for standard Internet protocols.

Verified by VisaVisa’s security service for verifying cardholderauthentication during a purchase transactionin e-commerce environments.

8

Appendix BPOST specifications

The merchant POST

The following sections describe the fields that can be sent to the CPI in the merchant (secure)POST operation. Sending other information causes the CPI to generate an OrderHash value thatwill not match the value generated (and submitted) by the merchant website.

The merchant POST undergoes character validation by the CPI server. For example, an emailaddress can only contain certain characters, should an invalid character be included the CPIserver will reject the transaction.

Note: The field names are case-sensitive – the CPI server will reject information if the submitted field names are not anexact match to those listed in table 1, table 2 and table 3 below.

Merchant security and order details

The following table lists the fields that can used to calculate the OrderHash and be sent to theCPI. Most of these fields are required.

The merchant can submit a MerchantData field that will be returned along with the authorisationresults. This field can contain any type of data, to a maximum of 512 characters. It may contain,for example, a session ID that tracks a shopper’s activities at the merchant site, detailed informationrelating to a particular shopping basket item etc.

Table 1 Merchant security and order details

Field Name Description Value

CpiDirectResultUrl Required. The URL for 1024 characters maximum.returning data to the merchant. Must begin with https://

CpiReturnUrl Required. The web page to 1024 characters maximum.display on the customer’s web Must begin with https://browser after the CPItransaction is complete.

MerchantData Optional. Any additional 512 characters maximum.data the merchant wants to include in the hash, such assession data.

Mode Optional. Must be one of the Merchants can move from following values: Production mode to Test P – Production mode. The mode at any time.customer will be billed for theorder. This is the default value.

9

Appendix B (continued)

Field Name Description Value

Mode (continued) T – Test mode. Specify this However, only HSBC can value only when you have move a merchant from testmade arrangements with mode to Production mode.the payment processor. 1 character maximum.

OrderDesc Required. A free-form 54 characters maximum 1.description of the order.

OrderHash Required. The value returned 28 characters maximum.from the Hash Generator

OrderId Required. A unique identifier 36 characters maximum.for the order. This value mustbe generated by the merchant.

PurchaseAmount Required. The amount of the 18 digits maximum.purchase, expressed as apositive integer.If the currency containsdecimals, omit the decimalpoint. The Secure ePaymentsServer interprets the valueas having the appropriatenumber of decimal places.For example, a 9999999value in Sterling (GBP),which has two decimalplaces, is interpreted as99999.99 pounds.

PurchaseCurrency Required. The currency code 3 characters maximum.for the order. See AppendixE for information onacceptable values.

StorefrontId Required. The client ID or A valid client ID is a numberclient alias of the Store. between 0 and 999999999.

A valid client alias is of theform UK12345678CUR.The alias name is case sensitive.

10

Notes:1 OrderDesc – Freeform field for merchant use, reserved for future implementation. At present can be ‘zero-filled’

(whitespace/alphanumeric – but not zero-length).

Appendix B (continued)

Field Name Description Value

TimeStamp Required. Date and time of Integer value (currently the purchase expressed as 13 digits in length).the number of milliseconds See note 3 below.elapsed since January 1,1970 00:00:00 GMT.

TransactionType Optional. Must be one of the See note 2 below.following values:Auth – Known as a PreAuthtransaction within theSecure ePayments Server.Capture – Known as anAuth transaction within theSecure ePayments Server.

UserId Optional. A unique identifier 32 characters maximum.associated with a user.

Notes:2 TransactionType:

An Auth transaction places a reserve on the cardholders open-to-buy balance, the cardholder’s available remainsunchanged. Once the goods have been confirmed as ‘shipped’, a merchant will use the Store Administrator tool tomark the order as ‘shipped’. This process then automatically marks the funds ready for settlement.

A Capture transaction verifies the cardholder’s account to be in good standing, and automatically marks thefunds ready for settlement. This is typically used for goods that do not need to be physically shipped (for example,software download).

3 TimeStamp – The window of opportunity for a valid TimeStamp is +/-1 hour from the HSBC CPI server time, basedon the actual time of submitting the merchant POST. All calculations are to be based on GMT time zone.

11

Appendix B (continued)Billing information

The following table lists the billing fields. Billing information is optional, because the merchantcan collect this information from the CPI. However, if one billing field is submitted, then all fieldslisted as required must be submitted.

Table 2 Billing information

Field Name Description Value

BillingAddress1 Required. The first line of 30 characters maximum.the customer’s address.This field typically includesthe street name and numberor box number.

BillingAddress2 Optional. Additional 30 characters maximum.address information.

BillingCity Required. The city in which 25 characters maximum.the customer resides.

BillingCountry Required. The 3-digit 3 characters maximum.country code. See AppendixF for information

on acceptable values.

BillingCounty Optional. The state or 25 characters maximum.county in which thecustomer resides.

BillingFirstName Required. The customer’s 20 characters maximum.first name.

BillingLastName Required. The customer’s 20 characters maximum.last name.

BillingPostal Required. The customer’s 20 characters maximum.postal code.

ShopperEmail Required. The customer’s 30 characters maximum.e-mail address.

12

Appendix B (continued)Delivery information

The following table lists the delivery fields. Delivery information is optional, because the merchantcan collect this information from the CPI. However, if one delivery field is submitted, then allfields listed as required must be submitted.

Table 3 Delivery information

Field Name Description Value

ShippingAddress1 Required. The first line of 30 characters maximum.the recipient’s address. This field typically includes thestreet name and number or box number.

ShippingAddress2 Optional. Additional 30 characters maximum.address information.

ShippingCity Required. The city in which 25 characters maximum.the recipient resides.

ShippingCountry Required. The 3-digit 3 characters maximum.country code. See AppendixF for information onacceptable values.

ShippingCounty Optional. The state or 25 characters maximum.county in which the recipient resides.

ShippingFirstName Required. The recipient’s 20 characters maximum.first name.

ShippingLastName Required. The recipient’s 20 characters maximum.last name.

ShippingPostal Required. The recipient’s 20 characters maximum.postal code.

13

Appendix B (continued)CPI returned POST

When the CPI has completed its series of tasks, the PurchaseDate and CpiResultsCode fields arealways returned to the storefront via a secure POST to the merchant’s website.

The PurchaseDate field indicates the date and time of the purchase as the number of millisecondselapsed since January 1, 1970 00:00:00 GMT.

Table 4 CPI returned POST – obligatory returned fields

Field Name Description Value

CpiResultsCode Transaction status Numeric value between0 and 16. See separate table onpage 15 for more information.

PurchaseDate Processing date and time System generated.of the purchase expressed Integer value (currently as the number of 13 digits in length),milliseconds elapsed since based on GMT time zone.January 1, 197000:00:00 GMT.

In addition to the two fields detailed above, the CPI, assuming that they were contained withinthe merchant POST, will return the following fields:

Table 5 CPI Return POST – optionally returned fields

Field Name Description Value

MerchantData Merchant security and 512 characters maximum.order details

OrderHash System generated. See CPI 28 characters maximum.returned order Hash section(page 14) for more information

OrderId Merchant security and 36 characters maximum.order details

PurchaseAmount Merchant security and 18 digits maximum.order details

PurchaseCurrency Merchant security and 3 characters maximum.order details

14

Appendix B (continued)

Field Name Description Value

ShopperEmail Billing information 30 characters maximum.

StorefrontID Merchant security and 13 characters maximum.order details

In order to avoid the possibility of data tampering, merchants are advised to check the validity ofthe CPI returned POST fields by comparing them to the information they originally sent withinthe merchant POST.

CPI returned OrderHash

The CPI returned OrderHash is constructed from the other data returned within theCPI returned POST.

To check the validity of the CPI returned POST OrderHash (and to check the data integrityof the returned information), a merchant is advised to create a second OrderHash using thereturned information (excluding the CPI returned OrderHash). The merchant will generatea new OrderHash, and then compare with the CPI returned POST OrderHash.

With a successful comparison of the OrderHash values (and comparisons of the other returnedinformation, for example the original MerchantData and returned MerchantData fields),a merchant will be able to deduce if data tampering has occurred, and construct an appropriateresponse to the situation.

15

Appendix B (continued)CpiResultsCode breakdown

The CpiResultsCode field indicates the transaction result. The following table lists the possiblereturn values of the CpiResultsCode field:

Table 6 CpiResultsCode Values

Code Description

0 The transaction was approved.

1 The user cancelled the transaction.

2 The processor declined the transaction for an unknown reason.

3 The transaction was declined because of a problem with the card. For example,an invalid card number or expiration date was specified.

4 The processor did not return a response.

5 The amount specified in the transaction was either too high or too low for the processor.

6 The specified currency is not supported by either the processor or the card.

7 The order is invalid because the order ID is a duplicate.

8 The transaction was rejected by FraudShield.

9 The transaction was placed in Review state by FraudShield.1

10 The transaction failed because of invalid input data.

11 The transaction failed because the CPI was configured incorrectly.

12 The transaction failed because the Storefront was configured incorrectly.

13 The connection timed out.

14 The transaction failed because the cardholder’s browser refused a cookie.

15 The customer’s browser does not support 128-bit encryption.

16 The CPI cannot communicate with the Secure ePayment engine.

Note:1 When a transaction is placed in ‘Review’ state by FraudShield, it can be authorised, but it cannot be settled until

it is reviewed by a merchant administrator and either accepted or rejected. For more information on reviewingtransaction, refer to the Store Administrator Guide.

16

Appendix CExample code

Java code sampleNote: Supported platforms for the Java package are outlined in the CPI integration software requirements on page 3.

The Java package contains the com.clearcommerce.CpiTools.security. HashGenerator class, whichcontains one public method, generateHash( ). This method generates a base64-encoded hash fromthe specified vector and key.

The params argument is a vector of strings. The key argument is the CPI Hash Key sent by letterto the merchant. The syntax of this method is as follows:

public static String generateHash( Vector params, String key )

The following example code illustrates the use of the HashGenerator class.

import java.lang.*;import java.util.*;importcom.clearcommerce.CpiTools.security.HashGenerator;

class HashTest{

public static void main( String argv[] ) throws Exception{

if ( argv.length < 2 ){

System.err.println("Usage: HashTest encryptedKey hashElement..." ); return;

}

String encryptedKey = argv[ 0 ];Vector hashElements = new Vector( );for ( int i=1; i

Appendix C (continued)C code sampleNote: Supported platforms for the C library are outlined in the CPI integration software requirements on page 3.

The CcCpiTools.h file contains two functions. The GenerateHash function creates a base64-encodedhash of the specified parameters using a specified key. The function returns a pointer to the hashif successful, or NULL if the case of a failure. Its syntax is as follows:

GenerateHash(char **params, const char *key );

The params argument is a NULL-terminated array of C strings. The key argument is the CPIHash Key sent by letter to the merchant. The DestroyHash function deletes a hash created byGenerateHash function. Its syntax is as follows:

DestroyHash(char *hash );

The following sample code illustrates the use of the OrderHash functionality.

/* TestHash.c */#include #include

int main( int argc, char **argv ){

char *strEncryptedKey;char **ppHashElements;char *strHashValue;int rc = 0;if ( argc < 3 ){

fprintf( stderr, "Usage: TestHash encryptedKeyhashElement...\n" );return 1;

}strEncryptedKey = argv[ 1 ];ppHashElements = &argv[ 2 ];

strHashValue = GenerateHash( ppHashElements, strEncryptedKey );

if ( !strHashValue ){

fprintf( stderr, "Error generating hash!\n" );rc = 2;

}else

{fprintf( stdout, "Hash value: %s\n", strHashValue );}

DestroyHash( strHashValue );return rc;}

18

Appendix C (continued)Sample HTML form code

The following sample code contains basic HTML form information that could be used toconstruct the merchant POST. The sample form data supplies the CPI with all (required andoptional) merchant security and order details. If a merchant had chosen to collect billing anddelivery information, more data fields would need to be supplied for maximum fraud prevention(see page 7 for more information).

Result Url: Return Url: Merchant Data: Mode: Order Description: Order Hash: Order Id: Purchase Amount: Purchase Currency:

Storefront Id:

Time Stamp:

Transaction Type:

User Id:

19

Appendix C (continued)CGI code sample

The example code below uses PERL to handle the returned CPI data and appends theinformation to a local results file.

#!/usr/local/bin/perl

if ($ENV{'REQUEST_METHOD'} eq 'POST') {read(STDIN, $buffer, $ENV{'CONTENT_LENGTH'});@datapairs = split(/&/, $buffer);

}

foreach $pair (@datapairs) {local($name, $value) = split(/=/, $pair);$Form{$name} = $value;

}

open ("LOG", ">> results.txt");print LOG "$Form{'CpiResultsCode'} , $Form{'PurchaseDate'} ,$Form{'OrderId'}, $Form{'PurchaseAmount'} ,$Form{'PurchaseCurrency'} , $Form{'ShopperEmail'} ,$Form{'StorefrontId'} \n";close (LOG);

exit;

20

Appendix DOrderHash Generation

The supplied Java and C libraries contain the (public) function GenerateHash.

This function acts on supplied data and generates an OrderHash for further use (eithersubmission to the engine, or validation of returned data).

If the information from the sample HTML form code on page 19 were to be used to generatean OrderHash, the relevant fields would be as follows:

CpiDirectResultUrl https://srvr:8443/cpi/result.jspCpiReturnUrl https://srvr:8443/cpi/return.jspMerchantData SessionId1234567890Mode POrderDesc Item DescriptionOrderId UK11111111GBP_00000001PurchaseAmount 10000PurchaseCurrency 826StorefrontId UK11111111GBPTimeStamp 1041379200000TransactionType CaptureUserId User_000001

The array of data to be sent to the GenerateHash program would be:

{https://srvr:8443/cpi/result.jsp, https://srvr:8443/cpi/return.jsp,SessionId1234567890, P, Item Description, UK11111111GBP_00000001, 10000,826, UK11111111GBP, 1041379200000, Capture, User_000001}

Note:The field names are not sent to the GenerateHash function.The order of the submitted information is irrelevant.

The GenerateHash program then returns the constructed OrderHash, with a maximum length of28 characters, (for example “abcdefghijklmnopqrstuvwxyzab”) for further use.

In a multi-currency situation, the shared secret supplied to the OrderHash generator must matchthe currency of the transaction – see multi-currency on page 6 for more information.

21

Appendix ECurrency codes

For each transaction that is submitted from a storefront to the PAS, an ISO4217 (fifth edition standard) currency code must be specified. The table below lists examplesof currency codes acceptable by the Secure ePayments.

Table 7 Currency codes

Country Currency Currency Code Exponent

Europe Euro 978 2

Hong Kong Hong Kong Dollar 344 2

Japan Japanese Yen 392 0

United Kingdom Pound Sterling 826 2

United States US Dollar 840 2

22

Appendix FCountry codes

Country codes needed to determine the BillingCountry/ShippingCountry fields for submittedorders are listed within ISO 3166. See the Store administrator guide for a detailed list ofcountry codes.

23

Appendix GSupported encryption technologies

The CPI currently supports secure POSTs via SSL3.0 and TLS1.0 technologies(please note, SSL2.0 is unsupported).

Only a limited set of cipher suites are enabled for the two security protocols,these are outlined below:

TLS1.0

RC4 encryption with a 128-bit key and an MD5 MACTLS_RSA_WITH_RC4_128_MD5

FIPS 140-1 compliant triple DES encryption and a SHA-1 MACTLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA

Triple DES encryption with a 168-bit key and a SHA-1 MACTLS_RSA_WITH_3DES_EDE_CBC_SHA

SSL3.0

RC4 encryption with a 128-bit key and an MD5 MACSSL_RSA_WITH_RC4_128_MD5

FIPS 140-1 compliant triple DES encryption and a SHA-1 MACSSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA

Triple DES encryption with a 168-bit key and a SHA-1 MACSSL_RSA_WITH_3DES_EDE_CBC_SHA

24

Appendix HStore administrator tool

The Store Administrator Tool provides access to store details on the Secure ePayments (enablingstore user set-up, report generation etc – full details of the functionality of the store administratortool are provided in the ‘Store Administrator Guide’).

At present, the following browsers are supported for access to the store administrator tool:

Netscape 6.2.x or later on HP-UX, Sun Solaris, or Microsoft WindowsInternet Explorer 5.5 with Service Pack 2 or greater on Microsoft WindowsInternet Explorer 6.0 (with no service pack, or Service Pack 1 or greater) on Microsoft Windows

At present, the following browsers are blocked for access to the Store Administrator Tool:

Netscape 6.0.x on HP-UX, Sun Solaris, or Microsoft WindowsNetscape 6.1.x on HP-UX, Sun Solaris, or Microsoft Windows

Note:Access to the store administrator tool through Internet Service Provider software, which provides a custom interface toMicrosoft Internet Explorer software (for example, AOL (versions 8 and below), CompuServe) is unsupported.

25

HSBC Bank plcCommercial Service andSales Centre51 De Montfort StreetLeicesterLE1 7BB

www.hsbc.co.uk MC

P18

295

05/

03

Issued by HSBC Bank plc. We are a principal member of theHSBC Group, one of the world’s largest banking and financialservices with over 9,500 offices in 80 countries and territories