-
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