eCommercePaymentSolutions sg246177

Front cover
e-commerce Payment Solutions

Implementation and Integration
Using IBM WebSphere Payment Manager
Planning and installing payment

solutions
Integration with payment

protocols
Payment Manager and

WebSphere Commerce Suite
Bill Moore
John Fisher-Smith
Terry Hudson
Jose Novillo
Reto Sigl
ibm.com/redbooks
International Technical Support Organization

Using IBM WebSphere Payment Manager
October 2001
SG24-6177-00
Take Note! Before using this information and the product it supports, be sure to read the
general information in “Special notices” on page 325.
First Edition (October 2001)
This edition applies to WebSphere Payment Manager Versions 2.2 and 2.2.1 for use with Windows
NT, Windows 2000 Server, AIX, and Solaris.
Comments may be addressed to:

IBM Corporation, International Technical Support Organization
Dept. HZ8 Building 662
P.O. Box 12195
Research Triangle Park, NC 27709-2195
When you send information to IBM, you grant IBM a non-exclusive right to use or distribute the
information in any way it believes appropriate without incurring any obligation to you.
© Copyright International Business Machines Corporation 2001. All rights reserved.

Note to U.S Government Users – Documentation related to restricted rights – Use, duplication or disclosure is subject to
restrictions set forth in GSA ADP Schedule Contract with IBM Corp.
Contents
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix
The team that wrote this redbook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix
Notice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii
IBM trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii
Comments welcome . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii
Chapter 1. Introduction to payments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

1.1 Our objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1.1 Who should read this book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1.2 How this book is structured . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1.3 Supported environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.2 Payment history . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.2.1 Credit cards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.2.2 Internet payment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.3 Positioning online payment solutions . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.3.1 Payment service provider is key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.4 Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.5 IBM WebSphere Payment Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
1.5.1 Content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
1.5.2 Functionality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Chapter 2. Payment solutions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

2.1 Future payments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
2.1.1 Wireless payments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
2.2 Emerging payment challenges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
2.3 Payment Manager solutions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
2.3.1 Integration considerations when using Payment Manager . . . . . . . . 13
2.4 The Payment Manager internal architecture . . . . . . . . . . . . . . . . . . . . 16
2.5 Capacity planning, scalability and performance . . . . . . . . . . . . . . . . . 28
Chapter 3. Installation and configuration . . . . . . . . . . . . . . . . . . . . . . . . . 29

3.1 Installation planning and design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
3.1.1 Decide operating system, database manager and HTTP server . . . 30
3.1.2 Find out which versions are supported by the product . . . . . . . . . . . 31
3.1.3 Decide if you want a 1, 2 or 3-tier architecture . . . . . . . . . . . . . . . . . 32
3.1.4 Prepare all the software, fixes, patches and information . . . . . . . . . 35
3.1.5 Make a backup of the system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
3.2 Windows installation and configuration . . . . . . . . . . . . . . . . . . . . . . . . 37
3.2.1 Scenario 1: stand-alone or 1-tier . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
© Copyright IBM Corp. 2001 iii

3.2.2 Scenario 2: Remote database with WebSphere Commerce Suite . . 40
3.2.3 Scenario 3: remote HTTP server . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
3.3 AIX installation and configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
3.3.1 Scenario 1: stand-alone machine . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
3.4 Sun Solaris installation and configuration . . . . . . . . . . . . . . . . . . . . . . 53
3.4.1 Scenario 1: Oracle, iPlanet, WebSphere Application Server and
Payment Manager on a single machine . . . . . . . . . . . . . . . . . . . . . . 54
3.5 Install WebSphere Application Server . . . . . . . . . . . . . . . . . . . . . . . . 89
3.5.1 WebSphere Application Server V3.5 install prerequisites . . . . . . . . . 89
3.5.2 WebSphere Application Server V3.5 install . . . . . . . . . . . . . . . . . . . 89
Chapter 4. Integration with SET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

4.1 Secure Electronic Transaction architecture . . . . . . . . . . . . . . . . . . . 110
4.1.1 The key entities in an e-commerce transaction. . . . . . . . . . . . . . . . 110
4.1.2 Consumer certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
4.1.3 Merchant certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
4.1.4 Acquirer certificates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
4.2 SET extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
4.2.1 MIA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
4.2.2 Merchant originated payment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
4.2.3 Creating an order when using the SET cassette. . . . . . . . . . . . . . . 116
4.2.4 Verification of card holder address . . . . . . . . . . . . . . . . . . . . . . . . . 116
4.2.5 Japanese payment option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
4.2.6 Other SET extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
4.3 The Visa 3D SET model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
4.3.1 The three domains (3D) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
4.4 Installing the SET cassette . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
4.4.1 Verifying the installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
4.4.2 Configuring Payment Manager to use the SET cassette . . . . . . . . 118
4.4.3 Consumer certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
4.4.4 Sample Checkout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
Chapter 5. Integration with VisaNet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141

5.1 What is VisaNet? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
5.1.1 Worldwide restriction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
5.1.2 Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
5.2 Payment Manager cassette for VisaNet . . . . . . . . . . . . . . . . . . . . . . 143
5.2.1 Supported environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
5.2.2 Class certification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
5.2.3 Gateway connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
5.3 Does your merchant qualify for using VisaNet? . . . . . . . . . . . . . . . . 145
5.4 Installing the VisaNet cassette . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
5.4.1 Installing the PTF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
iv e-commerce Payment Solutions Implementation and Integration using IBM WebSphere Payment Manager
5.5 Configuring a cassette for VisaNet . . . . . . . . . . . . . . . . . . . . . . . . . . 150
5.6 Using the Vital test account . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
5.6.1 Merchant profile data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
5.6.2 SampleCheckout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
5.6.3 Adjustment of SampleCheckout . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
5.6.4 Adjustment of WebSphere Payment Manager . . . . . . . . . . . . . . . . 152
5.6.5 Connect to the VisaNet test account . . . . . . . . . . . . . . . . . . . . . . . . 156
5.6.6 Sample orders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
5.6.7 View the test order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
5.6.8 Consult the trace log files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
Chapter 6. Integration using other payment cassettes . . . . . . . . . . . . . . 159

6.1 What is a cassette? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
6.1.1 How does a cassette work? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
6.1.2 Why payments are supported only through cassettes . . . . . . . . . . 161
6.1.3 Cassette development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
6.2 List of cassettes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
Chapter 7. Integration with WebSphere Commerce Suite . . . . . . . . . . . . 169

7.1 Sharing users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
7.1.1 Customization for Commerce Suite and Payment Manager . . . . . . 170
7.1.2 Customization when Payment Manager is on a remote machine . . 171
7.2 Remote database configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
7.3 Payment Manager administration . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
7.4 Commerce Suite-supplied payment resources . . . . . . . . . . . . . . . . . 175
7.4.1 Payment Class files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
7.4.2 Controller commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
7.4.3 Sample JSPs and related views . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
7.4.4 Payment Manager cashier profiles . . . . . . . . . . . . . . . . . . . . . . . . . 178
7.4.5 Understanding the WCS51_SET_Wallet cashier profile . . . . . . . . . 178
7.5 Enabling a non-IBM supplied cassette . . . . . . . . . . . . . . . . . . . . . . . 183
7.6 Enabling the sample store to use Payment Manager . . . . . . . . . . . . 183
7.6.1 Change the role of wcsadmin for Payment Manager tasks. . . . . . . 183
7.6.2 Decide which protocols to use for processing orders . . . . . . . . . . . 184
7.6.3 Enabling the Commerce Suite sample store for SET purchases . . 187
7.6.4 Payment Manager set up with the InFashion Sample store . . . . . . 209
Chapter 8. Customization using the payment API . . . . . . . . . . . . . . . . . . 211

8.1 Customization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
8.2 Branding with Java properties files . . . . . . . . . . . . . . . . . . . . . . . . . . 212
8.2.1 How to find the objects to be modified . . . . . . . . . . . . . . . . . . . . . . 213
8.2.2 Creating your properties files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
8.2.3 Naming your properties files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
8.2.4 Replacing images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
Contents v
8.2.5 Branding using your Payment Manager stylesheet. . . . . . . . . . . . . 220
8.3 Customizing the CustomOffline cassette . . . . . . . . . . . . . . . . . . . . . 221
8.4 Payment Manager users and realms . . . . . . . . . . . . . . . . . . . . . . . . 222
8.4.1 PSDefaultRealm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
8.4.2 Single sign-on . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
8.5 Merchant integration using the cashier framework . . . . . . . . . . . . . . 236
8.5.1 Exercise software components . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
8.5.2 What you need to proceed with the exercise . . . . . . . . . . . . . . . . . 238
8.5.3 Install exercise software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238
8.6 Merchant integration using Sample Checkout. . . . . . . . . . . . . . . . . . 253
8.6.1 Exercise software components . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
8.6.2 Approving orders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
8.6.3 Depositing payments. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
Chapter 9. Cassette development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273

9.1 Why develop a Payment Manager cassette? . . . . . . . . . . . . . . . . . . 274
9.2 How to create a Payment Manager cassette . . . . . . . . . . . . . . . . . . 274
9.2.1 Choose a cassette name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
9.2.2 Obtain and install materials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
9.2.3 Design your cassette. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
9.2.4 Prepare the base files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
9.2.5 Implement a data model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295
9.2.6 Implement an account class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295
9.2.7 Implement a batch class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
9.2.8 Implement an order class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
9.2.9 Implement a payment class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
9.2.10 Implement a credit class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
9.2.11 Test the cassette . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
9.2.12 Package and ship the cassette . . . . . . . . . . . . . . . . . . . . . . . . . . . 299
9.2.13 Practice with LdbCard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299
9.2.14 Using the cookbook sample store . . . . . . . . . . . . . . . . . . . . . . . . . 302
9.2.15 Tips and techniques . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
9.3 Cassette Developers Toolkit. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
9.3.1 Payment Manager enhancements . . . . . . . . . . . . . . . . . . . . . . . . . 306
9.3.2 Understanding the Payment Manager framework. . . . . . . . . . . . . . 308
9.3.3 Designing your cassette . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308
9.4 KitCash cassette . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
9.4.1 Overview of cassette for KitCash . . . . . . . . . . . . . . . . . . . . . . . . . . 309
9.4.2 KitCash installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
9.4.3 Configuring the Web server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314
Appendix A. Additional material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317

Locating the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317
vi e-commerce Payment Solutions Implementation and Integration using IBM WebSphere Payment Manager
Using the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317
System requirements for downloading the Web material . . . . . . . . . . . . . 318
How to use the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318
Related publications . . . . . . . . . . . . . . . . . . . . . . ...... ....... ...... . 319

IBM Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . ...... ....... ...... . 319
Other resources . . . . . . . . . . . . . . . . . . . . . . . . ...... ....... ...... . 319
Referenced Web sites . . . . . . . . . . . . . . . . . . . . . . ...... ....... ...... . 320
How to get IBM Redbooks . . . . . . . . . . . . . . . . . . . ...... ....... ...... . 323
IBM Redbooks collections . . . . . . . . . . . . . . . . . ...... ....... ...... . 323
Special notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325
Abbreviations and acronyms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
Contents vii
viii e-commerce Payment Solutions Implementation and Integration using IBM WebSphere Payment Manager
Preface
This redbook describes the requirements for implementing e-commerce payment

solutions in today’s dynamic Web environment. It provides guidance for
architects and developers who will use WebSphere Payment Manager as part of
a full e-commerce payment solution.
We explain the role that WebSphere Payment Manager plays in an e-commerce

solution and describe how to install and configure WebSphere Payment Manager
to meet different requirements. We discuss how to integrate WebSphere
Payment Manager with SET and VisaNet using the cassette features provided.
Further details are provided about the full range of available cassettes that allow
WebSphere Payment Manager to interact in a standard way with many different
payment protocols.
We examine the way in which WebSphere Payment Manager is used in

WebSphere Commerce Suite to provide an integrated payment solution.
We then provide examples to show how WebSphere Payment Manager APIs can
be used to customize the product, and give details of how to develop custom
cassettes so that WebSphere Payment Manager can be used with different
payment protocols.
The team that wrote this redbook

This redbook was produced by a team of specialists from around the world
working at the International Technical Support Organization, Raleigh Center.
Bill Moore is a WebSphere Specialist at the International Technical Support

Organization, Raleigh Center. He writes extensively and teaches IBM classes on
WebSphere and related topics. Before joining the ITSO, Bill was a Senior AIM
Consultant at the IBM Transarc lab in Sydney, Australia. He has 16 years of
application development experience on a wide range of computing platforms and
using many different coding languages. He holds a Master of Arts degree in
English from the University of Waikato, in Hamilton, New Zealand. His current
areas of expertise include the VisualAge family of application development tools,
object-oriented programming and design, and e-business application
development.
© Copyright IBM Corp. 2001 ix

John Fisher-Smith is from QSI Payments Inc. whose head office is in Australia.
He has 20 years of experience in the IT field, first as a hardware Field Service
Engineer and lately as a software Product Implementation Specialist. He holds a
degree in Internet Computing from Griffith University in Brisbane, Australia. His
areas of expertise include the designing and writing of e-commerce integration
software for QSI and writing their associated manuals.
Terry Hudson is a Senior IT Specialist working for IBM in the UK. He has 12
years of IT experience working at IBM. A CICS application developer for nine
years, he has worked on all major releases of CICS, specializing in CICS
customization, SNA, CPI-C, X.400, X.500 and SMTP technologies. He has a
Mathematics for Business Honours Degree from Middlesex University in London,
England. He has been involved in a technical capacity with IBM e-commerce
products and services for the past three years. His current responsibilities
include pre-sales technical support for the IBM WebSphere Commerce Suite
portfolio of software products across Europe, the Middle East, and Africa.
Jose Novillo is an IT Specialist in Spain. He has three years of experience in the

Web application development field. He holds a degree in Physics from
Complutense University, Madrid. His current areas of expertise include Web
publishing and development, payment transactions, and software
implementation. Before joining IBM he wrote extensively in computer magazines
about the Internet and its use.
Reto Sigl is an IT Specialist in Switzerland. He has five years of experience in

the Technology Deployment and Research field. He holds a degree in economics
from the University of Zurich, Switzerland. His areas of expertise include
business transformation, Lotus Notes migration, and Web-based software
distribution.
x e-commerce Payment Solutions Implementation and Integration using IBM WebSphere Payment Manager
The authors: John Fisher-Smith, Jose Novillo, Bill Moore, Reto Sigl, Terry Hudson
Thanks to the following people for their contributions to this project:
Lance Bader
Phil Kregor
Christopher Meyer
Robert Perry
Jennifer Ricard
David Soroka
Mark Wainwright
IBM Raleigh
Melissa Polizzotto
IBM Austin
Scott Esposito
IBM Poughkeepsie
Preface xi
David Jackson
IBM Columbus
Juan P Ferrandiz
IBM Spain
Dieter Roth
IBM Germany
Raymond Kwok
Rob Pereen
Sam Wong
IBM Canada
Angelo Scaccabarozzi
IBM Italy
Notice
This publication is intended to help administrators and developers who work with
WebSphere Payment Manager to provide payment solutions for e-commerce
applications. The information in this publication is not intended as the
specification of any programming interfaces that are provided by WebSphere
Payment Manager. See the PUBLICATIONS section of the IBM Programming
Announcement for WebSphere Payment Manager V2.2 for more information
about what publications are considered to be product documentation.
IBM trademarks
The following terms are trademarks of the International Business Machines
Corporation in the United States and/or other countries:
e (logo)® Net.Data®
IBM ® OS/400®
AIX® Redbooks™
CICS® Redbooks Logo ™
DB2® RS/6000®
DB2 Universal Database™ S/390®
Home Director™ SP™
IBM Consumer Wallet™ VisualAge®
IBM Payment Gateway™ WebSphere®
IBM Payment Registry™ Lotus®
MQSeries® Lotus Notes®
Net.Commerce™
xii e-commerce Payment Solutions Implementation and Integration using IBM WebSphere Payment Manager
Comments welcome
Your comments are important to us!
We want our IBM Redbooks to be as helpful as possible. Send us your

comments about this or other Redbooks in one of the following ways:
Use the online Contact us review redbook form found at:
ibm.com/redbooks
Send your comments in an Internet note to:
redbook@us.ibm.com
Mail your comments to the address on page ii.
Preface xiii
xiv e-commerce Payment Solutions Implementation and Integration using IBM WebSphere Payment Manager
1
Chapter 1. Introduction to payments

In the early years of the Internet, a Web site providing only information content by
using text and low resolution graphics was considered enough to attract
customers. Millions of companies, institutions and individuals have published
Web sites in the past years following this simple method. Today’s consumers
expect more from a Web site than information on store opening times or pictures
of staff and family. While consumers may still accept low resolution graphics,
they demand more benefit when surfing the Internet. A visitor to a Web site will
not look at travel fares without the possibility to book one, will not look at scenic
images of his local golf course without the possibility to sign in to play, will not
buy a digital camera without previously having a database compare its
functionality with others. A consumer will prefer the Web site that provides ease
of use, so a company that publishes the Web content must enhance its
infrastructure and adjust its processes to fit this demand. It has to transform its
Web sites into applications, store data on products and customers in databases,
and personalize Web content to what the visitor expects. In order to address a
worldwide customer community, with different languages and cultures, with
different payment methods, with sometimes challenging network performance -
the company needs assistance to build this infrastructure from a serious partner
who is specialized in this area.
© Copyright IBM Corp. 2001 1

1.1 Our objectives
In this book we focus on how to establish and maintain a customer payment
service based on WebSphere Payment Manager. Because your customer is
most likely selling goods or services to its customers, we use the term merchant
throughout the book. Building the infrastructure for the payment service allows
the merchant to perform financial transactions between his customers and a
financial institution.
1.1.1 Who should read this book

This book is designed for people who build and maintains a payment server for
one or more merchants. We assume that you will use WebSphere Payment
Manager as a key part of the payment solution.
After reading this book you should understand the concept of a payment server,
be aware of the software that is required to establish a running environment, and
have the ability to maintain the server for adding new merchants and defining
administration roles. We also provide information on what other payment
solutions are being offered and what kind of features are to be expected from
upcoming e-commerce services.
1.1.2 How this book is structured

Each chapter of this book will introduce you to a component or related topic of
WebSphere Payment Manager. It will guide you step by step through the tasks to
be performed during installation or maintenance, with window where appropriate.
Most chapters offer you the ability to test the merchant environment without the
need to have live connectivity of a financial institution to the system. This makes
it easy for you to simulate the complete merchant and bank environment, without
having to use a production system.
In our installation routines we have the password set the same as the username.
This is for ease of use in a test environment and should not be adopted in any
production system.
2 e-commerce Payment Solutions Implementation and Integration using IBM WebSphere Payment Manager
1.1.3 Supported environment
Independent of what server operating system and what database products you
have or prefer to run, we explain the most frequently used ones in detail: AIX,
Windows NT, and Solaris at the operating system level, and DB/2 and Oracle at
the database level. The book does not cover installation on Linux platforms,
because WebSphere Payment Manager was not available on that operating
system at the time we wrote this book.
Although some install variables are operating system dependent, the code of
WebSphere Payment Manager relies on the pure Java programming language so
that it operates in a similar manner on different platforms. Connectivity software
used between the customer, merchant and financial institution is based on
common security standards such as SSL (Secure Socket Layer) or SET (Secure
Electronic Transaction).
The book provides instructions for setting up a split payment environment, where
WebSphere Payment Manager runs on a different server from the database or
the Web server. For merchants with large transaction volumes, this is the
preferred way to build the infrastructure, because it gets the greatest
performance out of the servers.
This book will not cover the aspects of installing and using WebSphere Payment
Manager in an Application Service Provider (ASP) environment, where
merchants can sign up for a payment service. Although interactive signup to
payment services might be the preferred way for merchants and has already
been realized using WebSphere Payment Manager code, this concept is not
detailed by our redbook.
1.2 Payment history

Paying for goods obtained by sell or trade is one of the oldest habits of mankind.
Currency in the form of coins has been in use for more than 2000 years, and for
at least 400 years ago that the value of money has been additionally measured
on printed paper, known as bills.
1.2.1 Credit cards

Paying with coins and bills was not the end of currency evolution, since more
than 50 years ago credit cards were introduced. Instead of having to pay with
bills and coins, the customer could pay for goods and services by letting the
merchant take an imprint of his card and compare the card holder’s signature on
the receipt with the one on the back of the card. The money would then be
Chapter 1. Introduction to payments 3

transferred from the customer’s financial account to the merchant. Today, over
200 million shops, restaurants and organizations, mostly in industrial countries,
accept those credit cards as a valid payment method between the customer and
the merchant.
The bank may decide which credit card brands it wants to offer to their
customers. The credit card can only be used, if there is debit on the buyer’s bank
account. While in earlier days a print of the card was taken and later sent for
verification to the payment institution, today’s merchants have validation
machines that check the customer’s liquidity over phone lines before the
purchase is being accepted. Signing the receipt for every payment and having
the merchant compare it with the signature on the back of the card is still the
commonly used verification method. Nevertheless some banks now print a
picture of the card holder on the credit card as an additional verification method.
1.2.2 Internet payment

As the Internet became more and more popular in the major industrial countries
for connecting companies and governments to each other within a permanent
worldwide communication network, it was extended to allow individuals at home
to use the network for their convenience. For some, the Internet had the image of
the open and free world, when everything was available for free and Web sites
were mainly used to publicize companies and products.
Early adopters of the Internet were often financially well off, and companies soon
realized that there was money to be made on the Web. The Internet began to be
used as a carrier for performing financial transactions. Customers could pay for
goods and services through the Internet, and they did not have to leave their
home or office in order to complete their purchases. Customers can purchase
more goods in less time. Web sites are online 24 hours and accessible through a
Web browser from all over the world, and customers can pay for goods whenever
and wherever they want.
As more financial transactions were performed online, payment methods were

required and credit cards seemed to be the best solution to authenticate a
customer and check his or her bank balance. Instead of presenting the credit
card to a sales person in a shop, the customer provided a credit card number
and expiration date to a Web site. The buyer’s payment capability is then either
checked automatically and confirmed by the financial institution, or can be
validated at a later time. By 2003, 10% of the overall credit card payment volume
is expected to be done through the Internet.
1.3 Positioning online payment solutions
Almost every institution that sells goods and services can use the payment
capabilities of the Internet as an additional or primary way of selling their
products to customers.
Merchants often use the Internet to reach a wider customer community, instead
of only selling their goods locally in a store. Offering their goods and services
online has also had advantages for the merchants, since they don’t have to
maintain office space or pay staff to take care of their sales business and
financial transactions. In many cases it is cheaper to rent or buy server space
and run an online shop, instead of renting office space to sell the goods.
Today, many large businesses are starting to sell their goods online. As a result,
online payments made on the Web are increasing rapidly from year to year and
the number of online shops on the Web is increasing at a similar rate. Large
companies are finding an advantage in migrating their selling online, and small
and medium businesses find that they can reach out for more customers on the
Internet.
1.3.1 Payment service provider is key

For both the merchant and the customer, payment is a key element of selling and
buying. A Web site can be fancy or not, the text can be in any language, the
range of credit cards to be supported can be small or large, but the electronic
transaction between merchant, bank, and customer must always be the same:
reliant, secure and fast. So the greatest demand of merchants and buyers is
having the best partner providing the payment software, which is the heart of
every transaction.
1.4 Security
The primary issue of the buyer and the merchant is security. Transactions must
be as secure as possible, and it is important to understand who takes the risk
with Internet payments.
Credit cards are a valuable possession for many people. The card number,
expiration date and the signature are the important things that control access to
the buyer’s bank account.
Because the Internet still has a reputation as the open and free world,
uncertainty persists when buying goods online. The buyer does not see where
the Web site is located, what people are behind the bits and bytes, or by whom
the payment is validated, and as a result trust is often hard to establish.

Today, well-known merchants, payment software providers, credit card
companies and banks are important in establishing the trust relationship that
customers demand. The goal of all involved parties is to limit the risk of misuse of
online payments to a minimum. New technologies reduce the risk, but still there
is no 100% secure mechanism to avoid misuse of online payments. Stolen credit
cards often give thieves the ability to use the card for online payments, since the
card holder’s signature is not needed and address verification is not always
implemented.
Technologies for improving security

New online payment systems additionally ask for the card holder’s street address
and zip code, information that is not provided on the card but can be checked
during validation of the bank account with the buyer’s bank. Secure Electronic
Transaction (SET) local certificates ensure that only the buyer’s computer is
authorized for electronic payments on the Web. Upcoming new digital certificates
on computers and mobile devices will ensure even better security. Computer
mice which scan and validate your fingerprint before doing an electronic payment
might also become a standard in future. While an iris scan of your eye might still
be limited to high-security military and government buildings, it might become a
standard for secure authentication.
1.5 IBM WebSphere Payment Manager

WebSphere Payment Manager provides merchants a secure, reliable and fast
solution to perform online payments. WebSphere Payment Manager provides a:
Complete Web shop solution integrated in WebSphere Commerce Suite.
A stand-alone version that can be built into the merchant’s existing payment
environment of Web servers, Web shops, and database servers.
An Application Service Provider environment (not covered in this book).
Many banks use IBM payment solutions on their infrastructure, and merchants
trust WebSphere Payment Manager because it is fully compatible and scalable
with the bank’s infrastructure and can be seamlessly integrated into their
financial environment without writing additional application code.
1.5.1 Content
WebSphere Payment Manager provides the payment server software, but also
the following products that make it easier for you to build the merchant’s
infrastructure environment:
IBM HTTP Server
WebSphere Application Server, Advanced Edition
IBM Universal DataBase (UDB)
Cassette support for SET (Secure Electronic Transaction) and CyberCash
1.5.2 Functionality
WebSphere Payment Manager has a Web-based front end that is used for
payment server administration as well as by the hosted merchants for merchant
administration. The front end can be easily accessed remotely through any
industry-standard browser. As the server administrator, you can define users and
their roles with access to the payment server. You also have the ability to adjust
the layout of the Web interface to reflect the customer’s corporate requirements.
For each merchant and transaction method, administrators can define whether
orders should be automatically processed by the payment server and routed to
the financial institution for validation, or if each order requires manual approval
from the merchant. This decision often depends on how many transactions are
expected to be processed each day.
WebSphere Payment Manager can also be used by merchants who don’t need
interaction with a financial institution at all, but want to use offline transaction
procession capabilities. For example, a local supermarket could use offline
payment methods to allow customers to choose the desired goods online, but
pick them up and pay for them when visiting the local shop.
Figure 1-1 WebSphere Payment Manager infrastructure

Worldwide service
WebSphere Payment Manager is designed to be used worldwide as payment
server software. The interface can be translated into any language that is
supported by the administrators Web browser. The payments are accepted in
multiple currencies.
The transaction software called cassettes might sometimes be restricted to

certain geographies or regions. Please consult your financial institution or
cassette provider to assure they cover your needs.
2
Chapter 2. Payment solutions

This chapter positions the many general aspects of payment processing that are
being discussed in the Internet world today. We also discuss the internal
architecture of the WebSphere Payment Manager product and how the product
helps in payment solutions

2.1 Future payments
A well-known IBM advertisement shows a man being filmed by security guards in
a grocery store, carefully placing goods in the inside of his coat, until he has no
more room to add anything else. The security guards keep an eye on his every
movement. He then attempts to walk out of the store through a walkthrough
system similar to the metal detectors in airport security areas. A security guard
quickly chases after the man and taps him on the shoulder only to say “Sir, you
have forgotten your receipt”.
Technology had managed to read the bar codes on the goods inside the man’s
coat and pay for them using the payment details on his person.
While this vision of the future may seem fanciful, it does represent an example of
how quickly the requirements for payment solutions are changing in order to
meet the demands of new technology and new ways of doing business.
In this chapter we detail some of the requirements expected of payment solutions

and position WebSphere Payment Manager in relation to these requirements.
2.1.1 Wireless payments

Payments involving initiation or confirmation of a payment transaction using a
wireless device are known as wireless payments.
Imagine using your cell phone or PDA to pay for goods when and where you
want. For example, you reach a drink vending machine in the street. You want to
purchase a drink but you have no money on you at the time. You do, however,
have your cell phone with you so you call the drink machine on your cell phone
and pay for a can of drink using the information on your cell phone, either prepaid
or via your own Internet bank account.
This concept of being able to buy whenever or whereever you are is fast
becoming reality.
At the time of writing this book, Nokia, the world leader in Mobile
communications, announced a collaboration with IBM, Luottokunta, and
Radiolinja to jointly pilot secure credit card payments by using a mobile phone
with a wallet application contained in the phone itself. The intention of the parties
involved is to demonstrate their commitment to the mobile wallet concept and
Wireless Identity Module WIM) technology. IBM WebSphere Commerce Suite
and Payment Manager technology will be used in the pilot. For more information
on the project, please refer to
http://press.nokia.com/PR/200109/834847_5.html
For more information on the Nokia wallet phone, please see:
http://www.nokia.com/phones/6310/wallet.html.
The following URL is an IBM white paper on wireless payments, which discusses
the concept and reality of wireless payments in more detail:
http://www.ibm.com/pvc/tech/pdf/Pvwee02.pdf
2.2 Emerging payment challenges

As electronic commerce becomes more prevalent in all types of industries, the
payments model for electronic commerce becomes more complex. Challenges in
supporting payments in the Business-to-Business(B2B) model will require
payment processing for methods other than credit or debit cards. In addition, as
the Business-to-Consumer (B2C) commerce model progresses, further complex
requirements will be made on the payments software of the future. The following
sections outline real-life payments scenarios that will inevitably require electronic
payments solutions in any payment system of the future.
Purchase orders
Almost all businesses in the worldwide marketplace use purchase orders in
some fashion. Purchase orders are a complex area when dealing with
authorization for payment. They frequently have a total amount restriction per
order, in addition to the same restriction over a period of time (for example, a
customer may be allowed to purchase only 2000 units of currency over six
months). In addition to limit restrictions, purchase orders often require some kind
of sign-off/signature by, for example, the manager of a group. These features of
purchase orders bring new challenges when the ideas are placed in the
electronic commerce world. For example:
The payment processor would be required to keep track of the organizations’
orders and enforce the time/amount restrictions of the purchase orders.
Some way of documenting the signature would be required (maybe through
assigning certificates to a purchase order for instance).
Decisions would have to be made whether these features were supported in a

payments architecture or whether these features should be dealt with by an
accounting system and have that system link closely with a payments system.
Chapter 2. Payment solutions 11

Manufacturers’ coupons
As retail shopping, especially large supermarket grocery shopping, becomes
more widely used on the Internet, consumers buying their grocery goods over the
Web will demand the same features offered to them in the store. At most
supermarket stores you can use manufacturers’’ coupons to discount the amount
you pay, provided that you have purchased the manufacturers’ goods. The
coupons often have an expiration date.
Support of these features implies that the payment system will be required to be
have knowledge of the contents of the shopping basket being processed so that
the coupons can be authorized and redeemed for payment.
Deferred credit
Buy-now, pay-later offers are widely seen throughout the retail sector. There is
no reason why merchants/manufacturers wouldn’t also want to offer this kind of
feature with Internet-based purchases. Details of credit or debit cards, and direct
debits would need to be collected by the commerce store, and a method of
indicating to the payment system that the purchase is a deferred credit purchase
would be required. Decisions on where the order would lie dormant (until the
deferred credit period had expired) would need to made. Would the e-commerce
system hold the information? Probably not, since the merchant would require
some form of authorization check on the consumer’s payment details before the
goods were released to the customer. Other options are the merchant payment
system (most likely to be given the responsibility) or the back-end financial
institution.
Multiple payments installments

Again, most retail stores offer some kind of multi-payment features to their
consumers, for example buy this washing machine in three installments. The
feature is sometimes given some kind of price premium reflecting any interest
charges. The consumer also usually has the choice of when the regular amount
is drawn from their accounts. On occasions where interest-free payments are
offered, these can also sometimes incur additional charges if the final amount is
not deposited to the merchant by a given time.
The challenge here for the payment system will be similar to that raised for
deferred payments: how does the payment system keep track of the regular
payments and notify the merchant/consumer of any failures?
2.3 Payment Manager solutions
Chapter 8, “Customization using the payment API” on page 211 discusses the
details on how WebSphere Commerce Suite V5.1 integrates with WebSphere
Payment Manager V2.2.
WebSphere Payment Manager 2.2 also integrates into the WebSphere

Commerce Suite, Marketplace Edition. A white paper is available on the Web that
discusses the details of how to do this. It can be found at:
http://www-4.ibm.com/software/webservers/commerce/epit/reports.html
2.3.1 Integration considerations when using Payment Manager

You can also integrate Payment Manager into any front-end system that requires
a generic payments framework.
One example is the process of collecting registration or subscription fees via

users credit card details.
Note: This does necessarily imply that you would need an e-commerce
application to create a shopping basket. In this case, Payment Manager could be
integrated into a set of static HTML pages using the Payment Manager API . The
user could enter any user-specific information on pages prior to the pay/buy or
checkout page.
At the checkout page your application could:

Show the amount to be paid and a description of the goods to be purchased.
Detail any taxes that are relevant for the purchase.
Collect credit card information:
– Brand - You will need to limit the credit card brands you show to only those
that are authorized within the Payment Manager cassette accounts.
– Number - Simple verification checking on the value entered in this field is
also advisable, for example:
• Does what is specified by the consumer in this field contain (only)
numeric values?
• Does the numeric value specified contain the required number of digits
for the corresponding credit card brand?
• Perform a luhn check on the data specified in the field:

The luhn check is a standard method of verifying credit card details
when you only know the credit card brand and the supplied number.
The check is based on an algorithm that determines if the credit card is
valid without going to any back-end financial institution for further
verification. If you decide to code the luhn check into your payment
application, you can more readily reject credit cards that are invalid
right away without incurring any possible charges associated with an
approval attempt and subsequent rejection. Successful luhn checking
of the number passed in the credit card field means that the number
passed looks like a credit card (since all credit card numbers pass the
check). However, it does not mean that the number is a valid credit card
and is credit worthy. Only the card issuer can check this by Payment
Manager passing the details on to the back-end financial institution.
The full luhn check is derived from ISO 7812:1987(E) standard, Annex
B. For more information on how to perform a luhn check, it is advisable
to review the specification and check the Internet for already defined
luhn validation algorithms. Since this is a common algorithm, you will
find that lots of people have made the code for their luhn checking
algorithms available on the Web.
– Expiration date - Verify the values before passing this information on to
Payment Manager, for example:
• Is the month value numeric and between 1 and 12?
• Is the combination of month and year specified in the future?
Collect the consumer’s e-mail address and validate. Simple user@domain
checking would probably suffice. Traditionally this information is used to
inform the purchaser of the status of their order (successful or otherwise).
The owner may also choose to display their logo and any terms and
conditions that may be associated with the purchase.
If the owner has decided to support SET as a payment protocol you may also
want to provide the following:
– Instructions on how to obtain a valid certificate for the purchase.
– A button to pay by using a SET wallet, in addition to a pay-now option.
This would enable the owner to collect payment information via a SET
wallet as well as by entering credit card details on the Web page.
– You may also decide that you will accept SET wallet purchases without a
certificate enabling the consumer to use the pre-fill function ofSET wallet
software.
When collecting this type of sensitive information, the page must be displayed
using the HTTPS interface.
Payment Manager also provides support for collecting the security codes
usually displayed on the signature side of most credit cards. The information
is not embossed, so it does not appear on credit card receipts. By collecting
this information, the owner of the site would be reducing the risk of someone
using the stolen credit card details from a paper receipt. If you know the
security code, the chances are that you are physically holding the credit card.
This does not, however, protect against a stolen card, but does give an extra
measure of protection.
The designer of the checkout area may also want to look at making the area
Electronic commerce modelling language (ECML) compliant.
ECML is an attempt to make filling out a checkout area easier and more
uniform across the Internet. It is estimated that over a quarter of all
Internet-based sales are lost because the consumer didn’t fill out the
checkout area, either because they found it too hard or because of the
(personal) information they had to provide. Since the owner of a site is
responsible for making it easy for users to fill in the payment details, it is
advisable to look into the modeling language. For more information on ECML,
see:
http://www.ecml.org
Once the information has been successfully obtained, simple verification
checks have been performed, and any errors resolved, the information could
be passed using the Payment Manager API AcceptPayment command.
You also have to decide on your policy of automatically approving orders. You
may want to set up Payment Manager so that the full amount is automatically
approved by the back-end financial institution. This would give the
merchant/owner an indication that the credit card was good and credit worthy.
At this stage no money would have been drawn from the user’s credit card. If
you were selling merchandise that the consumer needed to obtain, for
instance by shipping the merchandise, you would also have to ensure that
you complied with your country’s laws. In some countries it is unlawful to
collect payment for goods that the consumer (or payer) has not received.
Processing of a subscription, for example, may not be bound by this type of
rule, so it may be possible to also set up automatic approval of the credit card
payment.
After successfully creating an order, it is common for the consumer to receive
some kind of notification (for example via e-mail) that the payment was
successful or to detail any error situations that were encountered as part of
the payment request.

Note: In payment rejection situations where, for example, the credit limit
has been reached and the approval fails, the back-end financial institution
may or may not give the reason for the error.
The error code may just indicate that the payment failed and it would be up
to the consumer to further investigate the reason for the failure with their
card issuer. Clearly if the policy of the card issuer is to give out the
granularity of error detail (such as the limit has been reached) then it would
be dependent on the back-end payment cassette used for the credit card
brand to pass that detail back to the front end “store” application.
This is no different from purchasing goods using the phone and being told
that the payment request has been rejected, and not being told the reason
why.
For more information on using the Payment Manager API and the tools available
in Payment Manager to help build payment application, please refer to the
product manual IBM WebSphere Payment Manager for Multiplatforms
Programmer’s Guide and Reference Version 2.2.
For more information on how customers have used the power and flexibility of
IBM WebSphere Payment Manager in real-life business situations, please refer
to some case studies at the following URL:
http://www.software.ibm.com/casestudies/swcs.nsf/swgsearch?SearchView&Query=Web
Sphere+Payment+Manager
2.4 The Payment Manager internal architecture

The following discusses the high-level Payment Manager architecture made
available in V2.2 of the product and how it fits with the other IBM products in an
e-commerce software stack.
Payment Manager is designed to run as an application under WebSphere

Application Server, which supplies the Payment Manager with the environment in
which to run its Java Servlets as well as the mechanism for external
communications using HTTP requests (Payment Manager gives XML
responses). The infrastructure uses IBM HTTP Server as its Web server and
supports various database products, including DB2 UDB and Oracle.
The high-level architecture of WebSphere Payment Manager is shown in

Figure 2-1.
Administrator
Browser
Merchant Merchant
Application Browser
Web Server, WebSphere
Payment Servlet
Query Engine UI Servlet
Cassette
Cassette
Cassette
Payment
Manager
DB2
Payment Engine
Cassette
Cassette
IBM WebSphere Cassette
Payment Manager
Figure 2-1 A high-level view of the Payment Manager architecture
The infrastructure is designed to:

Support multiple merchants who are all using the system at the same time,
processing orders from their respective storefronts.
Enable service providers to integrate with their already existing merchant
authentication environment using plug-in support.
Enable continuous availability while still allowing for:
– Adding new merchants
– Authorizing merchants to use different payment protocols (cassettes)

– Changing the configuration by, for example, supporting new protocols and
adding new cassettes to the framework
Provide a programmable API for extending and customizing the WebSphere
Payment Manager infrastructure. An overview of the Payment Manager API is
shown in Figure 2-2.
Administrator
Browser
Merchant Merchant
Application Browser
Payment Servlet
Cassette
Cassette
Cassette
Payment
Manager
DB2
Payment Engine
Cassette
Cassette
Payment Manager
Figure 2-2 The Payment Manager API
The Payment Manager API

The API allows for flexible integration with merchant applications. Access to
Payment Manager is handled by a payment servlet, and the merchant application
uses the Payment API, which provides:
Function calls for:
– Payment processing
– Queries
– Administration
An HTTP interface for low-level programming
A Java client library (CAL)
A 128-bit SSL client
For more information on the Payment Manager API, please refer to IBM
WebSphere Payment Manager for Multiplatforms Programmer’s Guide and
Reference Version 2.2.
The Payment Manager user interface

The Payment Manager user interface allows interactive access to almost all
payment functions and parameters that are available using the API. XML
responses to Payment Manager (HTTP) requests made through the user
interface are displayed through the Payment Manager Presentation Language
(PSPL). The UI is available to all levels of merchant as well as to the service
provider (owner of the Payment Manager). Figure 2-3 shows the Payment
Manager user interface.

Administrator
Browser
Merchant Merchant
Application Browser
Payment Servlet
Cassette
Cassette
Cassette
Payment
Manager
DB2
Payment Engine
Cassette
Cassette
Payment Manager
Figure 2-3 The Payment Manager user interface
WebSphere Commerce Suite V5.1 also uses the Payment Manager user
interface to manage orders and users as part of its Commerce Accelerator
function. For more information on the integration of WebSphere Payment
Manager with WebSphere Commerce Suite, refer to Chapter 7, “Integration with
WebSphere Commerce Suite” on page 169. It is also possible to customize the
look and feel of the user interface when using Commerce Suite.
The Payment Manager servlet is a Java servlet that runs under WebSphere
Application Server, Advanced Edition V3.5 and acts as the communications layer
between the Web server and the Payment Engine. Figure 2-4 shows details of
the Payment Manager servlet.
Administrator
Browser
Merchant Merchant
Application Browser
Payment Servlet
UI Servlet
Query Engine
Cassette
Cassette
Cassette
Payment
Manager
DB2
Payment Engine
Cassette
Cassette
Payment Manager
Figure 2-4 The Payment Manager servlet
The Payment Manager servlet:

Handles all API calls directly or through the UI servlet
Interacts with Payment Engine
Interacts with the payment database though the Payment Manager Query
Engine
Deals with all access control (access rights) whether through the UI or the
API calls
All users have a (merchant-specific) role assigned that can be one of the
following(in ascending order of authority):

– Clerk
– Supervisor
– Merchant Administrator
– Payment Manager Administrator (Service provider)
Administrator
Browser
Merchant Merchant
Application Browser
Payment Servlet
Cassette
Cassette
Cassette
Payment
Manager
DB2
Payment Engine
Cassette
Cassette
Payment Manager
Figure 2-5 The Payment Manager UI servlet
The UI servlet handles GUI access. All requests passed to the Payment servlet
are passed via CAL methods.
The UI servlet, has one PSPL file with flags that points to a Java properties file
that decides the look and feel of each page. This enables you to customize and
brand the Payment Manager user interface according to your needs. The UI
servlet is shown in Figure 2-5.
The Payment Engine

The Payment Engine is a Java-based application that provides the Payment
Manager framework with the flexibility to support different protocols. It deals with
the payment requests (that is the actual financial transactions) that are sent to
Payment Manager for processing. The Payment Engine handles the framework
interface to the cassettes and the Payment Manager database tables. Figure 2-6
shows the Payment Engine.

Administrator
Browser
Merchant Merchant
Application Browser
Payment Servlet
UI Servlet
Query Engine
Cassette
Cassette
Cassette
Payment
Manager
DB2
Payment Engine
Cassette
Cassette
Payment Manager
Figure 2-6 The Payment Engine
If you have used Payment Server V1.2, the Payment Engine can be directly
accessed in compatibility mode.
For more information on the Payment Engine, please refer to the IBM
WebSphere Payment Manager for Multiplatforms Administrator’s Guide Version
2.2.
The Payment Manager Query Engine handles query API requests for viewing the
database (for example Query orders). Once the information is obtained by the
engine, the response is formatted into an XML document. This is shown in
Figure 2-7.
Administrator
Browser
Merchant Merchant
Application Browser
Payment Servlet
Cassette
Cassette
Cassette
Payment
Manager
DB2
Payment Engine
Cassette
Cassette
Payment Manager
Figure 2-7 The Query Engine
The Payment Manager database is a relational database that is used to store

Payment Manager configuration (cassette configuration/authorization, etc.) and
runtime data (that is, transactional information for example orders). Using
supported JDBC drivers, it can reside on a different machine from Payment
Manager if so desired. Figure 2-8 shows the database.

Administrator
Browser
Merchant Merchant
Application Browser
Payment Servlet
Cassette
Cassette
Cassette
Payment
Manager
DB2
Payment Engine
Cassette
Cassette
Payment Manager
Figure 2-8 The Payment Manager database
Restriction: If you configure your Payment environment using multiple
servers Payment Manager V2.2 does not support the following:
Two Payment Manager systems talking to one Payment Manager
database.
Two Payment Managers accepting orders from different (for example
alternate) sources.
One order source (for example e-commerce system) sending to alternate
Payment Managers: Order1 being sent to Payment Manager 1, Order 2
being sent to Payment Manager 2, Order 3 being sent to Payment Manager
1. This kind of flip-flop order processing is not supported in this current
release.
Each Payment Manager environment requires its own database. You will see
unpredictable results if more than one Payment Manager uses the same
database.
If you want to support multiple Payment Manager processing systems, then it is

recommended that you split the ownership of merchants between the Payment
Manager systems. For example, merchants from 1 to 100 are served by Payment
Manager 1, 101 to 200 are served by Payment Manager 2, and so on. Figure 2-9
shows the recommended split when installing multiple Payment Managers.

Merchants Merchants Merchants
1 101 201
100 200 300
WPM1 WPM2 WPM3
DB2
DB2 DB2 DB2
PAYMAN1 PAYMAN2 PAYMAN3
Figure 2-9 Recommended Payment Manager database ownership
2.5 Capacity planning, scalability and performance

Capacity planning, scalability and performance using WebSphere Payment
Manager V2.2 is discussed in a white paper available at:
http://www.ibm.com/software/webservers/commerce/payment/docs/paymgr22whitepaper
.pdf
3
Chapter 3. Installation and

configuration
This chapter describes some common installation scenarios for WebSphere
Payment Manager and discusses some optional but important tasks such as
user management and SSL.
The scenarios cover the most common situations from a practical point of view.
We have provided tips and critical steps for installation and configuration. We
also have added checks at the end of each section.
This chapter is a complement to the official installation guides that ship with
Payment Manager. It is not an exhaustive and detailed description of every
possible install situation, but a source of advice and guidance.
This chapter contains the following:

Installation planning and design
Windows installation and configuration
AIX installation and configuration
Sun Solaris installation and configuration
Post-installation tasks

3.1 Installation planning and design
Planning is an important part of a successful WebSphere Payment Manager
installation. Every installation should be properly planned and should consider
the requirements for an installation in a development environment, a test
environment and finally an implementation in the production environment.
We describe our experiences while installing and configuring WebSphere

Payment Manager in a number of common scenarios. We did our installations of
WebSphere Payment Manager V2.2 in clean environments so we do not detail
the issues involved in migration from older versions. Refer to the IBM WebSphere
Payment Manager for Multiplatforms Install Guide Version 2.2. for details about
migration from previous versions of the Payment Manager. Similarly if you intend
to install WebSphere Commerce Suite on the same machine as Payment
Manager, we suggest you refer to the IBM WebSphere Commerce Suite
Installation Guide and to the WebSphere Commerce Suite V5.1 Handbook,
SG24-6167.
When planning the installation of the main activities are:

1. Decide which operating system, database manager and HTTP server you are
going to use. To install WebSphere Payment Manager, WebSphere
Application Server is required.
2. Ensure that the software versions you plan to use have been tested together
and are official supported by the WebSphere Payment Manager product.
3. Decide if you want a 1, 2 or 3-tier architecture.
4. Prepare all the software, fixes, patches and information needed for the
installation.
5. You may also wish to back up your systems before beginning installation.
3.1.1 Decide operating system, database manager and HTTP server

WebSphere Payment Manager put some restrictions on these products. Payment
Manager requires WebSphere Application Server so the main restrictions are
imposed by the need to use components that are supported by WebSphere
Application Server. Depending on which version of WebSphere Application
Server will you use, you will be able to choose between different database
managers, HTTP servers and operating systems.
WebSphere Payment Manager supports and has been tested with WebSphere
Application Server Versions 2.0.3.x through to 3.5.4. In all the scenarios we used
WebSphere Application Server, Advanced Edition 3.5.4. We recommend that you
do not use older versions of WebSphere Application Server, because they will
not be supported with future releases of WebSphere Payment Manager.
Keep the following restrictions in mind:

The operating system must be Windows NT/2000, AIX and Sun Solaris (only
english, no other languages are supported),
The database manager should be DB2 or Oracle,
The HTTP server should be IBM HTTP Server, Apache server, Microsoft
Internet Information server, iPlanet Web Server, Lotus Domino or Netscape
Enterprise server.
3.1.2 Find out which versions are supported by the product

The prerequisite hardware and software requirements for WebSphere Payment
Manager can be found in the IBM WebSphere Payment Manager for
Multiplatforms Install Guide Version 2.2.
The prerequisites for WebSphere Application Server Supported hardware and

software can be found at:
http://ibm.com/software/webservers/appserv/doc/latest/prereq.html
In our test we use WebSphere Application Server V 3.5.4. We recommend that

you not use the 3.5 base version; instead apply at least patch 1. It is also
necessary to apply at least Fix Pack 1 to DB2 7.1.
We did test Payment Manager with DB2 Version 7.2 on the Windows platform
and it worked without problems, but we did not do any stress testing. At the time
we wrote this redbook, DB2 V7.2 was not officially supported with WebSphere
Application Server, Advanced Edition V3.5.x and WebSphere Payment Manager
V2.2, so we do not recommend that you use this combination in a production
environment, until you have checked the official hardware and software
prerequisites. We used DB2 7.1 with Fix Pack 2 or 3 for most of the testing done
in this redbook.
We used IBM HTTP Server V1.3.12, which ships with WebSphere Application
Server, Advanced Edition V3.5, and this gets patched to V 1.3.12.3 when
upgrading to WebSphere Application Server V3.5.4.
On the Solaris platform, we installed Oracle 8.1.7 as the database and iPlanet
Enterprise Server 4.1 Service Pack 7 as the HTTP server.
Chapter 3. Installation and configuration 31

As the operating systems, we used Windows NT SP4, Windows 2000 Server,
AIX 4.3.3.0.08 and Sun Solaris 2.7 with some fixes.
3.1.3 Decide if you want a 1, 2 or 3-tier architecture

Depending on the volume of transactions and the existing environment, each tier
structure has its pros and cons.
In every case, WebSphere Payment Manager must be installed along with

WebSphere Application Server, but can use a remote database and a remote
HTTP server. For more information on clustering and scalability of WebSphere
refer to WebSphere Scalability: WLM and Clustering Using WebSphere
Application Server Advanced Edition, SG24-6153, because the scalability of
Payment Manager relies on WebSphere.
The 1-tier architecture is ideal for a small to medium number of transactions. It

requires a stand-alone medium machine that is used only for WebSphere
Payment Manager.
The great advantage of this architecture is its low initial cost. Also it is easy to
escalate to cope with more transactions.
If the machine is used only to host payment services for several merchants, the
more demanding application is WebSphere Application Server, since the HTTP
server is a very light process and the database is accessed locally and only from
Payment Manager.
As more transactions are processed, another machine can be added with the
HTTP server, WebSphere Application Server and Payment Manager installed
using a remote database (2-tier). To balance the load, a network dispatcher must
be installed in a separate machine or in any of the WebSphere Application
Server machines as shown in Figure 3-1 on page 33. The dispatcher can be
used to split wisely the requests to the less busy WebSphere Application Server
and provide almost twice the performance. This way, new machines can be
added as needed.
Application Server
Node 1
WebSphere
eND Application
Server
Application Server
Node 2
WebSphere
eND Application Database
Server
...
Application Server
Node n
WebSphere
eND Application
Server
Figure 3-1 Scalability from 1-tier to 2-tier architecture
The new machines at the same time will provide higher availability, but will be
relying on the first machine, which has the database installed. To further improve
the availability, the database should be kept in another machine and a backup
replica of the database kept on a backup machine. The replica will only be in use
when the main machine is down. As you see, high availability is expensive. At
least four machines are needed.
There is a way to achieve high availability with only two machines, both of which
should be highly scalable so that one can assume the load of the other. The
architecture is a mix between1-tier and 2-tier. The method is to configure two
machines identically and have those machines use mirror disks to access the
data (RAID 1), as shown in Figure 3-2 on page 34. One of the nodes will act as
the application server and the other as the database server, but both are able to
work independently so that if one fails, the other can take all the load. This can
be achieved in AIX using HACMP mode 2 for all the software.

Database Server
Node 1
DB2
Active
HACMP
Mirroring
Mode 1
Database Server
Node 2
Disks
DB2
Standby
HACMP
Mirroring
Figure 3-2 High availability database service in AIX using mode HACMP1 and RAID 1
The load on the HTTP server in an exclusive Payment Manager environment is

not normally high enough to justify another machine or machines dedicated to
the HTTP server.
A 2-tier architecture is more convenient when there is a central database

manager installed. In this case WebSphere Payment Manager can use this
remote database. The installation will benefit from the backup and availability of
the central database.
As more transactions are received we can proceed as in the 1-tier architecture

and balance new application server machines with a network dispatcher.
A 3-tier architecture is an improvement on the 2-tier when the use of the HTTP
server is not limited to the access to the administration interface of WebSphere
Payment Manager and its corequisite software.
Typically, a unique machine or a cluster manages all the HTTP servers using
virtual hosts and dispatching techniques. Then one or more WebSphere
Application Server and Payment Manager machines use the HTTP server cluster
and a remote database.
Web HTTP WAS

Client Server WPN
Other HTTP Database

Server or WAS Server
Other
Applications
Figure 3-3 Standard architecture - central HTTP server, application servers and
database
This architecture has two main applications: high availability and reusing existing
servers. But high availability can be achieved with a 2-tier architecture as we
explained earlier and since this requires fewer machines we suggest that reuse
of an installed, configured and known HTTP server is the best reason to use a
3-tier architecture with Payment Manager.
3.1.4 Prepare all the software, fixes, patches and information

The most important step in ensuring a quick installation is to prepare all the
software and data required and have it on hand ready to use.
Assure that all product CDs are on hand and that you have downloaded any fixes
required. Here we list useful Web sites to get fixes and information:
If you need to download an AIX maintenance level you can do so from:
http://techsupport.services.ibm.com/rs6000/support/

If the download is too big you can ask for a CD. This window has all the
instructions to check the download by size and checksum and to uncompress
every file needed.
If you don’t have a gzip decompressor for your AIX system, you may find free
software for the AIX operating system at:
ftp://ftp.software.ibm.com/aix/freeSoftware/
The latest Fix Packs for DB2 can be downloaded from:
http://www.ibm.com/software/data/db2/udb/support.html
Along with the Fix Pack, there are detailed instructions to check for
prerequisites and to install the update.
Oracle database server and its fixes can be downloaded from the Oracle
Technology Network at:
http://otn.oracle.com/
This is also the main source of documentation for the Oracle products.
Information and downloads for IBM HTTP Server can be found at:
http://ibm.com/software/webservers/httpservers/
The main source of information about WebSphere Payment Manager is:
http://ibm.com/software/websphere/paymgr/support/index.html
You can access all the official documentation, gather contact information and
download new patches from this site.
If you need to manually install or upgrade WebSphere Application Server, you
can install WebSphere Application Server Version 3.5 using the CD-ROM
provided with Payment Manager, or download the version for your operating
system from:
http://ibm.com/software/webservers/appserv/
For migration instructions, see the WebSphere Application Server Info Center,
which you can download or view directly from the Web.
Documentation for IBM DB2 Universal Database is at:
http://ibm.com/software/data/pubs/index.html
Along with the fixes, download and read any related information including the
installation instructions. Don’t forget to read the IBM WebSphere Payment
Manager for Multiplatforms Install Guide Version 2.2 instructions for detailed and
exhaustive installation scenarios. The IIBM WebSphere Payment Manager for
Multiplatforms Administrator’s Guide Version 2.2 also provides information about
administering and maintaining the WebSphere Payment Manager.
Always read the latest readme file, readme.framework.html, accessed through
documentation links on the Payment Manager Web site:
http://ibm.com/software/websphere/paymgr/support/
and on the Payment Manager CD-ROM.
Apart from the software, you need to collect some data from your system,
including the IP and host name of every machine involved in the installation.
Note: When installing WebSphere Application Server, you will be asked which
database you want to use. You must use a relational database. DB2 UDB is
recommended. Do not select the Quick option so the InstantDB is not used.
The installation program requires a graphical display. Ensure the resolution on

your display is set to 800 by 600 pixels or higher to best view the Payment
Manager installation program.
The administration and configuration of Payment Manager requires a browser.

It does not matter if the browser is on the same machine or on another.
3.1.5 Make a backup of the system

Prior to any installation we suggest that you back up the system using the
common ways available for your operating system. In our case, since we were
doing a new installation in a development environment, we omit this step in the
detailed description of each scenario. However in a production environment we
recommend that you do backups prior to any installation.
3.2 Windows installation and configuration

We have tested these scenarios:
1. Stand-alone or 1-tier: everything in the same machine, typical for a small
payment hosting environment.
2. 2-tier with WebSphere Commerce Suite: includes the installation of
WebSphere Commerce Suite using a remote DB2 and a local Payment
Manager. This focuses on the use of WebSphere Payment Manager as a
payment method for commerce instead of as a payments hosting service.
3. Using a remote HTTP server: we modified an existing installation of
WebSphere Payment Manager to use a remote HTTP server instead of the
local one.

3.2.1 Scenario 1: stand-alone or 1-tier
This was a straightforward process and we discovered no problems in this
environment when it was up and running. A few things to keep in mind are:
Avoid Windows NT Server with Service Packs 5 and 6. This will cause
problems with WebSphere Application Server. You should use Service Pack
6A. You can download the latest Service Packs from:
http://www.microsoft.com/downloads/
Do the installation as a user who is part of the administration group.
Don’t use more than 8 characters for the name of the owner of the DB2
instance. DB2 doesn’t admit more than 8 characters to maintain compatibility
with host S/390 environments.
Do not use directories names with a blank space in the name, even if it is the
default, specially with DB2. If you do, some versions of WebSphere
Application Server will not properly set files to use it and the WebSphere
Administration Server will not start.
Install the DB2 development client if you will patch Payment Manager (you
need to compile a Java class file using the a Java library installed by this
client.
Do not choose quick install in WebSphere Application Server because it will
install, configure and use InstantDB instead of DB2.
If you want to do the silent install of Payment Manager (which installs
WebSphere Application Server and IHS) do this before:
create db was
db2 update db cfg for was using applheapsz 256
create db payman
The install steps we followed in order were:

Install DB2
Apply Fix Pack to DB2
Install WebSphere Application Server (this will install IHS)
Patch WebSphere Application Server (this will patch IHS if necessary)
Install Payment Manager
IHS, WebSphere and Payment Manager in one install

Run the install and follow the instructions in the windows:
1. Log on to Windows as a user with Administrator’s group privileges.
2. Execute the program Install found on the root directory of the Payment
Manager for Windows NT and Windows 2000 CD-ROM.
3. In the Payment Manager Install window, click Next.
4. Accept the license agreement.
5. Accept the default destination directory or enter another directory.
6. If your Web server is already installed, you will be asked for the location of the
publish directory. If the location displayed is correct, click Next. If not, enter
the correct location and click Next. The publish directory is the directory out of
which your Web server serves documents. The publish directory for IHS is
determined by the setting of the DocumentRoot directive in the httpd.conf file
(the default directory is htdocs).
7. Select the DB2 UDB database.
8. When the install finds the JDBC driver information, click Next. If it does not
find the JDBC driver information, provide these values:
– JDBC Driver Class name: com.ibm.db2.jdbc.appDB2Driver
– JDBC Class location: \<db2installdirectory >\java \db2java.zip \
– JDBC Driver shared library path: \<db2installdirectory >\bin \
Note: If you enter incorrect database information and database errors
occur, using the Back button may cause more database error windows to
appear. If this occurs, you can either click Cancel and restart the
installation or you can click Back through several windows and then move
forward using the Next buttons (ensuring the correct values are entered at
each intervening window) until you get back to the database entry window.
Once this window reappears, you can enter the correct information.
9. In the Payment Manager Database Access Information window, enter your
values for the database owner user ID, administrator’s user ID, administrator’s
password, Payment Manager database name and the DB2 instance name.
For example, if you are using UDB, enter:
db2admin /*for the database owner user ID
db2admin /*for the database administrator's user ID
db2admin /*for the database administrator's password
payman /*for the IBM Payment Manager database name
DB2 /*the default DB2 instance name
10.In the Payment Manager Configuration Information window, take the default of
8611 for the Payment API port number or enter a new value if another
application on your system uses this TCP port.
11.If you want to create a Payment Manager shortcut on the Start menu, select
the check box.

12.In the Installation Summary window, review the chosen parameters. Click
Next to continue the installation.
Note: The progress bar will move during installation, although at times it may
appear to have stopped. Do not terminate the install, which is continuing. The
progress bar will resume moving when system resources permit.
13.Complete the Product Registration information to register your application
with IBM. Note that you can register after installation by clicking Start ->
WebSphere Payment Manager -> Product Registration.
14.When installation is complete, restart your system before starting the Web
server and the Payment Engine.
Stop, check and start services

It is possible to install Payment Manager as a service and stop it and start it
through the Services window. To install it, use the command file that is inside the
directory <Payment_Manager_home>/ntservice.
Keep in mind that starting this service doesn’t mean that Payment Manager is up
and running. It’s also necessary to verify that the application server for Payment
Manager inside WebSphere Application Server is not stopped. To do that, go to
the WebSphere Administrative Console. The service and the Payment Manager
application server are separate components of the WebSphere Payment
Manager framework and are started separately. If you need to restart Payment
Manager, you have to restart both components: the Windows NT service will load
environment variables, and the application server inside WebSphere Application
Server will load servlet properties.
3.2.2 Scenario 2: Remote database with WebSphere Commerce Suite

For this install we followed the IBM WebSphere Commerce Suite Installation
Guide that ships with the Commerce Suite product CDs and everything was OK
until we tried to install Payment Manager. Although the DB2 client was installed
on the Commerce Suite machine and the payman database was cataloged on
our remote database node and accessible in the client, Payment Manager
reported that the wrong DB2 prerequisite was installed. To work around this we
had to install the full DB2 server on the Commerce Suite client machine and then
the Payment Manager prerequisite check succeeded. After the install completed
we were able to uninstall the DB2 server from the Commerce Suite client
machine, leaving just the DB2 client installed and Payment Manager continued to
work as expected.
Note: this error applied only to the base level of WebSphere Payment Manager
V2.2 and has been corrected in the Payment Manager fixes that patch Payment
Manager to the V2.2.1 level.
To create a remote database and catalog it at the client, enter the following at the
client machine from a DB2 command line:
catalog tcpip node node_name remote server_hostname server port_of_service
attach to node_name user user_name using user_password
create db db_name
catalog db db_name at node node_name
3.2.3 Scenario 3: remote HTTP server

This scenario is quite easy to set up. If the remote HTTP server already has the
WebSphere Application Server plug-in installed, you simply need to configure the
plug-in properties so that requests are forwarded to the target application server.
If the plug-in is not yet installed on the remote HTTP server, you first need to use
the WebSphere Application Server setup program to install the plug-in.
3.3 AIX installation and configuration

In this section we describe the general process of installing 1-tier and 2-tier
configurations on AIX. Tips are provided to make the scenarios more useful, but
be sure that you think carefully before applying our general examples to your
specific configuration and version combination. We describe any problems
encountered and provide workarounds where appropriate.
We have endeavored to keep these install descriptions quite simple, because our
intention is to provide an overview of the process and not to duplicate the
detailed install instructions found in the manuals for each product. Also we
assume that you are familiar with the AIX operating system.
3.3.1 Scenario 1: stand-alone machine

This scenario is suitable for a small business that does not have enough
transactions a day to justify separate machines for the database and the
application server. Also such a business does not have enough hits on its Web
site to justify putting the Web server on another machine.
Therefore, all products are installed locally, including IBM HTTP Server,
WebSphere Application Server, and DB2. WebSphere Payment Manager is an
application server inside WebSphere Application Server and as such it has to be
on the same machine.

Preinstallation checking
The most important step to assure a quick installation is have all the software
and data ready to use. For our install we had at hand all the required software in
a temporary fileset in our AIX machine.
Since this installation is for testing purposes we decided to use a small number of
large filesets instead of creating one fileset for each product. Logical Volume
Manager was used to provide some level of separation from physical disk
sub-systems. For each database instance created, we created a logical volume.
This may not be suitable for a production environment, but no matter how you
partition a machine the installation steps remain the same.
Again because this was a test environment we did not create many users on our
AIX system, but only created one user to act as the DB2 administrator. All other
operations were done by the root user.
Operating system
We started with a clean 4.3.3 AIX machine. The minimum maintenance level
tested to run WebSphere Application Server was level 2, but we upgraded our
AIX to the highest version available. That was maintenance level 8.
Verify your paging space with lsps -a. At least 128 MB of paging space is
needed, but the recommendation for AIX is twice the size of the system RAM.
Prior to installation we suggest you back up your system using the mksysb
command.
DB2
We installed DB2 UDB Enterprise Edition 7.1. You need to apply at least Fix
Pack 1 to get WebSphere Application Server, Advanced Edition 3.5.x up and
running properly. We downloaded UDB Fix Pack 3 to a temporary directory and
decompressed it for later use.
Before starting the actual installation, we created a DB2 user and group, created
a new volume for the DB2 instance, and allocated disk space.
The main steps are:

1. Create a new file system for the DB2 instance, where all databases will be
kept. We called this /home/db2inst1.
2. Allocate file system storage space to journaled file systems, including the one
just created, as shown in Table 3-1. As the WebSphere Application Server
and WebSphere Payment Manager databases grow, the size of the
/home/db2inst1 file system may need to be increased.
Table 3-1 Free space needed in journaled file systems.
File system Blocks of free space needed in
scenario 1
/ 100,000
/home 100,000
/home/db2inst1 600,000
/usr 1,000,000
3. Create a user db2inst1 (the same name as the instance for ease of use) in a
new group db2admin.
Note: Don’t use more than 8 characters for the name of the owner of the DB2
instance. DB2 recommends no more than 8 characters to keep compatibility
with host S/390 environments.
4. Give the ownership of the file system where the DB2 instance will reside
(/home/db2inst1) to this new user (db2inst1). Use the command chown -fR
db2inst1:db2iadm1 /home/db2inst1. Then verify the file system ownership
(user db2inst1, group db2iadm1) with ls -la /home/db2inst1.
The AIX machine is now ready for the installation of DB2 UDB Enterprise Edition
7.1 software.
WebSphere Application Server

WebSphere Application Server, Advanced Edition V3.5 base is included with the
WebSphere Payment Manager product, so we downloaded Fix Pack 4 for
WebSphere Application Server. With the AIX maintenance level and the DB2 Fix
Pack level we used, at least Fix Pack 3 for WebSphere Application Server was
required, but we installed Fix Pack 4.
WebSphere Payment Manager

We installed the WebSphere Payment Manager framework and tested it with the
included OfflineCard cassette. The installation of other cassettes is very
straightforward once all the data required by the specific cassette is obtained,
and is discussed in later chapters of our redbook.
Installation steps
The following steps should used to complete the install:
1. Install the latest maintenance level for AIX.

2. Install DB2.
3. Apply the Fix Pack to DB2.
4. Create a database for WebSphere Application Server.
5. Install WebSphere Application Server. If you can get Version 3.5.2 of
WebSphere Application Server, use it. It solves some problems with
prerequisites checks. This will also install IBM HTTP Server (IHS).
6. Apply the patch to WebSphere Application Server. This will also patch IHS.
7. Create a database for Payment Manager.
8. Install Payment Manager.
9. Apply the patch to Payment Manager.
Although Payment Manager includes a silent installation of WebSphere

Application Server for a clean machine (avoiding step 4) we did not use this
installation approach. This install imposes several restrictions on the database
and directory names, and provides you with few configuration options. If this
approach does meet your requirements, ensure that the following steps are taken
before running the install:
1. Check that the following AIX packages are installed:
a. bos.adt.include
b. bos.adt.lib
c. bos.rte
d. X11.adt.lib
e. X11.adt.motif
2. Install the latest maintenance level for AIX.
Operating system
The only step necessary here is the installation of the correct maintenance level.
Check for the required space in the / (root), /tmp, /usr and /var file systems by
making a preview of the maintenance level update using smitty update_all. The
space requirements are included in the summary at the end of the SMIT output.
You can choose whether to commit the software updates. The advantage of
committing is more free space on the file systems. The disadvantage is that you
cannot roll back the changes.
You can check out if the fixes has been installed with the command:
instfix -ikv 4330-08_AIX_ML
This will report that not all filesets have been found, but this is not a problem,
because not all packages to fix are installed on the machine. However, if no fixes
have been installed the report will say that no data was found about the fixes,
and this is a problem that you will need to correct.
If everything is OK, you can proceed with the installation.
Change the file systems size if needed and repeat the smitty update_all
command with the same options as in the preview, but this time applying the
changes.
Reboot the machine with the shutdown -Fr command after the update has
successfully completed.
After this, your AIX machine will be at the latest maintenance level.
DB2
Execute the db2setup command from the DB2 install directory to start the DB2
install. Follow these steps:
1. When the Install DB2 V7.1 window appears, select DB2 UDB Enterprise
Edition, highlight OK, and press Enter.
2. When the Create DB2 Services window appears, select Create a DB2
Instance, highlight OK and press Enter.
3. In the DB2 instance authentication window, enter the following:
– User Name: db2inst1
– Group Name: db2admin
– Home Directory: /home/db2inst1
– Highlight OK and press Enter.
Note: The password field is intentionally left blank. In this example, we

have manually created the user db2inst1 and set the password. DB2
cannot change an existing user’s password. If a password is entered, it will
be ignored.
4. You can ignore the message about DB2 not being able to change an existing
password and continue.
5. Enter the following DB2FENC values:
– User Name: db2fenc1
– Group Name: db2admin

– Home Directory: /home/db2fenc1
– Password: <your_password>
– Verify password: <your_password>
– Highlight OK, and press Enter.
6. In the Create DB2 Services window, highlight OK and press Enter.
7. Once the Summary Report window appears, listing the product components
to be installed, highlight Continue and press Enter.
8. The db2setup program installs the selected components. Depending on the
speed of your processor, this can take up to 15 minutes. When the install
completes, a notice window informs you whether it was successful.
9. Scan the Status Report to ensure that all components were installed
successfully. The log of all installation process is saved on /tmp/db2setup.log.
Modify the .profile file of the DB2 instance owner so that the db2profile is set up
automatically every time the user logs on. Create a new or edit the existing
.profile for the DB2 instance owner and add this line:
$HOME/sqllib/.db2profile
Switch to the DB2 instance owner ID ( su - db2inst1) and ensure that you can
start ( b2start) and stop DB2 (db2stop). Also test that you can access the DB2
command line by typing db2.
Before applying the DB2 Fix Pack, all DB2 service must be stopped. The
commands to do this are:
su - db2inst1
db2 force applications all
db2 terminate
db2stop
db2licd end
exit
To install the .bff files that comprise the DB2 Fix Pack, with all the prerequisites in
apply state, use the command smit update_all and make sure to select the
options COMMIT software updates = NO and SAVE replaced files = YES. Before
actually applying the fixes, do a preview. If everything is OK, proceed with the
real update. You can later commit or reject the Fix Pack using SMIT again.
This Fix Pack has an additional subdirectory in the installation image. The name
of this subdirectory is “extras”. This extras subdirectory contains the filesets for
the double-byte and unicode conversion tables, specifically the following filesets:
db2_07_01.cnvucs
db2_07_01.conv.jp
db2_07_01.conv.kr
db2_07_01.conv.sch
db2_07_01.conv.tch
To install the filesets in the extras subdirectory, use the command smit
install_all.
Note: Installing the extras subdirectory will automatically commit the above
filesets. You will not be able to reject the Fix Pack if you install the extras
subdirectory.
Since future Fix Packs will require this Fix Pack to be already installed, they will
no longer include the extras subdirectory. This means that you must have these
filesets installed before installing future Fix Packs.
After applying fixes, you must enter the following at a command prompt:
db2 terminate
db2 CONNECT TO dwcntrl
db2 BIND $HOME/sqllib/bin/@db2ubind.lst BLOCKING ALL GRANT PUBLIC
db2 BIND $HOME/sqllib/bin/@db2cli.lst BLOCKING ALL GRANT PUBLIC
db2 terminate
IHS, WebSphere and Payment Manager

Before starting the install program of WebSphere Payment Manager we need to
create the databases for WebSphere Application Server and for WebSphere
Payment Manager, and to create some alias for the installation to work.
To create the database for WebSphere Application Server issue these

commands as the user db2inst1 (the owner of DB2).
db2 create db was
db2 update db cfg for was using applheapsz 256
If you install UDB and WebSphere Application Server Version 3.5 on the same
machine, you must enter these commands (substituting the names appropriate
for your system) from a DB2 prompt to circumvent a known problem in
WebSphere Application Server:
catalog tcpip node node_name remote hostname server svcename
catalog database db_name as db_alias at node nodename
Then edit the /etc/environment file and add the following line:
EXTSHM=ON
As DB2 Database Administrator (db2inst1), edit the .db2profile file in

/home/db2admin/sqllib/ and add the following lines:

DB2COMM=tcpip
export DB2COMM
Start or restart DB2.
If you want the setup program to install WebSphere Application Server,

Advanced Edition V3.5, you must use the alias of wasalias for db_alias when
cataloging the WebSphere Application Server database.
Then, create a database for the Payment Manager by entering:

db2 create db payman
You may want to have the Payment Manager database in a different DB2
instance from the WebSphere Application Server database. If this is the case you
need to create a new DB2 instance (for example psadmin). If you do this you will
also have to define service name ports in the /etc/services file:
db2cpsadmin 50000/tcp
(e.g., db2c + instance name; port = 50000) and
db2ipsadmin 50001/tcp
(e.g., db2i + instance name; port = 50001)
Note: Make sure your Internet connection is up and running before starting
the installation program. You have to have a fully qualified host name
configured; otherwise, WebSphere Payment Manager will use a host name
ending with a dot. If you are not sure, at the end of the installation check the
httpd.conf file of the HTTP server; probably it will have the value for the
directive ServerName with a dot at the end.
Also ensure that the resolution on your display is set to 800 by 600 pixels or
higher to best view the Payment Manager installation program.
The database, the HTTP Server, and WebSphere Application Server must be
running during the installation.
Install procedure on AIX:

1. Log on as root (use su - root to load all environmental variables as root).
2. Mount the Payment Manager AIX CD-ROM.
3. Run the Install command found on the WebSphere Payment Manager CD.
5. Accept the license agreement.
6. Accept the default destination directory or enter another directory. Do not
include blanks or spaces in the destination directory name to avoid DB2
problems.
7. Select the UDB database to use with Payment Manager.
8. If the install finds the JDBC driver information, click Next. If the install program
does not automatically find the JDBC driver information you should enter the
correct values. For example:
– JDBC Driver Class name: com.ibm.db2.jdbc.appDB2Driver
– JDBC Class location: /usr/lpp/db2_07_01/java12/db2java.zip/
– JDBC Driver shared library path: /usr/lpp/db2_07_01/lib/
Note: If you entered incorrect database information and database errors
occur, using the Back button may cause more database error pop-ups to
appear. If this occurs, you can either click Cancel and restart the installation
or you can click Back through several windows and then move forward using
the Next buttons (ensuring the correct values are entered at each intervening
window) until you get back to the database entry window. Once this window
reappears, you can enter the correct information.
9. In the Payment Manager Database Access Information window, enter your
values for the database owner user ID, administrator’s user ID, administrator‘s
password, Payment Manager database name and the DB2 instance name.
For example, if you are using UDB, enter:
db2admin /*for the database owner user ID
db2admin /*for the database administrator's user ID
db2admin /*for the database administrator's password
payman /*for the IBM Payment Manager database name.
DB2 /*The default DB2 instance name
application on your system uses this TCP port.
Note: The progress bar will move during installation, although at times it may
Applying a Fix Pack to WebSphere Application Server

The WebSphere Application Server Fix Pack 4 also patches the IBM HTTP
Server, so you must stop both IBM HTTP Server and WebSphere Application
Server before applying the Fix Pack.
Install the Fix Pack by following the instructions of the readme, taking care to
define the correct classpath.

Stop, check and start services script
A basic task needed after the installation is the automation of the starting,
stopping and checking of the services, be it all in one block or one by one.
For AIX we have build a script that does all three things and that even checks if
the application server for the Payment Manager servlets inside WebSphere
Application Server is up and running. The script is run as root and also makes
use of the DB2 user (in our example, db2inst1).
Three files are needed. One is the shell script that controls the starting, checking
and stopping of processes as shown in Example 3-1 on page 51.This should be
edited to use the actual directories where all the products are installed. The other
two shown in Example 3-2 and Example 3-3 on page 53 are TCL script files used
for WebSphere Application Server to stop and start the Payment Manager
application server. These two also need to be edited to use the node name of
your WebSphere Application Server. These two scripts must be placed in the bin
directory of WebSphere Application Server.
If you choose to start all the Payment Manager services manually, points to note
include:
The Payment Manager environment for IHS must be loaded before starting
IHS. If it is not loaded, the servlets won’t be able to connect to the database.
This is done with the command
. <WPM_directory>/SetupWebServerEnvironment
Make sure to run this command with the same user that starts the IHS.
The database must be running before starting Payment Manager or
WebSphere Application Server.
Use nohup to start the Payment Engine:
nohup <WPM_directory>/IBMPayServer
The order in which we recommend you start all the services is as follows:
1. Make sure IHS is stopped.
2. Start DB2.
3. Start Payment Manager.
4. Start WebSphere Application Server and the Payment Manager application
server.
5. Load the Payment Manager environment for the HTTP server.
6. Start IHS.
To stop the services, reverse this order.
Example 3-1 Code for rc.wpm. Before using it, be sure to edit the directories and user
names
#!/bin/sh
#
# Start, Stop and Check Payment Manager related services
case $1 in
start)
CURDIR=$PWD
echo
cd /usr/HTTPServer/bin
./apachectl stop > /dev/null 2>&1
echo "Starting DB2 instance"

su - db2inst1 -c "db2start" > /dev/null 2>&1
echo "Starting Payment Manager"

cd /usr/lpp/PaymentManager
nohup ./IBMPayServer &
echo "Starting WebSphere Application Server"

cd /usr/WebSphere/AppServer/bin
./startupServer.sh &
sleep 120
echo "Starting Payment Manager Application Server"
./wscp.sh -f ./startWAS.tcl
echo "Starting Apache Web Server"

. ./SetupWebServerEnvironment
/usr/HTTPServer/bin/apachectl start > /dev/null 2>&1
cd $CURDIR
echo
echo "Servers Started"
echo
;;
stop)
CURDIR=$PWD
echo
echo "Stoping Apache Web Server"

cd /usr/HTTPServer/bin
./apachectl stop > /dev/null 2>&1
echo "Stoping WebSphere Application Server"

cd /usr/WebSphere/AppServer/bin
./wscp.sh -f ./stopWAS.tcl
echo "Stoping Payment Manager"

./StopIBMPayServer
cd $CURDIR
echo
echo "Servers stoped"
echo
;;
check)
PROC=$(ps -ef | grep java | grep framework.ETill | awk '{print $2}')
if [ -n "$PROC" ]; then
echo "OK: Payment Manager Active"
else
echo "ERROR: Payment Manager Stoped"
fi
PROC=$(ps -ef | grep java | grep AdminServer | awk '{print $2}')
echo "OK: WebSphere Application Server Active"
else
echo "ERROR: WebSphere Application Server Stoped"
fi
PROC=$(ps -ef | grep httpd | grep HTTPServer | awk '{print $2}')
echo "OK: Apache Web Server Active"
else
echo "ERROR: Apache Web Server Stoped"
fi
;;
*)
echo " Usage: /etc/rc.wpm [ start | stop | check ]"
esac
exit
Example 3-2 shows a TCL script that can be used to start the WebSphere
Payment Manager application server.
Example 3-2 Code for startWAS.tcl
ApplicationServer start {/Node:<your_node_name>/ApplicationServer:WebSphere
Payment Manager/}
Example 3-3 shows a TCL script that can be used to stop the WebSphere
Payment Manager application server.
Example 3-3 Code for stopWAS.tcl
ApplicationServer stop {/Node:<your_node_name>/ApplicationServer:WebSphere
Payment Manager/}
3.4 Sun Solaris installation and configuration

This section discusses the installation of WebSphere Payment Manager on
Solaris. We use an Oracle database and the iPlanet Web Server because we
believe that these products are commonly used in Solaris environments. We
include detailed instructions for setting up Solaris, Oracle and iPlanet. These will
be useful for readers who are not familiar with these products, but can be
skipped if you do have experience installing and configuring these products.
In preparing these detailed instructions, we used the install instructions from the
redbook WebSphere Commerce Suite V5.1 Handbook, SG24-6167, because
this provided us with detailed information about running WebSphere Application
Server on Solaris.
For Solaris documentation, visit:

http://docs.sun.com

Note: Payment Manager for Solaris is provided only in English. You must use
an English version of Solaris, as well as an English version of the prerequisite
products (that is, a Web server product, WebSphere Application Server, and a
database product), when installing and using the Payment Manager. This will
change in future releases.
3.4.1 Scenario 1: Oracle, iPlanet, WebSphere Application Server and

Payment Manager on a single machine
An Oracle database and an iPlanet HTTP server is a very common scenario for a
Solaris environment. IBM HTTP Server and DB2 Universal Database can also be
used. WebSphere Application Server is the only application server supported by
Payment Manager.
During the installation, except when noted otherwise, you have to be logged in as
root.
The basic steps to complete before starting the WebSphere Payment Manager
install are:
1. Configure Solaris and apply the recommended fixes.
2. Install Netscape Communicator (prerequisite for iPlanet). Note: Don’t run the
install command from the directory that the iPlanet document specifies, but
from the parent of that directory.
3. Install iPlanet.
4. Configure SSL for iPlanet:
– Request certificate
– Download it
– Install it
5. Change the parameters of the operating system as described in the IBM
WebSphere Payment Manager for Multiplatforms Install Guide Version 2.2,
especially semmsl and semmns. Otherwise, Oracle won’t have enough
processes and memory available and it won’t let you create databases.
6. Install Oracle.
7. Create databases for WebSphere Application Server and Payment Manager.
You can use any name for the SID (the user that owns the database), but
preferably limit it to names up to 4 characters long (Oracle recommendation).
In the creation windows don’t accept the default values; this won’t work. You
must changes some directories and variable values.
8. Install WebSphere Application Server 3.5.1 to avoid a problem with the
prerequisites check that occurs when checking supported versions of iPlanet.
(WebSphere Application Server does support iPlanet 4.1 SP7 when Fix Pack
4 is applied, but since we want to install the base WebSphere Application
Server 3.5 before upgrading to 3.5.4, it is necessary to turn off prerequisite
checking).
9. Confirm changes to the iPlanet server.
Preparing the Solaris machine

First, we prepared all the data and software needed to assure a quick installation.
We checked the prerequisites and downloaded the patches to a temporary
directory on our Solaris machine.
If you will be installing Solaris on a new machine, be sure to configure Solaris so

that enough space is allocated to the file systems created. This is because the
default install of Solaris will only create 27 MB for the /opt file system where all
products in this guide will be installed. At least 2 GB will be needed but providing
more space may be also be desirable. More space should also be provided to
the /usr and root file systems. Table 3-2 provides some guidance on the space
requirements on Solaris.
Table 3-2 Disk space needed - Commerce Suite server by application
Product File system installed to Disk space needed
iPlanet Web Server V4.15 /usr 130 MB
WebSphere Application /opt 250 MB

Server V3.5
WebSphere Commerce /opt 250 MB

Suite V5.1
Oracle8i database client /opt 350 MB
Install Netscape Communicator

The iPlanet Web Server requires Netscape Communicator V4.61 or higher to be
used for administration.
Complete the following steps to install Netscape Communicator V4.76:

1. Start a Solaris Console window and enter the following:
# cd /opt
# mkdir ns476
2. Netscape Communicator V4.76 can be downloaded from:
http://www.sun.com/solaris/netscape/getnetscape476.html

Download the file to the /opt/ns476 directory.
Note: Netscape Communicator V4.76 installation instructions can be found at:

http://www.sun.com/software/solaris/netscape/476_install.html
3. Uncompress the download file.

Check the name of the downloaded Netscape Communicator file:
– If the Netscape file does not have a .Z suffix, your browser has
uncompressed the Netscape file automatically. Use the following
command to extract its files.
# tar -xf <filename>
– If the Netscape file has a .Z suffix, your browser did not uncompress the
Netscape file automatically. Use the following command to uncompress
and extract its files.
# zcat <filename>.Z | tar -xvf -
4. Change to the directory where the compressed version of Netscape
Communicator was extracted.
For example:
# cd /opt/ns476/NSCPcom
5. Install Netscape Communicator using pkgadd:
# pkgadd -d `pwd` NSCPcom
6. Follow the install instruction prompts.
7. To start Netscape Communicator, do one of the following:
– Command line:
# /opt/NSCPcom/netscape
– Click Internet (the globe icon) from the Solaris 7 CDE Front Panel.
8. Add an entry to your PATH for the directory in which Netscape Communicator
is installed. For example, if Netscape Communicator were installed in the
default directory, you would add /opt/NSCPcom to your path. The path may be
set in the .dtprofile, .login, or .cshrc file.
For example, we added the following path to the /etc/.dtprofile file:
export PATH=$PATH:/opt/NSCPcom
9. Configure Netscape Communicator by clicking Edit -> Preferences from the
menu bar. We configured the SOCKS server, fonts, and home page.
Install iPlanet Web Server
This section provides detailed instructions for installing, configuring, and verifying
the Netscape iPlanet Web Server, Enterprise Edition V4.1 SP7 (4.17).
Installing the iPlanet Web Server involves the following steps:

Pre-installation steps for iPlanet Web Server
iPlanet Web Server
Enable SSL for iPlanet Web Server
Verify iPlanet Web Server
Note: For more detailed information on iPlanet Web Server refer to:
http://developer.iplanet.com/docs/manuals/enterprise.html
Pre-installation steps for iPlanet Web Server

Before installing the iPlanet Web Server, complete the following steps:
1. Determine that the host name and IP address of the server machine are
properly configured.
For example:
Host name: sun4.itso.ral.ibm.com
IP Address: 9.24.105.29
2. Determine if the server needs a DNS alias.
You may wish to establish a DNS alias that points to the server machine. If a
DNS alias will be needed, create it. In our example, we do not create a DNS
alias.
3. Ensure that you have two unique, reserved port numbers available, one for
standard Web access, and one for secure Web access.
The most common ports are 80 (HTTP) for standard access and 443
(HTTPS) for secure access.
4. Create a UNIX user account to be used by the iPlanet Web Server. This
account should have restricted access for security reasons. To create a user,
follow the steps below. In this example, we create a user and group, both
named iplanet.
# groupadd iplanet
# useradd -g iplanet -d /export/home/iplanet -m -s /usr/bin/ksh iplanet
# passwd iplanet
After the last command, you will be prompted for a password for the new user,
and then asked to confirm it.

Install iPlanet Web Server
To install the iPlanet Web Server, complete the following steps:
1. Start a Solaris Console window and log in as root.
2. Change to the install directory for the iPlanet Web Server and start the install
by typing the following:
# ./setup
3. When you are prompted with the message Would you like to continue with
the installation [Yes], press Enter (for Yes as default).
Tips: The following tips are used for navigation during the install.
Press Enter to choose the default and go to the next window.
Type Ctrl+B to back to the previous window.
Type Ctrl+C to cancel the installation program.
You can enter multiple items using commas to separate them, for example
1,2,3.
4. When you are prompted with the message Do you agree to license terms?
[No]: type Yes, and then press Enter.
5. When you are prompted with the message Choose the installation type
[2], press Enter to accept the default (Typical installation).
6. When you are prompted with the message Install location
[/usr/netscape/server4], press Enter to accept the default.
7. When you are prompted with the message Specify the components you
wish to install [All], press Enter to accept the default.
8. When you are prompted with the message Specify the components you
wish to install [1,2,3,4,5,6,8]: type 1,2,3,4,5 and then press Enter.
Note: The following components are required by WebSphere Commerce

Suite:
– Server Core
– Java Runtime Environment
– Java Support
– SSJS Support
– SSJS Database Support
9. When you are prompted with the message Computer name
[your_hostname.domain], press Enter.
10.When you are prompted with the message System User [nobody], type the
user created in the pre-installation steps, for example iplanet, and then
press Enter.
11.When you are prompted with the message System Group [nobody], type the
group created in the pre-installation steps, for example iplanet, and then
press Enter.
12.When you are prompted with the message Run iWS Administration Server
as [root], press Enter.
13.When you are prompted with the message iWS Administration Server User
Name [admin], press Enter. You will be prompted for a password.
14.When you are prompted with the message iWS Admin Server Port [8888],
press Enter.
15.When you are prompted with the message Web Server Port [80], press
Enter.
16.When you are prompted with the message Do want to register this with
an existing Directory Server [No], press Enter.
17.When you are prompted with the message Web Server Content Root
[/usr/netscape/server4/docs], press Enter.
18.When you are prompted with the message Do you want to use your own JDK
[No], press Enter.
19.Review messages to make sure everything extracted and installed
successfully. Press Enter to continue and return to the command prompt.
The iPlanet Web Server installation is complete.
Enable SSL for iPlanet Web Server

In this section we provide detailed instructions for requesting a certificate,
installing the certificate and configuring an iPlanet Web Server for SSL. In our
example, we will request a test certificate from VeriSign. For a production
environment you will need to request a real certificate from VeriSign.
The iPlanet Web Server SSL enablement is divided into the following steps:
Create a server for SSL transactions
Create a certificate trust database
Request a server certificate
Install the server certificate
Turn SSL encryption on

To enable SSL for iPlanet Web Server, complete the following steps:
1. Start the iPlanet Web Server Administration server by typing the following
commands:
# cd /usr/netscape/server4
# /usr/netscape/server4/startconsole
2. When the Login window appears, enter the following:
– User ID: iPlanet (iWS Administration server User Name created during
the installation steps above)
– Password: <your_password>
3. If the Servers tab is not already selected, click the Servers tab.
4. Click Add Server in the left navigation pane.
5. In the Add Server window, enter the information for your SSL server as
follows:
a. In the Server Name field, enter your fully qualified host name, for example
sun4.itso.ral.ibm.com.
b. In the Server Port field, enter the port you chose as your SSL port, for
example 443.
c. In the Server Identifier field, enter a name that will identify your SSL
server, for example sun4_SSL.
d. In the Server User field, enter the UNIX user that you created for the Web
server, for example iplanet.
e. In the MTA Host field, accept the default of localhost.
f. Select Never attempt to resolve IP addresses into host names. This is
the default.
g. In the Document Root field, accept the default, which will be the document
root that you specified during installation, for example
/usr/netscape/server4/docs.
h. Click OK to create the server.
6. In the Success! window, you will be shown a link to Configure your new
server. Click this link.
Note: You can configure your server at any time from the Manage Server
window of the iPlanet Administration server by completing the following steps:
– Enter URL: http://<host>:8888/https-admserv/bin/index.
– In the Select a Server pull-down, select the server you want to
configure, for example SSL (the server name added for SSL in previous
steps).
– Click Manage.
7. In the Server Manager window, click the Security tab to create a Certificate
Trust database.
8. Enter and re-enter a password to use for this database, then click OK to
create the database.
9. A pop-up window should appear, indicating that a database was successfully
created.
10.The next step is to generate a certificate request. Click the Request a
Certificate link in the left navigation pane.
11.Generate your request as follows:
a. Select the New Certificate radio button.
b. In the CA-email address field, enter your e-mail address.
c. Select internal (software) in the Cryptographic module pull-down.
d. Enter you certificate trust database password in the Key pair file password
field.
e. In the Common Name field, enter the URL by which your host will be
known. This is normally the fully qualified host name, for example:
f. In the remaining fields, enter your contact information.
g. Click OK to generate the certificate request.
12.The next window will inform you that your request has been sent. Take note of
the file name specified by the line:
A copy of the certificate request has been saved in the file:
<file_name>.
13.Proceed to a Certificate Authority Web site to submit your request. Follow the
instructions provided there for the completion of your request.

Note: Most sites will allow you to generate a test certificate to use for
non-production servers. We went to VeriSign to generate a test certificate, at
the following URL:
http://digitalid.verisign.com/server/index.html
14.When you receive the certificate, go to the Security section of the server
manager for the SSL server (if you are not already there), by doing the
following:
a. Enter URL: http://<host>:8888/https-admserv/bin/index.
b. In the Select a Server pull-down, select the server you want to configure,
for example sun4_SSL (the server name added for SSL in previous steps).
c. Click Manage.
d. Click the Security tab.
15.Click the Install Certificate to install your new certificate. Figure 3-4 shows
the certificate installation window.
Figure 3-4 Certificate installation
16.Fill in the fields with the following values:

a. In the Certificate For field, select the This Server radio button.
b. In the Cryptographic module pull-down, select internal (software).
c. In the Key Pair File Password field, enter the certificate trust database
password defined above.
d. Leave the Certificate Name field blank.
e. Select the Message Text radio button.

f. Paste the certificate sent to you by the Certificate Authority into the
Message Text text area.
Note: Alternatively, you can save the certificate to a file, and specify the
file name in the Message is in this file: text area.
g. Click OK to begin installing the certificate.

17.In the Add Server Certificate window, take note of the information provided
(For example, certificate name: Server-Cert) and click Add Server
Certificate. Figure 3-5 shows an example of this window. The certificate
details must match the information you provided while requesting the
certificate.
Figure 3-5 Check certificate information
18.A success window will pop up, as well as a window warning you that the
server will need to be restarted for the changes to take effect.
19.In order to activate SSL encryption, go to the Preferences section of the
server manager for the SSL server (if you are not already there), by doing the
following:
a. Enter URL: http://<host>:8888/https-admserv/bin/index.
b. In the Select a Server pull-down select the server you want to configure,
for example SSL (the server name added for SSL in previous steps).
c. Click Manage.
d. Click the Preferences tab.
20.Click Encryption On/Off in the left navigation pane.
21.Under Encryption, select the On radio button, verify the port number is 443
(or as previously defined), and then click OK.
22.When the warning message Security changes require shutdown and
restart appears ,click OK.
23.When the Save and Apply window appears, click Save and Apply.
24.When the Warning window message The security information that you
entered below will be sent in the clear, and may be exposed to
network snooping appears, enter the password for internal (software):
<trust_database_password>.
25.A success window should appear. Click OK.
26.Configuration is now complete. Both the HTTP and HTTPS servers will need
to be restarted for changes to take effect.
Verify iPlanet Web Server

To verify that the iPlanet Web Server is working properly, complete the following
steps:
1. Start the iPlanet Administration server by entering the following URL:
http://<host>:8888/https-admserv/bin/index
2. In the Select a Server pull-down, select the HTTP server, for example
3. Ensure that the HTTP Server is started. The server status will be displayed. If
the server is not running, click Server On to start the server.
If the server starts successfully, you should the message:
The server is currently on.
4. Verify that the HTTP server is running by accessing the server from a Web
browser client, by entering the following URL: http://<hostname>
5. Ensure that the HTTPS server (SSL) is started from the iPlanet
Administration server console. The server status can be checked by selecting

the Select a Server pull-down for the SSL server. If the server is not running,
click Server On to start the server.
6. Verify that the HTTPS server is running by accessing the server from a Web
browser client, by entering the following URL: https://<hostname>
The iPlanet Web Server install, configuration, and verification section is now
complete.
Install Oracle8i server

This section provides detailed instructions for installing and configuring the
Oracle8i Enterprise Edition Release 2 (8.17) for Sun SPARC Solaris on the
Oracle8i database server system.
We have organized the Oracle8i Enterprise Edition database server install into
the following phases:
Oracle8i install prerequisites
Install Oracle8i Enterprise Edition Database Server
Oracle8i post install configuration
Prepare the Oracle8i databases
Oracle8i install prerequisites

Prior to the installation of Oracle8i you are required to complete the following
prerequisites:
Oracle8i disk space requirement
Verify Solaris 7 patch levels required by Oracle8i
Verify Solaris 7 required packages for Oracle8i
Verify system executables
Configure the UNIX kernel for Oracle8i
Create UNIX groups for Oracle8i
Create UNIX user account for Oracle8i
Set environment variables
Create mount points
Oracle8i disk space requirement

We recommend that you allocate the following disk space:
Oracle8i Enterprise Edition Server 8.1.7
Requires 1160 MB of free disk space.
Oracle8i Client 8.1.7
Requires 450 MB of free disk space.
We allowed for this space when we installed Solaris 7 by allocating space to the
/opt file system.
Verify Solaris 7 patch levels required by Oracle8i

Prior to the installation of Oracle8i, we need to verify that the required level of
Solaris 7 patches are applied.
1. Ensure the following Solaris 7 patches are installed at the indicated level or
higher as seen in Table 3-3.
Table 3-3 Solaris 7 patches required by Oracle8i (JRE 1.1.8_10)
Solaris 7 Required or
patch ID Description Recommended
107636-01 X input and output method patch Required
106980-05 Lib thread patch Recommended
107607-01 Motif fontlist, fontset, libxm Recommended
107078-10 Open Windows 3.6.1 Xsun patch (1) Recommended
2. Verify the following Oracle8i (JRE 1.1.8_10) required patches are installed by
typing the following command:
# showrev -p | grep <patch_name>
Where <patch_name> is included without -<level> listed above.
For example:
# showrev -p | grep 107636
Verify Solaris 7 required packages for Oracle8i

Prior to the installation of Oracle8i, we need to verify that some required Solaris 7
packages are installed.
1. Ensure the following Solaris 7 packages are installed.
Table 3-4 Solaris 7 packages required by Oracle8i
Solaris 7
package name Description
SUNWarc Archive libraries
SUNWbtool CCS tools bundled with SunOS
SUNWhea SunOS header files

Solaris 7
package name Description
SUNWlibm Sun workshop bundled libm
SUNWlibms Sun workshop bundled shared libm
SUNWsprot Solaris bundled tools
SUNWtoo Programming tools
2. Verify the following Solaris 7 packages are installed by typing the following
command:
# pkginfo -i <package_name>
Where the <package_name> is one listed in Table 3-4.
For example:
# pkginfo -i SUNWarc
Verify system executables

This step verifies that the correct version of the system executables is being
used.
Type the following commands to verify system executables:

$ /usr/bin/which make
$ /usr/bin/which ar
$ /usr/bin/which ld
$ /usr/bin/which rm
The which command returns you to the executable path. The path search order is
determined by the location of the path in the path environment variable of the
shell.
The required directory for the executable is /usr/ccs/bin. If this is not already in
your path or not in the beginning of the path, you will need to add /usr/ccs/bin to
the beginning of the path of the current shell.
Configure the UNIX kernel for Oracle8i

To ensure that Oracle8i has enough system memory, we need to configure the
UNIX kernel.
To configure the UNIX kernel for Oracle8i, complete the following steps:
1. Start a Solaris Console window and log in as user root.
2. Back up the system file:
# cd /etc
# cp system system.bak
3. Add or modify the Solaris kernel configuration parameters as explained in the
IBM WebSphere Payment Manager for Multiplatforms Install Guide. In our
case, for 1024 MB of physical memory the kernel parameters are:
set msgsys:msginfo_msgmax=65535
set msgsys:msginfo_msgmnb=65535
set msgsys:msginfo_msgmap=258
set msgsys:msginfo_msgmni=256
set msgsys:msginfo_msgssz=16
set msgsys:msginfo_msgtql=1024
set msgsys:msginfo_msgmax=65535
set msgsys:msginfo_msgseg=32768
set shmsys:shminfo_shmmax=4294967295 (more than the indicated value for WPM

is required for Oracle)
set shmsys:shminfo_shmseg=16
set shmsys:shminfo_shmmni=300
set semsys:seminfo_semmni=1024
set semsys:seminfo_semmap=1026
set semsys:seminfo_semmns=2048
set semsys:seminfo_semmnu=2048
set semsys:seminfo_semume=200
set semsys:seminfo_semopm=200
Add also this extra kernel configuration parameters needed for Oracle:
set shmsys:shminfo_shmmin=1
set shmsys:shminfo_shmmni=100
set semsys:seminfo_semmsl=2048
set semsys:seminfo_semvmx=32767
Important: In particular the semmns and semmsl parameters determine the

number of processes the kernel will handle and each Oracle database
requires, by default, 150. If these values are set too low, new databases
cannot be created or started.
4. Type the following command to shut down and reboot:

# /usr/sbin/shutdown -i6 -g0 -y

Create UNIX groups for Oracle8i
Depending on the size and makeup of your organization, you may have several
roles defined for database administration. The Oracle Installation Guide, Release
3 (8.1.7) for Sun SPARC Solaris, A85471-01, recommends that you create
groups for the roles as seen in Table 3-5.
Table 3-5 Groups for Oracle8i
Role of Oracle8i group Suggested group name
Database administrator dba
Database operator dboper
Oracle installer group oinstall
In our example, we created groups called dba and oinstall as follows:

1. Start a Solaris Console window and log in a root.
2. Create groups by typing the following:
# groupadd dba
# groupadd oinstall
Create UNIX user account for Oracle8i

To create a user named oracle and make the user a member of the dba group,
complete the following steps:
1. Start a Solaris Console window and log in a root.
2. Create user oracle by typing the following:
# useradd -d /export/home/oracle -m -g oinstall -G dba -s /usr/bin/ksh
oracle
Syntax:
# useradd -d <path_home_dir> -m -g <primary_group> -G <secondary_group> -s
<path_shell> <username>
Where:
• -d <path_home_dir> is the home directory of the user
• -m creates the directory of the user and .profile
• -g is the primary group to add the user to
• -G is the secondary group to add the user to
• -s <path_shell> is the path of the shell used by this user
• <username> is the user name to create
3. Create password for user oracle by typing the following:
# passwd oracle
This will prompt the user for the password.
4. Verify login with user:
# su - oracle
$ su - oracle
You will be prompted for your password.
Set environment variables

To set environment variables as part of the .profile of the oracle user shell,
1. Log in as user oracle
# su - oracle
2. Add the following environment variables to the oracle user .profile:
umask 022
export ORACLE_BASE=/opt/oracle8/u01
export ORACLE_HOME=$ORACLE_BASE/app/oracle/product/8.1.7
export ORACLE_SID=oracle
export PATH=$PATH:$ORACLE_HOME/bin
# The following export is required for XWindows used by Oracle8i install.

export DISPLAY=hostname:0.0
If you will be working on the Solaris machine you can use :0.0 without the
host name.
Attention: A SID is the owner of a database, a user inside the Oracle

environment, because the owners of the databases are not Solaris users as
with DB2. No matter what you type here, in subsequent steps we will create
new SIDs for each database. It is necessary to use a SID, although the Oracle
Installation Guide, Release 3 (8.1.7) for Sun SPARC Solaris, A85471-01,
states that is optional. If you don’t provide a SID at this stage we found that the
installation produces an error.
Create mount points

To create mount points, complete the following steps:
2. Create the following directories:
This directory is used for the Oracle8i software:
# mkdir -p /opt/oracle8/u01

The following directories are intended to be used for databases:
3. Change the owner of the directories to user oracle and group dba by typing
the following command:
# chown -R oracle:dba /opt/oracle8
4. Change permissions as follows:
# chmod -R g+w /opt/oracle8
Install Oracle8i Enterprise Edition Database Server

On the database server system, we install the Oracle8i Enterprise Edition. This
database server will host the WebSphere Application Server and Payment
Manager databases.
Complete the following steps to install the Oracle8i Enterprise Edition server:
1. Start a Solaris Console window, and log in as user oracle.
# su - oracle
2. Insert the Oracle8i Enterprise Edition Release 2 (8.1.7) for Sun SPARC
Solaris CD-ROM on the database server.
3. To start the Oracle8i install, type the following:
# xhost +
access control disabled, clients can connect as any host
# su - oracle
$ /cdrom/oracle8i/runInstaller
4. When the Oracle8i Welcome window appears, click Next.
5. When the File Locations window appears, verify that the paths are as follows
and then click Next:
– Source: /cdrom/oracle8i/stage/products.jar
– Destination: /opt/oracle8/u01/app/oracle/product/8.1.7
Note: The destination should be the path specified as the ORACLE_HOME in

“Set environment variables” on page 71.
6. When the UNIX Group Name window appears, enter the group oinstall
defined above, and then click Next.
7. When the Oracle Universal Installer window appears, you will be prompted to
run a script as user root in another Solaris Console window.
a. Start a Solaris Console window and log in as root.
b. Execute the script by typing the following:
# /tmp/OraInstall/orainstRoot.sh
c. You should see a message that states the following:
Creating Oracle Inventory pointer file (/var/opt/oracle/orainst.loc).
Changing groupname of /opt/oracle8/u01/oraInventory to dba.
8. Click the Oracle Universal Install window to bring it back to the foreground,
and then click Retry.
9. When the Available Products window appears, select Oracle8i Enterprise
Edition 8.1.7.0.0, and then click Next.
10.When the Installation Types window appears, select Custom, and then click
Next.
11.When the Available Product Components window appears, do the following:
– Deselect Legato Storage Manager
– Deselect Oracle HTTP Server 1.3.12.0.1a
– Deselect Oracle Product Options 8.1.7.0.0
– Deselect Development Tools 8.1.7.0.0
– Select Oracle Java Products 8.1.7.0.0 -> Oracle JDBC drivers and
select all the available drivers:
• Select Oracle JDBC/OCI Driver for JDK 1.1 8 1.7.0.0
• Select Oracle JDBC/OCI Driver for JDK 1.2 8.1.7.0.0
• Select Oracle JDBC Thin Driver for JDK 1.1 8 1.7.0.0
• Select Oracle JDBC Thin Driver for JDK 1.2 8.1.7.0.0
– Click Product Languages and verify that English is selected.
– Click Next.
You should see the status bar indicating the components are loading.
12.When the Component Locations window appears, accept the default and click
Next.
13.When Privileged Operating System Groups window appears, accept the
default and click Next.
In our example, the Database Administrator and Database Operator are in
group dba.

14.When the Authentication Methods window appears, do not select anything
and then click Next.
15.When the Create Database window appears, select No and click Next.
Note: We will create databases for WebSphere Application Server and

Payment Manager in subsequent steps via the Database Configuration
Assistant.
16.When the Summary window appears, review all the information. You can click
Back to change any selection. When everything is OK, click Install.
The installation will begin. It cannot be left unattended because it requires
some scripts to be run as root during the process.
17.When the Setup Privileges window appears, a message will be displayed to
run the following script:
a. Start a Solaris Console window and log in as root.
b. Execute the script by typing:
# /opt/oracle8/u01/app/oracle/product/8.1.7/root.sh
c. You will be prompted to enter the full path to the local bin directory. We
entered /usr/bin. Press Enter.
d. Click the Setup Privileges window to bring it to the foreground, and then
click OK.
18.When the Net8 Configuration Assistant Welcome window appears, click Next.
19.When the Net8 Configuration Assistant: Directory Service Access window
appears, click No, I want to defer directory service access configuration
to another type.
20.When the Net8 Configuration Assistant: Listener Configuration Listener Name
window appears, accept the default (LISTENER) and click Next.
21.When the Net8 Configuration Assistant: Listener Configuration Select
Protocols window appears, accept the default (TCP in selected protocols) and
click Next.
22.When the Net8 Configuration Assistant: Listener Configuration TCP/IP
Protocols window appears, accept the default (use the standard port number
of 1521)) and click Next.
23.When the Net8 Configuration Assistant: Listener Configuration More
Listeners window appears, accept the default (No additional listeners) and
click Next.
24.When the Net8 Configuration Assistant: Listener Configuration Done window
appears, click Next.
This configuration is saved in a tnsnames.ora file.
25.When the Net8 Configuration Assistant: Naming Methods Configuration
window appears, select No, I do not want to change the naming methods
configured, and then click Next.
26.When the Net8 Configuration Assistant Done window appears, click Finish.
27.When the End of Installation window appears, click Exit.
28.Confirm the Exit window prompt with Yes.
29.The Oracle8i Enterprise Edition server installation is now complete.

After the Oracle8i installation, we need to perform the following configuration
steps:
Update oracle user .profile
Net8 configuration
Create dbora for database autostart (optional)
Net8 configuration
Update oracle user .profile

In this section we will add Oracle8i required environment variables to the oracle
user .profile that we created by completing the following steps:
1. Start a Solaris Console window.
2. Log in as the oracle user.
# su - oracle
3. Add entries to the end of the oracle user .profile as seen in Example 3-4.
Example 3-4 oracle user .profile entries required for Oracle8i
export LD_LIBRARY_PATH=$ORACLE_HOME/lib
CLASSPATH=$ORACLE_HOME/JRE:$ORACLE_HOME/jlib:$CLASSPATH
CLASSPATH=$ORACLE_HOME/product/jlib:$CLASSPATH
export CLASSPATH
ORACLE_SID=oracle
ORAENV_ASK=NO
. /usr/bin/oraenv

4. Modify /usr/bin/oraenv to correct the problem that this script overrides the
ORACLE_HOME defined in the oracle user .profile. Find the following text
and add a # at the beginning of each line to make it a comment:
ORAHOME=`dbhome "$ORACLE_SID"`
case $? in
0)ORACLE_HOME=$ORAHOME ;;
*)echo $N "ORACLE_HOME = [$ORAHOME] ? $C"
read NEWHOME
case "$NEWHOME" in
"")ORACLE_HOME=$ORAHOME ;;
*)ORACLE_HOME=$NEWHOME ;;
esac ;;
esac
export ORACLE_HOME
Net8 configuration
This section describes the required configuration for Net8 after the Oracle8i
installation.
2. Update the /etc/services file with the listener. The listener name and port were
defined during the Oracle8i installation (Net8).
We added the following line to our services file:
LISTENER 1521/tcp
3. Save the services file.
Note: The /etc/services file is symbolically linked to /etc/inet/services. When

saving the file with vi use the vi w! command to override the default write
permissions.
4. Check the status of the listener.

# su - oracle
$ lsnrctl status LISTENER
Where LISTENER is the name or your listener.
Prepare the Oracle8i databases

Prior to the installation of WebSphere Application Server and WebSphere
Payment Manager their databases need to be created.
The steps in this process are as follows:

Create an Oracle8i database
Oracle8i database verification
Database tuning
Configure autostart of database
Create Oracle ID and tablespace
Create Payment Manager Oracle ID and tablespace
Configure Net8 on Oracle8i Server
Create an Oracle8i database

We will create the following Oracle8i databases in preparation for the WebSphere
Application Server and Payment Manager installation. Repeat the database
creation process for both databases:
was (WebSphere Application Server repository database)
wpm (WebSphere Payment Manager application database)
To create an Oracle8i database, complete the following steps on the Oracle8i

Enterprise Edition Server system:
1. Start a Solaris Console window as root.
2. Disable access control so that any user can access to the display:
# xhost +
3. Log in as user oracle:
# su - oracle
4. Run the Oracle8i Database Configuration Assistant:
$ dbassist &
5. When the Oracle Database Configuration Assistant welcome window
appears, select Create a database and then click Next.
6. Select Custom as the database type and then click Next.
7. Select Multipurpose as the application type and then click Next.
8. Enter the Concurrently connected users: <value>. We accepted the default
(15). Then click Next.
9. Select Dedicated Server Mode as the server mode and then click Next.
10.In the select options window deselect all options, except SQL *Plus help
(optional), and then click Next.
11.When asked to review the database information, enter the following:
– Global Database Name: was
– SID (don’t use more than 4 characters for this name): was

– Initialization Filename: /opt/oracle8/u01/admin/was/pfile/initwas.ora
– Compatible Parameter: 8.0.5
12.Click Change Character Set
a. Select the Character Set pull-down and select UTF8.
b. Select the National Character Set pull-down and select UTF8.
c. Click OK.
13.Click Next.
14.When the Review the control file parameters window appears, look for the
directories where it will save the database data.
– If it is something to do with admin, then leave the default /opt/oracle8/u01
directory.
– Otherwise, if it is something to do with the oradata, change the directory to
u02 for the first database (was) and u03 for the second (wpm).
Carefully check that all paths are correct, because the defaults are incorrect.
The control files should be placed under the user SID directory (u02 or u03).
See Figure 3-6 for an example. Click Next.
Figure 3-6 Modify control files paths
15.When the Review the SYSTEM tablespace information window appears, look
for the directories where it will save the database data, correct them if
necessary, and click Next as shown in Figure 3-7.
Figure 3-7 Check that the correct paths are used
16.When the Review the redo log file parameter information window appears,
carefully review the paths and click Next. See example in Figure 3-8.
Figure 3-8 The path for the Redo log files must be changed

17.When the Review the logging parameter information window appears, review
it carefully and click Next.
18.When the Review the SGA information window appears, check the number of
processes this database will use.
– If you have followed our instructions and set the kernel parameters semmsl
and semmns, then the default setting of 150 processes will work.
– If you have not set high values for semmsl and semmns, decrease the
processes value. Decreasing this value will not prevent the creation of the
database and this value can be changed in the future. If this value is too
high for your system, the database won’t be created. Figure 3-9 shows the
settings we used.
Click Next (more tuning will be done in later steps).
Figure 3-9 Check if the number of processes is too high for your system or not
19.When the Review the directory path information window appears, accept the
defaults and click Next. See Figure 3-10.
Figure 3-10 Directory path settings must be kept under u01
20.Select Create database now, and click Finish.

21.When the Oracle Database Configuration Assistant alert appears, asking if
you want to proceed, click Yes.
The database creation progress indicator should be visible. This process
takes approximately 20 minutes.
22.Repeat the database creation process for the wpm database.
Oracle8i database verification

After the installation, we recommend that you take some steps to verify that the
Oracle8i Enterprise Edition server is installed correctly.
To verify the Oracle8i Enterprise Edition, complete the following steps:

1. Start a Solaris Console window and log in as user oracle.
# su - oracle
2. To start an Oracle command window, type the following:
– For the WebSphere Application Server database:
$ sqlplus system/manager@was
SQL> quit
– For the WPM database:
$ sqlplus system/manager@wpm

SQL> quit
The syntax of these commands is:
> sqlplus system/<system_password>@<SID>
The Oracle user system has a default password of manager and has access
to all databases. Later we will create users for each database.
Database tuning
1. Start a Solaris Console window and log in as user oracle.
# su - oracle
2. In the $ORACLE_HOME/dbs/init<your_SID>.ora initialization file, modify the
values of the parameters shown in Table 3-6 on page 82. In this table we
show the recommended minimum values for these parameters, but our
Solaris system we kept the highest values of the two values: the
recommended and the default.
Table 3-6 Oracle8i database tuning parameters
Parameters WebSphere Application
Server database value
open_cursors 200
db_block_buffers 2000
shared_pool_size 20000000
processes 100
3. Stop and start the Oracle8i Server for database tuning changes to take effect:
# su - oracle
$ dbshut
$ dbstart
Note: The Oracle8i dbshut and dbstart scripts will stop and start all
databases. This behavior is desired in this example, but may not be
appropriate in other situations.
Using svrmgrl is another option for stopping and starting the databases.
4. If your Oracle8i Server database instances do not start, check the tuning
parameters entered for errors. Changing the tuning values beyond the
physical memory available on the system will result in the database instance
not starting.
Configure autostart of database
The following procedure will automate the startup and shutdown of the Oracle8i
database server.
1. Edit the /var/opt/oracle/oratab file.
Database entries in the oratab file appear in the following format:
ORACLE_SID:ORACLE_HOME:{Y|N}
Where Y or N specifies whether you want the dbstart and dbshut scripts to
start up and shut down the database. Find the entries for all the databases
that you want to start up. They are identified by the SID in the first field.
Change the last field for each to Y to enable the database to start when the
dbstart command is run.
For example:
wpm:/opt/oracle8/u01/app/oracle/product/8.1.7:Y
2. Create a dbora file.
This procedure only needs to be completed once on the Oracle8i database
server.
a. Change to the /etc/init.d directory:
# cd /etc/init.d
b. Create a file called dbora.
Example 3-5 provides a sample dbora file. We changed the ORA_HOME
to reflect the directory specified during the Oracle8i server installation.
Example 3-5 Sample dbora
#!/bin/sh
# Set ORA_HOME to be equivalent to the ORACLE_HOME
# from which you wish to execute dbstart and
# dbshut
# set ORA_OWNER to the user id of the owner of the
# Oracle database in ORA_HOME
ORA_HOME=/opt/oracle8/u01/app/oracle/product/8.1.7
ORA_OWNER=oracle
case "$1" in
’start’)
# Start the Oracle databases:
# The following command assumes that the oracle login will not prompt the
# user for any values
su - $ORA_OWNER -c $ORA_HOME/bin/dbstart &
;;
’stop’)
# Stop the Oracle databases:
# The following command assumes that the oracle login will not prompt the
# user for any values

su - $ORA_OWNER -c $ORA_HOME/bin/dbshut &
;;
esac
c. Link the file dbora as follows:

# ln -s /etc/init.d/dbora /etc/rc0.d/K10dbora
# ln -s /etc/init.d/dbora /etc/rc2.d/S99dbora
Create Oracle ID and tablespace

To create a WebSphere Application Server Oracle user ID and tablespace,
1. Start a Solaris Console window on the database server system, and log in as
user oracle (Oracle DBA).
2. Create a was.sql file as shown in Example 3-6. We include a sample was.sql
file as part of the redbook additional material. See Appendix A, “Additional
material” on page 317 for details on obtaining the sample code.
Example 3-6 was.sql to create the WebSphere Application Server tablespaces and users
drop tablespace temp
/
drop tablespace was
/
drop user ejsadmin
/
drop user ejb
/
create tablespace temp
datafile '/opt/oracle8/u02/oradata/was/temp.dbf'
size 50M
reuse
autoextend on next 2M
maxsize unlimited
/
create tablespace was
datafile '%ORACLE_HOME\DATABASE\was.ora'
size 4M
reuse
maxsize unlimited
/
create user ejsadmin
identified by ejsadmin
default tablespace was
quota unlimited on was
/
grant dba to ejsadmin
/
alter user ejsadmin temporary tablespace temp
/
create user ejb
identified by ejb
default tablespace was
quota unlimited on was
/
grant dba to ejb
/
alter user ejb temporary tablespace temp
/
3. Start a SQL Plus session by typing the following command:

$ sqlplus system/manager@was
Syntax:
> sqlplus system/manager@<was_SID>
4. Create the WebSphere Application Server tablespace and users by typing:
SQL> @was
Create Payment Manager Oracle ID and tablespace

To create a Payment Manager Oracle user ID and tablespace, complete the
following steps:
1. Start a Solaris Console window on the database server system, and log in as
user oracle (Oracle DBA).
2. Create a wpm.sql file as shown in Example 3-7. We include a sample
wpm.sql file as part of the redbook additional material. See Appendix A,
“Additional material” on page 317 for details on obtaining sample code.
Example 3-7 wpm.sql to create the WPM tablespace and user
drop tablespace wpm
/
drop user wpmadmin
/
create tablespace wpm
datafile '%ORACLE_HOME\DATABASE\wpm.ora'
size 4M
reuse
maxsize unlimited
/
create user wpmadmin
identified by wpmadmin

default tablespace wpm
quota unlimited on wpm
/
grant dba to wpmadmin
/
alter user wpmadmin temporary tablespace temp
/
3. Start a SQL Plus session by typing the following command:

$ sqlplus system/manager@wpm
Syntax:
> sqlplus system/manager@<wpm_SID>
4. Create the WebSphere Application Server tablespace and user by typing:
SQL> @wpm
Verify user creation

To verify that users have been corrected, log on to SQL Plus with each of the
user IDs as follows:
1. Log in as user oracle.
# su - oracle
2. Start SQL Plus using ejsadmin:
$ sqlplus ejsadmin/ejsadmin@was
SQL> quit
3. Start SQL Plus using ejb:
$ sqlplus ejb/ejb@was
SQL> quit
4. Start SQL Plus using wcsadmin:
$ sqlplus wpmadmin/wpmadmin@wpm
SQL> quit
Configure Net8 on Oracle8i Server

To configure Net8 on the Oracle8i Enterprise Edition database server, complete
the following steps:
1. Start a Solaris Console window.
2. Disable access control for the X-Windows display by user root by typing the
following:
# xhost +
3. Log in as user oracle:
# su - oracle
4. Start Net8 Assistant:
# netasst
5. Verify that Service Names exist for the following:
– was
• Service Name: was
• Protocol: TCP/IP
• Host Name: sun4
• Port Number: 1521
– wcs
• Service Name: wpm
• Protocol: TCP/IP
• Host Name: sun4
• Port Number: 1521
See Figure 3-11 for an example.

Figure 3-11 Check the values of the Service Names in the Net8 configuration
6. Check the status of the listener.

$ lsnrctl status <listener_name>
For example:
$ lsnrctl status LISTENER
Note: All listeners’ statuses will be displayed if the listener name is omitted.
7. If the listener is not started, start as follows:

$ lsnrctl start <listener_name>
For example:
$ lsnrctl start LISTENER
Note: All listeners will be started if the listener name is omitted.
3.5 Install WebSphere Application Server

We have organized the WebSphere Application Server V3.5, Advanced Edition
installation into the following phases:
WebSphere Application Server V3.5 install prerequisites
WebSphere Application Server V3.5 install
Configure port 80 for iPlanet Web Server
WebSphere Application Server configuration for Oracle8i
Configuring the WebSphere Application Server
WebSphere Application Server V3.5 install verification
WebSphere Application Server V3.5 Fix Pack 2 installation
WebSphere Application Server V3.5 eFixes installation required by
WebSphere Commerce Suite V5.1
3.5.1 WebSphere Application Server V3.5 install prerequisites

Before installing the WebSphere Application Server, verify the following
prerequisites:
Ensure your iPlanet Web Server is stopped:
– Stop HTTP Web server:
# cd /usr/netscape/server4/https-sun4.itso.ral.ibm.com
# ./stop
– Stop HTTPS Web server:
# cd /usr/netscape/server4/https-SSL
# ./stop
Ensure the Oracle8i server and listener are started.
3.5.2 WebSphere Application Server V3.5 install

The IBM WebSphere Application Server V3.5.1, Advanced Edition GUI
installation, executed via ./install, will not work for iPlanet Web Server V4.1SP7
due to a prerequisite check failure. For this reason, we edited the
prereq.properties file, which is in the same directory as the install program. We
changed the line:

prereq_checker=1
to:
prereq_checker=0
in order to turn off prerequisite checking.
To install WebSphere Application Server, complete the following steps:

2. We downloaded and used the WebSphere Application Server Version 3.5.1.
3. Edit the prereq.properties file to remove the prerequisite check.
4. Start the WebSphere Application Server V3.5 install program by typing the
following:
# /<install_directory>/install.sh
5. Click Next on the welcome window.
6. When the Install Options window appears, select Custom Installation.
Otherwise, the Quick install option will use InstantDB and we want to use our
Oracle for the WebSphere repository database. Click Next.
7. When the Choose Application Server Components window appears, select
the following as shown in Figure 3-12:
– Server Runtime
– Administrative Console
– Samples (optional)
– Configure Default Server and Application
– WebServer Plugins
Click Next.
Figure 3-12 We will install everything except the IBM HTTP Server, because we have already installed an
HTTP server
8. When the second Choose Application Server Components window appears,

select to install the plug-in for:
– Netscape V4.0 plug-in
– Netscape V4.0 Security plug-in
Click Next. See Figure 3-13.

Figure 3-13 We will install and configure the WebSphere Application Server plug-in for both iPlanet servers,
with and without SSL
9. When the Location of Configuration files window appears, enter the path for
each Web server. The paths are normally in the form:
/usr/netscape/server4/<name_of_HTTP_server>/config
Figure 3-14 shows the paths we used for our example installation on Solaris.
Click Next.
Figure 3-14 The directory name where the configuration files are stored varies with the name of your
iPlanet server
10.When the Database Options window appears enter the following information:
– Database Type: Oracle
– Database Name: was
Note: The WebSphere Application Server repository database name is user

defined and can be different from the name was. Within the context of Oracle,
a WebSphere Application Server database is the equivalent of a tablespace
within the Oracle database.
– DB Home: /opt/oracle8/u01/app/oracle/product/8.1.7
– DB URL: jdbc:oracle:thin@<hostname>:<server_port>:<db_SID>
For example: jdbc:oracle:thin@sun2:1521:was
– Database User ID: ejsadmin
– Database Password: <your_password>
– Confirm Password: <your_password>

Figure 3-15 shows an example.
Click Next.
Figure 3-15 Fill all the details of your database connection
11.When the Security Information window appears enter root as the user ID and
fill in the password fields. This password won’t be kept. It’s just for the
installation process. Choose Use dummy key ring file as shown in
Figure 3-16. Click Next.
Figure 3-16 The WebSphere Application Server installation program needs the root password
12.When the Select Destination Directory window appears, accept the default
/opt/WebSphere/AppServer and click Next.
13.When the Install Options Selected window appears, revise the options. Use
the Back button if you need to change something. If everything is OK, click
Next.
14.Click Yes to begin the installation of files.
Confirm changes to iPlanet configuration files

The next time you open the administration console of iPlanet, it will complain
about manual edits not bing loaded. These are the changes the WebSphere
Application Server installation program has done. They have to be done
separately to both HTTP servers, the SSL and the non-SSL.
To apply the changes follow this steps:

1. Click Apply at the upper right of the iPlanet administration console, as shown
in Figure 3-17.

Figure 3-17 Apply iPlanet configuration updates for WebSphere Application Server
2. Click Load Configuration Files as shown in Figure 3-18.
Figure 3-18 Click Load Configuration Files
3. After a success message confirms that all the changes found in the
configuration files are consistent, a new window appears where you can apply
the changes found. Click Apply Changes as shown in Figure 3-19.

Figure 3-19 Click the Apply Changes button
4. If you are applying the changes, you must provide the password to the
certificate database before proceeding.
The HTTP servers have to be restarted for these changes to take effect.
WebSphere Application Server configuration for Oracle8i

Prior to starting the WebSphere Application Server, we need to complete the
following configuration steps:
2. Change to the WebSphere Application Server directory
/opt/WebSphere/AppServer/bin.
3. Make a backup of startupServer.sh before modifying it.
a. Search for the following:
DB_INSTANCE_HOME=fully_qualified_path_to_your_Oracle_home_directory
export DB_INSTANCE_HOME
If the path ends in a slash (..../.), remove it from the path.
b. Search for the following:
if ["${DB_TYPE}"!="DB2"]
then
{
LD_LIBRARY_PATH=$WAS_HOME/lib/odbc/lib:$WAS_HOME/bin:
$WAS_HOME/lib:$JAVA_HOME/lib:$LD_LIBRARY_PATH
export LD_LIBRARY_PATH
${JAVA_EXE?}\
-classpath $CLASSPATH \
-DDER_DRIVER_PATH=$DER_DRIVER_PATH \
com.ibm.ejs.sm.util.process.Nanny admin.config
}
c. Change this section as shown below. New parts are indicated in bold text.
if ["${DB_TYPE}"!="DB2"]
then
{
ORACLE_HOME=Oracle_home_directory
export ORACLE_HOME
LD_LIBRARY_PATH=$WAS_HOME/lib/odbc/lib:$WAS_HOME/bin:
$WAS_HOME/lib:$JAVA_HOME/lib:$LD_LIBRARY_PATH
LD_LIBRARY_PATH=$ORACLE_HOME/lib:$LD_LIBRARY_PATH
export LD_LIBRARY_PATH
LIBPATH=$LD_LIBRARY_PATH
export LIBPATH
NLS_LANG=AMERICAN_AMERICA.UTF8
export NLS_LANG
${JAVA_EXE?}\
-classpath $CLASSPATH \
-DDER_DRIVER_PATH=$DER_DRIVER_PATH \
com.ibm.ejs.sm.util.process.Nanny admin.config
}
Where Oracle_home_directory is the fully qualified path to your Oracle
home directory. For example,
/opt/oracle8/u01/app/oracle/product/8.1.7 .
d. Save your changes.

This section includes some general configuration steps for the WebSphere
Application Server.
Start the WebSphere Application Server

To start the WebSphere Application Server, complete the following steps:
2. Start WebSphere Application Server.
# cd /opt/WebSphere/AppServer/bin
# ./startupServer.sh
3. View the tracefile log as follows:
# cd /opt/WebSphere/AppServer/logs
# tail -f tracefile
Look for the following message if successfully started:
AdminServer A Initializing WebSphere Administration server
AdminServer A WebSphere Administration server open for e-business
Install WebSphere Payment Manager

1. Before installing WebSphere Payment Manager, review the hardware and
software prerequisites detailed in the IBM WebSphere Payment Manager for
Multiplatforms Install Guide Version 2.2. If you have used the install
instructions for the prerequisite products described in this chapter, then you
will already meet the Payment Manager requirements.
Note: Ensure the resolution on your display is set to 800 by 600 pixels or
higher to best view the Payment Manager installation program.
The database, the HTTP server and WebSphere Application Server must be
running during the installation.
2. Insert the Payment Manager for Solaris CD-ROM, and mount the CD-ROM
file system, if necessary. Run the Install command.
4. Accept the license agreement and click Next.
5. Accept the default destination directory or enter another directory. Do not
include blanks or spaces in the destination directory name. Figure 3-20
shows an example using the default Payment Manager install directory. Click
Next.
Figure 3-20 Payment Manager install directory
6. If your Web server is already installed, you will be asked for the location of the
publish directory. If the location displayed is correct, click Next. If not, enter
the correct location and click Next. The publish directory is the directory out of
which your Web server serves documents. Figure 3-21 shows an example
using the default publish directory the iPlanet Web Server.

Figure 3-21 iPlanet publish directory for Payment Manager install
7. If WebSphere Application Server is already installed and the installation

program cannot determine which JDK WebSphere Application Server is
using, you will be asked to enter the location of the JDK directory.
8. Select which database you will use with Payment Manager: UDB or Oracle.
We selected Oracle 8.0/8i as shown in Figure 3-22.
Figure 3-22 Payment Manager install using Oracle database
9. The install then attempts to find JDBC driver information for your database.
As we have not yet specified the correct location of the JDBC classes, the
JDBC Driver Information window will advise that the JDBC driver class could
not be loaded. This is shown in Figure 3-23.

Figure 3-23 Load failure for JDBC driver class
10., Enter the name of the file where the JDBC classes can be found and click
Next. The location of the JDBC classes for Oracle 8.1.7 is
$ORACLE_HOME/jdbc/lib/classes12.zip where the default value of
$ORACLE_HOME is /opt/oracle8/u01/app/oracle/product/8.1.7
Figure 3-24 shows an example of this. Note that no entry is required for the
JDBC shared load library path.
Figure 3-24 Location of ORacle JDBC driver classes
11.In the Payment Manager Database Access Information window, enter your
values for the database owner user ID, administrator’s user ID, administrator’s
password, Payment Manager database name, and the DB2 instance name.
See Figure 3-25 for an example. Click Next.

Figure 3-25 Payment Manager database information
application on your system uses this TCP port. Click Next.
13.In the Payment Manager WebSphere Configuration Information window, enter
your WebSphere Administrative Node Name and click Next.
15.Note: The progress bar will move during installation, although at times it may
After the installation is complete you can verify that WebSphere Payment
Manager has been correctly installed by taking the following steps:
1. Start the Payment Engine:
a. Change to the Payment Manager install directory
cd /opt/PaymentManager
b. Enter ./IBMPayServer
2. Using the WebSphere Administrative Console start the Payment Manager
application server. Note: Before starting the Payment Manager application
server use the WebSphere Administrative Console to check that the virtual
hosts entries for the default host still have aliases that include the SSL port
443, because these aliases may be removed by the Payment Manager install.
3. Launch the Payment Manager user interface in a Web browser using the
URL:
http://<hostname>/webapp/PaymentManager/PaymentServletUI/Start
4. Check that you can log on to Payment Manager using the default
administration user ID of admin.

4
Chapter 4. Integration with SET

The Secure Electronic Transaction ( SET) protocol was developed by
MasterCard and Visa with leading technology providers, including GTE, IBM,
Microsoft, Netscape, SAIC, Terisa Systems, and VeriSign.
The SET protocol was designed to address the problems of authentication and
trust across an e-commerce transaction on the Internet. When you purchase
goods from the Internet you do not really know the credentials of the merchant
you are buying from. You supply the merchant your credit card details, but you
don’t know if the merchant might mis-use the information you provide.
In turn the merchant does not really know who you are. The merchant only
knows that you are using a credit card for an e-commerce transaction. The
merchant trusts the details provided by the purchaser and really has no way of
identifying the consumer with any confidence.
The card issuer also has no real method of confirming the credentials of either
the consumer or the merchant.
The SET protocol has been designed to provide a secure solution to the
challenges provided by Internet-based transactions. The following sections
discuss how the SET protocol works and outlines the IBM products that support
the protocol. For a full definition of SET and the low-level protocol specifications
please refer to:
http://www.setco.org

4.1 Secure Electronic Transaction architecture
Across an e-commerce transaction the SET protocol:
Authenticates all parties involved in the transaction using digital certificates
Provides confidentiality at all stages of the transaction
Ensures integrity of the data
The protocol also prescribes how payment data should be handled so that, for
example, merchants never see a consumer’s credit card details.
4.1.1 The key entities in an e-commerce transaction

In any electronic payment transaction buyers use their credit cards to buy goods
from merchants, who in turn supply goods to the buyers in return for a payment
promise.
The usual method of transferring the value across the Internet in today’s
e-commerce transactions is via credit or debit card. The merchant usually passes
the buyer’s card details on to an acquirer organization. The acquirer provides the
merchant with the capability of accepting and authorizing multiple credit card
brands in return for a percentage fee on all transactions dealt with by the
acquirer. This avoids the merchant having to deal directly with the credit card
issuers. The processing of the financial transaction is then the acquirer’s
responsibility. The financial transaction is then submitted to the card issuer for
authorization, who uses validation rules to authorize or deny the payment.
Figure 4-1 outlines the key players in an e-commerce payment transaction flow
and also shows the use of certificates for authentication.
Payment Payment
Promise Authorization Transaction
CREDIT CARD
Fee
1234 5678 9012
VALI D FROM G OOD THRU
XX/XX/XX
XX/XX/XX XX/XX/XX
XX/XX/XX
PAUL FISCHER
PAUL FISCHER
Consumer Merchant Acquirer

VISA
CERTIFICATE CERTIFICATE CERTIFICATE
MasterCard
this day of , 199 , thi s day of , 199 , this day of , 199 ,
Type name here Type name here Type name here
by by by
Diners Club
etc. Card Issuer
Payment
Network
Certificate
Authority
Credit Card Bill
Figure 4-1 The players in an e-commerce SET payment transaction
Ultimately it is the financial institution (the card issuer) that is responsible for
collecting the card holder’s debt. However certain credit card issuers are
beginning to shift the liability from card issuer to acquirer for non-SET secure
transactions.
So parties involved in an SET transaction are:

1. Credit card holders (who buy goods and services across the Internet)
2. Merchants (who sell goods and services)
3. Acquirers (who act as intermediaries between the merchants and card
issuers
4. Card issuers (financial institutions that issue credit cards to consumers)
With SET, all the above require a secure method of authentication. SET
mandates that all parties (with the exception of the card issuer) use digital
certificates in order to securely identify each party involved in a financial
transaction.
IBM provides a solution for SET certificate issuing authorities (known as CAs) in
the form of IBM Payment Registry software. The high-level function of this
software is to handle certification management, routing, decrypting and
encrypting as well as other validation activities. The certificate issuing authority is
a critical component of the SET architecture.
Chapter 4. Integration with SET 111

The Payment Registry is capable of handling all levels in the SET certificate
hierarchy such as:
Root CA (private label)
Brand CA
Cardholder CA
Merchant CA
Acquirer CA
The mechanism it uses for certificate request is either manual or through a

custom user exit, making the approval mechanism flexible. The AIX V4 Payment
Registry software is also fully certified by Visa and MasterCard.
For more information on the IBM Payment Registry see:
http://ibm.com/software/webservers/commerce/paymentregistry/features.ht
ml
4.1.2 Consumer certificates

Consumers request SET certificates from the SET issuing authority. On
successful validation of the consumer, the issuing authority responds with a valid
and unique electronic certificate containing encryption and signature certificates.
The challenge of where consumers keep their certificates is a subject of much

debate. Today IBM provides a solution to this problem using a client-based
consumer wallet. The IBM Consumer Wallet is a software product that is installed
locally on a buyer’s computer. The electronic (software) wallet emulates the
wallet shoppers use to carry credit cards. Details of credit card numbers,
expiration dates and so on are kept in the electronic wallet along with the
consumer’s own certificate, which is used to uniquely identify the consumer. The
wallet is launched manually by the consumer or automatically via the merchant
software when the consumer is ready to pay for the goods.
At the time of writing this book IBM is to withdraw the current client-based IBM
Consumer Wallet software from marketing. A possible replacement product is a
server-based wallet. This allows for portability of the wallet so that consumers
are able to activate the credit card details when not using their regular
workstation. For more information on this product see:
http://ibm.com/webservers/commerce/payment/
4.1.3 Merchant certificates
The merchant uses a payment server to store certificates. The payment server
accepts all e-commerce financial transactions directly from the consumer’s
electronic wallet, stores and passes the financial information for the transaction
directly on to the financial institutions for authorization. All transactions going
through the payment server are logged for audit purposes. IBM’s solution for the
payment server in this scenario is WebSphere Payment Manager using the
Cassette for SET.
4.1.4 Acquirer certificates

Acquirers use the concept of a payment gateway in order to fulfill their role with
the SET architecture. When the merchant requires authorization for a credit card
payment, acquirer services are used to avoid the technical challenges brought
about by the merchant dealing directly with various card issuers (for example
each card issuer deals with various different protocols internally). The merchant
requests authorization through the payment gateway and receives responses
through the same route.
IBM’s solution for acquirers is the IBM Payment Gateway product. For more
information on this product see:
http://ibm.com/software/webservers/commerce/payment/paymentgateway/featur
es.html
Figure 4-2 outlines the various IBM products that support the SET protocol.
Consumer Merchant Software Acquirer

Software Software
Merchant Store
IBM
Payment
Commerce Suite Cassettes Gateway
Credit SET
Card OTHERS
Details Financial
IBM Payment
Consumer IBM WebSphere
Network
Wallet Payment Manager
Figure 4-2 IBM products supporting the SET protocol

4.2 SET extensions
The SET protocol allows for certain extensions to the full SET definition. The
following sections outline the additional support provided by the IBM Cassette for
SET.
4.2.1 MIA
Merchant Initiated Authorization (or MIA) is an SET extension that permits
merchants to processes order payments from card holders where the payment
request from the consumer has not been captured using the SET protocol, that is
when no SET certificate was used during the exchange of details between the
consumer and merchant. It does requires that a secure transport protocol (SSL)
must have been used by both parties.
The merchant must, however, process the transaction with the acquirer using the
SET protocol. The acquirer must also have a policy of accepting these requests
from merchants by indicating that purchasers without certificates are supported.
MIA is sometimes referred to as half SET (since only half the parties involved in a
regular SET transaction use the full SET certificate exchange). The MIA
message flow between the parties is also sometimes referred to as a 2KP (two
key pairs) message flow, the key pairs being the certificates exchanged during
the payment transaction. The message flow for full SET is also sometimes
referred to 3KP (since consumer, merchant and acquirer all exchange certificates
to process the payment).
Figure 4-3 outlines the difference between full SET and MIA.
Consumer Merchant Acquirer
CERTIFICATE
SET CERTIFICATE
SET CERTIFICATE
t his day of , 199 , this day of , 199 , this day of , 199 ,

by Type name here by Type name here by Type name here
SET
CERTIFICATE SSL CERTIFICATE SET CERTIFICATE
MIA
CERTIFICATE
SSL CERTIFICATE
SSL CERTIFICATE

Full
SSL
Figure 4-3 MIA and SET
4.2.2 Merchant originated payment

Prior to the formal specification of the MIA SET extension, Payment Manager
implemented an IBM-defined extension known as Merchant Originated Payment
(or MOP). For acquirers who have implemented the MOP architecture and want
to support the standard SET-defined MIA architecture, IBM Payment Manager
with the SET cassette currently supports both MIA and MOP extensions without
the merchant or acquirer having to do anything. Both extensions are non-critical,
meaning that they are optional for the acquirer. Acquirers not supporting either
extension just ignore the data provided by the two extensions.
For more detailed technical information on the MIA extensions and others please
refer to the following:
WebSphere Payment Manager Guide - Cassette for SET supplement, found
at:
http://www.ibm.com/webservers/commerce/payments/lib/

Documentation pages on the SET Secure Electronic Transaction LLC Web
site at:
http://www.setco.org/
4.2.3 Creating an order when using the SET cassette

The SET cassette provided by IBM supports orders created with and without
consumer wallet participation. This allows the merchant to support either full SET
or MIA. With an SET payment the credit card details are requested through the
consumer wallet. If no consumer wallet is available the front end e-commerce
order creation application must request the consumer’s credit card details
directly. More specifically the following must be passed to the SET cassette:
– Credit card brand
– Account number
– Expiration date
For more information on how to integrate non-SET consumer applications with

the SET cassette, please refer to the IBM WebSphere Payment Manager
Cassette for SET supplement.
4.2.4 Verification of card holder address

The SET protocol defines a mechanism for specifying additional order-specific
payment-related information that can be used in the authorization process
outlined by the SET acquirer. The structures SaleDetail and AVSData are
additional optional fields that can be collected at order creation time. SaleDetail
is used to collect specific order information such as hotel charges, auto rental or
transport charges. AVSData is a field used to specify the card holder’s billing
address. Some acquirers prefer to use this field as an additional level of payment
authentication by comparing the details passed in the payment request with the
details on record with the acquirer.
4.2.5 Japanese payment option

The use of SET in Japan is slightly different from that defined in the standard
SET specification. The SET cassette provided by IBM supports the Japanese
Payment Option (JPO) SET extension. This JPO extension is provided with the
Japanese version of the SET cassette and supports the variety of payment
options available in Japan. For more information on this country-specific
extension, please refer to documentation at the SET Web site:
http://www.setco.org/extensions.html
4.2.6 Other SET extensions
A comprehensive list of SET extensions is available at:
http://www.setco.org/extensions.html
4.3 The Visa 3D SET model

Although not specifically supported by the SET cassette it is necessary to talk
about the 3-Domain SET model being proposed by Visa. Although similar to the
SET-defined protocol, the 3D SET model is different in that it defines the use of
servers to hold authentication certificates. The following sections outline what is
being proposed by Visa.
4.3.1 The three domains (3D)

Visa mandates that all its acquirer members are capable of authenticating all
parties in an e-commerce transaction, but the 3D SET model allows the
merchants and acquirers the flexibility to determine how this authentication is
performed. The 3D SET model splits authentication challenge into three distinct
domains:
1. An acquirer domain
2. An issuer domain
3. An interchange domain
With the 3D model, it is the responsibility of each owner of the domain to verify
the other party. For example, the acquirer needs to satisfy himself that the
merchant is genuine. Similarly the issuer is required to verify the card holder. The
interchange domain is a safe area where authentication and payment transaction
details can be exchanged once authentication has been passed.
4.4 Installing the SET cassette

The IBM WebSphere Payment Manager Cassette for Set Supplement gives
detailed instructions on how to install the cassette. The remainder of this chapter
deals with the configuration and verification that the installation of the Cassette
for SET has been successful.

4.4.1 Verifying the installation
IBM provided a demonstration site that allows testing of Payment Manager with
the SET cassette. The following sections describe how to test an installation of
the SET cassette using the demo IBM Payment Gateway and IBM Payment
Registry. Information on how to get to the SET demonstration site is available at:
http://ibm.com/software/webservers/commerce/paymentmanager/support/paydemo.html
Figure 4-4 shows the welcome page of the SET demo site.
Figure 4-4 The IBM SET demo site
4.4.2 Configuring Payment Manager to use the SET cassette

The following sections detail how to configure the installed SET cassette so that
a given merchant can choose to use it. The windows shown in these sections
have been taken from a WebSphere Commerce Suite V5.1 system with
WebSphere Payment Manager installed. The Payment Manager installation has
the V2.2.1 PTF installed (for both the framework and the SET cassette).
Before registering with the IBM demo site, you can use an ID generator to
provide information that is required when completing SET registration. If you are
doing this with a genuine acquirer, the organization should have given you the
necessary details in order to obtain the SET certificates. Substitute these real
values for the values in the following sections.
The details that were registered for the purposes of this book are shown in
Figure 4-5.
Figure 4-5 IBM SET demo registration results
You can use either using the Payment Manager administrator interface or the
Commerce Suite administrator interface to do the SET cassette configuration.
Note: The Payment Manager administrator provides a standard Payment

Manager interface, but in order to illustrate the close integration between
Commerce Suite and Payment Manager the windows shown here use the
WebSphere Commerce Suite administrator interface.

To configure the SET cassette:
1. Sign on to the Commerce Suite Administrator console.
2. Choose the Payment Manager link on the options bar at the top of the window
and select Merchant Settings. This is shown in Figure 4-6.
Figure 4-6 Select Merchant Settings from Commerce Suite admin console
3. A list of merchants is displayed. In our example there are five merchants

defined all configured to use the Offline cassette. Two of the merchants are
authorized to use the SET cassette. Of the two SET merchants, the
InfashionMerchant is authorized to use the SET cassette, However, the
cassette has been disabled for this user. We are interested in configuring the
SET cassette for the merchant with the name wcsadmin.
4. Click the SET Cassette icon for this merchant as shown in Figure 4-7.
Figure 4-7 Select the SET cassette for merchant wcsadmin
5. Select Accounts, because we want to be able to add an acquirer account to

the SET cassette
6. Click Add an Account. The window shown in Figure 4-8 will appear. For the
purposes of clarity the bottom portion of the window is shown and the values
have been added that were used to create the account using the IBM demo
SET environment. You will need to replace these values with those given to
you by your financial institution.

Figure 4-8 Create the SET account in Payment Manager
Note: The SET Acquirer Profile attribute in the account object defines how
the acquirer uses the SET protocol. In our example we define a value of 3
to denote a Customized profile (since it is the demonstration environment).
Since the SET profile value is defined with the account object this means
Payment Manager can easily support multiple acquirer profiles (by defining
new account objects). For more information on the Payment Manager SET
cassette support of SET acquirer profiles please refer to the URL:
http://ibm.com/software/webservers/commerce/paymentmanager/support/acqpro
file.html
7. If the account creation is successful, a window similar to Figure 4-9 will be

displayed.
Figure 4-9 SET account successfully created
Once an account is defined for the merchant we need to define a brand for the
account. A brand is a credit card type such as Visa, MasterCard and Diners Club.
In our example the brand ROBO will be added as a brand to the SET account.
To create a Brand within the account:

1. Choose the link displayed behind the wcsadmin Account
2. In the Settings configuration window, choose Brands.
3. If you have any existing brands they will be displayed in the next window.
Click Add a Brand.
4. For our demo scenario, we entered the values shown in Figure 4-10.

Figure 4-10 Create a brand
The full URL for the Certificate Authority used in this example is
http://setca-demo.ebiz.ca.ibm.com:5065/ROBOMCA.
5. Click Create Brand. The window shown in Figure 4-11 appears.
Figure 4-11 Fill out the acquirer-specific information
6. Enter the acquirer details and click Continue Request.... This initiates
Payment Manager SET message pairs Me-AqCInitReq and Me-AqCInitRes.
These message pairs are SET protocol-defined messages and work in the
following way:
– The BIN and Merchant ID are sent by Payment Manager to the certificate
issuing authority in the MeAqCInitReq message.
– The Certificate Authority sends back a MeAqInitRes containing the
registration and policy statement, which the merchant then fills in and
accepts the policy statement.
7. Payment Manager then returns the completed application form in a CertReq
message to the Certificate Authority. If you are renewing certificates, these
are also included in the CertReq message.
8. The Certificate Authority then generates the certificates using the information
supplied. These are then sent back to Payment Manager. The Payment
Manager certificates by default are kept in a file called key.db in the Payment
Manager data directory.

To maintain your merchant certificates you can use the certificate utility
supplied with Payment Manager called CertUtil. The utility allows you to
maintain, delete, and analyze the details of the certificates in your
environment. It is very useful if you believe you have a certificate problem.
During the writing of this book CertUtil was used to delete all the certificates
used by our Payment Manager test environment. We experienced a problem
with the SET cassette, which was reported in the eTillError log as:
CEPSET0726: IBM WebSphere Payment Manager SET transaction failed composing
a MOPREQ message with return code 18015 for Merchant 10001, and order 1.
The IBM WebSphere Payment Manager Cassette for SET Supplement
detailed that there was an internal SET error and support were to be
contacted to resolve the problem.
A SET dump called eTillSETMsgDump.1 was created in the Payment
Manager log directory.
Using fmttrace the dump was analyzed. Example 4-1 shows the last 15 lines
of the formatted dump:
Example 4-1 Dump message for CEPSET0726 return code 18015
732 <CMSWrapper::retrieveGatewayEncryptionKey()
732 KeyDetails Choice for which no cert is found: 2
732 >KeyDetails::trace()
732 KeyDetails Tracing:
AsnBrandID: "ROBO"
BIN :701896
PGWY Serial Number :3322115544
732 <KeyDetails::trace()
732 SETUnexpectedConditionException thrown
732 ModuleName : ./src/cmswrapper/cmswrapper.cpp
732 LineNumber : 183
732 PrimaryRC : 7
732 SecondaryRC: 18015
732 ErrorText : Certificate searched for is not found
To fix this problem we used CertUtil to remove all certificates in the Payment
Manager database and deleted the brand created for the SET cassette.
Recreating the brand and requesting the certificates again removed the
problem.
Important: The removal of all certificates in the database was only
possible since this was a test environment and we had no other working
certificates. If this happens in your environment and you have other
working certificates, you must contact support to resolve the problem.
9. Successful definition of the brand and the acquisition of the SET certificates
results in an information window shown in Figure 4-12. Note: IP
communication is required for this process to work successfully.
Figure 4-12 Successful brand creation
10.If you now go back to the brand link, you can verify that the brand was created
successfully and a table will be displayed showing the certificate validity as
well as the expiration date. This is shown in Figure 4-13.

Figure 4-13 Verify successful creation of the brand
We now have an SET certificate for the merchant. As a consumer purchasing

goods from the merchant’s SET-enabled Internet shop, we require an SET
certificate and electronic wallet software to keep the certificate and credit card
details.
4.4.3 Consumer certificates

Consumer certificates are required by the SET architecture for use with an SET
transaction. Electronic wallets are used to hold consumer certificates and credit
card information. If you don’t use a consumer wallet when purchasing from a
merchant supporting SET transactions, then you will be attempting to use the
Merchant Initiated Authorization (MIA). In order to demonstrate what happens
from a consumer perspective when purchasing using the SET protocol, it is
necessary to obtain a consumer certificate from a trusted SET Certificate
Authority (in this case the IBM SET demo site). The following sections detail how
to do this using IBM’s Consumer Wallet product.
Obtaining a consumer certificate
Make sure that:
You have Internet connectivity.
If you are working on a secure network, valid proxy settings have been
defined in your browser.
The domain setca-demo.ebiz.ca.ibm.com is pointing at the correct IP address
- (the SET demo site contains the correct IP addresses that should be used).
You have installed wallet software (for example the IBM Consumer Wallet
V2.1 was used for the purposes of obtaining the consumer certificates in this
book).
To obtain the consumer certificate:

1. Enter http://setca-demo.ebiz.ca.ibm.com:31855/ROBOCCA into a Web
browser. This will trigger the IBM Consumer Wallet to start on your machine.
2. Log on to the consumer wallet application when prompted. You can either
register yourself to the application during this phase or use a user ID that has
already been set up.
3. Once logged in to the application you are prompted to select the credit card
you want to enable for SET transactions. If you don’t already have a credit
card set up for the certificate brand you are requesting, you will see a warning
message and be prompted to add a card that is supported by the demo
acquirer system. If this happens, add the credit card details using the GUI
interface. When you have finished entering the details the wallet application
has a conversation with the acquirer to obtain the credit card logo. When
successfully downloaded, the logo is shown in the window. It is then possible
to proceed with the certificate request.
The credit card details that were passed back as part of the IBM SET demo
site registration were used in our example. These details were already
registered in the wallet application for a credit card brand called ROBO. Note
the URL to request the certificate must change if you want to request a
certificate for a different brand. The IBM SET demo system gives details of
the credit card brands that are supported as part of the demo acquirer
system. These are detailed in the section titled IBM wallet setup.
4. When the window shown in Figure 4-14 appears, click Request Certificate.

Figure 4-14 Consumer wallet request certificate for credit card
5. The wallet application then shows a window saying that it is initiating the
certificate request.
Note: The first time you request a certificate for a credit card using the wallet
application you will be prompted for the URL of the Certificate Authority.
Figure 4-15 shows the URL that we used with the IBM SET demonstration
site.
Figure 4-15 SET CA URL prompt
A root hash is also required. This information was given in the IBM SET demo
registration response. For example the root hash value shown in Figure 4-16
was used in our setup.
Figure 4-16 Prompt for the root hash
6. The wallet application now has sufficient information to converse directly with
the IBM demo SET registry authority software. If the initiation of the
conversation is successful, you will see a policy agreement prompt. In the
IBM Demo system this has no text. In a real-life situation this window will
contain the terms and conditions of the certificate issuing authority. Click
Accept to continue.
7. Now the certificate registration windows will appear. These consists of three
pages of consumer registration information required by the SET issuing
authority. Enter in the details requested and click Finish to continue the
certificate request.
8. The wallet then passes this information back to the SET certificate issuing
authority. If the request is successful a message window as shown in
Figure 4-17 will be displayed.
Figure 4-17 Consumer SET certificate issued successfully
9. Click Close. This will show the wallet application and the credit card details.
Note: The certificate status should be shown as Valid and the credit card logo
should appear with the credit card details. An example of this is shown in
Figure 4-18.

Figure 4-18 Wallet application showing valid credit card
10.In the Web browser where you entered the original credit card (SET brand)
certificate request you will see a window detailing that the certificate request
was successful.
Remember that in order to purchase goods using the SET architecture, both
merchant and consumer require certificates from the same SET issuing authority.
We used the Payment Manager merchant settings to request and obtain the
merchant certificate. With the SET certificate request completing successfully,
we can now use the Sample Checkout tool to verify that these certificates have
been installed correctly and can be used in an SET Internet online purchase.
We now need to configure the application to use the SET cassette. This is often
an Internet online shop such as a shop created using Commerce Suite. For
simple verification, the Payment Manager Cassette for SET also supplies a tool
called Sample Checkout to simulate a merchant’s online Internet shop and
enable the creation of orders that require payment processing by the cassette.
Using the Sample Checkout helps verify the configuration works correctly before
getting involved with the complexities of a real e-commerce application. The
following sections discuss how to ensure that the cassette is running correctly
using the Sample Checkout tool.
4.4.4 Sample Checkout
The sample checkout is supplied with the SET cassette. Configuration of the
SampleCheckout.xml is required before you can successfully use the tool.
To do this:
1. Change to the directory
<payment_Manager_Install_directory>/Samples/SampleCheckout/.
Note: If you kept to the supplied defaults when installing Payment Manager,
the directory is <drive>:\Program
Files\IBM\PaymentManager\samples\SampleCheckout.
2. Edit the file SampleCheckout.xml
a. Add the MIA and SET (with wallet) options to the XML file.
Add two additional payment option ids to the PaymentOptionList as
follows:
<PaymentOptionList>
<PaymentOption id="SET" profile="SampleCheckoutSET">SET </PaymentOption>
<PaymentOption id="SETWallet"
profile="SampleCheckoutSETWallet">SETWallet</PaymentOption>
Note: The text for each option ID should be on a single line.
b. Configure merchant information
SampleCheckout acts as a application that creates orders for specific
Payment Manager merchants. Since it mimics the merchant, Payment
Manager details on the merchant are required. It uses these details to
pass on to Payment Manager when creating the order. The supplied XML
file assumes a user ID of admin with a password of admin.
This is the default Payment Manager setup when using the supplied
Payment Manager realm. If you have changed Payment Manager to use
another realm, make sure that the realm has this specific user ID and
password or alternatively change the user ID and password values in the
XML file to reflect users that will be able to log on to Payment Manager as
an administrators. In our test environment the user ID and password
values were changed to wcsadmin.
merchantNumber="123456789"
Change this value to the merchant number associated with the merchant
specified in the userid= field. This number can be found in the Payment
Manager merchant settings option.

cashierProfileDirectory= and cashierTraceDirectory= are both specified
with the values for the default directories. If you changed these values
when you installed Payment Manager, edit these values to the correct
settings.
The resulting XML file should look similar to Example 4-2.
Note: The comments at the beginning of the file have been removed for
clarity.
Example 4-2 Configured SampleCheckout.xml file
<SampleCheckout merchantNumber="10001"
pmHostname="localhost"
pmPort="80"
userid="wcsadmin"
password="wcsadmin"
useSSL="0"
cashierProfileDirectory="C:/Program
Files/IBM/PaymentManager/profiles"
cashierTraceDirectory="C:/Program
Files/IBM/PaymentManager/log">

<PaymentOptionList>
<PaymentOption id="SET" profile="SampleCheckoutSET">{SET}
</PaymentOption>
<PaymentOption id="SETWallet" profile="SampleCheckoutSETWallet">{SETWallet}
</PaymentOption>
<PaymentOption id="Offline" profile="SampleCheckoutOfflineCard"
default="1">{OFFLINECARD}
</PaymentOption>
<PaymentOption id="COD"
profile="SampleCheckoutCustomOfflineCOD">{CASHONDELIVERY}
</PaymentOption>
<PaymentOption id="BillMe"
profile="SampleCheckoutCustomOfflineBillMe">{BILLME}
</PaymentOption>
</PaymentOptionList>
c. Save the configured SampleCheckout.xml file.

3. To use the Sample Checkout point a browser at the following URL:
http://localhost/SampleCheckout
The result is shown in Figure 4-19.
Figure 4-19 Sample Checkout
To test the merchant and consumer wallet certificate installation and

configuration:

1. Select the SETWallet radio button to simulate the FULL SET architecture.
2. The brand, credit card number, expiration date should then be removed from
the window. The reason for this is that the wallet software will be triggered into
action and the choice of credit card brand and so on will be made by the
consumer through the wallet software.
3. Enter an order number that has not previously been processed by Payment
Manager.
4. Enter the amount and the chosen currency as shown in Figure 4-20.
Figure 4-20 Sample Checkout create order
Tip: Out of the box the Sample Checkout supports only two currencies, US
and Canadian Dollars, even though you are able to select other currencies
using the GUI interface. If the currency is not defined in the properties file
for SET (for the language you are using) the SETWallet request will fail. if
you want to test your SET environment using other currencies add the
required currency code to the file SampleCheckoutSET_en.properties file.
A list of valid currencies can be found in the file
SampleCheckout.properties file. To get the above example working with
the Euro currency, the currency code “CURCODE.978=Euro” was added to
the SampleCheckoutSET_en.properties file.
5. Click Buy. The Sample Checkout formulates an order and passes the
information on to Payment Manager. If any errors occur at this stage (for
example the order already exists for this merchant) then they are passed back
to the SampleCheckout GUI interface. If the order is created successfully, the
SET Consumer Wallet software is triggered. If you are not already logged on,
then sign on to the consumer wallet software.
6. Once successfully logged on to the Consumer Wallet you will be presented
with a window showing the details of your purchase including the amount
being requested, the order number and a description of the order. You now
have the choice of cancelling the order or paying with the SET card.
7. Click Pay to continue with the purchase as shown in Figure 4-21.

Figure 4-21 SET wallet pay prompt
8. An information box appears to say that the wallet is sending a payment

initiation request. If this is successful, then a merchant verification window
appears that enables the consumer to verify the credentials of the merchant.
This is the information created by the merchant when requesting the
merchant SET certificate. Figure 4-22 shows an example.
Figure 4-22 SET wallet verify merchant prompt
9. Another dialog takes place with the Payment Manager and the order is
successfully placed. A message detailing that the order was successfully
placed is written to the SampleCheckout window, as shown in Figure 4-23.
Figure 4-23 Successful Sample Checkout order
Note that the consumer has not been required to enter any credit card number or
expiration date and has also been able to verify the credentials of the merchant.
If you log on directly to Payment Manager as the wcsadmin merchant, you can
see the order in the list of orders ready for the merchant to process. If you open
this order (by clicking the order number) you will see that the merchant does not
see the credit card details. They are kept in the Payment Manager database fully
encrypted (128-bit encryption is used to save the details).

Figure 4-24 shows an example of an order created using SET.
Figure 4-24 Payment Manager view of SET wallet order
5
Chapter 5. Integration with VisaNet

This chapter provides information on how to integrate the WebSphere Payment
Manager cassette for VisaNet into your payment server. It gives you
step-by-step instructions on how to connect to a VisaNet test server and how to
perform sample orders.
The following topics will be covered:

What is VisaNet?
Does your merchant qualify for using VisaNet?
Installing the Payment Manager cassette for VisaNet
Configuring a cassette for VisaNet
Performing a sample checkout through a VisaNet test server

5.1 What is VisaNet?
The VisaNet system is the global processing network of Visa International
Internet unit, called e-Visa. Visa is the leading payment brand and VisaNet the
largest consumer payment system worldwide. The VisaNet global processing
network is operated by Vital Processing Services.
More than 14,000 U.S. financial institutions rely on VisaNet as their processing
system, to facilitate over $765 billion in annual transaction volume.
Although the name VisaNet might suggest that it is only limited to one credit card
type for payment, it in fact supports all the common credit cards such as Visa,
MasterCard, American Express, Diners Club and Novus card types. For an
actual list of supported credit and debit cards, please consult the Vital
Processing Services Web site at:
http://www.vitalps.com
Vital Processing Services does not directly perform merchant registration.

Merchants must contact a processing bank that uses VisaNet as a processor.
Merchants can contact their existing bank or local banks and ask for their
merchant services department and then ask if they support VisaNet. The bank
will then provide the merchant with the required gateway parameters to be
included within WebSphere Payment Manager.
Visa partners with IBM and other global firms to develop and test Visa
Authenticated Payment. Together they speed up e-commerce programs to
ensure safe and secure online payment transactions. With Visa Authenticated
Payment, Visa is providing the same level of security in the virtual world as Visa
has in the physical world.
VisaNet is often chosen as the favorite solution for electronic payment service,
because the transaction connection can be established quickly. This is mainly
because VisaNet uses frame relay and no certification software has to be
installed on the client workstations.
5.1.1 Worldwide restriction

At the time we wrote this book, VisaNet would only allow electronic transactions
that use US dollars as currency. This is one reason why VisaNet is mainly
chosen by merchants in the United States of America as their transaction
system.
5.1.2 Architecture
To establish a connection between your payment server and the Visa VirtualNet
Internet Payment Gateway (VIPG), your server requires an IP-based connection
from a frame relay Internet to VisaNet. When authorizations are performed on
the payment gateway, results are sent back to your payment server in real time.
Visa 2nd Generation is the required format for all transactions being processed
by VisaNet.
Authorization and data capture messages are formatted in accordance with the
following specifications”
EIS 1080 Authorization Protocol Version 6.0
EIS 1081 Data Capture Protocol Version 6.0
Details about these specifications can be read on the Vital Processing Services
Web site at:
5.2 Payment Manager cassette for VisaNet

The WebSphere Payment Manager cassette can be ordered for free through any
Lotus Business Partner in the US. For more details see:
http://www.ibm.com/news/usalet
Search for “Announcement Letters” and use the key word “VisaNet”.
5.2.1 Supported environment

The WebSphere Payment Manager cassette for VisaNet supports a multiplatform
environment, including AIX, Windows NT/2000, and Solaris. Upcoming versions
will also provide support for Linux operating systems.
The cassette can be integrated into either a WebSphere Commerce Suite

environment, or into a stand-alone WebSphere Payment Manager. Instead of
using a client-based certification as other cassettes do (for example, SET or
CyberCash), the cassette for VisaNet ensures a secure payment processing built
on the VirtualNet IP Gateway (VPN over Frame Relay) network infrastructure:
Chapter 5. Integration with VisaNet 143

The cassette for VisaNet allows several attempt cycles in case a payment
process between your server and the Vital gateway is interrupted for any reason.
You will be able to specify how many times it should retry and how frequent the
interval should be.
Detailed technical information about the VisaNet cassette can be found in the
Cassette for VisaNet supplement at:
http://ibm.com/software/webservers/commerce/payment/docs/paymgr221visane
t.pdf
Figure 5-1 shows an overview of the cassette architecture.
Web Server and WAS
Payment
UI Servlet
Servlet
Merchant
Web Browser
Internet
Payment
Manager
Data
Merchant Payment Engine

Server
Cassette for VisaNet
VirtualNet IP
Financial
Institution
VisaNet Host
Figure 5-1 WebSphere Payment Manager cassette for VisaNet - architecture
5.2.2 Class certification
WebSphere Payment Manager cassette for VisaNet is Class B certified, which
indicates that you will get support from IBM as your payment system integrator,
and not from Vital Processing Services.
5.2.3 Gateway connection

Communication between the WebSphere Payment Manager and the VirtualNet
IP Gateway happens over an IP-based Virtual Private Network. Sensitive
information such as the credit card number is encrypted using DES3 before
being stored in the WebSphere Payment Manager database.
5.3 Does your merchant qualify for using VisaNet?

US dollars is the only currency that is currently supported by VisaNet. This is due
to a restriction of the VisaNet network, not the VisaNet cassette. As soon as
VisaNet opens its service to support other currencies as well, you will be able to
use them with your cassette.
The merchant must work through an acquiring bank to establish an account with
Vital Processing Services. It is recommended that the merchant inform the
acquiring bank that he'll also need a test account. The acquiring bank will work
with Vital to create both accounts and provide you with the necessary
configuration parameters (store number, bin, etc.), which go into the Payment
Manager/VisaNet configuration.
If a merchant does not have a bank relationship yet, he can refer to the Vital
Processing Networks Web site, select Merchant and find a list of acquiring banks
complete with contacts and phone numbers.
The merchant is responsible for setting up a frame relay Internet link (PVC) into
the UUNet VirtualNet IP router. UUNet controls the router, and you should
contact their local representative for details. UUNet also supports a PPP
connection (56 kbps dialup). For the PPP connection, they will send you software
to install and it makes the connection. The connection can last all day or be
dynamic, depending on the volume. One UUNet customer does 200,000
transactions/day using the PPP connection. The data streams are small, so PPP
is definitely a possibility.

5.4 Installing the VisaNet cassette
The following guides you step-by-step through the installation of the WebSphere
Payment Manager cassette for VisaNet.
Make sure that before starting the installation of the cassette for VisaNet v2.2,
the following software prerequisites are met:
WebSphere Application Server, Advanced Edition v3.5
WebSphere Payment Manager v2.2 or later
Java Development Kit 1.1.8
If your current installation does not meet the required level, please visit the IBM
Payment Web site and download the new framework or PTF (Program
Temporary Fix):
http://www.software.ibm.com/commerce/payment/support/serv/index.html
1. On AIX and Solaris, you must log on as root. On Windows NT and Windows
2000, you must log on as a user who is a member of the administrator group.
2. Change to the cassette install directory.
3. Enter InstallVisaNetCassette to start the installation.
4. A Java window will appear, guiding you through the installation process. Make
sure that WebSphere Application Server, Advanced Edition is running and
WebSphere Payment Manager is stopped before you continue with the
installation. If one of these conditions is not met, the installation will prompt
you to either start or stop the service.
5. Before the installation process starts, you will be prompted to enter the
password to access the WebSphere Payment Manager database. The
password will be immediately validated and the install process will only
continue if the password entered is correct.
6. Enter the information requested on the installation windows.
7. The IBM Cassette for VisaNet Readme window, as shown Figure 5-2,
indicates that the configuration of the Cassette for VisaNet has successfully
completed and displays the README file, if desired.
Figure 5-2 Cassette for VisaNet installation
5.4.1 Installing the PTF

To download the latest available fix for your server operating system, consult the
Payment Manager Web site at:
http://ibm.com/software/webservers/commerce/paymentmanager/support/index.
html

Note: During installation of the PTF, you will be prompted to enter the
password for the WebSphere Payment Manager database. Be sure to have
that password accessible before starting the installation.
Payment Manager PTFs are shipped as Java class files. These class files will
install the PTF when run. Each ptf.class file includes the version number, the
product and the platform in the name. For example
IBMPayMgr_aix_VisaNetCassette_2.2.1_ptf.class would be the name of the
Payment Manager Cassette for VisaNet PTF, Version 2.2.1 for AIX. The
instructions below use the generic name ptf.class.
1. Log on as a user who is a member of the Administrator's group (on Windows
NT) or as root (on Solaris or AIX).
2. Download the ptf.class file from the Web site or copy it from the CD to a
directory that you have write access to.
3. Stop your Web server, WebSphere Application Server, and Payment Engine.
4. Make sure the JDK classes.zip file is in the CLASSPATH environment
variable. The classes.zip file is usually located in:
On Windows NT: <JDK_HOME>\lib\classes.zip
On Solaris or AIX: <JDK_HOME>/lib/classes.zip
where <JDK_HOME> is the directory where the JDK is installed.
5. Make sure the location of the directory containing the ptf.class file is in the
CLASSPATH environment variable.
6. To start the PTF installer, enter
java <ptf>.
where <ptf> is the actual class name of the PTF to be installed. Figure 5-3
shows an example of installing the cassette PTF.
Important: It is mandatory to launch the PTF from a path that is in your
classpath! If you forget to do that, installation will work but Payment Engine will
fail to load after that. You are then forced to re-install WebSphere Payment
Manager and the cassette for VisaNet.
Figure 5-3 Install PTF in WindowsNT/2000
Tip: When installing the PTF, be sure not to include ‘.class’ when executing
the Java command.
7. Enter the information requested on the installation windows.

8. Before the installation process starts, you will be prompted to enter the
password to access the WebSphere Payment Manager database. The
password will be immediately validated and the install process will only
continue if the password entered is correct.
9. The IBM Cassette for VisaNet Readme window indicates that the update of
the Cassette for VisaNet has successfully completed and displays the
README file containing new and changed functions, if desired.
To check if the update has been processed successfully, start WebSphere

Application Server, Advanced Edition and the Payment Engine. Within the
Payment Engine window you will see exactly what levels of Payment Manager
and VisaNet cassette are actually used and if WebSphere Payment Manager has
started successfully.

5.5 Configuring a cassette for VisaNet
The first step involves the merchant establishing a relationship with a VisaNet
processing bank, which results in the creation of a merchant profile. The
merchant profile includes the following information: Acquirer BIN, Agent Bank
Number, Agent Chain Number, Store Number, Terminal Number, Merchant
Name, VisaNet Merchant Number, Merchant Category Code, Merchant Location,
Time Zone Differential, Merchant State, Merchant City Code.
It is recommended that the merchant informs the acquiring bank that he'll also
need a test account.
The main steps to configure a cassette for VisaNet include:

1. Set up connectivity information in the VisaNet Cassette Settings.
2. Set up Merchant-Cassette information by updating the VisaNet Cassette's
MerchantCassetteSettings. The information needed to do this setup is
obtained from the merchant profile.
3. Create a VisaNet Cassette Account. The information needed to do this setup
is obtained from the merchant profile.
5.6 Using the Vital test account

If this is the first time you have set up a VisaNet cassette for a merchant, it is
recommended that you use a test account rather than the production system for
becoming familiar with VisaNet. A test account consists of a test merchant that
you create in your WebSphere Payment Manager, and a test server located at
Vital Processing Services.
5.6.1 Merchant profile data

Your merchant should be able to provide you with a test merchant profile that he
received from his bank. The data you get for the test server is a little bit different
from what you will get for the production merchant profile. This is because you
additionally need test credit card numbers and card holder’s address and zip
code for verification on the test server. The test merchant profile should include
the following data:
– Account settings
• Acquirer BIN
• Agent Bank
• Agent Chain
• Store Number
• Terminal Number
– Merchant cassette settings:
• VisaNet Merchant Number
• Merchant Category Code
– Payment information
• Test card numbers for Visa, MasterCard, Discovery Card, American
Express etc.
• CVV value
• Expiration date rules
• Test Street Address
• Test Zip
Additionally you will receive host name and port information of the Vital Test
Server as well as sample amounts, which would result in different responses
from the server.
5.6.2 SampleCheckout
We will use the SampleCheckout for use with the test merchant account. Sample
Checkout provides an XML test page that can be used in every browser for
placing a test payment. The SampleCheckout Web site can be accessed at:
Because SampleCheckout is not yet configured to use VisaNet as a payment

option, we will guide you through the adjustments that have to be made.
5.6.3 Adjustment of SampleCheckout

To offer VisaNet as an option within the SampleCheckout Web site, the following
lines must be added to the SampleCheckout.xml file:
<PaymentOptionList>
<PaymentOption id="Offline"
profile="SampleCheckoutOfflineCard"
default="1">{OFFLINECARD}
</PaymentOption>
<PaymentOption id="COD"
profile="SampleCheckoutCustomOfflineCOD">{CASHONDELIVERY}
</PaymentOption>
<PaymentOption id="BillMe"

profile="SampleCheckoutCustomOfflineBillMe">{BILLME}
</PaymentOption>
<PaymentOption id="VisaNet"
profile="SampleCheckoutVisaNet">VisaNet
</PaymentOption>
</PaymentOptionList>
5.6.4 Adjustment of WebSphere Payment Manager

To connect to the Vital test gateway, you have to remove all options beginning
with -D from the file called
IBMPayServer.cmd
You might only have -D options within that file, if you have used
PaymentManager for other test scenarios before.
Make sure that WebSphere Application Server, Advanced Edition and

WebSphere Payment Manager Payment Engine are started.
Open your preferred Web browser and access the Payment Manager site at:
http://localhost/PaymentManager/index.html
Log on using your administrator ID and password.
Creating a test merchant

Create a test merchant by selecting Administration -> Merchant Settings->
Add a Merchant. Use merchant number 123456789. The test merchant’s name
is not significant, but must be consistent throughout the setup of this test
environment. Figure 5-4 shows creating a test merchant.
Figure 5-4 VisaNet test account - creating a test merchant
Merchant cassette settings

1. To edit the cassette settings of the merchant you just created, select
Administration -> Merchant Settings and click the green square box with
the white lightning bolt just below VisaNet. See Figure 5-5.
Figure 5-5 VisaNet test account, merchant settings
2. Enter the test merchant data for VisaNet cassette. You will need to fill in the
Merchant Number and Category Code as provided in the test merchant
profile. This is shown in Figure 5-6.

Figure 5-6 VisaNet test account, merchant cassette settings
3. Enter the merchant account settings by selecting Merchant Settings ->

VisaNet -> Accounts- > Create an Account. You will need to fill in all the
account settings as provided in the test merchant profile. This is shown in
Figure 5-7.
Figure 5-7 VisaNet test account, account configuration
4. The only thing left to configure now is the gateway settings of the Vital Test
Server. This can be done by selecting Cassettes -> VisaNet. Enter the host
name and port as provided within the test merchant profile. See Figure 5-8 for
an example.

.
Figure 5-8 VisaNet test account, gateway configuration
5.6.5 Connect to the VisaNet test account

Now it’s time to open the SampleCheckout window by typing:
in your preferred Web browser. You are ready to send test orders to the Vital
Test Server and receive responses according to the amount and the credit card
information you have entered. See Figure 5-9.
Figure 5-9 VisaNet test account, submitting a sample order
5.6.6 Sample orders

Together with your test merchant profile you usually receive a list of sample
amounts that can be used with the Vital test account. For testing purposes, each
amount would result in different responses from the server.
For example, if you place an order for $0.11, the Vital Test server would generate
a DECLINE and store further details about the reason why the order has been
declined. If you place an order for $0.50, the Vital test server would generate an
ACCEPT. All this data is stored within the Payment Manager trace log file (see
5.6.8, “Consult the trace log files” on page 158).
5.6.7 View the test order

In case you have not selected AutoApprove from within the cassette settings,
you will see the order within PaymentManager Approve section:

Figure 5-10 VisaNet test account, Order received within Payment Manager
Click the checkbox next to the order and select Approve Selected.
5.6.8 Consult the trace log files

The trace log files store all relevant information for VisaNet transactions. The log
file can be found at:
PaymentManager/log/eTillTrace1.log
Every order you place will be traced in the log files. Create some test orders and
look how the test server responds to them. Be sure to have the word wrap option
disabled in whatever editor/viewer you are using to look at the log files. If you use
word wrap, the log file will become unreadable. The following example out of the
log file would show a request that was declined by the test server:
MerchantName = 123456789
OrderNumber = 1001
TransactionNumber = 1
approvalCode = null
authResponseCode = 61
authResponseText = DECLINE
Now that you successfully used the test merchant profile, you are ready to
configure your WebSphere Payment Manager to connect to a production Vital
gateway. This will allow your merchant to use VisaNet for electronic transactions
from his Web site.
6
Chapter 6. Integration using other

payment cassettes
In Chapter 4, “Integration with SET” on page 109 and Chapter 5, “Integration with
VisaNet” on page 141 you read about two popular cassettes for WebSphere
Payment Manager, SET and VisaNet. In this chapter we define terms and
distinguish between cassettes and payment protocols. We discuss why it is
necessary to install cassettes and why casettes are separate from the basic
Payment Manager installation.
Also, we include a comprehensive listing of all the cassettes for WebSphere

Payment Manager, available from IBM or from third parties.

6.1 What is a cassette?
WebSphere Payment Manager is a central structure or framework with
extensions that plug in (called cassettes). The framework manages all the
common infrastructure needed by any electronic payment methods including
feature such as access to the database, server redirects, definition of a
language, and so on. The cassettes specify the flow of the electronic payment
transaction, including the parties involved, the objects used and its meaning.
They control all the process. They define the rules.
The framework just gives support. Without a cassette, the framework can not do
any electronic payment. That’s why along with the framework the WebSphere
Payment Manager installs two cassettes for testing purposes. It’s the only way
Payment Manager can have functionality right out of the box.
6.1.1 How does a cassette work?

A cassette sends and receives XML messages to and from the Payment
Manager framework and translates them to the customer (usually a merchant
software) and to the acquirer (usually a bank or credit card holder). This way,
WebSphere Payment Manager can manage any payment through a specifically
developed piece of software, the cassette.
The cassettes define all or part of a payment protocol. For example, the
cassettes that include the use of a card (credit, debit, exclusive) define the PAN
and the checks associated with this PAN. This is not defined by the framework.
This data is cassette dependent, since there are cassettes that don’t use a card
to carry out an electronic payment. If communication is needed, the cassettes will
format the messages.
The protocol usually includes security: SET certificates, private network, SSL or
any other security defined in the payment protocol. Figure 6-1 shows the way in
which a cassette typically interacts with the WebSphere Payment Manager
framework.
Figure 6-1 An example of how a cassette is integrated with WebSphere Payment
Manager.
6.1.2 Why payments are supported only through cassettes

New payment protocols are supported within WebSphere Payment Manager by
developing a new cassette. New payment methods can be added without having
to modify and reinstall the core WebSphere Payment Manager application.
Instead a new cassette is simply added as a plug-in to the base Payment
Manager. New payment schemes can be created anywhere in the world, so new
cassettes can be developed and service providers can easily add new
functionality for hosted merchants.
Also, this is the best way to create an efficient code that manages payments: the
core of the Payment Manager takes care of processing messages with a unique
format. The plug-ins will handle the task of translating everything and
communicate with other systems.
Chapter 6. Integration using other payment cassettes 161

6.1.3 Cassette development
Each cassette has a different implementation, but they have things in common:
they must talk with the Payment Manager framework the same way.
To reduce coding and efficiently develop new cassettes IBM provides a

development kit. The kit includes a programmer’s guide, a sample cassette, a
tool to generate commands for WebSphere Payment Manager and, of course,
the development tools. Cassette development is described in more detail in
Chapter 9, “Cassette development” on page 273.
6.2 List of cassettes

We provide a comprehensive list of Payment Manager cassettes available as of
the writing of this book. Not all these cassettes are compatible with the latest
version of WebSphere Payment Manager (V2.2) but back-level cassettes may be
updated in the future. If the developer of the cassette decides to migrate to later
versions of WebSphere Payment Manager, the current tools support data
migration from 1.x to 2.x, and to 2.x to 3.x, but not from 1.x to 3.x. The list is not
exhaustive, since cassettes don’t have to be certified by IBM and some cassettes
are a specific development for a specific customer, not a product that can be
resold.
IBM currently ships a cassette for SET with the base Payment Manager software.
Most of the other IBM developed and owned cassettes are available free of
charge. Contact your local IBM representative for more information. Cassettes
from third parties must be obtained from the cassette developers and terms and
conditions may vary. Some cassettes are not publicly available, because they
were written as custom engagements.
You can consult the full list of cassettes in Table 6-1 on page 167.
Note: The availability of cassettes changes frequently so we recommend that

for up-to-date contact information about cassettes you check:
http://ibm.com/software/webservers/commerce/payment/paymentcards.htm
l
APACS
The Association for Payment Clearing Services (APACS) is the United Kingdom
bank consortium that owns the standards for all inter-bank transfer related items.
The APACS cassette connects to financial networks that process requests
according to APACS standards. For authorization the cassette uses APACS
Standard 30, “Specification for a Credit Authorization Terminal”. For data capture
and settlement, the APACS cassette is designed to process two standards:
APACS Standard 29B (“Flexible File Format for Card Companies and Retail”)
and APACS Standard 40 (“Acquirers' Interface Requirements for Electronic Data
Capture Terminal”).
The physical communication for all APACS messaging is X.25. Most acquirers
still only support an X.25 environment. All the major acquirers are in the process
of creating Internet support for their merchants. The APACS cassette uses
acquirer configuration files to support the needs of today as well as future
environments. A configuration file defines the protocol and connection used by
the acquirer. In addition, the configuration file references a specific connection
implementation.
The first service offering of this cassette was to support an acquirer/processor

that supported APACS Standard 30 and APACS Standard 40 over IP. If your
target acquirer is not currently supported, then a small piece of service work
must be completed to implement a configuration file and supporting classes.
Atos IPS
The IPS cassette, available from Atos, provides full functional access to Atos
Poseidon Internet Payment System (IPS), a SSL gateway with support of
international credit cards (Visa, MasterCard, American Express, JCB), debit
cards, direct debit, and stored value cards (for example, German Geldkarte). For
the transmission of sensitive financial data, IPS offers a direct SSL
communication to the consumer (thin wallet). Beyond this the IPS gateway can
be integrated with the IBM SET solution so it provides the back-end connection
to IBM Payment Gateway (via Atos customization).
It is based on credit cards (Visa, MasterCard, American Express, JCB). It needs

a wallet on the client side, and also supports a server wallet.
BankServACH
This cassette, available from IBM, does not need a card for payments. It admits
electronic checks and ACH funds transfers. The electronic check is a version of
ACH funds where the electronic media substitute for the traditional paper check.
The account information is encrypted and sent to the server, which compares it
with a huge database for real-time authorization.
Although the BankServ gateway is prepared for a greater variety of payments,

including credit cards, the cassette implementation only admits Internet checks
and ACH funds transfers.

The BankServ payment gateway interfaces with the Automated Clearing House
(ACH) network to support online electronic check payments, made in a single
transaction using the automated ACH system operated by the Federal Reserve
to debit and credit the appropriate accounts at different financial institutions.
For more information, visit http://www.bankserv.com, or contact your local IBM

Sales Representative.
ClearCommerce
The ClearCommerce cassette, from CSI, allows merchant applications to
integrate with ClearCommerce's Payment module. The cassette uses
ClearCommerce's JLink 3.8 libraries to connect securely and transact with their
servers. The JLink API uses Secure Sockets Layer (SSL) to encrypt data
transmission during processing.
The communication between the cassette and the ClearCommerce servers is

done following some Payment Manager commands. All other operations are
local.
For information on ClearCommerce, visit http://www.clearcommerce.com. CSI

it’s not an independent software vendor (ISV), so this cassette may not be
available as a product.
CustomOffline and OfflineCard

The OfflineCard cassette enables the reading of card transaction details without
being connected to a financial processing network. When using the OfflineCard
cassette, you can view reports that consolidate both online and offline payments.
This cassette is used in the examples OrderEntry and CheckOut applications

installed with WebSphere Payment Manager. Its main objective is to provide for
development and testing, and an example of using the Java cashier framework.
The CustomOffline cassette enables the recording of arbitrary payment

information such as voucher payments, cash on delivery payments, or other
payment schemes where money is not required to flow. This also works without
being connected to a financial network.
The idea behind this cassette is that the customer can define (customize) what
each function of the cassette means, which provides complete freedom of
personalization without the need for developing a cassette.
CyberCash
The IBM cassette for CyberCash provides access to the CyberCash
CashRegister processing service in US English and US dollars. Currently, only
the North American CashRegister service supports the CyberCash Merchant
Connection Kit (MCK) Version 3.2 protocol. This service enables merchant
access to the set of North American acquirers listed at
http://www.cybercash.com/. While CyberCash CashRegister services may be
available in other countries, they may not support the Version 3 interface.
The cassette for CyberCash admits payments with credit cards, electronic
checks and micro payments. Payments are made using merchant-collected
information, where merchant software asks for card information over a secured
connection or an electronic wallet. The merchant must already have an account
with an acquiring financial institution and authorization as a credit card merchant.
More detailed information is provided in the Cassette for CyberCash Supplement

available for download at:
http://ibm.com/software/webservers/commerce/payment/docs/paymgr221cyber.
pdf
CyberSource
Available from CyberSource, this cassette communicates with the CyberSource
Transaction Server (CTS) in real time to authorize and settle credit card and
other payment transactions. The payment is done through pre-built connections
with third-party processors and merchant banks.
For more information, visit http://www.cybersource.com.
FDMS
The IBM Cassette for First Data Merchant Services (FDMS) North provides
access through a leased-line connection to First Data's North platform through
SSL. This is available through an IBM Services engagement only.
It uses the standard ISO 8583 message format for authorization requests and
responses. The FDMS protocol can handle authorizations for credit cards,
electronic checks and debit cards, but the cassette is developed to support credit
cards only. Also, although FDMS supports authorization reversals for Visa credit
cards only, the cassette does not currently implement this facility.
FDMS does not work with real-time transactions. Instead, all the transactions
done in a day are sent in a “settlement” file and processed at the end of the day.

GlobalCollect
Available from a third party (GlobalCollect), this cassette is focused on
supporting several payment methods, both card and non-card, based on local
standards.
For more information, visit http://www.globalcollect.nl
RiTA
Available from Go Software, this cassette is certified with most major North
American processors. The RiTA Payment Cassette for IBM offers credit card,
ACH processing and fraud protection features.
For more information, visit http://www.pccharge.com.
PaylinX
Available from Lynk Systems, the PaylinX cassette processes card and check
payments. It is valid only for North American credit and debit cards, corporate
procurement cards, private label gift cards, and check transactions. Apart from
the cassette Lynk also provides optional fraud-scoring and risk management
services.
For more information, visit http://www.lynksystems.com.
Payflow Pro
Available from VeriSign Payment Services, the Payflow Pro cassette supports
online payment processing for merchants to all major North American payment
processors. Fraud screening and ACH processing are optional services also
offered by VeriSign. The Signio cassette is now part of VeriSign.
Although the cassette is currently supported only on Windows NT and OS/400,

there are plans to port it to AIX and Solaris.
For more information, visit http://www.verisign.com/products/payment.html.
SET
Chapter 4, “Integration with SET” on page 109 provides a detailed explanation of
this cassette.
VisaNet
Chapter 5, “Integration with VisaNet” on page 141 provides a detailed
explanation of this cassette
Table 6-1 Cassettes available for Payment Manager, in alphabetical order
Cassette OS Version(s) How to obtain it
APACS AIX Payment Ask your local IBM Sales Representative

NT Manager
Solaris 2.2
WIN2K
Atos IPS AIX Payment Contact your local IBM Sales Representative
NT Manager
Solaris 2.1
WIN2K Payment
Manager
2.2
BankServACH AIX Future Visit http://www.bankserv.com, or contact your local

NT 3.X IBM Sales Representative
Solaris
WIN2K
ClearCommerce AIX Payment Visit http://www.clearcommerce.com

NT Manager
2.1
CustomOffline AIX Payment Included in Payment Manager

OfflineCard AS400 Manager
NT 2.2
OS/390
Solaris
WIN2K
CyberCash AIX Payment Ask your local IBM Sales Representative

AS400 Manager
NT 2.1
OS/390 Payment
Solaris Manager
WIN2K(*) 2.2
CyberSource AIX Payment Visit http://www.cybersource.com

NT Manager
Solaris 2.1
GlobalCollect AIX Payment Visit http://www.globalcollect.nl

NT Manager
Solaris 2.1

Cassette OS Version(s) How to obtain it
FDMS AIX Payment Ask your local IBM Sales Representative

Manager
2.1
RiTA AIX Payment Visit http://www.pccharge.com

NT Manager
Solaris 2.2
WIN2K
PaylinX AIX Payment Visit http://www.lynksystems.com

NT Manager
Solaris 2.1
Payflow Pro NT Payment Visit

OS/400 Manager http://www.verisign.com/products/payment.html
2.2
SET AIX eTill 1.0 Ask your local IBM Sales Representative
AS400 eTill 1.2
NT Payment
OS/390 Manager
Solaris 2.1
WIN2K(*) Payment
Manager
2.2
VisaNet AIX Payment Ask your local IBM Sales Representative

NT Manager
Solaris 2.1
WIN2K Payment
Manager
2.2
(*) This Operating System is supported only in WebSphere Payment Manager

Version 2.2.
7
Chapter 7. Integration with WebSphere

Commerce Suite
In this chapter we describe how the WebSphere Payment Manager framework
fits within the WebSphere Commerce Suite tool set. More specifically we tested
with WebSphere Commerce Suite V5.1.01 Professional Edition on Windows
2000. The chapter goes through a split software stack installation and describes
the necessary activities required to get a fully working system.
Integration of WebSphere Payment Manager with WebSphere Commerce Suite

Marketplace Edition V4.2 is not covered in this chapter. If you want more details
about enabling WebSphere Payment Manager with WebSphere Commerce Suite
Marketplace Edition please see:
http://ibm.com/software/webservers/commerce/epit/mpepm.html

7.1 Sharing users
If you are going to offer merchants a powerful commerce tool set integrated with
a payment engine, you need to make the maintenance of user IDs as easy as
possible for the merchant and avoid the merchant having to maintain separate
user IDs for each tool.
WebSphere Payment Manager 2.2 supplies a Java-based plug-in mechanism for

realm support that allows Payment Manager to access user ID details from
another source. A standalone Payment Manager is supplied with a default realm
and uses simple user ID maintenance tools.
This section describes the mechanism provided with WebSphere Commerce

Suite that allows for sharing of users with a Payment Manager installation.
Note: Each Payment Manager installation can use only one realm at a time. The
integration between Commerce Suite and Payment Manager in terms of user ID
support is supplied already written and only needs to be activated using
customization of the supplied Payment Manager configuration files.
Note: The realm support is not exclusively open to Commerce Suite installations.
It is possible to write your own plug-in realm that will allow (for example) user IDs
to be stored in another format, or for Payment Manager to use the same user ID
repository of a different e-commerce engine.
7.1.1 Customization for Commerce Suite and Payment Manager

The IBM WebSphere Commerce Suite Installation Guide provides details of the
necessary customization for configuring Payment Manager to use the supplied
Commerce Suite realm. Briefly the customization consists of the following steps:
Back up the supplied PMRealm.jar in the Payment Manager install directory.
Copy the supplied Commerce Suite PM realm JAR file
<drive>\Websphere\Wcs\Lib\wcspmrealm.jar into the Payment Manager
install directory and rename it PMRealm.jar.
In the PaymentServlet.properties file, set the value of the WCSWebPath:
WCSWebPath=/webapp/wcs/stores/servlet
After restarting the Payment Manager application server, the users defined within
Commerce Suite will also be defined in Payment Manager. The users are kept
once in Commerce Suite. Payment Manager is given access to the same user
IDs that Commerce Suite has defined. If this is the first time you have installed
Payment Manager with Commerce Suite, use the default-supplied wcsadmin
user ID to access the Payment Manager merchant administration interface. By
default this ID has also been given the Payment Manager administrator role.
For more detailed instructions, please refer to the Commerce Suite installation
guide.
7.1.2 Customization when Payment Manager is on a remote machine

When Payment Manager and Commerce Suite are not installed on the same
machine an additional step is required. Customize the WCSHostName property
to contain the IP host name of the server where Commerce Suite is installed:
WCSHostName=<wcs_host_name>
This informs Payment Manager where Commerce Suite is installed so the class
files defined in PMRealm.jar can obtain information on the users defined by the
Commerce Suite administration interface. An IP connection to this host is
required in order for Payment Manager to find the Commerce Suite installation.
Figure 7-1 outlines this architecture.
IBM WebSphere
Commerce Suite Payment Manager
PMRealm.jar
WCS Supplied WPM Supplied
User Authentication PSDefaultRealm

WCS User Requests
Database
WCSHostName = <WCS_host_name>
(from PaymentServlet.properties)
Figure 7-1 Payment Manager realm support with Commerce Suite
Chapter 7. Integration with WebSphere Commerce Suite 171

7.2 Remote database configuration
If you decide to split the installation of Commerce Suite and Payment Manager
when you install DB2 on its own machine, you will also need to install the DB2
client on the Payment Manager machine so that Payment Manager commands to
access the DB2 database can be dealt with. Figure 7-2 shows the layout the
installation.
Machine A Machine B
Orders IBM WebSphere

Payment Manager
Commerce Suite
DB2 Client
Machine C
DB2 Payment
Manager
DB2
Figure 7-2 Split Commerce Suite Payment Manager and DB2 configuration
With Payment Manager V2.2 and no PTFs applied, Payment Manager

installation verification fails with an error message as shown in Figure 7-3.
Figure 7-3 Payment Manager install error with a remote DB2
It was clear from our previous successful installs of Commerce Suite and
Payment Manager on the same machine that the only difference with this attempt
was that the DB2 was remote to the machine where Payment Manager was
being installed. We had already installed the DB2 client and cataloged the
Payment Manager database on the machine where Payment Manager was being
installed. To quickly get around the problem, we decided to install a DB2 server
environment on the Payment Manager machine. When we did this, the
installation of Payment Manager using the remote DB2 completed successfully
so it appears that the Payment Manager installation verification checks required
a full installation of DB2 on the machine where it was being installed.

Important: After further investigation we discovered that the installation
problem had already been reported and fixed. The fix was made generally
available in the V2.2.1 PTF upgrade available on the Web. We installed this
PTF, which solved the problem.
For more information on the V2.2.1 PTF please go to the following URL, which
will give information on how to download the PTFs for all platforms:
http://ibm.com/software/webservers/commerce/paymentmanager/support/sbu
ll2.html
For the specific V2.2.1 PTF upgrade that we installed in the Windows 2000
environment, go to the following URL:
http://www.software.ibm.com/dl/paymgr/srvupdts-p
There is a PTF upgrade for the Payment Manager framework as well as an

upgrade to the IBM-supplied cassettes.
7.3 Payment Manager administration

Payment processing and administration is provided through the following:
WebSphere Commerce Suite Accelerator
The Commerce Suite Accelerator provides a button that launches the
Payment Manager user interface within the same frame as the accelerator.
This gives the Commerce Suite merchant a seamless interface between the
two applications.
The WebSphere Commerce Suite Administration Console
The Commerce Suite Administration Console also includes links to all
Payment Manager administration functions from the Payment Manager menu.
This is useful when you are setting up your store and want to configure the
Payment Manager cassette for the store or assign the Payment Manager
administrator role to the WebSphere Commerce Suite administrator.
The Payment Manager user interface
Administrators who have been assigned Payment Manager access roles will
be able to access the Payment Manager user interface through one of the
Payment Manager launch points in the Commerce Suite Accelerator or the
Administration Console. They will not need to log on a second time.
7.4 Commerce Suite-supplied payment resources
WebSphere Commerce Suite V5.1 supplies resources (class files, commands,
and JSPs) for use with WebSphere Payment Manager 2.2. The following
sections give detail of these resources.
7.4.1 Payment Class files

WebSphere Commerce Suite implements a number of classes that use the
framework of Payment Manager to do payment processing within a Commerce
Suite environment.
DoPaymentMPFCmdImpl class
This Commerce Suite-supplied class uses the DoPaymentCmd (task) command
interface to instruct Payment Manager to initiate the payment process for an
order via the Payment Manager 2.2 cashier function. Please refer to the
Commerce Suite documentation for more information on this supplied class file.
GetOrderDescCmdImpl class
This class file uses the Commerce Suite GetOrderDescCmd (task) command
interface. It formats the order description for use by wallet applications. In
Commerce Suite, this task command is called by a cashier extension function
specified in the cashier profiles used for the Payment Manager Cassette for SET.
7.4.2 Controller commands

A number of WebSphere Commerce Suite controller commands also use
Payment Manager functions.
The PayResetPM controller command

This command is used to reset a WebSphere Commerce Suite order to the
pending state and to purge the order record created in the Payment Manager
tables. This allows the Commerce Suite order to be re-submitted for processing
by Payment Manager. This command is typically called via a consumer action
after the consumer is informed of an error or problem processing the payment for
the order.

The PaySynchronizePM controller command
This command is executed by the Commerce Suite scheduler periodically, to
synchronize the information between Commerce Suite and Payment Manager.
Only orders that have been submitted to Payment Manager for processing and
are still in state I (inventory update pending) or state M (authorization pending)
are processed by this command. Once the order has been authorized, this
command changes the order state to C (Complete) and will not track its status
any further.
7.4.3 Sample JSPs and related views

WebSphere Commerce Suite V5.1 also supplies two JavaServer Pages that deal
directly with payment views. They are configured for use with Payment Manager
and contain a number of views to be used by the default cassettes. The two JSPs
are:
1. PayStatusPM.jsp
This JSP is used to display different text depending on the status of the
payment. The payment status of the order is obtained through the Commerce
Suite PayStatusPMDataBean, which is designed to be used by JSPs to
display the payment status of an order to a customer after the completion of a
purchase.
2. PayService.jsp
PayStatusPM.jsp and PayService.jsp together are used in the Commerce Suite

default views:
– OrderOKView
– PaySuccessView 1
– PayCancelView1
– PayFailureView1
– PayServiceView1
– DoPaymentErrorView
1
These views are used only by the Cashier Profile for SET when a wallet
application is used.
The default install of Commerce Suite sets up all stores (storeEnt_id of 0) in the
VIEWREG table to use the PayStatusPM.jsp for the PaySuccessView,
PayCancelView and PayFailureView. PayService.jsp is used for the
PayServiceView. If you want to customize the use of any of these JSPs you can
modify the VIEWREG table.
The PayStatusPM.jsp is an all-purpose sample JSP file that many of the views
related to payment processing could specify. In addition to the SET Wallet
specific views set up by Commerce Suite mentioned above, the OrderOKView
could also be set up to specify this JSP file. To do this the process is currently
manual, because the default page for the OrderOKView is a simple static page
named OrderOK.jsp. The OrderOKView could also be mapped to the
PayStatusPM.jsp file if Payment Manager is used to process payment for the
store.
To set up the OrderOKView manually in the Commerce Suite VIEWREG table,

ensure you specify the RedirectViewCommand interface or the
HTTPForwardViewCommand interface. The appropriate values for setting up the
OrderOKView entry in the VIEWREG table are shown in Table 7-1:
Table 7-1 Commerce Suite VIEWREG entries for OrderOKView
Column Value
ViewName OrderOKView
interfacename com.ibm.commerce.command.RedirectViewCommand or
com.ibm.commerce.command.HttpForwardViewCommand
classname com.ibm.commerce.command.HttpRedirectViewCommandImpl or
com.ibm.com.commerce.command.HttpForwardViewCommandImpl
devicefmt_id -1
properties If you use the RedirectViewCommand interface:
redirecturl=<JSP file name>

where <JSP file name> is the name of the JSP file you want to use.
For example, to use PayStatusPM.jsp, the value would be
redirecturl=PayStatusPM.jsp.
If you use the HTTPForwardViewCommand interface
docname= <JSP file name>

where <JSP file name> is the name of the JSP file you want to use.
For example, to use PayStatusPM.jsp, the value would be
docname=PayStatusPM.jsp.
The default page for the DoPaymentErrorView is the Commerce Suite

GenericApplicationError.jsp. It can be found in
WCS_install_dir\instances\instance_name\stores\web\.

This sample JSP file is specified by many error views by default. Its purpose is to
show the error information that is available from the ErrorDataBean that the JSP
file receives from Payment Manager. You should provide your own customized
error page to display a more meaningful message to the consumer.
You may also want to customize the default views by, for example, adding your
own store banner, logo or changing the color scheme and fonts. Customization of
these views is outside of the scope of this redbook, so we used the default views
and their default JSP specifications.
7.4.4 Payment Manager cashier profiles

Cashier profiles are XML documents that describe how Payment Manager orders
should be created for use by Payment Manager with specific cassettes. For
example there are two cashier profiles relevant to the Payment Manager support
of SET, one which allows Payment Manager to trigger a wallet application as part
of the purchase (WCS51_SET_Wallet.profile) and a similar cashier profile for the
use of MIA purchases (SET order without the use of a wallet) that is
WCS51_SET_MIA.profile.
For more information on how cashier profiles are defined, please refer to the IBM
WebSphere Payment Manager for Multiplatforms Programmer’s Guide and
Reference Version 2.2. For the integration of Commerce Suite and Payment
Manager - Commerce Suite supplies relevant profiles for all the IBM-supplied
cassettes, so it is unlikely that you would be required to change any of these
profiles.
7.4.5 Understanding the WCS51_SET_Wallet cashier profile

The cashier profiles define how payment requests are sent to Payment Manager
and how in turn Payment Manager processes that payment. The following gives a
brief description of the important parameters and their use within the SET wallet
cashier profile as supplied with WebSphere Commerce Suite V5.1. This method
of payment was chosen since it is probably the most complex to configure and
get working and there is very little documentation currently available to get a
store up and running with this cassette.
Example 7-1 shows the supplied cashier profile for SET Wallet purchases. It can
be found in <wcs_install_directory>\instances\<instance_name>\xml\payment\.
Example 7-1 Default Commerce Suite-supplied SET Wallet Cashier profile
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Profile SYSTEM "../../../../xml/PaymentManager/profile.dtd">


<Profile useWallet="true" enableTrace="true" >
<CollectPayment>
<BuyPageInformation reference="WCS51_SET_Wallet"></BuyPageInformation>

<Parameter name="PAYMENTTYPE"><CharacterText>SET</CharacterText></Parameter>
<Parameter name="MERCHANTNUMBER"><CharacterText>{storeId}</CharacterText></Parameter>
<Parameter name="ORDERNUMBER"><CharacterText>{orderId}</CharacterText></Parameter>
<Parameter name="CURRENCY"><CharacterText>{CURRENCY}</CharacterText></Parameter>
<Parameter name="AMOUNT"><CharacterText>{AMOUNT}</CharacterText></Parameter>
<Parameter name="AMOUNTEXP10"><CharacterText>{AMOUNTEXP10}</CharacterText></Parameter>


<Parameter name="APPROVEFLAG"><CharacterText>1</CharacterText></Parameter>

<Parameter name="PAYMENTAMOUNT"><CharacterText>{AMOUNT}</CharacterText></Parameter>

<Parameter name="PAYMENTNUMBER"><CharacterText>1</CharacterText></Parameter>

<Parameter name="DEPOSITFLAG"><CharacterText></CharacterText></Parameter>

<Parameter
name="$SUCCESSURL"><CharacterText>http://{WCSHostName}{WebPath}/PaySuccessView?storeId={storeId
}&orderId={orderId}&langId={buyer_language_id}</CharacterText></Parameter>
<Parameter
name="$FAILUREURL"><CharacterText>http://{WCSHostName}{WebPath}/PayResetPM?storeId={storeId}&am
p;orderId={orderId}&fail=1&langId={buyer_language_id}&URL=PayFailureView</Character
Text></Parameter>
<Parameter name="$CANCELURL"
><CharacterText>http://{WCSHostName}{WebPath}/PayResetPM?storeId={storeId}&orderId={orderId
}&cancel=1&langId={buyer_language_id}&URL=PayCancelView</CharacterText></Parameter>
<Parameter
name="$SERVICEURL"><CharacterText>http://{WCSHostName}{WebPath}/PayServiceView?storeId={storeId
}&orderId={orderId}&langId={buyer_language_id}</CharacterText></Parameter>

<Parameter name="$ORDERDESCRIPTION" encoding="8859_1" >
<ExtensionValue name="com.ibm.commerce.payment.extensions.GenericExtension" />
</Parameter>


<Parameter name="$AVS.STREETADDRESS"><CharacterText></CharacterText></Parameter>


<Parameter name="$AVS.CITY"><CharacterText></CharacterText></Parameter>


<Parameter name="$AVS.STATEPROVINCE"><CharacterText></CharacterText></Parameter>


<Parameter name="$AVS.POSTALCODE"><CharacterText></CharacterText></Parameter>

<Parameter name="$AVS.COUNTRYCODE"><CharacterText></CharacterText></Parameter>

<Parameter name="$AVS.LOCATIONID"><CharacterText></CharacterText></Parameter>

<Parameter name="$CHARSET"><CharacterText></CharacterText></Parameter>

<Parameter name="$MERCHCATCODE"><CharacterText></CharacterText></Parameter>

<Parameter name="$MERCHGROUP"><CharacterText></CharacterText></Parameter>

<Parameter name="$MERORDERNUM"><CharacterText></CharacterText></Parameter>

<Parameter name="$SPLITALLOWED"><CharacterText>1</CharacterText></Parameter>


<Parameter name="$REQUIRECARDCERT"><CharacterText>1</CharacterText></Parameter>
</CollectPayment>
</Profile>
The PAYMENTTYPE parameter specifies the actual name of the cassette that
the profile is use for.
Note: Commerce Suite requires that this name also appear as part of the file
name of the profile.
Variables surrounded by the curly brackets {} are environment variables passed

by the DoPaymentMPFCmdImpl command to the Payment Manager cashier. It is
this Commerce Suite command that verifies with Payment Manager that the
merchant owner of the store is authorized to use the cassette and it also
performs validity checks on any credit card number or expiration dates passed to
it (for example it checks that the date specified is not in the past and is not more
than 10 years in the future). Error processing done by the command includes the
provision for error codes passed by Payment Manager as well as messages for
both merchant and consumer. The use of these fields will be dependent on the
cassette used and the implementation policy of the back-end financial institution.
For more information on the function and behavior of this Commerce Suite
payment command and the error codes passed by it, please refer to the online
Commerce Suite documentation.
The reference attribute of the BuyPageInformation element is used by

Commerce Suite Accelerator to locate buy page information for use when the
merchant administrator needs to submit an order to Payment Manager for
processing
By definition, the WCS51_SET_Wallet cashier profile specifies the use of a

wallet. It uses the GenericExtension class to obtain value for the parameter
$ORDERDESCRIPTION, which is needed to generate the payment-initiation
message and display the description of the order in the wallet application. (The
GenericExtension class actually calls the Commerce Suite GetOrderDescCmd
command to obtain a value for the $ORDERDESCRIPTION parameter. This
allows different stores to have different GetOrderDescCmd command
implementations but the same cashier profile can still be used for all Commerce
Suite stores.)
The profile also specifies the use of the PaySuccessView, PayFailureView,

PayCancelView and PayServiceView for the $SUCCESSURL, $FAILUREURL,
$CANCELURL and $SERVICEURL parameters respectively. Note the use of the
PayResetPM command for $FAILUREURL and $CANCELURL. The "fail=1" and
"cancel=1" parameters are parameters for the default sample JavaServer Pages
(PayStatusPM.jsp) used by both the PayFailureView and the PayCancelView.
The parameter directs the JSP file to display different messages to the shopper
depending on which parameter is set.
For more information on the parameters required by the Cassette for SET refer to
IBM WebSphere Payment Manager for Multiplatforms, Cassette for SET
Supplement, Version 2.2.
7.5 Enabling a non-IBM supplied cassette

WebSphere Commerce Suite can be configured to use Payment Manager
cassettes other than IBM-supplied cassettes. Details of how to do this are in the
Commerce Suite online help.
7.6 Enabling the sample store to use Payment Manager

The Commerce Suite InFashion sample store comes with a partially set-up
Payment Manager interface. When you create your store for the first time using
the InFashion store archive the process involves setting up the default wcsadmin
ID to be a Payment Manager administrator. This is the highest Payment Manager
role and enables you to administer all Payment Manager users. Since this is a
very high-powered user we changed the role of the wcsadmin user ID to be a
merchant administrator. This would have the effect of wcsadmin only being able
to administer orders/users for the store that this merchant owned and would be a
more realistic scenario.
7.6.1 Change the role of wcsadmin for Payment Manager tasks

To change the Payment Manager role for wcsadmin do the following:
Create a new user ID and assign it the highest Payment Manager role. This
user ID was created by wcsadmin.

Since it is not possible to change the role of the user you are logged in as, log
on to the new user ID.
Change the role of the wcsadmin user ID to be a merchant administrator.
Assign the wcsadmin merchant to the user ID. This has the effect of ensuring
that wcsadmin can only administer orders from its own store.
Note: The Commerce Suite and Payment Manager in our environment both
shared the Commerce Suite realm so this has the effect of sharing user IDs
between the two systems. However, Commerce Suite is the owner of the
users so if you need to add a user to administer Payment Manager you add
the user ID through the Commerce Suite admin console and not through the
supplied Payment Manager PSDefaultRealm <add> command.
In the above example even though the Payment Manager role for wcsadmin
has effectively been downgraded for Payment Manager tasks the Commerce
Suite role for wcsadmin remains unchanged.
If you choose not to implement the above policy, this should have little effect.
However, in practice the wcsadmin user will be able to administer all aspects
of Payment Manager.
7.6.2 Decide which protocols to use for processing orders

Once the role policy for your merchant has been decided, the merchant must
decide which payment protocols will be used to process orders. By default the
wcsadmin user has a choice of using the cassettes CustomerOffline and
OfflineCard (default selected option) or any other defined cassette. We defined
the SET cassette to the Payment Manager environment. To add or change
cassettes made available to the merchant:
Log on to the Commerce Suite Admin console using a Commerce
Suite/Payment Manager Administrator (the new user ID we set up earlier in
this chapter).
Choose to administer the site (not store).
When the Admin console main options window appears choose Payment
Manager and in the drop-down box that appears choose Merchant Settings.
This should now give you a table listing all the defined merchants and which
cassettes they are authorized to use.
Click a merchant name (in blue). This will show you the detail for that
individual merchant. Enable the required cassette by selecting the cassette
name, and then click Update. For example Figure 7-4 shows how to add SET
for the wcsadmin merchant:
Figure 7-4 Authorize merchant for an additional cassette
If the authorization works correctly, a green message will appear indicating

that the update was successful.
To verify the additional cassette authorization for the merchant, select the
Merchant Settings link at the top left corner of the window. A table will
appear detailing all merchants and their authorization for the Payment
Manager-defined cassettes. If the cassette is authorized for use by the
merchant and is active, a green logo appears in the column for that cassette.
For example Figure 7-5 shows that the merchant wcsadmin has authorization
for the OffLineCard and SET Cassettes.

Figure 7-5 Verify merchant cassette authorization
Now follow the instructions provided in Chapter 4, “Integration with SET” on

page 109 to configure the SET cassette for the merchant and obtain the
correct SET merchant certificates by creating a Brand and using the SET
Demo Registration environment (or if you doing this for real then use the
financial institution’s instructions for acquiring the certificates).
Once this is complete the merchant is ready to begin processing payments for
the chosen cassettes.
Note: Cassette authorization for a merchant enables the merchant to choose
which cassettes they use. It is not mandatory that the merchant uses all
cassettes for which he/she is authorized.
7.6.3 Enabling the Commerce Suite sample store for SET purchases
The sample WebSphere Commerce Suite V5.1 store InFashion is configured to
use the offline card by default. This will enable you to process payments without
using any automatic processing by a back-end financial institution. As well as
using the offline card cassette for demonstration purposes, a merchant may
choose to use this cassette in a production store. For example if they already had
a card swipe system in their bricks and mortar shop, it could make sense for a
merchant to use offline card with their e-commerce store. However, a merchant
may require payments to be processed by a back-end financial institution if they
need additional payment processing features such as credit card authorization
and approval checking. In this case the merchant would want to opt for a
commercial cassette. Chapter 6, “Integration using other payment cassettes” on
page 159 details the commercially available cassettes.
To demonstrate how to configure a Commerce Suite store to use a cassette other

than the offline card, we detail the configuration that was performed to the
sample InFashion store to get the store running with SET wallet purchases:
1. Validate InFashion working with the offline card
First of all, ensure that the InFashion store works correctly with the offline
card cassette. By default the offline card should have been set up with a
brand called ROBO. On the InFashion store checkout window (where you are
asked for a credit card type in the credit card information section) you should
see ROBO as the default credit card type.
Important: The Payment Engine must be up and running without any

errors. If the engine is not running correctly for any reason the Commerce
Suite commands that enquire about the valid credit card brands for the
owning merchant will not work correctly and the ROBO credit card type will
not appear in the list of available credit card types.
Use credit card number 2222222222222224 with any future expiration date to
get an order through to Payment Manager. Using Commerce Suite
Accelerator, check that the order appears in Commerce Suite and that the
order has been created in Payment Manager.
If the InFashion store works with the offline card, you can begin to configure
the store to work with the SET cassette.

2. Configure OrderDisplayPending.jsp
This JSP (supplied with the WebSphere Commerce Suite V5.1 sample store)
handles the checkout processing for the sample store. By default it is
configured to collect credit card information (using the offline card), perform a
limited credit card validity check and use the relevant Commerce Suite
payment beans to pass the order payment details on to Payment Manager.
You can find the OrderDisplayPending.jsp file in
<WCS-install>\stores\web\<instance name>.
To change the JSP to work for SET wallet purchases, the value of
ECConstants.EC_PAYMTHDID was changed from 200 to 400 as shown in
Example 7-2.
Example 7-2 Change the value of ECConstants.EC_PAYMTHDID
<form Name=CardInfo METHOD=Post action="<%="OrderProcess"%>">

<input type=hidden name="<%= ECConstants.EC_PAYMTHDID %>" value="400">
<input type=hidden name="orderId" value="<%= orderBean.getOrderId()%>">
<input type=hidden name="storeId" value="<%= storeId %>">
<input type=hidden name="langId" value="<%= languageId %>">
<input type=hidden name="catalogId" value="<%= catalogId %>">
The default supplied values of ECConstants.EC_PAYMTHDID for the

IBM-supplied cassettes are defined in the wcs.bootstrap.xml file (in
<WCS_install_dir>\schema\). The contents of this file are shown in
Example 7-3.
Example 7-3 Supplied paymthd_id values
<paymthd paymthd_id="100" profilename="WCS51_CustomOffline" />
<paymthd paymthd_id="200" profilename="WCS51_OfflineCard" />
<paymthd paymthd_id="300" profilename="WCS51_SET_MIA" />
<paymthd paymthd_id="400" profilename="WCS51_SET_Wallet" />
<paymthd paymthd_id="500" profilename="WCS51_CyberCash" />
The paymthd_id value maps to a profile name and the profile names match to
Payment Manager cashier profiles that are supplied by WebSphere
Commerce Suite V5.1.
The brand display logic in OrderDisplayPending.jsp for the credit card type
also requires changing, since by default it has OfflineCard hard coded in the
JSP as shown in Example 7-4.
Example 7-4 Default display logic in OrderDisplayPending.jsp
//Display brands for OfflineCard and for the currency presently
//being used.
for (int i = 0; i < acctInfo.length; ++i)
{
if (acctInfo[i].getCassetteName().trim().equals("OfflineCard") &&
acctInfo[i].getCurrencyCode().trim().equals(currentCurrency))
{
%>
<option
value="<%=acctInfo[i].getBrand()%>"><%=acctInfo[i].getBrand()%></option>
<%
}
}
%>
Change the above OfflineCard code to use SET. This value matches the
value of the parameter name PAYMENTTYPE in the relevant cashier profile.
See Example 7-5.
Example 7-5 Specify SET in credit card brand display logic
//Display brands for OfflineCard and for the currency presently
//being used.
for (int i = 0; i < acctInfo.length; ++i)
{
if (acctInfo[i].getCassetteName().trim().equals("SET"))
{
%>
<option value="<%=acctInfo[i].getBrand()%>"><%=acctInfo[i].getBrand()%>
</option>
<%
}
}
%>
3. Save the changed OrderDisplayPending.jsp file.

4. Remove the Commerce Suite InFashion stores cache so that Commerce
Suite will use the updated JSP. Go to the
<WCS-install>\instances\<instance_name>. If you have Commerce Suite
caching turned on and you have been using the store, the instance cache
directory will contain a directory with the name of the store’s numeric identity
(StoreEnt_id). For our Commerce Suite InFashion store this value was 10001.

Delete the 10001 directory to remove all cache entries. See Figure 7-6 for an
example.
Figure 7-6 Delete the InFashion stores cache
Tip: If you have any Commerce Suite transactions open in a browser, it is

advisable to restart these orders again to avoid errors. The first time you
use each page of the store it may take longer than usual to show in the
browser. This is because a new cache is being created. If you make any
mistakes in the changes to OrderDisplayPending.jsp you will need to clear
the cache each time you are ready to test the changed code.
5. Customize the Commerce Suite payment JSPs

The following two JSP files:
– PayStatusPM.jsp
– PayService.jsp
must be moved from <WCS_install_dir>\samples\web\payment\ to the same
directory as OrderDisplayPending.jsp, that is to \stores\web\<store name>\.
6. Install and configure a wallet application
For the purposes of this test the IBM Consumer Wallet (2.1.5.5) was used as
the wallet application. The installation of this software is very simple and is
considered out of the scope of this book.
In order to verify that the wallet application works correctly and to obtain
consumer certificates, follow the steps outlined in Chapter 4, “Integration with
SET” on page 109. Also test the wallet application and the SET setup using
the Payment Manager SampleCheckout tool.
Note: The IBM Consumer Wallet application requests proxy details for
Internet communication. The environment used to write this chapter
already had a SOCKS client configured and running. To avoid having to
configure the DNS settings for the IBM Demo SET environment, the IBM
Consumer Wallet was configured to use no proxy, instead using the system
default SOCKS settings for Internet communication. The system’s HOSTS
file also contained the domain and corresponding IP address given with the
IBM Demo SET registration. Without this communication between the
wallet and the back-end financial institution, the wallet application will fail
while processing the order.
7. Create an order
You are now ready to test SET wallet purchases using the Commerce Suite
V5.1 sample store. Use the sample store to create a Commerce Suite
shopping basket. The Commerce Suite InFashion sample store allows you to:
– Choose items to add to the shopping basket
– Create a name and address book entry used for shipping information
– Choose the relevant shipping options
– Proceed to check out
The sample store requires the consumer to enter credit card details,
expiration date and the credit card brand (choice from a drop-down box).
Since the store has been developed for collecting credit card values we
are forced to enter a valid credit card number and expiration date here.
However, in a wallet purchase this is not required, since the wallet is used
to pass the credit card details on to the Payment Engine.

To avoid any store development (which is outside the scope of this book),
for demonstration purposes the credit card details from the IBM DEMO
SET site will be entered in the checkout form. However, this is only to
successfully pass the credit card checking logic supplied in the sample
store. It is not relevant for the SET wallet purchase.
Tip: If you create a store that will use only SET wallet purchases, no credit
card information would be collected at any HTML-based Web pages. The
credit card information section in the InFashion store should be removed
and the logic for credit card checking be removed from the store. The
cassette for SET, Payment Manager and the back-end financial institution
would have the responsibility of checking these details.
You might also want to add logic to your store so that either SET wallet or
MIA purchases could be made from your store. This would avoid losing
any potential orders from customers without wallet software. This option is
only open to you if your back-end financial institution supports SET
Merchant Initiated Authorization as well as SET.
Figure 7-7 shows the InFashion sample store checkout and the credit card
information. Click Order Now to start the SET purchase.
Figure 7-7 Electronic checkout area provided by InFashion store
Once the SET wallet order process starts, the first thing to happen is that the
wallet will be triggered into action. When it appears sign on to the wallet
application.

Important: In the environment used to write this book the wallet did not start
automatically, or the Web browser went into a download window and waited
for a prompt to download a file of type SET Initiation called
OrderProcessb601f985.stp. If you download the file and open it this does
open the wallet application. However, you should not be required to download
the SET initiation file and it should be possible to run the file from the source.
At the time of writing we were still not able to identify the cause of this error.
The wallet application will show a window similar to Figure 7-8.
Figure 7-8 Wallet purchase review page
The purchase details list in the middle of the window shows the granularity of
the order details. In our example, details from the Commerce Suite shopping
basket are shown, enabling the consumer to verify what they are paying for.
This is shown in Example 7-6.
Example 7-6 Commerce Suite Shopping basket details in wallet application
Purchase amount : 76.25 USD
Order description:
Order #10460
SKU# Description Quantity Price/Unit Price
-------------------------------------------------------------------------------
sku-105 Cords 1 25.00 25.00
sku-194 Casual shirt 1 25.00 25.00
sku-239 Bodysuit 1 15.00 15.00
-------------------------------------------------------------------------------
Sub-Total 65.00
Tax 3.25
Shipping 8.00
Shipping Tax 0.00
---------------
Grand Total 76.25
The credit card choice section allows the purchaser to choose which credit
card to use with the merchant. However, the Cassette for SET application has
already informed the wallet software of the credit card brand to be used in the
purchase.
Click Pay. This will show a window as in Figure 7-9.
Figure 7-9 Wallet initialization request window
The consumer now has the chance to verify the merchant details as defined
with the back-end financial institution. This uses the Verify Merchant window
shown in Figure 7-10.
Figure 7-10 Verify the merchant’s registered details before you confirm the order

Click OK. This triggers the process to complete the order. With the InFashion
sample store the consumer is also given an additional information message
from the merchant’s financial institution. This must, however, be set up by the
back-end financial institution. When using the IBM DEMO SET environment
the message window appears as in Figure 7-11.
Figure 7-11 Message from merchant’s financial institution
Close the message window.

The InFashion store now uses the PayStatusPMDataBean and
PayStatusPM.jsp to show the status of the order. Since the order was
successful, the PaySuccessView has been used to show the status of the
order as in Figure 7-12.
Figure 7-12 Default consumer PaySuccessView page
The default PayStatusPM.jsp file has a Continue Shopping button that works
only if you have a Commerce Suite MallFrontView and a corresponding JSP
created. You can avoid having to do this by removing the reference to
MallFrontView and adding the code shown in Example 7-7 to the JSP file.
Example 7-7 Activating the Continue Shopping button
remove
<form action="/webapp/wcs/stores/servlet/MallFrontView">
replace with
<form action="/index_infashion.html">
In your HTTP server’s htdocs directory, add a file called index_infashion.html

and add the Java script shown in Example 7-8.
Example 7-8 JavaScript for index_infashion.html
<html>
<SCRIPT>self.location='http://' +top.location.host +
'/webapp/wcs/stores/servlet/StoreCatalogDisplay?storeId=10001&langId=-1&cat
alogId=10051';</SCRIPT>
<BODY>
</BODY>
</HTML>
Customize the storeId and catalogId values if necessary.

Clicking the Continue Shopping button should now take you back to the
InFashion store main page.
Tip: In addition to activating the Continue Shopping button in the above

example, the above JavaScript will enable you to access your store using
http://<host_name>/index_infashion.
8. Verify the SET Wallet purchase in Payment Manager.

Sign on to the WebSphere Commerce Suite Accelerator application
(http://<hostname>/Accelerator) as the wcsadmin user ID. See Figure 7-13
for an example.
Figure 7-13 Log on to the WebSphere Commerce Suite Accelerator application
When prompted, choose the store and language you ordered from.
Note: wcsadmin stills hold its Commerce Suite administrator role even
though it has been given a downgraded Payment Manager role so you will
see other stores that are available on the Commerce Suite system. If you
do choose the incorrect store, then you will not be able to perform any
Payment Manager actions using the wcsadmin user.
On the main WebSphere Commerce Suite Accelerator application menu

select Customers Orders. Then from the resulting drop-down box, choose
Orders. You will be presented with a window showing all the orders made in
that store. In our example we want to select order number 10460 as in
Figure 7-14.
Figure 7-14 Select order 10460
You will see the standard WebSphere Commerce Suite Accelerator order
view window, which contains details of the order including the SKU’s, billing
address, order status, and so on. Note that the payment status is Approved.
This means that the order has automatically been approved, but no money
has been exchanged yet. An authorization for the amount of the order has

been obtained. Click OK to return to the orders table. In the orders table, click
the box at the side of the order number (a check should appear) and the four
blue option boxes on the right hand side of the window should become
enabled.
As the merchant processing the order, you can now change the status, add
comments to the order (which can be kept for audit purposes ) or process the
payment. Since we are interested in processing the payment, choose this
option, as shown in Figure 7-15.
Figure 7-15 Select order 10460 and choose process payment option
A new window will appear with the payment details as shown in Figure 7-16.
Figure 7-16 Deposit for order 10460
This window is obtained by WebSphere Commerce Suite V5.1 directly from

Payment Manager. The contents look exactly the same as if we had used the
Payment Manager user interface tool. But the calls have been initiated by the
WebSphere Commerce Suite Accelerator application. Click the order number
in this window to see the payment order details. Note these are different from
the Commerce Suite order details since they contain only payment
information. See Figure 7-17 for an example.

Figure 7-17 Order 10460 payment detail
The window shows the payment details for the order. Note that the payment
type is defined as SET and the PAN and expiration date has been partially
hidden since we are using the Payment Manager 221 directive
“MinSensitiveAccessRole=psadmin” in the PaymentServlet.properties file.
This means that only Payment Manager administrators are allowed to see the
credit card information. The user wcsadmin who is the owner of our store is
defined as a merchant administrator so it does not therefore see the sensitive
information.
Let us now imagine a scenario where the order can only be partially fulfilled
and the merchant will need to wait a couple of weeks before the rest of the
order can be completed. The merchant can deposit an amount for the items
he is ready to ship to the consumer. To do this, click Deposit.
The Payment Manager deposit window will appear as shown in Figure 7-18.
Enter 25.00 dollars in the deposit amount box and click Deposit. This would
be an example of the merchant being able to send the consumer the casual
shirt (at 25 dollars).
Figure 7-18 Deposit partial amount
When the Deposit button in this window is clicked, the order is assigned a
batch number when passed to the back-end financial institution. This
prepares the order for settlement at a later stage. If this process is successful,
a window similar to that in Figure 7-19 will be shown with all the relevant SET
message and approval codes. Once you have reviewed the details in this
window use the Payment Manager back button (the green arrow circled in
Figure 7-18) to return to the previous page.

Figure 7-19 Successful partial deposit of the order 10460
If you decide you want to void the deposit it is possible to do this using the
Void Deposit button at the bottom of the window. This removes the deposited
amount from the payment batch set up with the financial institution. You can
then deposit a different (partial or full) amount.
Important: If you settle the partial deposited amount, you will only be able
to issue a credit for that order. You will not be able to issue the deposit for
the full amount without recreating an order on behalf of the customer.
However, the merchant does not have the user’s wallet !!!!!
If the approval amount total equals the whole amount of the order, then
multiple deposits can only be performed within the approved amount and you
are forced into reversing any previously deposited amounts and then
re-issuing the deposit.
To avoid this, it is necessary to approve partial amounts. You would do this if,
for example, you (as a merchant) did not have all the goods available for
dispatch to the customer and you needed to order the goods yourself from
your supplier, but you did have some of the order that you could dispatch
immediately. You would approve the value of the amount that you had in stock
(a partial amount) and deposit the same amount. This would then allow you to
issue another partial approval when you received the (delayed) goods from
your supplier.
For example, Figure 7-20 shows an order (number 5558), with a value of 565
German Marks (note the automatic Euro conversion for this currency).

Figure 7-20 An Order with Multiple Payments
With this order there have been four payments made:

1. Payment 1 is void. Prior to this being done the first payment had an automatic
approval for the whole amount. This was reversed to demonstrate multiple
payments.
2. Payment 2 has an approved amount of 165 and corresponding deposit for the
same amount.
3. Payment 3 has an approved amount of 100 and corresponding deposit
amount
4. Payment 4 has an approval of 265 DEM but no corresponding deposit
amount.
The following windows show the process of adding another (final) payment to
the order
For example, click Approve and specify a final amount of 35 German Marks
as shown in Figure 7-21.
Figure 7-21 Approve the final amount

This then creates a fifth payment. Payment 5 in the list shows the approved
amount and you can then deposit the final amount (including the previously
approved, undeposited amount) so in this example we deposited 300 German
Marks in the final fifth payment. See Figure 7-22.
Figure 7-22 Deposit the final amount
The details of the order now show the deposited amount equal to the value of
the order.
7.6.4 Payment Manager set up with the InFashion Sample store
When you install the Commerce Suite sample store using the InFashion store
archive, certain payment assets are automatically defined in Payment Manager.
These include which cassette the merchant owner of the InFashion store is
authorized to use, as well as corresponding accounts and brands supported by
the store.
The definition of these elements is done using a payments asset file. The
supplied sample store archive file contains a predefined payment asset file called
paymentinfo.xml. If you look in the InFashion SAR using a zip extraction utility,
you will see this XML file.
The payments asset file is used by the Commerce Suite publish process to
define
If the store will use Payment Manager
The type of cassette used by the store
An account for each currency supported by the store
A brand for each account.
Example 7-9 shows the supplied paymentinfo.xml file with the InFashion SAR
file.
Example 7-9 paymentinfo.xml supplied with Infashion_en_US_fr_FR.sar
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE paymentinfo SYSTEM "paymentinfo.dtd">

<paymentinfo>


<PaymentManager enable="yes"/>

<Cassette type="OfflineCard">

<Account currency="USD">
<Brand type="MasterCard"/>
<Brand type="VISA"/>
<Brand type="American Express"/>
</Account>
<Account currency="FRF">
<Brand type="MasterCard"/>
<Brand type="VISA"/>

<Brand type="American Express"/>
</Account>
</Cassette>
</paymentinfo>
For more information on the contents of this file, please refer to the
paymentinfo.dtd file.
8
Chapter 8. Customization using the

payment API
This chapter examines some of the options for customizing a standard
installation of WebSphere Payment Manager. It provides practical details of:
Customization of Payment Manager using:
– Branding with Java properties files
– Branding using your Payment Manager stylesheet
Customizing the CustomOffline cassette
Payment Manager users and realms
An example of merchant integration using the Cashier framework
An example of merchant integration using the Sample Checkout

8.1 Customization
You can customize the look and feel of the Payment Manager user interface to
suit yourself. This activity is called branding. Branding can be universal across all
languages, or you can choose to limit changes to a single language. Branding is
performed in two ways:
By creating Java properties files.
These allow you to modify the text for the options and actions presented in
the window. These changes are limited to the individual items referenced
from within the properties file.
By changing the Payment Manager stylesheet or creating additional
stylesheets.
The stylesheets control background color, text and table specifications, and
other window attributes. Any changes made in the stylesheets will be
reflected by all pages in Payment Manager.
Customization also includes the ability to:

– Change the masthead banner.
– Add HTML links to other pages. This technique can be used to attach
customized reports to the Payment Manager user interface.
– Change certain text within the user interface.
8.2 Branding with Java properties files

Payment Manager does not initially contain an installed PMCustomUI.properties
file. When you create a properties file, its contents override the Payment
Manager default values. There are three ways you can use properties files:
1. Create a global properties file. The contents of this file will override the
Payment Manager defaults for all languages.
2. Create a unique properties file for each of the available languages. In this
case, you can make changes for those languages that you choose, and leave
the files for the other languages blank. Note that you must create a file for
every language, even if that language is not used or if the properties for that
language are not to be modified. These properties files override the Payment
Manager defaults.
3. Create both a global properties file and a complete set of properties files for
each of the languages. In this case, the language-specific properties file takes
priority. If it is blank, the global properties file overrides the Payment Manager
defaults.
Your Java properties files may be located wherever you wish, but they must be
pointed to in the classpath that is set for the WebSphere Application Server. It is
usually created in the root directory of the Payment Manager program. These
files must be in unicode.
8.2.1 How to find the objects to be modified

When you have identified an item that you want to modify, open Payment
Manager and go to the Payment Manager window where the object is found.
Then use your browser to display the HTML source for that page by right-clicking
the frame and choosing View Source. (Note that some browsers will not display
the source with this method.)
The information you need is an identifier that is associated with the object in the
HTML. Each comment begins with PMTID, followed by the type of the object, then
the object's identifier as shown in Figure 8-1.
Figure 8-1 Example of browser source code showing PMTID comment fields
Chapter 8. Customization using the payment API 213

In the following example, the object is a field with the identifier:
admin.PSUserInfoSearch.us.userNamer
Note: There are no spaces and the parts of the identifier are separated by
periods. The comment field should appear in the source code like this:

8.2.2 Creating your properties files

Using an editor, place one line in your properties file for each object to be
changed. Each object can be in a different Payment Manager Web page. The line
begins with the object identifier, followed by an equal sign (=) and then the new
value to be applied to that object. Here are some examples of actual lines in a
properties file. The last word before the equal sign is always an option or action
and is always in capital letters.
If a PMCustomUI.properties file was created using the above information, it

would look like this:
#***********************************************************************
#* This is a new properties file created for the purpose
#* of showing how a properties file works.
#***********************************************************************
admin.HEADER=<h2>This is the new header of the admin component</h2>
admin.PSUserInfoSearch.search.ACTION=Start Search
admin.PSUserInfoSearch.roles.role.psadmin.OPTION=<b>The Big Boss</b>
We saved this file in the <drive>\Program Files\IBM\ Payment Manager directory.

If the page was viewed before the PMCustomUI.properties file was invoked, the
page looked like Figure 8-2.
Figure 8-2 Display before PMCustomUI.properties file invoked
After the PMCustomUI.properties file was invoked, it looked like Figure 8-3.

Figure 8-3 Display after PMCustomUI.properties file invoked
Before the PMCustomUI.properties file takes effect, the WebSphere Application

Server must be stopped and restarted. This is done using the WWebSphere
Administrative Console as shown in Figure 8-4.
Figure 8-4 The WebSphere Administrative Console
Highlight the Payment Manager application and click the Stop button to stop it.
After it shows the application has stopped, click the Start button to restart it.
Once this operation completes, the PMCustomUI.properties file will take effect
the next time you refresh the Payment Manager windows(s).
The highest level of object is the component and changes all windows within the
component. There are three components in Payment Manager: admin, payment,
and reports. Therefore, there is no single line that can be written in a properties
file to make a change throughout all of Payment Manager. You must write at least
one line per component. The list of items that can be changed for a component
are:
Name Appears in the title bar of the browser
Header Appears at the top of every window in the component; often contains
an image
Trailer Appears at the bottom of every window in the component; may
include an image or text
An example of changing all headers within a component is:

admin.HEADER=<h2>This is the new header of the admin component</h2>

The next level of object is the window. The list of items that can be changed for a
window are:
Name Appears at the top of the window under the component's header
Header Appears under the window's name; only displayed on windows that
have a default header
Trailer Appears at the bottom, just above the component's trailer; only
displayed on windows that have a default trailer
emptylist Appears when a Payment Manager query is made with no results
found from the search
An example of changing the name of a window is:

payment.screen1.NAME=new_name
The next level of object is the fieldgroup and the list of items that can be changed
for a fieldgroup are:
Name Appears centered on the banner above the fieldgroup name
Header Appears left-aligned above the fields of a fieldgroup
Trailer Appears left-aligned below the fields of a fieldgroup
An example of changing the trailer for all the fields that use trailers in a particular
fieldgroup is:
payment.screen1.fieldgroup3.TRAILER=new_trailer
The lowest object level is the field. The list of items that can be changed for a
field are:
Name Appears to the left of the field in a colored box
Shorthelp Appears to the right of the field to provide help information
for the field content
Defaultvalue Appears in the text box as the default text
Preferredwidth Width of the field defined as whole number of pixels or
percent
Preferredheight Height of the field defined as whole number of pixels or
percent
Maximumlength Sets maximum number of characters for the field
An example of changing the column width of a field called somename to 15% of

screen width is:
payment.screen1.fieldgroup3.somename.COLUMNWIDTH=15%
Without the percent sign, the column width would be set to 15 pixels.
To change the text associated with an action, such as a push button, use the
following as an example:
payment.screen.ACTION=Next
In this example, the text on the button will be changed to "Next". You can do the
same with radio buttons.
8.2.3 Naming your properties files

If you create a global properties file, it must be named PMCustomUI.properties.
Properties files for specific languages must be named
PMCustomUI_xx.properties, where the xx represents the language.
Remember that in order to make changes for individual languages, you must
create a complete set of files for all the languages. To make changes to the
French version only of your Payment Manager, you must put your changes in the
PMCustomUI_fr.properties and leave the files for the other languages blank.
Your Java properties files may be located wherever you wish, but they must be
pointed to in the classpath that is set through WebSphere Application Server.
These files must be in unicode.
The current list of languages and their assigned character values is included
below.
Language Language Code
Brazilian Portuguese pt
Dutch nl
English en
French fr
German de
Japanese ja
Korean ko
Simplified Chinese zh
Spanish es
Traditional Chinese zh_TW

8.2.4 Replacing images
To replace the header image for all windows of a component, determine the
component name by looking at the HTML source for one of the windows that you
want to change, and in your properties file include the following:
<component_name>.HEADER=<image>
<image> is replaced by the HTML reference to an image, like this:

<IMG SRC="/images/newimage.gif" width="584" height="75" BORDER="0" ALT="New
Image's ALT text">
To replace a header image for a single window do this:

<component_name>.<screen_name>.HEADER=<image>
Note: If a single quote is needed within double quotes, you must use two single
quotes.
8.2.5 Branding using your Payment Manager stylesheet

The stylesheet defines the background color, text specifications (size, font, color,
underlining, boldness), table specifications (borders, colors, text) and other
attributes of the Payment Manager user interface. Payment Manager defaults to
a single, cascading stylesheet for the entire user interface, which means all
windows will be affected by the stylesheet in use.
The default stylesheet is located at

<webserverdirectory>/PaymentManager/style.css. The full directory in the
writer’s computer is translated as:
<drive>\Program Files\IBM HTTP Server\htdocs\PaymentManager\style.css
Rather than edit this file, you should copy it, make your changes to the copy, and
then point to the copy in your properties file. This protects you from overwriting
your changes when you apply service.
To use a particular stylesheet, use the identifier stylesheet in your properties file,
followed by the location and name of the new stylesheet. For example, if your
new stylesheet is located at
<webserverdirectory>/myStyleSheets/newStyleSheet.css, then the line in your
properties file would be:
styleSheet=/myStyleSheets/newStyleSheet.css
Note: If you upgrade or reinstall Payment Manager, it's a good idea to have your
branding properties files and stylesheets backed up.
8.3 Customizing the CustomOffline cassette
If you are the provider of a hosted Payment Manager, you will probably want to
customize the Payment Manager user interface to ensure that all of your
merchants have a fixed set of payment method names from which to select
during account creation. This provides consistency across all merchants. If you
are running a Payment Manager as a single merchant, then you need not worry
about performing this step.
After you decided which methods to use for manually collecting payments, you
can update the Payment Manager user interface to seamlessly support your
chosen methods. After the user interface is updated, the payment methods are
selectable when an account is being created for the CustomOffline cassette.
To update the user interface with your payment method names, update the
PMCustomUI.properties file. PMCustomUI.properties is the properties file that
must be modified to do branding (customization) of the Payment Manager user
interface. This file is not provided during the Payment Manager installation, so
you will need to create it if you have not already done so. See 8.2.2, “Creating
your properties files” on page 214 for more information. Any changes that you
make to PMCustomUI.properties will appear in all languages supported by the
user interface.
If you wish to provide language-specific changes, you will need to create (or edit
your existing) PMCustomUI_xx.properties files, where xx represents a supported
language. See 8.2.3, “Naming your properties files” on page 219 for the list of
supported options. For example, if you want “Cash On Delivery" to appear when
the user interface is viewed in English, edit PMCustomUI_en.properties.
For each payment method that you want to support, you make an entry in the
properties file. The entry will specify the text to display in the user interface and
the value that will be passed for the "$METHOD" parameter of the
CreateAccount API call. The format of these entries is as follows:
CustomOffline.CustomOfflineAccount.CustomOfflineAccountDetails.Method.
index=apiValue:displayValue
where:
apiValue is the value used on the CreateAccount API call. This value must
correspond to the $METHOD value used for AcceptPayment commands for
this payment method. The apiValue must not contain any colons.
displayValue is the value displayed in the user interface.
index is a unique index of the method name used to order the method names
in the user interface. The index value for your first payment method should be
1 and other entries should be numbered consecutively.

Note: Entries are case-sensitive and the apiValue and displayValue must be
separated by a colon. For example:
CustomOffline.CustomOfflineAccount.CustomOfflineAccountDetails.Method.1=COD:Cas
h On Delivery
CustomOffline.CustomOfflineAccount.CustomOfflineAccountDetails.Method.2=BillMe:
Bill me later
After you have made your changes to the properties files, you must restart
Payment Manager using the WebSphere Administrative Console (as shown in
Figure 8-4) for the changes to take effect.
8.4 Payment Manager users and realms

Every Payment Manager command must identify the user that is issuing the
command. Payment Manager will ensure that the user’s credentials are valid,
usually by checking a password, and that the user has permission to perform the
command. To support these security checks, Payment Manager needs access to
a list of users and it needs to know how it can authenticate any given user. This
mechanism is known as a realm.
A realm is a registry of users along with a single method of authenticating those

users (for example, a user’s name and password). Although Payment Manager
provides a simple realm that allows you to administer a list of users and their
passwords, it is possible for you to write a Payment Manager realm that
integrates with your existing systems. See “Writing a new Payment Manager
realm” on page 226.
Examples of realm types include LDAP realms and operating system realms. A
user must be defined in a realm before being granted access to resources in that
realm. Therefore, a user is a valid Payment Manager user if, and only if, he is
both:
In the realm
Assigned a role in the Payment Manager
Payment Manager employs a role-based access control scheme that defines four
Payment Manager roles:
1. Payment Manager administrator (see Figure 8-2 on page 215)
2. Merchant administrator
3. Supervisor
4. Clerk
The Payment Manager administrator can use the Payment Manager user
interface window to assign access (based on a role) to a user defined in a realm.
Though other realms can be created, the following are provided with the Payment
Manager:
PSDefaultRealm:
This is a simple realm implementation provided by the Payment Manager that
uses a flat file to hold a list of realm users and their corresponding passwords.
Use this realm when you are using Payment Manager with Version 3.x of
WebSphere Application Server.
PSWAS2Realm:
This is the default realm of WebSphere Application Server, Version 2.0.x.
Users are added and deleted from the PSWAS2Realm through the
WebSphere Application Server administration client. Use this realm when you
are using Payment Manager with Version 2.0.x of WebSphere Application
Server. Apart from this mention, this realm will not be discussed in this
redbook.
As previously noted, these are not the only mechanisms for authenticating and
authorizing users. Other applications that use the Payment Manager may
override our realm implementation and use their own support.
8.4.1 PSDefaultRealm
For users with an installation of WebSphere Application Server, Version 3.x,
Payment Manager provides realm support in the form of the PSDefaultRealm.
The PSDefaultRealm is a simple realm implementation that uses flat files to hold
a list of realm users and their corresponding passwords. Each entry in this file is
Base64 encoded to provide a basic level of security.
Adding and deleting users in the PSDefaultRealm

You can add or delete users in the PSDefaultRealm using the Payment Manager
realm utility that manages the Base64 encoded realm flat file. The Payment
Manager realm utility can be invoked from the PaymentManager root directory
entering either:
PSDefaultRealm.cmd file (on Windows NT)
PSDefaultRealm file (on Solaris and AIX)
To add a user to the PSDefaultRealm:

1. Go to the PaymentManager root directory.
2. Enter the following:
PSDefaultRealm <<RealmFile>> add <<userName>> <<password>>

where:
<<RealmFile>> Is the absolute path of the realm flat file.
<<userName>> Is the name of the user you are adding to the
PSDefaultRealm.
<<password>> Is the password of the user you are adding to the
PSDefaultRealm.
To delete a user from the PSDefaultRealm:

1. Go to the Payment Manager root directory.
PSDefaultRealm <<RealmFile>> remove <<userName>>
where:
<<RealmFile>> Is the absolute path of the realm flat file.
<<userName>> Is the name of the user you are deleting from the
PSDefaultRealm.
Changing user passwords in the PSDefaultRealm

To change a user password in the PSDefaultRealm, you must delete the user
and then add the same user with a new password. See “Adding and deleting
users in the PSDefaultRealm” on page 223.
Viewing users in the PSDefaultRealm

In addition to adding and deleting users in the PSDefaultRealm, you may also
need to view users who are defined in the realm. To view a list of users defined
for the PSDefaultRealm:
1. Go to the Payment Manager root directory.
PSDefaultRealm <<RealmFile>> list
where:
<<RealmFile>> is the absolute path of the realm flat file.
The list command will display the users defined in the PSDefaultRealm.
Creating new realm files

The Payment Manager default realm file is PSRealm. To use a realm file other
than the default, you must:
Create a new realm using the PSDefaultRealm utility.
Change the RealmFile setting in PaymentServlet.properties to reflect the new
realm.
You must ensure that the user admin (or any other user currently defined to the
Payment Manager with Payment Manager administrator authority) is defined in
the new RealmFile prior to changing the RealmFile setting in
PaymentServlet.properties. You can then use this user ID to log on to Payment
Manager and assign user roles to other users in the new realm.
Note: To invoke the newly created realm, you need to switch from the realm
currently employed by the Payment Manager to the new realm. For information
on switching realms, see “Switching from one Payment Manager realm to
another” on page 225.
Protecting PSRealm files

After the Payment Manager installation, you should protect the PSRealm files as
follows:
On Solaris and AIX, you can use the UNIX permission bits.
On Windows NT, you need to keep the machine and the file system secured
in order to protect this file.
Switching from one Payment Manager realm to another

Because each Payment Manager installation can use only one realm at a time, it
is useful to understand how to switch between realms. The
PaymentServlet.properties file contains settings used by the Payment Servlet.
These settings include the specification of which realm should be used together
with any settings required by the realm itself.
To specify which realm should be used:

Change the RealmClass setting in the PaymentServlet.properties file to
reflect the realm you want to deploy.
After changing the RealmClass setting in the PaymentServlet.properties file, you

must add the realm-specific properties for the realm you just specified. The
PSDefaultRealm requires an additional RealmFile property to be present in the
PaymentServlet.properties file. This property value should be the absolute path
name of the Base64 encoded flat file. The following is an example of the
PaymentServlet.properties setting needed to configure the PSDefaultRealm:
RealmClass=com.ibm.etill.framework.payserverapi.PSDefaultRealm
RealmFile=<drive>/myPSRealm
Note: The slashes in the previous example must be forward slashes, rather than
back slashes, even on the Windows NT operating system.

Restarting your Web server and WebSphere Application Server
After updating the RealmFile setting and the realm-specific properties (above) in
the PaymentServlet.properties file, you must restart your Web server and
WebSphere Application Server for these changes to take effect. For instructions
on stopping and starting your Web server and WebSphere Application Server,
see Chapter 8, “Starting the Payment Manager” in the Payment Manager Install
Guide.
Plug-in realm support

The Payment Manager also provides a Java-based interface that allows
merchant software to supply the set of users that are allowed to access the
Payment Manager. This feature allows a single set of users to be shared
between the merchant software and the Payment Manager. For example, the
IBM WebSphere Commerce Suite V5.1 provides a realm that makes the users in
the Commerce Suite user registry available to the Payment Manager, eliminating
the need for each merchant to maintain Commerce Suite as well as Payment
Manager user IDs.
8.4.2 Single sign-on

Using the plug-in realm feature, it is possible to code your user interface to link
directly to the Payment Manager user interface without having to log in again
when you connect to Payment Manager.
Payment Manager is not a stand-alone application and will always work in

conjunction with other merchant software. If this software provides a user
interface, it is often desirable to provide links to the Payment Manager user
interface in order to perform payment operations such as making credits against
an existing order, closing batches, or viewing the status of existing payments.
Under normal operation, a user would log in to the merchant software and then,
when the user clicks a link to get to the Payment Manager user interface, he or
she would need to log in a second time to access Payment Manager.
If the merchant software and the Payment Manager both share the same realm,
this double login problem can be removed by coding the merchant software links
to pass authentication information through the Payment Manager user interface
and into the realm code. Single sign-on is often an important reason for wanting
to write a Payment Manager plug-in realm.
Writing a new Payment Manager realm

This section details the process for writing a new Payment Manager realm. In
preparing to write your new realm, you will need to:
Make decisions about the design of your realm
Implement a PaymentServletRealm subclass
Use the trace facility to enable easy problem determination
Implement single sign-on between another user interface and the Payment
Manager user interface (that is, provide links between your Web pages and
the Payment Manager Web pages using the single sign-on function)
Test the realm
Design points
To write a realm for Payment Manager you must provide a new class that
extends the com.ibm.etill.framework.payserverapi.PSDefaultRealm class. You
can find it in the eTillClasses.zip file in the Payment Manager root directory. You
should consider the following design points when writing your new Payment
Manager realm.
Realm name
One of the functions your new realm class will provide is getRealmName().
Payment Manager administrators can determine which realm is currently in use
by looking at the Realm field of the Payment Manager settings window in the user
interface. This realm name is determined by querying the realm using the
getRealmName() method. The result is passed to the user interface via the
QueryPaymentServer API response. You should provide a getRealmName()
method in your realm class that returns a string that can be used by the Payment
Manager administrator to understand which realm is in use and, therefore, how
he can manage that particular realm.
Realm properties
Your new realm may require specific configuration values. You will determine
what these new configuration values are and create new property keywords for
them. Your documentation should instruct your users to place these properties in
the PaymentServlet.properties file. For example, you may need a new property
for the host name of the system where your user registry is held. At startup time,
Payment Manager will read PaymentServlet.properties, instantiate your realm,
and pass all the realm configuration values in PaymentServlet.properties to your
realm’s init() method.
Authentication mechanism
The Payment Manager API uses HTTP post requests to transfer information. The
HTTP request will be made available to your realm’s getAuthenticatedUser()
method so that you can find the authentication information from the request and
determine whether the user issuing the API command is an authenticated
member of the realm or not. You must decide how your realm is going to get this
authentication information. There are three possible mechanisms for
authentication that your realm may use:

1. Basic authentication
2. Payment Manager Authentication Object (that is, PMAUTHOBJECT)
3. Custom authentication
If your realm requires only basic authentication (that is, user ID and password),
then Payment Manager supports this via the HTTP authorization header.
PaymentServletRealm contains a convenience method,
getFromHTTPAuthorizationString(), that can be used to read the user ID and
password from this HTTP header.
If user ID and password are not sufficient, you can use Payment Manager’s
PMAUTHOBJECT keyword to pass arbitrary authentication information to the
realm. Again, PaymentServletRealm provides a convenience method,
getPMAuthenticationString(), to allow your realm to retrieve this object from the
HTTP request.
Lastly, it is important to note that Payment Manager does not provide any
restriction on the mechanism a realm uses to authenticate any HTTP request, so
you can decide to implement any authentication method you like.
User interface single sign-on

As previously noted, if your merchant software and the Payment Manager both
share the same realm, the double login problem can be removed by coding the
merchant software links to pass authentication information through the Payment
Manager user interface and into the realm code.
There are two ways that merchant software links can be coded to achieve single
sign-on:
1. By passing the user ID and password on the link
2. By passing a PMAUTHOBJECT string containing authentication information
Note that passing the user ID and password can often be seen as a security risk,
particularly if this information is not protected by SSL. You should choose
whether you want to achieve single sign-on and, if so, which method you want to
support.
Realm scalability
The Payment Manager user interface will scale to support very large user
registries, providing that the realm is also capable of scaling. When Payment
Manager receives a QueryUsers command, the realm’s getUserNames() method
is called to get the users from the registry. If an inexperienced user queries
Payment Manager for all users in a very large realm, it is possible that:
The query may take a very long time
The Payment Manager JVM may run out of memory while processing the
command. There are two methods that realms can make use of to control
queries for very large numbers of users:
a. The first method is for the realm to limit the number of users it returns to
Payment Manager. A UserList object is provided that is basically a Vector
of user names along with a count of the total number of users that
matched the query. You should decide whether or not you want to limit the
number of users returned in response to a call to the getUserNames()
method.
b. The second method is to make use of the userFilter passed via the
QueryUsers API to the realm’s getUserNames() method. The user filter
should be used to search for a subset of users in the realm. However, its
exact meaning is determined by the realm. The realms provided with
Payment Manager all use this filter as a case-insensitive substring (that is,
getUserNames() will return only user names that contain the filter string).
The filter is made available on the Payment Manager user interface on the
User Search window. You should decide whether you want to follow
Payment Manager’s convention of using this filter as a substring to search
for, or to define this filter in another way.
Realm case-sensitivity
By default all Payment Manager realms are case-sensitive (that is, the user ID
admin is different from the user ID Admin. If you want to provide a
case-insensitive realm, you should override PaymentServletRealm’s
isCaseSensitive() method and return false.
Realm implementation
To write a realm, you must create a subclass of PaymentServletRealm. You can
find the Javadoc for the PaymentServletRealm class and the other classes it
uses in the docs/realmapi directory where Payment Manager is installed. The
subclass you create must provide implementations for the following methods:
getRealmName()
init()
getAuthenticatedUser()
isUserInRealm()
getUserNames()

String getRealmName()
You should override this method to return a String that identifies the realm to the
Payment Manager administrator. This string is returned on the
QueryPaymentServer API response and displayed both in the Payment Manager
settings window and in the Payment Manager trace files to identify a traced string
originating from the realm.
void init(Properties properties) throws RealmException

This method is called when the PaymentServlet is first started. Payment
Manager passes a Properties object that contains all the realm settings from the
PaymentServlet.properties file. You should use these settings to initialize your
realm. If settings are missing or invalid, you can choose either to use default
settings or to go through a RealmException.
If you throw a RealmException, the API response will contain a primary return
code of 1062 and a secondary return code of 1068, indicating to the calling
program that the realm could not be initialized. You should ensure that you use
the trace facility so that the exact problem can be diagnosed and corrected.
String getAuthenticatedUser(HttpServletRequest request) throws

RealmException
For each API command received, Payment Manager will call the realm’s
getAuthenticatedUser() method to check that the user is a member of the realm
and has provided valid authentication information. You can make use of the
PaymentServletRealm’s getFromHTTPAuthorizationString() and
getPMAuthenticationString() convenience methods to pull authentication
information from the HTTP request. This method must first determine the user’s
identity, and second determine whether the user is authenticated. If
authenticated, the method should return the user name; otherwise, it should
return null.
program that a realm error occurred. You should ensure that you use the trace
facility so that the exact problem can be diagnosed and corrected.
boolean isUserInRealm(String userName, String userFilter) throws

RealmException
This method is used by Payment Manager when a user uses the QueryUsers
API. The user filter must be null if there is no filtering. If this field is not null, you
should implement your filtered search mechanism in this method.
Payment Manager ensures that each user it returns on the QueryUsers response
is a valid member of the realm. To do this, it uses the realm’s isUserInRealm()
method. You should return true if the user is a valid member of the realm and any
optional following criteria is met. Otherwise, return false.
If you throwa RealmException, the API response will contain a primary return
UserList getUserNames(String userFilter) throws RealmException

In response to a QueryUsers API call, Payment Manager can also invoke the
realm’s getUserNames() method to get a list of users in the realm that match the
userFilter argument. You should implement your filtered search mechanism in
this method.
Tracing
You can enable realm tracing by adding the following line to the
PaymentServlet.properties file and restarting your Web server and WebSphere
Application Server:
RealmTraceFlag=1
For information on restarting your Web server and WebSphere Application

Server, see “Maintaining Payment Manager Security” in the IBM WebSphere
Payment Manager for Multiplatforms Administrator’s Guide Version 2.2.
Note: You can disable tracing again by removing this line or by setting the value
to ’0’ (zero) and restarting your Web server and WebSphere Application Server.
Trace output is sent to the PSTraceX.log files, which can be formatted with the
provided FormatServletTrace command file. The realm trace output lines can be
identified in the formatted log file by the prefix REALM.
The realm class can trace any information it chooses by using the following code
segment:
if (isTracing()) trace("Hello World!");
For performance reasons, it is good practice to include the test for isTracing(),
since this will avoid making the Java runtime code evaluate the argument of the
trace() method when tracing is disabled.

Linking directly into the user interface
In your Web pages you can provide links that bypass the login window and link
directly into the user interface. During installation, a sample HTML file called
SampleSingleSignon.html was installed in the samples directory where Payment
Manager is installed. Using various methods of authentication, this sample
shows you how to provide a link or button into one of Payment Manager’s
windows.
Authentication by the user interface

Authentication by the user interface can be performed in two ways. The two
types of field data used for authentication are:
f_userid=<userid> and f_password=<password>
f_pmauthobject=<bytearray of authentication data>
The field data information that you provide to the user interface is passed to the
PaymentServlet on all Payment Manager commands performed by the user
interface. The realm gets the authentication information from the HTTP request it
receives from the PaymentServlet.
The user interface servlet performs Payment Manager user interface functions
only for authenticated users with proper authorization. To determine whether or
not a user is authenticated, the user interface servlet needs authentication data.
There are multiple sources where the user interface can find authentication data.
Below is a list of sources and the order in which the user interface servlet
accesses them once an HTTP POST is received from a user:
Note: The user interface servlet uses the first authentication data found.
1. If the user has previously logged in during this session, the authentication
data saved when the user logged in originally is used on Payment Manager
commands sent to the PaymentServlet.
2. If a Payment Manager Authentication Object is passed in the FORM data
(using the f_pmauthobject keyword), the authentication data is used on
Payment Manager commands sent to the PaymentServlet.
3. If a username/password is passed in the FORM data, (f_userid and
f_password fields), the authentication data is used on Payment Manager
commands sent to the PaymentServlet.
4. If a username/password is passed in through the Authorization header of the
HTTP POST to the user interface servlet, the authentication data is used on
Payment Manager commands sent to the PaymentServlet.
Once authentication data is found using the precedence order above, it is

supplied on any commands sent to the PaymentServlet for the requested user
interface function.
When an authentication failure occurs while linking directly to one of Payment
Manager’s user interface Web pages, the sign-on Web page appears and
displays a login prompt. An authentication failure occurs if the PMAUTHOBJECT
value is considered not valid according to the realm.
Testing
To test your realm, you will need to:
Compile the realm
Switch Payment Manager to use the realm
Use the Payment Manager user interface and other programs to test the
realm
The Payment Manager realm support classes are contained in eTillClasses.zip.

When compiling the realm, you should remember to include this file and your
realm class in your classpath.
Note that information on switching to use the new realm you created can be
found in “How to deploy the new realm” on page 235.
SampleRealm
A sample realm class is provided with Payment Manager with its corresponding
Java source file, SampleRealm.java, in the samples subdirectory. This realm
uses a database table called USERTABLE to hold a list of users along with their
passwords. Since this is only a sample realm, all information is held unencrypted
in the database. The first time SampleRealm is used, it will automatically create
USERTABLE with three users (admin, fred and bob - all with the same
passwords as user names).
To switch to using SampleRealm, edit PaymentServlet.properties and change

the RealmClass setting to SampleRealm; this is the fully qualified class name.
Also add the following properties to PaymentServlet.properties:
SampleRealmJDBCURL=<<the URL of the database that contains the USERTABLE>> --
for example, jdbc:db2:sampledb
SampleRealmDBDriver=<<the JDBC driver name>> -- for example,
COM.ibm.db2.jdbc.app.DB2Driver
SampleRealmDBUserid=<<the userid that can be used to read USERTABLE>>
SampleRealmDBPassword=<<the password for SampleRealmDBUserid>>
RealmTraceFlag=1
When you restart your Web server and WebSphere Application Server, this class
will be enabled.

Note: The SampleRealm supports authentication via both the user ID/password
combination and the PMAUTHOBJECT. Examples of how you can enable
merchant software to implement single sign-on can be found in an HTML file
called SampleSingleSignon.html (an outline of how it looks is shown in
Example 8-1), which can be found in the samples directory where you installed
Payment Manager. To use SampleSingleSignon.html, you should copy this file to
your Web server’s publish directory and point a Web browser at
http://<<hostname>>/SampleSingleSignon.html.
Example 8-1 Samplerealm support
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 3.0//EN">

<HTML>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1">
<HEAD>

<STYLE TYPE="text/css">

</STYLE>
<TITLE>Sample web page linking into Payment Manager's Approve web
page</TITLE>
</HEAD>
<BODY>
<H1>Sample web page linking into Payment Manager UI</H1>
<P>This page shows several examples of how one can link directly to one of
Payment Manager's web pages without going through the logon page. View the
source to see how it is done.</P>
<P><STRONG>Note:</STRONG> You must copy this HTML file to your web server's
publish directory and point your browser at
http://<hostname>/SampleSingleSignon.html
to test these links.</P>
<HR>
<H2>Example #1</H2>
<p>A text link to the Approve screen using userid/password authentication.
Notice that the userid and password show up as part of the URL.</P>
<P><A
href="/webapp/PaymentManager/PaymentServerUI/Approve?f_userid=admin&f_password=
admin">Click here</A></P>
<HR>
<H2>Example #2</H2>
<P>A FORM (using POST) to go to the Approve screen using userid/password
authentication.
Click the image below to go to the Approve screen:</P>
<FORM METHOD="POST" ACTION="/webapp/PaymentManager/PaymentServerUI/Approve">

<INPUT TYPE="hidden" NAME="f_userid" VALUE="admin">
<INPUT TYPE="hidden" NAME="f_password" VALUE="admin">
<INPUT TYPE="image" NAME="approve_screen" src="/PaymentManager/images/ibm.gif">
</FORM>
<HR>
<H2>Example #3</H2>
<p>A FORM (using POST) to go to the Approve screen using PMAUTHOBJECT
authentication.
This example only works when the Payment Manager is setup to run under the
SampleRealm
with a properly setup configuration as described in SampleRealm.java.</P>
<FORM METHOD="POST" ACTION="/webapp/PaymentManager/PaymentServerUI/Approve">

<INPUT TYPE="hidden" NAME="f_pmauthobject" VALUE="1/admin">
<INPUT TYPE="image" NAME="approve_screen" src="/PaymentManager/images/ibm.gif">
</FORM>
</BODY>
</HTML>
How to deploy the new realm

Installing the new realm is the responsibility of the realm writer. This section
describes the steps necessary to deploy your new Payment Manager realm.

The PaymentServlet.properties file contains settings used by the Payment
Servlet. These settings include the specification of which realm should be used
together with any settings required by the realm itself.
To specify which realm should be used, change the RealmClass setting in the
PaymentServlet.properties file to reflect the realm you want to deploy. After
changing the RealmClass setting in the PaymentServlet.properties file, you will
also need to add the realm-specific properties for the realm you just specified.
The following is an example of the PaymentServlet.properties setting needed to
configure the PSDefaultRealm:
RealmClass=com.ibm.etill.framework.payserverapi.PSDefaultRealm
RealmFile=<drive>/myPSRealm
Ensure that the realm class is in the WebSphere Application Server classpath.
When the PaymentServlet is next initialized, your realm class will be loaded and
start being used. If you package your realm into a file called PMRealm.jar, then it
will not be necessary to change the Payment Manager classpath, because this
file name is already included in the classpath.
After updating the RealmClass setting and the realm-specific properties in the
PaymentServlet.properties file, you must restart your Web server and
WebSphere Application Server for these changes to take effect. For information
on restarting your Web server and WebSphere Application Server, see
“Maintaining Payment Manager Security” in IBM WebSphere Payment Manager
for Multiplatforms Administrator’s Guide Version 2.2.
8.5 Merchant integration using the cashier framework

This is an exercise for anybody interested in creating a Web application in
Windows that represents a very basic merchant store. It was created by Angelo
Scaccabarozzi, an IBMer in Italy. We include this sample code as a zip file
PMCAL.zip with the redbook additional material as described in Appendix A,
“Additional material” on page 317. After you create the store, you can then
complete a simple purchase and select a purchase mechanism (Visa or
MasterCard) and complete the buy. On the Buy command, the Web application
will retrieve order information from the database and build a parameter table,
which it will send as the arguments of the CollectPayment() method to the
Payment Manager. Payment Manager (using the Offline cassette) will
auto-approve the order and deposit the funds. The Web application (store) will
request the status of the purchase and post the appropriate HTML page to the
user to indicate the completion of the purchase.
8.5.1 Exercise software components
During this exercise, you will install from a download zip file the software
components needed to build the Web application. This consists of a set of files
representing a set of HTML pages, some GIF files, two servlets and a file needed
to populate a new database table in the Payment database. The functions of the
main components are described below:
MIACashier1.html
This page creates a simple merchant order page requesting an order number
from the user,. This page calls the first servlet in the Web application
(MIACashier1).
MIACashier1 servlet
This servlet builds the Buy Page and then collects the user input (Order
Number), and passes this as an argument to the second servlet (MIACashier)
in the Web application.
MIACashier servlet
This servlet retrieves the order information from a DB2 table (PM_STORE),
including 100 records about fictitious orders, inserts a record into another
table (PM_ORDSTAT) where the order status is tracked, and calls the
CollectPayment() method to the Cashier using the following parameters for an
automatic approval. The PM_ORDSTAT table columns are:
MERCHANTNBR Merchant number
ORDERNBR Order number
APPROVEAMOUNT The amount approved
DEPOSITAMOUNT The amount deposited
STATUS P - pending (initial status)
A - Approved
D - Deposited
F - Payment declined (Negative Authorization reply)
V - Void (successful AuthRev)
CHECKED 0 initial status, 1 the order status has been updated by
EventDemo1 servlet
The record will be inserted with STATUS = P and CHECKED = 0.
The servlet then issues the CollectPayment() method call to Payment
Manager, passing over to it the required purchase parameters. It then
requests a response to the purchase using the CheckPayment() method.

8.5.2 What you need to proceed with the exercise
The following conditions should have been set up before you can begin this
exercise:
1. A LOGON ID = payman and PASSWORD = pmadmin should have been
created for the server hosting Payment Manager 2.2. You are advised to use
this ID and password for all installed software components, but it is not
compulsory. The default LOGON ID = admin and PASSWORD = admin can
also be used.
2. DB2 UDB should have been installed and a payments database called pmdb2
should have been created. If you use another database name, you will have to
make the appropriate changes where noted in the text.
3. IBM HTTP Server 1.3.12, WebSphere Application Server, Advanced Edition
V3.5 and the JDK supplied with this version of Payment Manager should have
been installed and configured. If you are not sure, you can find out the version
of the JDK in Figure 9-1 on page 280.
4. A merchant store must be created with store number 123456789, using
procedures as defined in the previous exercise. You will also need to have
created a test account using the OfflineCard cassette and a Brand (use
ROBO) to be used with this account.
8.5.3 Install exercise software

Use the following procedure to install the test software needed for this exercise:
1. Download the file PMCAL.zip using the FTP facility outlined in this redbook.
2. Expand the zip file into the root of the hard drive you choose to use. It will
create a subdirectory called PM2.2CAL and unzip the files into this directory.
Create sample DB2 tables

A payment database (pmdb2) should have been created as part of a prerequisite
procedure for installing Payment Manager. If you have not called the database by
this name you will have to locate your Payment Manager database. This
database can be located using the DB2 Control Center application shown in
Figure 8-5.
As you can see in this figure, we used a database called Payman. If you have a
different database name, you will have to substitute this name wherever you see
<db-name>. This database will now have a new table created and this table will be
populated with a number of dummy orders and items. Use the DB2 Control
Center to check that you don’t already have a table called dati.db2 that you will
overwrite.
Figure 8-5 DB2 Control Center application
To create the DB2 table:

1. Open a DB2 command window. Click Start -> Programs -> DB2 for
Windows NT -> Command Window.
2. Change to the exercise database directory. Enter:
cd <drive>:\PM2.2CAL\Database
3. Connect to the payment database.Enter:
db2 connect to <db-name>
where <db-name> is the name of your Payment Manager database.
4. Create the table with the command:
db2 -tvf dati.db2
Create new folders in the WebSphere directory

You will now need to create a special set of directories under the WebSphere
subdirectories in which to place your Web application files.
1. Navigate to the following directory:
<drive>\WebSphere\AppServer\hosts\default_host
2. Under default_host, create a new folder called Merchant (the name of our
Web application).
3. Under Merchant, create two further subdirectories: servlets and web. See
Figure 8-6.

Figure 8-6 Display showing new directories created
4. Navigate back to the <drive>\PM2.2CAL\html subdirectory. Select all the files

in this folder and use the right mouse button to drag and copy them into the
new folder called web under the new Merchant directory (see Figure 8-7).
.
Figure 8-7 Display showing files copied
Copy the servlet Java class files

We will now need to copy both MIACashier.class and MIACashier1.class files
into the new servlets folder. Use the following procedure to do this:
1. Navigate back to the <drive>\PM2.2CAL\servlets subdirectory.
2. Select both the MIACashier.class and MIACashier1.class files in this folder
and use the right mouse button to drag and copy them into the new folder
called servlets under the new Merchant directory.
Create a Web application

You will now need to create your sample store Web application using the servlets
and HTML files we have just installed in the Web application’s web and servlets
folder. Use the following procedure to do this:
Note: The information entered is case sensitive.

1. Open the WebSphere Administrative Console.
Click Start -> Programs -> IBM -> WebSphere -> Application Server 3.5 ->
Administration Console.

2. Expand the WebSphere Administrative Domain by clicking the + sign next to
the green light.
3. Expand the Server Node by clicking on the + sign on the left side of the icon
with the name of your host server. Under the Server Node you will find at least
two application servers (see Figure 8-8):
– Default Server is the application server where we will add our Web
application
– WebSphere Payment Manager
Figure 8-8 Display showing the WebSphere Administrative Domain
4. Expand the Default Server. The Default Server contains the Default Servlet
Engine.
5. Expand the Default Servlet Engine. The servlet engine includes some Web
applications (default_app, admin and examples). We are going to add our
Web application under the servlet engine of the Default Server.
6. To add the Web application we will use the Task Wizard.
Choose the console menu Tasks -> Create a Web Application.
7. Enter Merchant in the Web Application Name text field.
8. Check Serve Servlets By Classname as shown in Figure 8-9.
9. Click Next.
Figure 8-9 Display showing Create Web Application entries
10.In the resultant window, expand Nodes (there is only one node).
11.Expand the Server Node (your host name).
12.Expand the Default Server Application Server.
13.Select Default Servlet Engine and click Next (see Figure 8-10).
Figure 8-10 Display showing the Nodes structure
14.in the Web Application Web Path text field, Enter /Merchant (see
Figure 8-11).

Figure 8-11 Display showing Web application name and path
15.Click Next.
16.Verify that the document root is
<drive>\WebSphere\AppServer\hosts\default_host\Merchant\web (see
Figure 8-12).
Figure 8-12 Display showing new Merchant Web application structure
17.Enter
<drive>\WebSphere\AppServer\hosts\default_host\Merchant\servlets
as the first line of ClassPath.
18.Add another ClassPath line <drive>\Program Files\IBM\PaymentManager\ to
the Merchant Web Application definition (see Figure 8-13).
19.Add another ClassPath line <drive>\PROGRA~2\IBM\PAYMEN~1\ to the
Merchant Web Application definition (see Figure 8-13).
20.Click Finish.
21.Expand Default Server then Default Servlet Engine. You will find your
Merchant Web application that you have just created (see Figure 8-12).

Figure 8-13 Display showing root and classpaths
22.Copy the SnoopServlet.class file to the merchant\servlets folder:

– Open an Explorer window by clicking Start -> Programs -> Windows NT
Explorer.
– Navigate to the directory:
WebSphere\AppServer\hosts\default_hosts\default_app\servlets.
– Copy the file SnoopServlet.class into the directory servlets under the
merchant directory (see Figure 8-14).
Figure 8-14 Display showing SnoopServlet.class in the default_app\servlets directory
Testing the Merchant Web application
To test that the Web application is working, we will create a test servlet within the
application and check that we can execute this from a browser window. Use the
following procedure to do this:
1. Use the WebSphere Administrative Console.
2. Define a servlet under the Merchant Web application. Right-click the mouse
button on the Web Application Merchant, and select Create -> Servlet (see
Figure 8-15).
Figure 8-15 Display showing menu selections for creating a servlet
3. In the Create Servlet window, enter SnoopServlet as the Servlet Name and
Servlet Class Name. Click OK.
4. Restart the Merchant Web application. Right-click Merchant and select
Restart Web App (see Figure 8-16).

Figure 8-16 Display showing menu selections for restarting Web application
5. Open a Web browser.

6. Go to the page http://<yourhostname>/Merchant/. It will appear as the
Home page of a test merchant Buy page (see Figure 8-17 left side).
7. Go to http://<yourhostname>/Merchant/servlet/SnoopServlet. The
SnoopServlet will be launched. You should see an information window giving
details of the Merchant Web application (see Figure 8-17 right side).
Figure 8-17 Display showing Merchant and SnoopServlet
Add servlets to the Merchant Web application

We must now start to build the content of our Merchant Web application by
adding the required servlets and any parameters that they may require when
they are launched. The various HTML pages that they call during their execution
have already been added to the appropriate web folder in the WebSphere root
directory. Use the following procedure to do this:
Add the MIACashier1 servlet

1. MIA stands for Merchant Initiated Authorization. To add the servlet use the
topology pane of the WebSphere Administrative Console.
2. Define a servlet from the context menu by right-clicking the Merchant Web
application and choosing Create ->Servlet (see Figure 8-15).
3. In the Create Servlet window enter MIACashier1 as the servlet name and
servlet class.
4. Click OK.
Add the MIACashier servlet

1. Select Create -> Servlet (see Figure 8-15).
2. In the Create Servlet window, enter MIACashier as the servlet name and
servlet class.
3. Select the Advanced tab in the Create Servlet window and add the following
values for Init Parm Name and Init Parm Value (see Figure 8-18):

Note: Replace payman, pmadmin, and pmdb2 with the actual data of your
configuration.
– user = payman
This is the administration user name that your Payment Manager database
was created under.
– puser = pmadmin
This is the password for the administration user that your Payment
Manager database was created under.
– jdbcurl = jdbc:db2:pmdb2
This is the name of your Payment Manager database.
– success = http://<your host server name>/Merchant/success.html
– failure = http://<your host server name>/Merchant/failure.html
4. Click OK.
5. Stop and start the Default Server.
Figure 8-18 Display of some of the MIACashier properties
Editing the cashier profile

The Cashier class relies on a profile file to determine from which source the
parameters can be retrieved. The MIACashier servlet is using the profile file
name test.profile in the subdirectory profile of the PM2.2CAL directory. Edit this
file and make the following changes:
1. Replace the host name in the PaymentManagerConfiguration with your
server host name. The PaymentManagerConfiguration should look like the
following:
<PaymentManagerConfiguration
hostname="m238p4yh.itso.ral.ibm.com"
port="80"
userid="admin"
password="admin"
useSSL="false"
/>
2. Replace the parameter SET in the PAYMENTTYPE line in the CollectPayment
section with OfflineCard.
<Parameter
name="PAYMENTTYPE"><CharacterText>SET</CharacterText></Parameter>
becomes
<Parameter
name="PAYMENTTYPE"><CharacterText>OfflineCard</CharacterText></Parameter>
3. While you are making these changes, examine the profile file to understand
the different parameters that are contained within it.
4. Save the file and exit.
Buying with the cashier servlet

Use the following procedures to test the sample Web application that you have
just built:
1. Restart either the Merchant Web application (see Figure 8-16) or the Default
Server application server.
2. Go to the following URL:
http://< host server name>/Merchant/MIACashier1.html
This page represents an example of data coming from a merchant application
and then passing it to the Payment Manager.
3. Enter an Order Number between 1 and 100 (see Figure 8-19 on the left side).

Figure 8-19 MIACashier1.html display and MIACashier.html display
4. When you see the Buy page (see Figure 8-19 on the right side) select a
payment option and click Buy. This display collects the data for the Payment
Manager and represents internal workings of the Payment Manager. The
display will finish each time after the buy operation with a browser window
saying: Order Complete. If it displays the message Order Incomplete, you
have not entered the correct configuration data to operate, and you will need
to re-check your settings.
5. Repeat this procedure to create more orders.
Checkout the orders using PM 2.2 user interface

When you have created some orders, log on to the Payment Manager user
interface as the merchant administrator for your test merchant, and check that
the orders have been placed into the payments database.
Auto-Approve Turned Off

Since the Approve Flag was set to 1 in the file test.profile you will not find any
orders to approve but will find that all orders will have been deposited. Modify
test.profile to Approve Flag = 0 (zero). Re-run the MIACashier1.html program
and its processes, and check the new orders that have been created. You will
now see these new orders are pending approval.
8.6 Merchant integration using Sample Checkout
This is a sample application that allows you to create Payment Manager orders
using any cassette. Source code is included to demonstrate techniques for
integrating storefront software with the Payment Manager in
cassette-independent fashion using the cashier module that is included with
Payment Manager.
8.6.1 Exercise software components

You will need to run Sample Checkout, which simulates a merchant’s Internet
storefront, and thus facilitate order creation (see Figure 8-20). You also need to
have a Payment Manager user status of Merchant Administrator to perform this
exercise.
To access the Payment Manager Sample Checkout and create orders:

1. Go to the Payment Manager directory called
paymentmanager/samples/samplecheckout and edit the configuration file
called SampleCheckout.xml. Make sure the following line is present under the
<PaymentOptionList>:
<PaymentOption id="Offline" profile="SampleCheckoutOfflineCard"
default="1">{OFFLINECARD}</PaymentOption>
2. Go to http://<<hostname>>/SampleCheckout, where <<hostname>> is the
machine where the Payment Manager is installed.
Note: You must have a fully qualified host name for this to work.
3. At the Sample Checkout window that appears, you will be prompted to enter
the following:
Merchant number Any number to represent a merchant number
Order number Any number to represent an order number
Amount Any number to represent the total numeric amount of
the order
Currency Choose US Dollar
Payment method Choose OfflineCard
Credit card number Enter 4111111111111111
Expiry date Highlight the expiration month and year for your
TestBrand credit card (choose any future month and
year combination)
Brand Choose ROBO
4. Click Buy.

Figure 8-20 Display of Sample Checkout with input variables
Repeat these steps two more times so that you have three orders for which to
process payments.
8.6.2 Approving orders

Once you have created three orders using the Sample Checkout, return to the
browser window where the Payment Manager user interface is displayed. Go
once again to the Payment Manager URL (that is,
http://<<hostname>>/PaymentManager/) and log on as a Merchant Administrator
user to approve an order. Follow these steps to approve the order:
1. In the navigation pane, click Approve under the Payment Processing section
(see Figure 8-21).
Figure 8-21 Display showing Payment Manager Payment Processing menu
2. From the Approve window (see Figure 8-22), check the box next to the order
you want to approve (select only one order for this exercise) and click
Approve Selected.
Figure 8-22 Display showing Payment Manager Approve window
3. At the Approve Results window, you will see the status of your approve
request. When processing is complete, success or failure status will appear
next to each order submitted for approval. When your approval is complete,
click Return to go back to the Approve window.

You will see that two orders are still awaiting your approval. You could have
approved them all at once (for their full amount) by clicking Approve All from the
Approve window. But to better demonstrate the many facets of the Approve
function, we will work with each order individually.
Approving orders from the order window

In this section, you will approve an order from the Order window (rather than from
the Approve window), but you will approve only part of the total order amount.
You may find it useful to approve only part of an order when some of the goods
associated with the order are not available for delivery at order processing (for
example, merchandise that is on back order).
1. From the Approve window (see Figure 8-22), click the Order number for one
of the remaining orders awaiting approval.
2. From the Order window you can view order details. Click Approve to approve
this order.
3. You will see the Order Approve window (Figure 8-23).
Figure 8-23 Display showing Approve window
The following information displays:
Currency The type of currency used to place this order. This is a
read-only field.
Order Amount The total amount of the order expressed in the
currency used to place the order. This is a read-only
field.
Approved Amount This field displays zeros since no amount of the order
has yet been approved. This is a read-only field.
Deposited Amount This field displays zeros since no amount has yet been
approved or deposited. This is a read-only field.
Approval Amount This is the total amount of the order.
Authorization Code The authorization code returned from the manual
off-line authorization request process. The payment
state is changed to “Approved”.
Decline Reason The decline reason returned from the manual offline
authorization process. The payment state is changed
to “Declined”.
Change the approval amount to 3.00 and click Approve to approve this order for
three dollars.
When approval processing has completed, you will be returned to the Order
window and notified of approval success or failure (see Figure 8-24). You will
notice in the order details that the approved amount has been updated to reflect
the three dollars we specified in the previous step.

Figure 8-24 Display showing part of Order window after approval
Using the Sale function to approve orders

Because you approved only part of the last order you worked with, you still have
two order entries in the Approve window. In this exercise, you will use the sale
function to approve the remaining orders.
The sale function allows you to approve an order and move it directly into
Deposited state, bypassing the Approved state. The sale function automatically
performs an Approve and a Deposit on your order payment (thus, you can think
of the sale function as Approve with auto-deposit). Use the sale function when
you want to expedite the delivery of goods to the buyer and guarantee your
capture of funds (for example, when you are selling downloadable software or
electronic information). However, with the sale function, you lose the ability to set
the authorization or decline reason on the approval. Because the sale function
provides you with the mechanism to merge Approve and Deposit into one
transaction, the sale function is also useful when you are charged on a
per-transaction basis.
Perform a sale as follows:

4. In the navigation pane, click Approve under the Payment Processing section
(see Figure 8-21 on page 255).
5. Click Sale All from the Approve window (see Figure 8-22 on page 255).
6. At the Approve Results window, you will see a progress bar indicating the
status of your sale request. When processing is complete, a Success or
Failure status will appear next to each order submitted for sale (see
Figure 8-25).
Figure 8-25 Display showing Approve Results from a ‘Sale All’ operation
7. When your sale is complete, click Return to the Approve screen.
8.6.3 Depositing payments

The deposit function allows you to deposit order payments. As demonstrated in
“Approving orders from the order window” on page 256, a single order number
can have multiple payments associated with it. You may see the same order
number appear multiple times in the same list, each time with different payment
information. To deposit a payment:
1. In the navigation pane (see Figure 8-21 on page 255), click Deposit under
the Payment Processing section. You will see Figure 8-26.

Figure 8-26 Display showing deposit window
2. Check the box next to one of the payments listed and click Deposit Selected.
3. When processing is complete, a Success or Failure status will appear in the
Deposit Results window next to the payment submitted for deposit (see
Figure 8-27).
Figure 8-27 Display showing deposit results
4. When your sale is complete, click Return to the Deposit screen.
Note: You can deposit only part of a payment, in much the same way you
approved part of an order:
a. From the Deposit window, click the Payment number for one of the
payments awaiting deposit.
b. The next window is the Payment window. From the Payment window, you
can view payment details. Click Deposit to deposit this payment.
a. On the Order Payment window (see Figure 8-28), change the deposit
amount to 2.00.
a. Click Deposit to deposit this payment for two dollars.
Figure 8-28 Display showing Deposit window
Settling batches
A batch is a collection of payments and credits that are processed as a unit by a
financial institution. A batch is associated with a merchant and an account.
Individual fund transfers are not performed for each individual payment, but
rather a group of transfers is processed so that both the merchant and the
financial institution can agree on the funds that are to be transferred. Before a
batch is closed (that is, the funds are exchanged) there is usually some type of
reconciliation process so that both sides agree on the amounts. The payments
that you deposited in the previous exercise will now appear in a batch. You must
settle this batch in order to initiate processing by the financial institution. To settle
a batch:

1. In the navigation pane (see Figure 8-21 on page 255), click Batch Search
under the Payment Processing section.
2. At the Batch Search window (see Figure 8-29), you will be prompted to enter
the following information (for the purposes of this tutorial, you will not be
entering any parameter information in the fields to narrow your search):
Merchant Name of the merchant whose batch you are searching
for.
Note: If there are less than 500 merchants in the
Payment Manager database, you select the merchant
name from the drop-down list. If there are more than
500 merchants in the Payment Manager database, you
enter the name of a merchant.
Batch Number The number that uniquely identifies the batch within
the merchant. Assigned when the payment is
deposited.
State The state of the batch:
Open
Closed
Balance Status The balance status of this batch:
Balanced: the batch has been successfully balanced
(that is, all totals agree).
Out of balance: an unsuccessful attempt has been
made to balance this batch (that is, all totals do not
agree).
Payment Type Identifies the payment type, or protocol, used to place
the order (for example, CustomOffline).
Batch Open Date Use the after and before fields to search for batches
opened during the specified range in time:
After: Specify a date to search for all batches opened
on and after this date (format is MM/DD/YY).
Before: Specify a date to search for all batches
opened on and before this date (format MM/DD/YY).
Batch Closed Date Use the before and after fields to search for batches
closed during the specified range in time:
After: Specify a date to search for all batches closed
on and after this date (format MM/DD/YY).
Before: Specify a date to search for all batches closed
on and before this date (format MM/DD/YY).
3. Click Search to initiate a batch search (see Figure 8-29).
Figure 8-29 Display showing Batch Search window
Note: In addition to using the after and before fields to specify a time range
for the batch search (such as 08/01/99 to 08/15/99), these fields can also be
used to narrow search results by excluding certain batches from the search.
For example, you could search on all batches opened before 08/01/99 and all
batches opened after 08/15/99, thus excluding batches opened between
08/02/99 and 08/14/99.
4. Click the batch number to view information about the batch (see Figure 8-30).

Figure 8-30 Display showing Batch Search Results
5. From the Batch window (see Figure 8-31), you can view useful batch
information, including the total number and amount of both payments and
credits in the batch. Click Batch Details to see a detailed listing of all
payments and credits in this batch.
Figure 8-31 Display showing batch summary
6. Click Settle to settle the batch, a Batch Settlement window will appear (see
Figure 8-32).

Figure 8-32 Display showing Batch Settlement window
7. Input a Financial Institution Batch Identifier (any alphanumeric identifier) and

click Settle.
8. When processing is complete, a Success or Failure status will appear in the
Settle Results window (see Figure 8-33).
Figure 8-33 Display showing Batch Settle Results window
9. When the success message displays, the settle command is complete. The
financial institution is now responsible for the transfer of funds.
Note: You also have the option to delete the settled batch by clicking Delete on
the Settle Results window. When a batch is deleted, all ancillary information
about that batch (that is, payments, credits, and cassette-specific data) is
deleted, as well. If you need to retain all payment data (for example, for audit
purposes), then you should not delete a batch. But if you need to prune outdated
information, you can exercise the Delete Batch option.
In Figure 8-31 you will see the Purge button. This button removes all associated
payments and credits from a Batch object, treating it as if it has just been
created.
Issuing a credit
Credits are issued against orders and can be given for any amount. To issue a
credit, you need to find the order against which you are issuing the credit:
1. In the navigation pane, click Order Search under the Payment Processing
section (see Figure 8-21 on page 255).

2. On the Order Search window (see Figure 8-29), you will be prompted to enter
the following information (for the purposes of this tutorial, you will not be
entering any parameter information in the fields to narrow your search):
Merchant Name of the merchant whose order you are searching
for.
Note: If there are less than 500 merchants in the
Payment Manager database, select the merchant
name from the drop-down list. If there are more than
500 merchants in the Payment Manager database,
enter the name of a merchant.
Order Number A number assigned by the merchant that uniquely
identifies the order.
State The state of the order:
Requested
Ordered
Refundable
Canceled
Closed
Payment Type Identifies the payment type, or protocol, used to place
the order (for example, CustomOffline).
Order Date Use the after and before fields to search for orders
opened during the specified range in time:
After: Specify a date to search for all orders opened on
and after this date (format MM/DD/YY).
Before: Specify a date to search for all orders opened
on and before this date (format MM/DD/YY).
Order Amount Currency: The currency used to place this order.
Select the currency type from the drop-down list.
Greater than: Specify a value to retrieve all orders with
order amounts that are greater than or equal to the
value you specify.
Less than: Specify a value to retrieve all orders with
order amounts that are less than or equal to the value
you specify.
3. Click Search to initiate an order search.
Note: In addition to using the after and before fields to specify a time range for
the order search (such as 08/01/99 to 08/15/99). These fields can also be
used to narrow search results by excluding certain orders from the search.
For example, you could search on all orders opened before 08/01/99 and all
orders opened after 08/15/99, thus excluding orders opened between
08/02/99 and 08/14/99.
4. From the order list, click an order number for an order in Refundable state to
view the details of that order.
5. From the Order window (see Figure 8-24 on page 258), click Credit to create
a credit against this order.
6. At the Create Credit window, the following information displays:
Currency The type of currency used to place this order. This is a
read-only field.
Order Amount The total amount of the order expressed in the
currency used to place the order. This is a read-only
field.
Approved Amount The total amount of the order that has been approved
expressed in the currency used to place the order.
This is a read-only field.
Deposited Amount The total amount of the order that has been deposited
expressed in the currency used to place the order.
This is a read-only field.
Credit Amount This field must be completed by the merchant
administrator with the total amount to be credited to
the shopper.
Authorization Reason The authorization code returned from the manual
off-line authorization request process. The credit state
is changed to “Refunded”.
Decline Reason The decline reason returned from the manual off-line
authorization process. The credit state is changed to
“Declined”.
7. Enter the credit amount (can be any amount) and click Credit.
When credit processing has completed, you will be returned to the Order
window (see Figure 8-29 on page 263), and notified of credit success or
failure. You will notice on the Order window that the newly created credit
appears under Credits at the bottom of the window (see Figure 8-34).

Figure 8-34 Display showing Credit Result window
Viewing batch totals

The last exercise in this tutorial is viewing daily batch totals. The Payment
Manager Reports function allows you to view daily totals for batches in a closed
state. To generate a daily batch totals report:
1. In the navigation pane, click Reports in the Payment Processing section.
2. In the Reports window, click Daily Batch Totals.
3. At the Batch Totals Report window, you will be prompted to enter the date for
which you would like a batch totals report (format MM/DD/YY). Payment
Manager computes the batch totals for the date entered and generates a
report. Leave this field blank to generate a report for the current date.
4. You will also be prompted to enter the Merchant name. If you do not enter a
merchant name, a list of all of the batches for the specified date will display. If
there are more than 500 batches, the first 500 batches will display and you
will be prompted to narrow your search by selecting a specific merchant.
5. Click Search to initiate a batch report search.
The Daily Batch Totals report computes the totals for all batches that were closed
on the date specified in the Search window (see Figure 8-35). Since you did not
specify a search date, the report that was generated contains the current day’s
batch totals. These totals are computed on a per-currency basis, so there is one
line per currency. Note that these totals cover all payments and credits made for
all payment types (not just those made through the CustomOffline cassette).
Figure 8-35 Display showing Daily Batch Totals Report window
You have just completed a day in the life of a Payment Manager administrator
and a Merchant administrator. While individual business models may vary, this
tutorial outlines the basic path to establishing a working Payment Manager and
demonstrates fundamental payment processing implemented through the
Payment Manager. For more information on specific fields in the Payment
Manager user interface, see the online help.

9
Chapter 9. Cassette development

This chapter discusses the following:
How to create a Payment Manager cassette
The IBM WebSphere Payment Manager for Multiplatforms Cassette Kit
Programmer’s Guide Version 2.2
Overview and installation of the KitCash cassette

9.1 Why develop a Payment Manager cassette?
Payment cassettes process electronic payments using a specific payment
protocol under control of the Payment Manager. Since the Payment Manager
presents a single, well-defined payment processing application programming
interface (API), adding new cassettes allows existing Payment Manager
applications, such as WebSphere Commerce Suite, to process payments
through new payment protocols with little or no integration effort.
However, be very careful. If you don’t spend the time and effort to fully develop a
cassette to cater for all of Payment Manager’s functions, you are asking for
trouble. Software engineers call this exporting the cost to the customer. In this
case, the merchant will need to justify the effort to do the research, design, and
development necessary to customize their installation to utilize your cassette.
If your financial system is attractive enough and valuable enough, merchants

may find the effort justified. Otherwise, they will choose a competitor’s cassette
that requires less effort to integrate.
If you do take a shortcut approach and your cassette is outrageously successful,

it is very likely that merchants will have questions and problems with their
integration. This could well overload your customer support system.
9.2 How to create a Payment Manager cassette

The best way to create a cassette is to start with the LdbCard, which is used as a
skeleton for writing future cassettes for WebSphere Payment Manager.
The following details are extracts from the Cassette Developer Cookbook. The
cookbook and related code are available for download through the Cassette
Developers Toolkit link at:
http://ibm.com/software/webservers/commerce/payment/download.html
You will have to sign up for the cassette development program and you will need
the download key available from your local IBM account manager.
After you download the Cookbook.exe, run the file to install it. By default it asks if
you want to extract it to the D:\ drive. You can change this to the root directory of
any drive on your computer and it will create a !pmcassette file to extract into, but
it will mean additional changes to your Payment Manager cassette files.
However, these changes are simple and they are documented in this redbook.
The cookbook is an excellent document and easy to follow. However, with the
release of Payment Manager 2.2, some of the details have been changed. We
have reproduced the first part of the cookbook as a prelude to data shown later in
this redbook.
9.2.1 Choose a cassette name

Although simple, this stage has wide-ranging effects.
The merchant software passes the cassette name as a parameter in at least
25 places. In each of places there is a parameter named PaymentType or a
parameter named CassetteName whose value is a character string that
contains the name of your cassette. The Payment Manager framework will
use this string to find your cassette class when routing API requests.
The framework uses the name to construct the fully qualified name of your
cassette class when the class is dynamically loaded during the initialization.
The framework uses the name to construct the fully qualified name of your
cassette query class when the class is dynamically loaded during
initialization.
The framework uses the name to find the properties file used to construct
your cassette ResourceBundle.
The framework uses the name to find the file containing the XML document
used to display and modify cassette dependent information in the user
interface windows. This document contains Payment Server Presentation
Language (PSPL) tags that are interpreted by the Payment Manager user
interface.
The cassette uses the name to specify the resource bundle to be used when
logging messages from the resource bundle or when retrieving data from the
resource bundle.
The cassette uses the name to identify the source of trace messages.
Important: It is important to remember that DB2 identifiers (table names, view

names, column names, and so on) are limited to 18 characters. If you choose a
cassette name that is longer than 8 characters, you will need to manually
abbreviate some of the table names that are automatically generated for you by
the cassette exercise.
This naming convention is based on Java rules to avoid name conflicts. These
rules avoid naming conflicts by utilizing the Internet domain name assigned to
your company. The Java system is case sensitive and, by convention, package
names are always lowercase and class names are mixed case with the first
character capitalized.
Chapter 9. Cassette development 275

When applying the cassette naming conventions, there are two cases:
1. The cassette is developed by IBM
2. The cassette is not developed by IBM
Cassette developed by IBM

Assume that IBM is developing a cassette for a payment protocol called FastPay.
Then:
Your company name is IBM.
Your cassette name is FastPay (mixed case). Merchants will use this
case-sensitive value to select your cassette.
Your cassette’s .jar file will be named FastPayCassette.jar.
Your Java package name is com.ibm.etill.fastpaycassette (lowercase).
Your development directory structure will be
D:\!PMCassette\com\ibm\etill\fastpaycassette where D:\!PMCassette is, by
convention, the root directory.
The name of your properties file is FastPay.properties (mixed case).
The name of your file containing the XML document used to display and
modify cassette dependent information on the user interface windows is
FastPay.en.pspl (for an English version).
The name of your cassette class is FastPayCassette (mixed case) or, as a
fully qualified name, com.ibm.etill.fastpaycassette.FastPayCassette.
The name of your cassette query class is FastPayCassetteQuery (mixed
case) or, as a fully qualified name,
com.ibm.etill.fastpaycassette.FastPayCassetteQuery.
Cassette developed by a third party

Using company called QSI Payments Inc. and a Web site of
www.qsipayments.com as an example, the following rules mean a cassette for
the QSI payment protocol would be called QSIPay. Use these rules to implement
the naming conventions for your own cassette. For example:
The abbreviated company name is QSI.
Cassette name is QSIPay (mixed case). Merchants will use this
case-sensitive value to select your cassette.
Cassette’s .jar file will be named QSIPayCassette.jar.
Java package name is com.qsi.ibmetill.qsipaycassette (lowercase). Your
development directory structure will be
D:\!PMCassette\com\qsi\ibmetill\qsipaycassette where D:\!PMCassette is, by
convention the root directory.
The properties file is QSIPay.properties (mixed case).
The name of the file containing the XML document used to display and modify
cassette-dependent information on the user interface windows is
QSIPay.en.pspl (for an English version).
The name of the cassette class is QSIPayCassette (mixed case) or, as a fully
qualified name, com.qsi.ibmetill.qsipaycassette.QSIPayCassette.
The name of the cassette query class is QSIPayCassetteQuery (mixed case)
or, as a fully qualified name,
com.qsi.ibmetill.qsipaycassette.QSIPayCassetteQuery.
9.2.2 Obtain and install materials

The next step is to obtain and install the following materials:
Java Development Kit
By definition, a cassette for the IBM WebSphere Payment Manager is
developed in Java. Even if you use a different language for developing the
payment protocols used by your cassette, the cassette itself must be written
in Java in order to plug into the Payment Manager framework. The
instructions in the cookbook assumed that you were using Version JDK 1.1.8.
However, if you want to be really certain you are using the correct version of
the JDK, use the version of the JDK that comes with your copy of Payment
Manager (see Figure 9-1 on page 280). At the time we wrote this redbook the
version was Java 1.2.2.
WebSphere Payment Manager
In order to develop and test a cassette, you will need to obtain and install the
WebSphere Payment Manager. It provides both the class files for your
development plus the framework necessary to exercise your cassette. It also
contains:
– IBM DB2 Universal Database
– IBM HTTP Server
– WebSphere Application Server
WebSphere Payment Manager Service Pack - available from:
http://ibm.com/software/webservers/paymgr/support/sbull.html.
Updates to the Payment Manager and its new features are posted here
regularly. Please check regularly for the latest product versions. It is very
important to use the latest version of the Payment Manager software while
developing your cassette.

A professional programmer’s editor
Your productivity can be substantially enhanced with a good Java
development environment. The cookbook uses Visual SlickEdit, but this is for
example purposes only and is not required.
Payment Manager Cassette Developers Toolkit
Although the cookbook contains the information needed by most cassette
developers, the WebSphere Payment Manager Cassette Developers Toolkit is
still a vital resource. It contains more detailed information about the Payment
Manager framework, Javadoc for the Payment Manager framework classes,
and a sample cassette that is different from the LdbCard sample included in
the cookbook. Whenever your cassette has requirements contrary to the
simple assumptions used to develop the cookbook, the Cassette Developers
Toolkit will provide information you need.
It is available from:
The PayGen Test Command Generator is a very powerful test tool. Using your
favorite text editor, you can build test scripts that contain any of the
WebSphere Payment Manager application program interface (API)
commands and verify the data values returned. The cookbook toolkit contains
sample test scripts that can easily be modified to test your cassette.
Although the WebSphere Payment Manager user interface can be used to
send commands to your cassette during development, there are a number of
things it will not do. For example, it will not omit required parameters and
verify that the correct return codes are returned. It will not run automatically
nor guarantee that a test scenario is repeated exactly the same way every
time.
PayGen is available from:
http://www.ibm.com/software/webservers/commerce/payment/download.htm
l
For convenience, you may want to make a hardcopy of the file
PayGen\Readme.txt. This file contains all the PayGen documentation.
9.2.3 Design your cassette

The next thing to do is to design your cassette. This section of the cookbook
describes the framework responsibilities, the objects you will be creating, and the
tasks included in subsequent chapters of this cookbook. The full details are
covered well in the cookbook so we don’t detail them in this redbook.
9.2.4 Prepare the base files
This section describes the steps required to prepare the base files for your new
cassette. It assumes that you have installed Payment Manager and that it is
working. Furthermore, the cookbook assumes that you have installed the
cookbook materials on your D: drive in a directory named D:\!PMCassette. This
is not essential, but if you wish to install the base files elsewhere you must make
some configuration changes.
The only purpose of the exclamation point in the directory name is to cause the
directory name to float to the top of an alphabetical directory list.
Throughout the following steps, windows from Visual SlickEdit show how each
step is carried out. However, you do not have to use this editor program to write
you own cassette. The Visual SlickEdit windows will help you no matter what
editor program you use, since the principles are exactly the same. You are
basically using the Search and Replace function for the editor you have chosen
to use to update the raw LdbCard files with your own data.
1. Use your favorite text editor and edit D:\!PMCassette\CreateCassette.cmd.
Note that near the beginning of this script, the working directory is set to
D:\!PMCassette.
D:
CD D:\!PMCassette
SET OLDDIR=com\ibm\etill\ldbcardcassette
SET NEWDIR=com\ibm\etill\ldbtestcassette
SET NEWCASSETTE=LdbTest
We did not have a D drive, so cookbook files were put into C:\!PMCassette
directory.
2. Change com.ibm.etill.ldbcardcassette to your package name.
3. Change NEWCASSETTE to your cassette name.
Using the name convention outlined in “Cassette developed by a third party”
on page 276, we changed the CreateCassette.cmd file to:
C:
CD C:\!PMCassette
SET OLDDIR=com\ibm\etill\ldbcardcassette
SET NEWDIR=com\qsi\ibmetill\qsipaycassette
SET NEWCASSETTE=QSIPay
4. Save the updated CreateCassette.cmd.
5. Execute the updated the CreateCassette.cmd, which will create the raw base
files for your new cassette and copy them into your new cassette directory. If
all goes well, the result should look like Figure 9-1.

Figure 9-1 Display showing successful completion of CreateCassette.cmd
6. If you are using Visual SlickEdit, this is a good time to create a project file for
your cassette. The Compile, Build, Rebuild, Make JAR, and Install tools in the
Build menu list will operate on your base cassette files. These tools all
assume that the editor’s current directory is the directory that contains your
base files. The instructions are for Visual SlickEdit Version 5.
a. From the Visual SlickEdit menu bar, select Project -> Open Workspace.
b. In the open Workspace window, navigate to D:\!PMCassette and select
!PMCassette.vpw. Click Open.
c. From the Visual SlickEdit menu bar, select Project -> Workspace
Properties.
d. In the Workspace Properties window, click Add.
e. In the Add files to Workspace window, navigate to D:\!PMCassette, select
the file with the file name that matches your cassette name and the file
type of .vpj, and click Open.
f. Back in the Workspace Properties window, select the project file you have
just added and click Set Active, then close the Workspace Properties
window.
g. From the Visual SlickEdit menu bar, select Project -> Project Properties.
h. In the Project Properties window, select the Open Command tab. You will
see Figure 9-2.
Figure 9-2 Display of Open Command window
i. On the line that begins set target, replace the LdbCard file name prefix
with the name of your cassette.
j. On the line that begins set jdkdir, check and adjust the directory path to
your JDK if necessary.
k. On the line that begins set workdir, change the
com\ibm\etill\ldbcardcassette directory with the directory name that
contains your new base files. Click OK to save the changes and close the
window.
Note: The remaining steps are required to assure that the changes made on
the Open Command tab take effect.
l. From the Visual SlickEdit menu bar, select Project -> Close Workspace.
m. From the Visual SlickEdit menu bar, select Project -> Open Workspace.
In the Open Workspace window, navigate to D:\!PMCassette and select
!PMCassette.vpw and click Open.

Figure 9-3 Changing to the cassette files
7. Change to the directory that holds all your cassette files (see Figure 9-3).
Change all occurrences of LdbCard (be sure to use this exact case) to the
name of your cassette (be sure to specify the exact case of your cassette
name) in every base file. Remember, your cassette name was determined in
the “Cassette developed by IBM” on page 276 or the “Cassette developed by
a third party” on page 276.
One way to do this is to open all your cassette files in your cassette directory
with an editing tool that allows you to do a Replace All operation in all open
files.
If you are using Visual SlickEdit, you can use these steps:
a. If necessary, navigate to the directory that contains your cassette files and
make it the current directory (see Figure 9-3) by double clicking it and then
clicking OK.
b. From the menu bar, select Search -> Replace.
c. In the Replace window, click Files -> Buffers >> to get the expanded
Replace window
d. In the expanded Replace window, enter LdbCard in the Search for: text
box, enter your cassette name in the Replace with: text box, select the
Match case option, enter *.* in the Files: text box, and click Replace All
(see Figure 9-4).
Figure 9-4 Display showing replacing cassette name (mixed case)
8. Using your favorite editing tool, change all occurrences of LDBCARD (be sure
to use this exact case) to the name of your cassette name in uppercase (be
sure to specify the exact case) in every base file. Remember, your cassette
name was determined in the , “Cassette developed by IBM” on page 276 or
the Section , “Cassette developed by a third party” on page 276.
files.
On the other hand if you are using Visual SlickEdit, you can use these steps:
make it the current directory (see Figure 9-3).
Replace window
d. In the expanded Replace window, enter LDBCARD in the Search for: text
box, enter your cassette name in uppercase in the Replace with: text box,
select the Match case option, enter *.* in the Files: text box, and click
Replace All (see Figure 9-5).

Figure 9-5 Display showing replacing cassette name (uppercase)
9. Using your favorite editing tool, change all occurrences of the Payment
Manager database name PSADMIN (be sure to use this exact case) with the
database name for your Payment Manager installation (be sure to specify the
exact case) in every base file.
files.
Replace window.
d. In the expanded Replace window, enter PSADMIN in the Search for: text
box, enter your Payment Manager database name in the Replace with:
text box, select the Match case option, enter *.* in the Files: text box, and
click Replace All (see Figure 9-6).
Figure 9-6 Display showing replacing database name
10.Using your favorite editing tool, change all occurrences of the directory name
com\ibm\etill\ldbcardcassette (be sure to use this exact case) with the name
of the directory for your cassette (be sure to specify the exact case) in every
base file. Remember, your directory name was determined in the “Cassette
developed by IBM” on page 276 or the “Cassette developed by a third party”
on page 276.
files.
c. In the Replace window, click Files -> Buffers to get the expanded
Replace window.
d. In the expanded Replace window, enter com\ibm\etill\ldbcardcassette
in the Search for: text box, enter your directory name in the Replace with:

Figure 9-7 Display showing replacing directory name
11.Using your favorite editing tool, change all occurrences of the package name
com.ibm.etill.ldbcardcassette (be sure to use this exact case) with the
package name for your cassette (be sure to specify the exact case) in every
base file. Remember, your package name was determined in“Cassette
developed by IBM” on page 276 or in“Cassette developed by a third party” on
page 276.
files.
Replace window.
d. In the expanded Replace window, enter com.ibm.etill.ldbcardcassette
in the Search for: text box, enter your package name in the Replace with:
Figure 9-8 Display showing replacing package name
12.If you are using the default drive of D: for your !pmcassette directory then skip
this step. If you are using some other drive, then you will have to make these
changes.
Using your favorite editing tool, change all occurrences of the drive name D:
with the drive name for your cassette. You only need to change
YourCassetteName#Build.cmd and YourCassetteName#Install.cmd files. All
other command files will remain unchanged.
Replace window.

Figure 9-9 Display showing changing the drive name on writer’s computer
d. In the expanded Replace window, enter D: in the Search for: text box,
enter your directory name in the Replace with: text box. There is no need
to select the Match case option. Enter *.* in the Files: text box, and click
Replace All (see Figure 9-9).
Caution: If your !pmcassette directory resides on your C: drive, this is a
one-way step, because there are other occurrence of C: in your .cmd files.
If you try to change it back using this method, you will make incorrect
changes to your files.
13.If you are using the default JDK directory of C:\jdk1.1.8, then skip this step. If
you are using some other directory, then you will have to make these
changes.
Using your favorite editing tool, change all occurrences of the default JDK
directory location C:\jdk1.1.8 with the JDK directory location for your
computer. You only need to change YourCassetteName#Build.cmd file. All
other command files will remain unchanged.
Note: In your directory path do not use directory paths with spaces in them.
Example:
SET JDKDIR=C:\Program Files\SQLLIB\Java\jdk
will produce errors and needs to be:
SET JDKDIR=C:\Progra~1\SQLLIB\Java\jdk
Replace window.
d. In the expanded Replace window, enter C:\jdk1.1.8 in the Search for:
text box, enter your JDK directory location in the Replace with: text box.
There is no need to select the Match case option. Enter *.* in the Files:
text box, and click Replace All (see Figure 9-10).
Figure 9-10 Display showing changing JDK directory location
14.Using your favorite editor, edit YourCassetteName#StartManager.cmd in your

cassette’s subdirectory.
a. Find the line that sets the CASSETTE_CLASSES environment variable
and remove the ;\.japi.zip from the end of the value set to become:
if exist .\japi.zip set CASSETTE_CLASSES=%CASSETTE_CLASSES%
b. Find the line that sets the ENVIRONMENT environment variable and
erase all the characters after the “=” character to the end of the line to
become:
set ENVIRONMENT=
c. Find the line that sets the DBOWNER environment variable and replace
“ldbader” with the user ID you used to log on to the workstation.
Note: Due to database restrictions, the user ID must be no longer than 8
characters.
d. Find the line that sets the DBUSER environment variable and replace
“ldbader” with the user ID you used to logon to the workstation.
Note: Due to database restrictions, the user ID must be no longer than 8
characters.

15.Using your favorite editor, edit your cassette’s YourCassetteNameInstall.sql
file. Find all occurrences of your cassette name that are in uppercase. If your
cassette name is longer than 8 characters, you will need to abbreviate the
table and view names so they are all less than 18 characters long.
16.Using your favorite editor, edit your cassette’s
YourCassetteNameRemove.sql file. If your cassette name is longer than 8
characters, you will need to change the table and view names so they match
the abbreviated names that you defined above.
17.Using your favorite editor, edit the file that contains your
YourCassetteNameAccount.java file.
a. Find and delete all the import statements that reference classes in a
package that begins with netverify prefix.
b. Find and delete all the constants (constants are those values that begin
with private static final String) with a name that begins with a prefix
of “ICV_” including the associated comment blocks.
c. Find the statement that defines objConnection. Change the statement
from:
private Connection objConnection
to
private Object objConnection
d. Find the connect() method. Leave the blocks that trace the function entry
and exit, but remove all the other statements (an entire try{}catch{} block).
e. Find the authorizePayment() method. Right after the block that traces the
function entry, you will find an assignment statement for varResult.
Change the statement from:
boolean varResult = false;
to
boolean varResult = true;
In the comment above the line you have just changed, change the word
declined to approved.
Then remove all the statements after this statement up to, but not
including the block that traces the function exit.
if (Trace.isAnyoneTracing()) {
Trace.traceFunctionExit(
TRACE_ID,
"QSIPayAccount.authorizePayment()"
);
}
return varResult;
18.Repeat step e above, for each of the following methods:
– capturePayment()
– voidPayment()
– captureCredit()
– voidCredit()
– settleBatch()
19.Build your cassette and copy the updated files into the Payment Manager
directories using your cassette’s YourCassetteName#Build.cmd script. Do this
by opening a DOS window and navigating to your !pmcassette directory.
Enter YourCassetteName#Build.
Note:The first time you run this script, there are no .class files to delete and
an error message will appear. Just ignore this message in this case (see
Figure 9-11).
If you get other errors you have made a mistake with either your naming
conventions or your previous steps. Remember you can always add
additional echo commands into the YourCassetteName#Build.cmd
parameters to track down what is failing.
Figure 9-11 Display showing #Build.cmd output

20.Edit the IBMPayServer.cmd file, which is located in the directory where
Payment Manager is installed to define the location of the cassette classes.
Add YourCassetteNameCassette.jar to the end of the line, for example:
set CASSETTE_CLASSES=.\eTillOfflineCardCassetteClasses.zip;.\eTillCustom
OfflineCassetteClasses.zip;.\QSIPayCassette.jar
Figure 9-12 Display showing changing the target location
21.If you find it convenient to use shortcuts to execute command scripts, you will
need to modify a few of the provided shortcuts so they will execute your
cassette’s command scripts instead of the LdbCard command scripts.
a. Select Start -> Programs -> Windows -> Windows Explorer.
b. In the Exploring window, navigate to the directory that contains your
cassette and open the Shortcuts directory.
c. In the right-hand file list, right-click your cassette’s Build shortcut and
select Properties on the pop-up menu.
d. In the resulting Properties window, select the Shortcut tab. In the Target:
text field, find and replace LdbCard with the name of your cassette.
Note: Do not change the working directory. By convention, your command
scripts assume that the Payment Manager directory is the current
directory.
Click OK.
e. Repeat step d for each of the following shortcuts:
i. Get Engine Trace
ii. Get Servlet Trace
iii. Install - the original path for the Target specified for this shortcut is
incorrect for PM2.2 and will have to be changed from:
"C:\Program Files\IBM\PaymentManager\SQLLIB\bin\db2cmd.exe"
To the path for DB2cmd.exe file in your computer. For example:
"C:\Program Files\SQLLIB\bin\db2cmd.exe"
iv. Remove - the original path specified for this shortcut is incorrect for
PM2.2 and will have to be modified as above.
v. Restore PostInstall - the original path specified for this shortcut is
incorrect for PM2.2 and will have to be modified.
vi. Restore PreInstall - the original path specified for this shortcut is
incorrect for PM2.2 and will have to be modified as above.
vii. Start Payment Manager - In addition, add a space and then your
password you use when you log on to the workstation to the end of the
Target. For example:
"C:\Program Files\IBM\PaymentManager\QSIPay#StartManager.cmd"
password
viii.Wipe Out - the original path specified for this shortcut is incorrect for
PM2.2 and will have to be modified to be the same as above.
ix. Save DB - the original path specified for this shortcut is incorrect for
PM2.2 and will have to be modified to be the same as above. You will
also have to change the Payment Manager database name from
PSADMIN to the name of your database name. For example:
"C:\Program Files\SQLLIB\bin\db2cmd.exe" db2 BACKUP DATABASE PAYMAN
TO C:\QSIPay\TestStart
As well as the Target directory, the Start In: directory will also have to
be modified to correspond with the above directory. However, this must
be in short DOS format - for example:
C:\Progra~1\SQLLIB\bin\
x. Test DB - the original path specified for this shortcut is incorrect for
PM2.2 and will have to be modified to be the same as above. You will
also have to change the Payment Manager database name from
PSADMIN to the name of your database name. In addition, delete the &
character and all characters from there to the end of the line. For
example:
"C:\Program Files\SQLLIB\bin\db2cmd.exe" db2 RESTORE DATABASE PAYMAN
FROM C:\QSIPay\TestStart REPLACE EXISTING
f. For convenience, you may want to copy these shortcuts or the ShortCuts
directory to your desktop.

22.Start a Web browser and navigate to:
http://yourhostServer/PaymentManager
23.In the Login page, enter admin as the user ID and admin as the password.
Click Log In.
24.In the WebSphere Administrative Console, go to the
PaymentManagerApplication. Select the Advanced tab as shown in
Figure 9-13.
Figure 9-13 Display showing WebSphere Administrative Console
Verify the Classpath in Use is the fully qualified classpath for the
eTillClasses.zip file. In most cases this will be the case.
Note: Short DOS names are used for directory names in this classpath.
If this is not the case, place the cursor on the end of the string in the
Classpath text field and enter a semi-colon (;). Then add the classpath of the
eTillClasses.zip file in short DOS format.
Click Apply and then right-click PaymentManagerApplication. Choose
Restart Web App to cause the changes to take effect.
25.In the navigation pane, click Log Off.
26.Close the browser, shut down, and restart your workstation.
27.Install your cassette into the Payment Manager and create your cassette’s
database tables using your cassette’s #Install script or its associated shortcut.
Note: This script will automatically back up the Payment Manager database
before it creates this version of the cassette database tables. When your
cassette tables are incrementally refined, this backup must be restored with
the #RestorePreInstall script or its associated shortcut.
28.You now have a primitive cassette. To start the Payment Manager with your
cassette, use your cassette’s #StartManager script or its associated shortcut.
Use the Payment Manager user interface to create a new merchant (by
convention, use merchant number 100) that is authorized to use your
cassette. Then create an new account (by convention, use account number
1000) for that merchant to use your cassette). Follow the directions in 8.6,
“Merchant integration using Sample Checkout” on page 253 or Appendix D of
the cookbook to set up a sample store and create a few orders. Use the
Payment Manager user interface to approve them, deposit them, reverse
them, refund them, settle the batch, and so on.
9.2.5 Implement a data model

You can now enhance your cassette to use the persistent data and protocol data
that you designed previously. This involves:
Updating the SQL script that creates your database tables and views
Updating the XML document so the Payment Manager user interface can
display your cassette-dependent data
Updating the constants with your column names and field identifiers
Updating the CassetteQuery class to return your cassette-dependent data
Updating the Cassette class to define the parameter validation for your
cassette’s protocol data
Refer to the cookbook for detailed instructions on these functions.
9.2.6 Implement an account class

The next step is to begin implementing an account class and test the commands
to create, modify, delete, start and stop an account. Additional methods will be
added to the account objects in subsequent stages.
We followed the cookbook’s detailed directions without changes, so we have not

reproduced these instructions in our redbook.

9.2.7 Implement a batch class
The next step is to implement a batch class. Although batch operations cannot
be tested here, they will be tested when payment and credits are added to the
batch in subsequent steps.

9.2.8 Implement an order class

The next step is to implement an order class and test the AcceptPayment
command.

9.2.9 Implement a payment class

The next step is to implement a payment class and test the Approve,
ApproveReversal, Deposit, and Deposit reversal commands. In addition, the
BatchClose and CloseOrder commands can be tested.

9.2.10 Implement a credit class

The next step is to implement a credit class and test the Refund and
RefundReversal commands. In addition, the BatchClose and CloseOrder
commands will be tested again.

9.2.11 Test the cassette

In this section, you will test your cassette.
Run the file payGenInstall.exe and extract it to your !pmcassette directory. In the
following instructions the directory will be labeled X: where X is the value of your
drive where your !pmcassette directory is located.
The directory X:\!PMCassette\PayGenTestCases contains all the payGen test
scripts used to perform regression testing on the LdbCardCassette. Although
there are only eight scripts that exercise the cassette, over 70% of the cassettes
code is tested. Note that the file type of a payGen script is .ps . To execute a
given script, you simply pass its file name as a parameter to the customized
batch file.
1. Using your favorite text editor, edit
X:\!PMCassette\PayGen\LdbCardTest0.bat. If necessary, modify the path to
java.exe and the classpath values so they are suitable for your environment.
Save the file using a file name that you will recognize. For example, if your
cassette name is QSIPay you could choose a name such as
QSIPayTest0.bat. The 0 (zero) suffix is convenient because, to run multiple
independent test scenarios at the same time, you will need a unique batch file
for each active scenario.
2. Using your favorite text editor, edit
X:\!PMCassette\PayGen\LdbCardTest0.properties. Modify the HOSTNAME
property value to match the host name where your Payment Manager test
system is running. Save the file using the same file name that you used in the
step above with a file type of .properties. PayGen finds the correct properties
file by matching the name of the batch file that invokes the payGen
application.
3. Test your batch file and your properties file by running the test script named
About.ps. Open a command prompt, change to the payGen directory, and
enter:
java -DFILE=LdbCardTest0.properties payGen about.ps
The usage for the payGen command is:
java -DFILE=fff payGen [[[testfilename] | [testdirname]] ... ]
where fff is the properties file that contains all the settings
or
java -Dxxx=yyy payGen [[[testfilename] | [testdirname]] ... ]
where xxx can be:
HOSTNAME, PORT, USER, PASSWORD, SERVLET, BRAND, $BRAND,
MERCHANTNUMBER, ACCOUNTNUMBER, ETAPIVERSION, THREAD, LOGPATH,
LOOP, INTERFACE, FILE, STATEFILE, BUYER, DEBUG, CALUSINGSSL,
CALSOCKSSERVERHOSTNAME, CALSOCKSSERVERPORT, VALIDATE, DELAY,
DELAYPERSCRIPT, DELAYPERLOOP, MAXHOURS, STARTBROWSER, KEEPALIVE,
HTTPVERSION, HTTPMETHOD, USINGSSL, PAUSEIFTESTFAILED,
STOPIFTESTFAILED, RETRYIFTESTFAILED, SAVEOUTPUTIFTESTFAILED
MIN$COUNT CURRENT$COUNT MAX$COUNT

4. Update and execute the other test scripts in
X:\!PMCassette\PayGenTestCases to make them suitable for your cassette.
To update the scripts:
a. Find and modify every :StartTest clause that contains a CreateAccount
command. Change the value of the CassetteName parameter and modify
the protocol data parameter names and values to match those necessary
for your cassette.
Figure 9-14 Display showing start of how payGen should output
b. Find and modify every :StartTest clause that contains an AcceptPayment

command. Change the value of the PaymentType parameter and modify
the protocol data parameter names and values to match those necessary
for your cassette.
c. Find and modify every :StartTest clause
:ExpectedString-<CassetteProperty … statement and
:ExpectedNoString-<CassetteProperty… statement. Remove any
statement that tests for cassette-dependent values that your cassette
does not supply. Add additional statements to test the cassette-dependent
values that you do supply.
d. If your cassette does not support the MaxBatchSize design, you will also
need to modify the X:\!PMCassette\PayGenTestCases\OrderExercise.ps
file by adding explicit BatchClose commands where the current script
expects the batch to be closed automatically.
5. Before this stage, your cassette was tested using the Sample Store and the
Payment Manager user interface but this methodology is not sufficient. There
will always be some error case that cannot be tested and automation is
required for reliable and repeatable testing. Using the scripts in
X:\!PMCassette\PayGenTestCases as an example, design, create, and
execute additional payGen test scripts to fully test your cassette. For
convenience, you may want to make a hardcopy of the file
X:\PMCassette\PayGen\Readme.txt. This file contains all the payGen
documentation.
– Be sure to validate that the database tables are updated correctly. Since
the Query command examines the database, not the objects in memory, it
can be used to automate this test.
– Be sure to validate the primary and secondary return code values
returned.
– Be sure to validate that the framework object states change correctly.
– Be sure to validate that the state checks are performed correctly.
– Be sure to test every supported platform.
6. There are also two other shortcuts that have not been mentioned until now.
These are YourCassetteName Get Engine Trace and YourCassetteName Get
Servlet Trace. These are both command scripts that convert the binary trace
outputs from Payment Manager to ASCII so you can follow them. You will
have to change the classpaths and other parameters to use them on your
computer.
At present the scripts are set up for the editor program of Visual SlickEdit.
However, you can change this to your favorite editor, such as EditPlus. Simply
change the vs in vs %DST% and vs %SRC%\PSError to an editor that allows
you to nominate a file. If it is not in your path you will have to add your path to
the command, for example, c:\Progra~1\EditPl~1\editplus.exe %DST%.
9.2.12 Package and ship the cassette

In this section, you will complete your cassette.
1. Find all the code that that is no longer used and delete it. Rebuild your
cassette to verify that the code is no longer needed. Fix any build errors.
2. Build an install package for every supported platform and test them. The
Cassette Kit Programmer’s Guide contains information that helps with this
task.
9.2.13 Practice with LdbCard

The LdbCard cassette was written to use a payment appliance developed by IBM
but never released as a product. This payment appliance was chosen mostly
because it was convenient but also because it illustrates most of the
implementation details you are likely to find in your own development project.
If you would like to use LdbCard as a practice cassette, the following steps
describe how modify to the LdbAccount class to make it independent of the
payment appliance so you can use it.

1. Using your favorite editor, edit the file that contains your
LdbCardAccount.java file.
a. Find the connect() method. Leave the blocks that trace the function entry
and exit, but remove all the other statements (an entire try{}catch{} block
of about 41 lines two thirds into the file).
b. Find the authorizePayment() method. Right after the block that traces the
function entry, you will find an assignment statement for varResult.
Change the statement (about two thirds into the file just below where you
made the previous deletion) from:
boolean varResult = false;
to
boolean varResult = true;
In the comment above the line you have just changed, change the word
declined to approved. Then remove all the statements after this statement
up to, but not including, the block that traces the function exit (shown
below) - about 168 lines of code.
if (Trace.isAnyoneTracing()) {
Trace.traceFunctionExit(
TRACE_ID,
"QSIPayAccount.authorizePayment()"
);
}
return varResult;
2. Repeat this step for each of the following methods:
– capturePayment()
– voidPayment()
– captureCredit()
– voidCredit()
– settleBatch()
3. Recompile the LdbCard cassette using the Rebuild tool in the Visual SlickEdit
project or with the following commands, with the appropriate changes to the
code, for example JDKDIR and WORKDIR locations, etc.
X:
CD X:\!PMCassette
SET JDKDIR=C:\jdk1.1.8
SET WORKDIR=com\ibm\etill\ldbcardcassette
SET ETILLDIR=C:\Program Files\IBM\PaymentManager
SET CLASSPATH=C:\JDK1.1.8\lib\classes.zip
SET CLASSPATH=%ETILLDIR%\eTillClasses.zip;%CLASSPATH%
SET CLASSPATH=%WORKDIR%\lib\japi.zip;%CLASSPATH%
SET CLASSPATH=.\;%CLASSPATH%
ERASE %WORKDIR%\*.class
%JDKDIR%\bin\javac %WORKDIR%\LdbCardCassette.java
%JDKDIR%\bin\javac %WORKDIR%\LdbCardCassetteQuery.java
4. Rebuild the LdbCardCassette.jar using the Make JAR tool in the Visual
SlickEdit project or with the following commands, with the appropriate
changes to the code, for example JDKDIR and WORKDIR locations, etc.
X:
CD X:\!PMCassette
SET TARGET=LdbCardCassette.jar
XCOPY %WORKDIR%\*.properties .\
%JDKDIR%\bin\jar cf0 %TARGET% %WORKDIR%*.class *.properties
ERASE *.properties
COPY %TARGET% %WORKDIR%\lib
5. Use your favorite text editor to edit LdbCard#StartManager.cmd. Find all
instances of the string “ldbader” and replace them with the workstation user
ID used to install the Payment Manager. Note that this command file takes
one parameter (find “%1”), the password used to authenticate this user ID.
6. Copy the LdbCard files into the production system using the Install tool in the
Visual SlickEdit project or with the following commands, with the appropriate
changes to the code, for example JDKDIR and WORKDIR locations, etc.
X:
CD X:\!PMCassette
XCOPY %WORKDIR%\*.cmd "%ETILLDIR%"
XCOPY %WORKDIR%\*.sql "%ETILLDIR%\Archive"
XCOPY %WORKDIR%\*.PSPL "%ETILLDIR%\pspl"
XCOPY %WORKDIR%\lib\*.* "%ETILLDIR%"
7. Install the LdbCard cassette into your production system by opening a DB2
command window and executing the LdbCard#Install.cmd script that was
copied into your production system in step 6 in the resulting command
window.
8. Start the Payment Manager using the LdbCard#StartManager.cmd script. Be
sure to specify a parameter, namely the password necessary to authenticate
the user ID you placed into the command file.
9. Use the Payment Manager user interface and log on to Payment Manager
(the default user ID and password are both admin), create a merchant that is
authorized to use LdbCard, and create an LdbCard account for the merchant
(the values specified for account parameters won’t matter).
10.Make some purchases with the sample store.

11.Return to the Payment Manager user interface and have some fun approving,
voiding, depositing, crediting, and settling transactions.
9.2.14 Using the cookbook sample store

The sample buy page that is provided with the Payment Manager is unsuitable
for testing a cassette. Its servlet contains hard-coded assumptions for the
PAYMENTTYPE parameter and the protocol data values to be passed on the
AcceptPayment verb. Moreover, the servlet invoked by the sample buy page
does not provide any feedback about the result of its actions.
The Sample Store provided with the cookbook materials overcomes these
limitations and can be used to generate Payment Manager orders to help you
test your cassette. The index.html file included in the Sample Store contains a
sample buy page containing an HTML form that uses an HTTP POST request to
invoke the Sample Store servlet. In turn, the servlet uses the parameters passed
on the POST request to issue an AcceptPayment command to the Payment
Manager. See Table 9-1 to understand the relationship between the form and the
servlet’s actions.
Table 9-1 Cookbook servlet actions
HTML form parameter Servlet action
PAYMENTTYPE The value is used as the value for the

PAYMENTTYPE keyword.
MERCHANTNUMBER The value is used as the value for the

MERCHANTNUMBER keyword.
AMOUNT The value is used as the value for the

AMOUNT keyword.
CURRENCY The value is used as the value for the

CURRENCY keyword.
ORDERNUMBER The value is ignored. The servlet

automatically generates a value for the
ORDERNUMBER parameter by using the
date and time. This allows multiple orders
to be generated from the same form.
EXPIRYYEAR The 4-digit year value is combined with

the 2-digit month value (YYYYMM) to
make the value for the $EXPIRY protocol
data keyword.
HTML form parameter Servlet action
EXPIRYMONTH The 4-digit year value is combined with

the 2-digit month value (YYYYMM) to
make the value for the $EXPIRY protocol
data keyword.
Any parameter that begins with $ The keyword and its value are passed as
cassette dependent protocol data.
Follow these steps to use the cookbook Sample Store.

1. Use your favorite text editor to modify
X:\!PMCassette\SampleStore\index.html. Change every occurrence of
LdbCard to your cassette name. Save the file.
2. If necessary, use your favorite text editor to modify
X:\!PMCassette\SampleStore\index.html. For example, if your cassette has
additional protocol data values that must be specified by the shopper, add the
required input fields to the HTML table inside the HTML form. Use the $PAN
parameter as an example. If your cassette has additional protocol data values
that, for the purposes of a test, are constants, add the required hidden input
fields to the HTML form. Use the PAYMENTTYPE parameter as an example.
3. Save the file.
4. If necessary, use your favorite text editor to modify
X:\!PMCassette\SampleStore\SampleStore.java. Typically this is
unnecessary. It is only required when protocol data values must be computed
instead of passing through. For an example, look how EXPIRYYEAR and
EXPIRYMONTH values are combined to make the $EXPIRY parameter
value.
5. Recompile the Sample Store cassette using the Compile tool in the Visual
SlickEdit project, the SampleStore#Build.cmd provided, or with the following
commands, with the appropriate changes to the code, for example JDKDIR
and WORKDIR locations, etc.
X:
CD X:\!PMCassette
SET WORKDIR=SampleStore
SET JAVAXDIR=%ETILLDIR%\IBMWebAS
SET CLASSPATH=%JDKDIR%\lib\classes.zip
SET CLASSPATH=%JAVAXDIR%\lib\jsdk.jar;%CLASSPATH%
SET CLASSPATH=%ETILLDIR%\eTillClasses.zip;%CLASSPATH%
SET CLASSPATH=%WORKDIR%;%CLASSPATH%
ERASE %WORKDIR%\*.class
%JDKDIR%\bin\javac %WORKDIR%\SampleStore.java

6. Copy the Sample Store files into the production system using the Install tool
in the Visual SlickEdit project, the SampleStore#Build.cmd provided, or with
the following commands, with the appropriate changes to the code, for
example JDKDIR and WORKDIR locations, etc.
X:
CD X:\!PMCassette
SET WORKDIR=SampleStore
SET HTMLDIR=%ETILLDIR%\httpd\htdocs
SET SERVLETDIR=%etilldir%\IBMWebAS\servlets
xcopy %WORKDIR%\*.class "%SERVLETDIR%"
xcopy %WORKDIR%\*.html "%HTMLDIR%\SampleStore\*.*"
7. Start a Web browser and go to http://yourhostname/SampleStore where
yourhostname is replaced with the host name of the workstation where the
Payment Manager is installed. To create an order, fill out the form and click
Buy.
9.2.15 Tips and techniques

Appendix F of the cookbook contains miscellaneous tips and techniques that
may help you design and develop your cassette. However, there is one additional
one not covered in the current list. This is a response from the author of the
cookbook, Lance Bader, to a customer for information.
Q: Can I do the following with my PSPL file:
a. Modify my PSPL so I can have an LDBcardUI.properties file.
b. If so, is there some trick or configuration that I need to do?
A: The LdbCard cassette was developed for WebSphere Payment Manager

Version 2.1, long before Version 2.2 became available. Its LdbCard.en.PSPL
file was developed with the inline style because that was the only choice
before Version 2.2.
a. Yes, any cassette developer using the LdbCard cassette as a template
can extend the example PSPL file to use the external properties style.
Note that PSPL that uses the inline style can be used in both WebSphere
Payment Manager Version 2.1 and Version 2.2 installations. The external
properties style requires WebSphere Payment Manager Version 2.2.
b. Instructions for developing a PSPL file that uses the external properties
style can be found in the Cassette Kit Programmer’s Guide Version 2.2
that can be downloaded from the Web site using the same key code that
was used to download the Cassette Developer Cookbook, which contains
the LdbCard cassette.The URL is:
http://www.ibm.com/software/webservers/commerce/payment/download.
html
In the Cassette Kit Programmer’s Guide (the PDF version), see pages
103-104 in Chapter 2 to understand the differences in the document
styles.
See pages 107-109 in Chapter 2 to learn how to create the external
properties file. Note file names are case sensitive and must follow the
naming conventions documented.
See pages 109-129 in Chapter 2 to learn how to code the PSPL tags. For
each tag that permits external properties, pay special attention to the
textid= attribute, which references strings in the external properties file.
See pages 129 for information on how to debug PSPL problems.
Two example files LdbCardUI.properties and LdbCard.PSPL are provided
in our redbook additional material for you to use. See Appendix A,
“Additional material” on page 317 for details on obtaining sample code.
If no cassette dependent fields are displayed, the most likely cause is
invalid PSPL introduced by the cassette developer. The cassette
developer should first look in the C:\Program
Files\IBM\PaymentManager\log\PSError file for error messages that
describe the problem. If the information there is insufficient to find the
problem, follow the instructions on page 129 in the Cassette Kit
Programmer’s Guide.
The next most likely cause is an invalid file name, either for the PSPL or
for the external properties files. Remember, property file names are case
sensitive. Furthermore, the files must be placed in the correct directory. Be
sure you follow the naming conventions documented in the Cassette Kit
Programmer’s Guide. Check each name three times.
9.3 Cassette Developers Toolkit

The Cassette Kit Programmer’s Guide is part of the Cassette Developers Toolkit
and it describes the Payment Manager cassette programming interface, and
cassette-specific programming or administrative considerations, and shows how
the cassette implements the Payment Manager’s various interfaces.
Payment cassettes process electronic payments using a specific payment

protocol under control of the Payment Manager. Since the Payment Manager
presents a single, well-defined payment processing application programming
interface (API), adding new cassettes allows existing Payment Manager
applications to process payments through new payment protocols with little or no
integration effort.

The Cassette Developers Toolkit is delivered as a ZIP file. To install the Cassette
Developers Toolkit, download the ZIP file to your computer and unzip it in the
directory of your choice. It will create these subdirectories:
docs, which contains the HTML and PDF representation of the Cassette Kit
Programmer’s Guide
docs/javadoc, which contains the Javadoc HTML for the IBM WebSphere
Payment Manager 2.2 Framework
tools/FSMTools, which contains the Finite State Machine tools
In addition, the file setupTestTables.txt, which is a sample database setup script,

will be in the directory where you unzipped the file.
9.3.1 Payment Manager enhancements

There are several enhancements that have been made in the Payment Manager
2.2 product that a cassette developer should consider.
Cashier
The cashier is a Java class library that allows the integration of merchant
application software with Payment Manager without having to write any code that
is specific to any given cassette. This allows the addition of new cassettes into
the merchant environment without having to rewrite any of the merchant
application software. Cassette independence is accomplished by creating
XML-based cashier profiles that describe all the cassette-specific parameters
that are needed to create a Payment Manager order. Once this profile is
available, the merchant software calls the cashier (instead of calling the Payment
Manager directly) to interpret the profile, build the appropriate AcceptPayment or
ReceivePayment command, and then send that command to the Payment
Manager. In addition, merchant applications can profile information to
dynamically build checkout/buy pages that present the list of available payment
options to the buyer.
New SampleCheckout application

Previous versions of Payment Manager required a cassette developer to create a
sample buy page servlet that allowed creation of Payment Manager orders for a
cassette. In the 2.2 release, a sample order entry application called
SampleCheckout is provided. See 8.6, “Merchant integration using Sample
Checkout” on page 253 of this redbook. Since SampleCheckout uses the new
cashier, cassette developers can use it as an install verification and training tool
by simply supplying cashier profiles and some small updates to the
SampleCheckout configuration file. Furthermore, source code is included to
demonstrate techniques for integrating storefront software with the Payment
Manager in cassette-independent fashion using the new cashier.
Branding
The user interface is enhanced so that you can change the appearance of the
IBM WebSphere Payment Manager 2.2 user interface by supplying customized
files. See 8.1, “Customization” on page 212 of this redbook. The user interface
appearance can be altered in several ways. Customization includes the ability to:
Change the masthead banner.
Add HTML links to other pages. This technique can be used to attach
customized reports to the Payment Manager user interface.
Change the stylesheet (colors, fonts, sizes, etc.).
Change certain text within the user interface.
Asynchronous auto approval

In previous versions of Payment Manager, when the merchant server software
issues an AcceptPayment command or a ReceivePayment command with the
autoApprove flag (APPROVEFLAG=1), the cassette is expected to perform
approval processing before completing the request and returning the
APIResponse. In Payment Manager 2.2, the APPROVEFLAG keyword on the
AcceptPayment and ReceivePayment API commands has been enhanced to
allow the specification of asynchronous approvals. See Cassette Kit
Programmer’s Guide, page 91.
AcceptPayment and ReceivePayment

The AcceptPayment and ReceivePayment API commands allow the
specification of autoApprove and autoDeposit flags that indicate whether
approvals and deposits should be attempted automatically. In Payment Manager
Versions 2.1.5.0 or greater, a new feature for specifying autoApprove and
autoDeposit is introduced. This feature provides merchants with an option, based
on their relationship with their acquirers, to specify autoApprove or autoApprove
with autoDeposit on an account basis rather than on an API basis. See Cassette
Kit Programmer’s Guide, page 92.
Return code messages

Payment Manager 2.2 provides cassette developers with the ability to add textual
descriptions to the return codes associated with the AcceptPayment and
ReceivePayment API commands. See Cassette Kit Programmer’s Guide, page
95.

AVS mapping
A set of Payment Manager framework constants have been added that define
common Address Verification Service (AVS) result codes. AVS is a primarily
US-specific credit card fraud detection mechanism that may be implemented by
a cassette if the payment protocol supports it. Since AVS result codes are not
standardized, the Framework has designed a common set of AVS result codes
that all cassettes utilizing AVS should use. See Cassette Kit Programmer’s
Guide: page 89.
9.3.2 Understanding the Payment Manager framework

Before writing a Payment Manager cassette, you must understand the Payment
Manager framework. The goal of the framework is to provide:
A single merchant programming interface, which allows merchant software to
exploit new payment protocols with little or no change
The internal structure into which cassettes must fit, function, and conform
A framework object model
“Framework commands”
The framework, which is explained in Cassette Kit Programmer’s Guide, also

provides services and features for cassettes and cassette developers that allow
them to support the merchant programming interface and support the
framework’s internal structure, as transparently as possible. These features are
described in Cassette Kit Programmer’s Guide:
Responsibilities and services on page 75
Framework Javadoc on page 130.
9.3.3 Designing your cassette

After you understand the Payment Manager framework, you can begin designing
your cassette. Read Chapter 3 of the Cassette Kit Programmer’s Guide from
page 133 onwards for a detailed explanation, and look at the LdbCard cassette.
LdbCard is a complete and functional cassette infrastructure upon which most
other cassettes can be built. LdbCard is designed specifically for credit card
processing and it is especially useful when developing other cassettes in this
category.
You can retrieve the LdbCard cassette and its accompanying documentation
from the same Web site from which you downloaded this Cassette Kit
Programmer’s Guide. The LdbCard code is explained in this chapter, and we help
you through the process of modifying the LdbCard code to implement your own
cassette. For many people, this documentation will provide most of what you
need. In other cases, however, LdbCard’s simplifying assumptions may not apply
to the given payment protocol. Other cassettes may need to use framework
features that are not used in LdbCard. In these cases, you should still use
LdbCard’s infrastructure as your starting point, augmenting its design as
necessary to suit your needs.
LdbCard is a complete and fully functioning cassette upon which you can build
your own cassette. The number of extensions and modifications to the LdbCard
design will vary according to the needs of your cassette.
9.4 KitCash cassette

The KitCash cassette is also provided as an example for cassette developers.
9.4.1 Overview of cassette for KitCash

The cassette for KitCash is a sample payment cassette that implements a
fictional electronic cash (stored value) protocol. The cassette for KitCash is
designed to show you how to use Payment Manager to support an Internet
payment system.
KitCash is an example for cassette writers that covers several aspects of

cassette writing not covered by the LdbCard skeleton cassette. KitCash is not
intended to serve as a skeleton upon which cassette writers will typically build
new cassettes. You should use the LdbCard cassette for that purpose.
KitCash illustrates these unique features:

An example of a payment protocol that is not oriented towards credit cards.
The fictional KitCash stored value protocol supports a limited set of financial
transactions. For example, the KitCash protocol does not support reversals or
credits. As a result, the cassette supports a limited subset of Payment
Manager’s API set to match the needs of the payment protocol.
How to support the ReceivePayment command, including:
– The definition of protocol messages representing a set of associated
protocol flows from a buyer’s wallet.
– The use of ComPoints to manage the protocol messages.
How to use CassetteWorkItems and the Framework’s service thread queue.
How to use the Finite State Machine (FSM) tools.
An alternative cassette design.

The alternative cassette design is possible because the framework uses Java
interfaces instead of abstract methods to define some of the key cassette
objects. Specifically, KitCash implements the CassetteOrder and
CassetteTransaction (representing a payment) interfaces in a single object
named KitCashPurchase.
KitCash provides full support for Payment Manager administration commands

and user interface according to the needs of the payment protocol. A test
harness is provided for the Cassette for KitCash. The test harness shows how
the cassette interacts with other components in an Internet payment system.
For full details about the KitCash cassette, see the Cassette for KitCash
Supplement which is included in the KitCash download files.
9.4.2 KitCash installation

The Payment Manager must be installed before the cassette for KitCash can be
installed. The Payment Manager installation will ensure that all prerequisite
products are available. The minimum framework level supported by the cassette
is 2.2.0.0.
Test harness
The KitCash card is implemented in software by a KitCashDriver class. No
special hardware is required to run the sample code. The KitCash test harness
allows you to see how the cassette interacts with other Internet payment
software. The KitCash test harness includes:
KitCash wallet (Java applet)
Merchant Web site with products for sale
Merchant code (Java servlet) to process consumer purchase requests
KitCash bank (Java application) to receive deposits from a merchant
Before installing Cassette for KitCash

Upgrade JDK. If you do not have a minimum of JDK 1.1.8, an upgrade is
required (see Figure 9-1).
Set required environment variables:
– Ensure that your PATH environment variable includes a reference to your
Java bin directory (see Figure 9-15).
– Ensure that your CLASSPATH environment variable includes your
database JDBC driver classes (see Figure 9-16).
– Set a new environment variable ETILL_INSTALL to point to the directory in
which Payment Manager was originally installed (see Figure 9-17).
Ensure that you comply with the specifications in Table 9-2 on page 312.
Installing the cassette for KitCash

Installing the cassette for KitCash involves updates to the:
Payment Manager and supporting database
Web server
To install the cassette for KitCash with Payment Manager, do the following:
1. Copy the KitCash compressed file to a directory and uncompress it. You
should name this directory /kitcashcassette (for AIX and Solaris) and
c:\kitcashcassette (for Windows NT and Windows 2000), since this example
uses these directory names.
Figure 9-15 Display showing adding the JDK to the path

Figure 9-16 Display showing adding classes.zip to classpath
Figure 9-17 Display showing adding variable Etill_Install
2. Set up cassette for KitCash database tables.

– On AIX and Solaris:
From a command prompt at subdirectory kitcashcassette/tables, enter:
./SetupKitCashTables.sh <dbUserID> <dbPassword> <DatabaseName>
– On Windows NT and Windows 2000:
From a command prompt at subdirectory c:\kitcashcassette\tables, enter:
SetupKitCashTables.bat <dbUserID> <dbPassword> <DatabaseName>
where:
dbUserID Is the user ID with write access to the database tables.
dbPassword Is the password for the respective user ID.
DatabaseName Is the Payment Manager database name (if omitted, a
defaultdatabase name, psadmin, is used).
Table 9-2 What should be running while installing KitCash cassette
WebSphere Application Server WebSphere Application Server 3.x
2.0.3
Payment Manager should not be running Payment Manager should not be running
during the cassette installation. during the cassette installation.
WebSphere Application Server WebSphere Application Server 3.x
2.0.3
None of the following programs should be The WebSphere Administrative Console
running during the cassette installation: should be running at cassette installation.
Any other Web server products
Figure 9-18 Display showing how table setup completes in Windows
3. Copy the KitCash JAR file to the Payment Manager install directory.
Copy /kitcashcassette/lib/eTillKitCashClasses.jar to
<PaymentManagerInstallDirectory>
Copy c:\kitcashcassette\lib\eTillKitCashClasses.jar to
<PaymentManagerInstallDirectory> (see Figure 9-19).
4. Copy the Cassette for the KitCash PSPL file to the Payment Manager PSPL
directory.

Copy /kitcashcassette/pspl/KitCash.PSPL to
<PaymentManagerInstallDirectory>/pspl.
Copy c:\kitcashcassette\pspl\KitCash.PSPL to
<PaymentManagerInstallDirectory>/pspl (see Figure 9-19).
Figure 9-19 Display showing files being copied in writer’s computer
5. Edit the IBMPayServer file (IBMPayServer.cmd on Windows NT and

Windows 2000), located in the directory where Payment Manager is installed,
and add ./eTillKitCashClasses.jar to the CASSETTE_CLASSES variable. For
example:
set
CASSETTE_CLASSES=.\eTillOfflineCardCassetteClasses.zip;.\eTillCustomOffline
CassetteClasses.zip;./eTillKitCashClasses.jar
9.4.3 Configuring the Web server

To make the merchant’s Web site available, configure the Web server as follows:
Create a directory named merchant under the
<HTTPServerPublishDirectory>.
Copy the contents of the /kitcashcassette/WebServer/HTML/merchant
directory to <HTTPServerPublishDirectory>/merchant (see Figure 9-20).
Figure 9-20 Display showing new merchant directory with KitCash files

To make the merchant servlet accessible to the consumer, WebSphere
Application Server must be configured. Configuring WebSphere Application
Server for the KitCash test merchant varies depending on which version of
WebSphere Application Server you are using. Use the instructions appropriate
for your installation direct from the Cassette for KitCash Supplement.

A
Appendix A. Additional material

This redbook refers to additional material that can be downloaded from the
Internet as described below.
Locating the Web material

The Web material associated with this redbook is available in softcopy on the
Internet from the IBM Redbooks Web server. Point your Web browser to:
ftp://www.redbooks.ibm.com/redbooks/SG246177
Alternatively, you can go to the IBM Redbooks Web site at:

ibm.com/redbooks
Select the Additional materials and open the directory that corresponds with
the redbook form number, SG246177.
Using the Web material

The additional Web material that accompanies this redbook includes the
following files:
File name Description
sg246177.zip Zipped Code Samples

System requirements for downloading the Web material
The following system configuration is recommended:
Hard disk space: 5 MB minimum
Operating System: Windows NT or Windows 2000
Processor: Intel Pentium II with 300 MHz processor or better
Memory: 512 MB minimum
How to use the Web material

Create a subdirectory (folder) on your workstation, and unzip the contents of the
Web material zip file into this folder.
Related publications
The publications listed in this section are considered particularly suitable for a
more detailed discussion of the topics covered in this redbook.
IBM Redbooks
For information on ordering these publications, see “How to get IBM Redbooks”
on page 323.
WebSphere Commerce Suite V5.1 Handbook, SG24-6167
WebSphere Commerce Suite V5.1 Customization and Transition Guide,
SG24-6174
Mobile Commerce Solutions Guide using WebSphere Commerce Suite V5.1,
SG24-6171
WebSphere Scalability: WLM and Clustering Using WebSphere Application
Server Advanced Edition, SG24-6153
Other resources
These publications are also relevant as further information sources:
IBM WebSphere Payment Manager for Multiplatforms Programmer’s Guide
and Reference Version 2.2
This product document is shipped with WebSphere Payment Manager or can
be downloaded from:
http://ibm.com/software/webservers/commerce/paymentmanager/lib.html
IBM WebSphere Payment Manager for Multiplatforms Install Guide Version
2.2
be downloaded from:
IBM WebSphere Payment Manager for Multiplatforms Administrator’s Guide
Version 2.2
be downloaded from:

IBM WebSphere Payment Manager for Multiplatforms Cassette Kit
Programmer’s Guide Version 2.2
This document is part of the Cassette Developer Toolkit as described in 9.3,
“Cassette Developers Toolkit” on page 305. The toolkit can be downloaded
from:
Referenced Web sites

These Web sites are also relevant as further information sources:
IBM Pervasive Computing - Wireless payments white paper
http://www.ibm.com/pvc/tech/pdf/Pvwee02.pdf
IBM e-commerce product integration test- Payment Manager and MPE
http://www-4.ibm.com/software/webservers/commerce/epit/reports.html
Electronic Commerce Modelling Language
http://www.ecml.org
WebSphere Payment Manager capacity planning, performance and
scalability
http://ibm.com/software/webservers/commerce/payment/docs/paymgr22whit
epaper.pdf
Secure Electronic Transaction home site
http://www.setco.org
Payment Registry
http://ibm.com/software/webservers/commerce/paymentregistry/features
.html
Payment overview
http://ibm.com/software/webservers/commerce/payment/
Payment Gateway
http://ibm.com/software/webservers/commerce/payment/paymentgateway/fe
atures.html
Vital Processing Services
IBM Announcements
http://www.ibm.com/news/usalet
Cassette for VisaNet supplement
http://ibm.com/software/webservers/commerce/payment/docs/paymgr221vis
anet.pdf
Payment Manager support
http://ibm.com/software/webservers/commerce/paymentmanager/support/ind
ex.html
Payment Manager payment cards (cassettes) list
http://ibm.com/software/webservers/commerce/payment/paymentcards.htm
l
Bankserv
http://www.bankserv.com
ClearCommerce
http://www.clearcommerce.com
CyberCash
http://www.cybercash.com/
CyberSource
http://www.cybersource.com
GlobalCollect
http://www.globalcollect.nl
GO Software
http://www.pccharge.com
Lynk Systems
http://www.lynksystems.com
Verisign payment processing services
http://www.verisign.com/products/payment.html
Payment Manager 2.1 support
http://ibm.com/software/webservers/paymgr/support/sbull.html
Integrating Payment Manager and WebSphere Commerce Suite Marketplace
Edition
http://ibm.com/software/webservers/commerce/epit/mpepm.html
Related publications 321

WebSphere Application Server hardware and software prerequisites
http://ibm.com/software/webservers/appserv/doc/latest/prereq.html
RS/6000 support
http://techsupport.services.ibm.com/rs6000/support/
DB2 Universal Database support
http://ibm.com/software/data/db2/udb/support.html
Oracle Technology Network
http://otn.oracle.com/
IBM HTTP Server Overview
http://ibm.com/software/webservers/httpservers/
WebSphere Application Server Overview
http://ibm.com/software/webservers/appserv/
Database and Data Management Library
http://ibm.com/software/data/pubs/index.html
Microsoft Download Center
http://www.microsoft.com/downloads/
Sun product documentation
http://docs.sun.com
Netscape for Solaris
http://www.sun.com/solaris/netscape/getnetscape476.html
iPlanet Web Server documentation
http://developer.iplanet.com/docs/manuals/enterprise.html
IBM SET tutorial and demonstration
http://ibm.com/software/webservers/commerce/paymentmanager/support/pa
ydemo.html
IBM Payment Manager acquirer profiles
http://ibm.com/software/webservers/commerce/paymentmanager/support/ac
qprofile.html
How to get IBM Redbooks
You can order hardcopy Redbooks, as well as view, download, or search for
Redbooks at the following Web site:
ibm.com/redbooks
You can also download additional materials (code samples or diskette/CD-ROM

images) from that site.
IBM Redbooks collections

Redbooks are also available on CD-ROMs. Click the CD-ROMs button on the
Redbooks Web site for information about all the CD-ROMs offered, as well as
updates and formats.
Related publications 323

Special notices
References in this publication to IBM products, programs or services do not imply

that IBM intends to make these available in all countries in which IBM operates.
Any reference to an IBM product, program, or service is not intended to state or
imply that only IBM's product, program, or service may be used. Any functionally
equivalent program that does not infringe any of IBM's intellectual property rights
may be used instead of the IBM product, program or service.
Information in this book was developed in conjunction with use of the equipment
specified, and is limited in application to those specific hardware and software
products and levels.
IBM may have patents or pending patent applications covering subject matter in
this document. The furnishing of this document does not give you any license to
these patents. You can send license inquiries, in writing, to the IBM Director of
Licensing, IBM Corporation, North Castle Drive, Armonk, NY 10504-1785.
Licensees of this program who wish to have information about it for the purpose
of enabling: (i) the exchange of information between independently created
programs and other programs (including this one) and (ii) the mutual use of the
information which has been exchanged, should contact IBM Corporation, Dept.
600A, Mail Drop 1329, Somers, NY 10589 USA.
Such information may be available, subject to appropriate terms and conditions,

including in some cases, payment of a fee.
The information contained in this document has not been submitted to any formal
IBM test and is distributed AS IS. The use of this information or the
implementation of any of these techniques is a customer responsibility and
depends on the customer's ability to evaluate and integrate them into the
customer's operational environment. While each item may have been reviewed
by IBM for accuracy in a specific situation, there is no guarantee that the same or
similar results will be obtained elsewhere. Customers attempting to adapt these
techniques to their own environments do so at their own risk.
Any pointers in this publication to external Web sites are provided for
convenience only and do not in any manner serve as an endorsement of these
Web sites.

The following terms are trademarks of other companies:
C-bus is a trademark of Corollary, Inc. in the United States and/or other

countries.
Java and all Java-based trademarks and logos are trademarks or registered
trademarks of Sun Microsystems, Inc. in the United States and/or other
countries.
Microsoft, Windows, Windows NT, and the Windows logo are trademarks of
Microsoft Corporation in the United States and/or other countries.
PC Direct is a trademark of Ziff Communications Company in the United States

and/or other countries and is used by IBM Corporation under license.
ActionMedia, LANDesk, MMX, Pentium and ProShare are trademarks of Intel

Corporation in the United States and/or other countries.
UNIX is a registered trademark in the United States and other countries licensed
exclusively through The Open Group.
SET, SET Secure Electronic Transaction, and the SET Logo are trademarks
owned by SET Secure Electronic Transaction LLC.
Other company, product, and service names may be trademarks or service

marks of others
Abbreviations and acronyms
2KP 2 key pairs JTA Java transaction API
3KP 3 key pairs LDAP Lightweight Directory Access
API Application Programming Protocol
Interface MCK Merchant Connection Kit
ASP Application Service Provider MIA Merchant Initiated
AVS Address Validation Service Authorisation
B2B Business-to-Business MOP Merchant Originated Payment
B2C Business-to-Consumer PSPL Payment Manager

Presentation Language
CA Certificate Authority
SAR store archive file
DTD Document Type Definition
SET Secure Electronic Transaction
ECML Electronic commerce
modelling language SSL Secure Sockets Layer
EJB Enterprise JavaBean UDB IBM Universal Database
FSM Finite State Machine VIPG Visa VirtualNet Internet

Payment Gateway
HTML HyperText Markup Language
VPN Virtual Private Network
HTTP HyperText Transfer Protocol
XML Extensible Markup Language
IBM International Business
Machines Corporation
IDE Integrated Development
Environment
IHS IBM HTTP Server
ISV independent software vendor
ITSO International Technical
Support Organization
J2EE Java 2 Platform, Enterprise
Edition
JDBC Java database connectivity
JDK Java Development Kit
JMS Java Message Service
JNDI Java Naming and Directory
Interface
JPO Japanese Payment Option
JRE Java Runtime Environment
JSP JavaServer Pages

Index
Numerics C
CA 111
1-tier 32, 38
CAL 22
2KP 114
card issuer 111
2-tier 32
cashier 306
3-Domain SET 117
cashier framework 236
3KP 114
cashier profile 178, 250
3-tier 34
cashier profile for Set wallet 178
cassette 7, 13, 17, 25, 43, 159, 184
A account class 295
AcceptPayment 307 batch class 296
account class 295 credit class 296
ACH 163, 166 data model 295
acquirer 110, 111, 113 design 308
acquirer domain 117 development 273
Address Verification Service 308 order class 296
administration 7 payment class 296
AIX 41 testing 296
APACS 162 Cassette Developer Cookbook 274
Application Service Provider 3 Cassette Developer Toolkit 278
architecture 16, 30, 32 cassette for VisaNet 141, 143
ASP 3, 6 Cassette Kit Programmer’s Guide 305
Association for Payment Clearing Services 162 certificate 6, 61, 110, 111
asynchronous approvals 307 certificate authority 111
Atos IPS 163 ClearCommerce 164
Atos Poseidon Internet Payment System 163 Commerce Suite realm 170, 184
authentication 6, 17, 109, 110, 111 confidentiality 110
authorization 185 consumer certificate 128
AVS 308 consumer wallet 112
controller commands 175
coupons 12
B
B2B 11 credit cards 3, 12
B2C 11 credit class 296
BankServ 163 credit issuing 267
BankServACH 163 CTS 165
batch 261 currency 142
settle 261 CustomerOffline 184
batch class 296 customization 212
batch totals 270 CustomOffline 164
brand 123 CyberCash 7, 165
branding 212, 307 CyberSource 165
brands 13 CyberSource Transaction Server 165

D IPS 163
database 25, 30 issuer domain 117
autostart 83
DB2 172, 277
dbora 83
J
Japanese Payment Option 116
debit card 12 Java Development Kit 277
deposit function 259 Java Servlets 16, 20
DES3 145 JDBC 25
Diners Club 123 JDBC driver 39, 103
direct debits 12 JPO 116
E K
ECML 15 KitCash cassette 273, 309
Electronic commerce modelling language 15
encryption 65, 145
e-Visa 142 L
EXTSHM 47 LDAP 222
LdbCard 274, 278, 299
luhn check 13
F Lynk Systems 166
FDMS 165
First Data Merchant Services 165
frame relay 143, 145 M
framework 13, 23 MasterCard 109, 123
full SET 114 MCK 165
merchant 5, 17, 32, 110, 111, 113, 142, 145, 150
merchant administrator 184
G merchant certificate 128
GlobalCollect 166 Merchant Initiated Authorization 114, 128
Merchant Originated Payment 115
H merchant profile 150
HACMP 33 MIA 114, 128
half SET 114 MIACashier 250
MOP 115
I
IBM HTTP Server 6, 16, 31, 277 N
InFashion 183 Net8 86
installation 29 Netscape Communicator 55
AIX 41 network dispatcher 34
planning 30 ntservice 40
SET cassette 117
Solaris 53
Windows 37
O
OfflineCard 43, 164, 184
installments 12 Oracle 16, 54
integrity 110 Oracle8i 66
interchange domain 117 order class 296
iPlanet 54 orders 254
iPlanet Web Server 57 approving 254
P services 40
Payflow Pro 166 SET 3, 6, 7, 14, 109, 162, 166
PayGen 278 architecture 110
PaylinX 166 SET extension 114, 116
payment class 296 SET wallet 178, 192
Payment Engine 20, 21, 23 shopping basket 13
payment gateway 113 Signio 166
Payment Manager API 13, 15, 18 Single sign-on 226
Payment Manager framework 308 SOCKS 191
Payment Manager Presentation Language 19 SSL 3, 19, 29, 59, 107, 114
Payment Manager Query engine 21, 24 stylesheet 212, 220
Payment Manager role 183
Payment Manager servlet 20
Payment Manager user interface 19
T
tablespace 84
payment protocol 14, 17, 159 TCL 50
Payment Registry 111 tracing 231
payment server 113 transaction 5, 110
Payment Server Presentation Language 275 trust 109
PMCustomUI.properties 212, 219
PPP 145
prerequisites 31 U
PSDefaultRealm 223 UDB 7, 16
PSPL 19, 23, 275 UI servlet 21, 22
PSWAS2Realm 223 Universal DataBase 7
purchase orders 11 users 222
PVC 145 UUNET 145
R V
realm 170, 222 VeriSign 109, 166
ReceivePayment 307 VIPG 143
Redbooks Web site virtual hosts 35, 107
Contact us xiii Virtual Private Network 145
remote database 40 VirtualNet IP Gateway 145
remote HTTP server 41 Visa 109, 117, 123
RiTA 166 Visa 2nd Generation 143
Visa Authenticated Payment 142
Visa VirtualNet Internet Payment Gateway 143
S VisaNet 141, 167
sale function 258 Vital Processing Services 142
Sample Checkout 253
sample checkout 133
Sample Store 302 W
SampleCheckout 151, 306 wallet 14, 128
SampleRealm 233 wcsadmin 183
Secure Electronic Transaction 3, 109 WebSphere Application Server 16, 30, 277
Secure Socket Layer 3 WebSphere Application Server, Advanced Edition
security 5 7
server-based wallet 112 WebSphere Commerce Suite 6, 13, 20, 169, 274
service providers 17 WebSphere Commerce Suite Marketplace Edition
Index 331
169
wireless payments 10
X
XML 16, 19, 24
e-commerce Payment Solutions Implementation and Integration Using IBM WebSphere Payment Manager
(0.5” spine)
0.475”<->0.875”
250 <-> 459 pages
Back cover ®

Using IBM WebSphere Payment
Manager
Planning and This redbook describes the requirements for implementing

installing payment e-commerce payment solutions in today’s dynamic Web
INTERNATIONAL
solutions environment. It provides guidance for architects and TECHNICAL
developers who will use WebSphere Payment Manager as SUPPORT
Integration with part of a full e-commerce payment solution. ORGANIZATION
payment protocols
It details the role that WebSphere Payment Manager plays in
an e-commerce solution and describes how to install and
Payment Manager configure Payment Manager to meet different requirements. BUILDING TECHNICAL
and WebSphere INFORMATION BASED ON
Commerce Suite PRACTICAL EXPERIENCE
The redbook shows how to integrate WebSphere Payment
Manager with SET and VisaNet using the cassette features
provided. Further details are provided about the range of IBM Redbooks are developed by
available cassettes that allow WebSphere Payment Manager the IBM International Technical
to interact with many different payment protocols. Support Organization. Experts
from IBM, Customers and
Partners from around the world
We show the way in which WebSphere Payment Manager is create timely technical
used in WebSphere Commerce Suite to provide an integrated information based on realistic
payment solution. scenarios. Specific
recommendations are provided
to help you implement IT
Examples show how the WebSphere Payment Manager APIs
solutions more effectively in
can be used to customize the product, and how to develop your environment.
cassettes so that WebSphere Payment Manager can be used
with different payment protocols.
For more information:

ibm.com/redbooks
SG24-6177-00 ISBN 0738423173

eCommercePaymentSolutions sg246177

Încărcat de

Informații document

Descriere originală:

Titlu original

Drepturi de autor

Formate disponibile

Partajați acest document

Partajați sau inserați document

Opțiuni de partajare

Vi se pare util acest document?

Este necorespunzător acest conținut?

Drepturi de autor:

Formate disponibile

eCommercePaymentSolutions sg246177

Încărcat de

Drepturi de autor:

Formate disponibile

Front cover

e-commerce Payment Solutions

Planning and installing payment

Integration with payment

Payment Manager and

e-commerce Payment Solutions

First Edition (October 2001)

Comments may be addressed to:

© Copyright International Business Machines Corporation 2001. All rights reserved.

Chapter 1. Introduction to payments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Chapter 2. Payment solutions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Chapter 3. Installation and configuration . . . . . . . . . . . . . . . . . . . . . . . . . 29

© Copyright IBM Corp. 2001 iii

Chapter 4. Integration with SET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

Chapter 5. Integration with VisaNet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141

Chapter 6. Integration using other payment cassettes . . . . . . . . . . . . . . 159

Chapter 7. Integration with WebSphere Commerce Suite . . . . . . . . . . . . 169

Chapter 8. Customization using the payment API . . . . . . . . . . . . . . . . . . 211

Chapter 9. Cassette development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273

Appendix A. Additional material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317

Related publications . . . . . . . . . . . . . . . . . . . . . . ...... ....... ...... . 319

Special notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325

Abbreviations and acronyms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327

This redbook describes the requirements for implementing e-commerce payment

We explain the role that WebSphere Payment Manager plays in an e-commerce

We examine the way in which WebSphere Payment Manager is used in

The team that wrote this redbook

Bill Moore is a WebSphere Specialist at the International Technical Support

© Copyright IBM Corp. 2001 ix

Jose Novillo is an IT Specialist in Spain. He has three years of experience in the

Reto Sigl is an IT Specialist in Switzerland. He has five years of experience in

Thanks to the following people for their contributions to this project:

We want our IBM Redbooks to be as helpful as possible. Send us your

Chapter 1. Introduction to payments

© Copyright IBM Corp. 2001 1

1.1.1 Who should read this book

1.1.2 How this book is structured

1.2 Payment history

1.2.1 Credit cards

Chapter 1. Introduction to payments 3

1.2.2 Internet payment

As more financial transactions were performed online, payment methods were

1.3.1 Payment service provider is key

Chapter 1. Introduction to payments 5

Technologies for improving security

1.5 IBM WebSphere Payment Manager

Figure 1-1 WebSphere Payment Manager infrastructure

Chapter 1. Introduction to payments 7

The transaction software called cassettes might sometimes be restricted to

Chapter 2. Payment solutions

© Copyright IBM Corp. 2001 9

In this chapter we detail some of the requirements expected of payment solutions

2.1.1 Wireless payments

2.2 Emerging payment challenges

Decisions would have to be made whether these features were supported in a

Chapter 2. Payment solutions 11

Multiple payments installments

WebSphere Payment Manager 2.2 also integrates into the WebSphere

2.3.1 Integration considerations when using Payment Manager

One example is the process of collecting registration or subscription fees via

At the checkout page your application could:

Chapter 2. Payment solutions 13