Java API Reference Guide
Transcript of Java API Reference Guide
Java API Reference Guide
Merchant Payment Service
Simple. Secure. Smart.™
i
Java API Reference Guide
Document Information
Document Name Java API Reference GuideDocument Part Number M-3030Product Version Merchant Payment Service 1.0Document Revision 1.0
This documentation and the software described constitute proprietary and confidential information protected by copyright laws, trade secrets, and other laws. No part of this publication may be reproduced or distributed in any form or by any means, or stored in a database or retrieval system, without the prior written permission of Achex, Inc.
© 2000 Achex, Inc. All rights reserved.
Achex and Simple. Secure. Smart. are trademarks of Achex Inc. Other product and company names mentioned herein may be the trademarks of their respective owners.
ii Requirements
Contents
Contents_____________________________________________________________________iii
Preface_______________________________________________________________________5
Chapter 1 The Java API______________________________________________________6
Chapter Contents_______________________________________________________________6
Additional Resources____________________________________________________________8
Chapter 2 Requirements______________________________________________________9
Chapter Contents_______________________________________________________________9
Assumptions___________________________________________________________________9
Software______________________________________________________________________9
Hardware____________________________________________________________________10
Chapter 3 Installing and Integrating the Java API________________________________11
Chapter Contents______________________________________________________________11
Pre-Installation Steps__________________________________________________________11
Installation Steps______________________________________________________________11
Achex API Installation_______________________________________________________12
Install Documentation_______________________________________________________12
Install the JavaScript API____________________________________________________12
Post-Installation Steps__________________________________________________________12
Generating Public/Private Key Pair____________________________________________12
Testing____________________________________________________________________12
How to Use the Java API________________________________________________________14
JavaDocs__________________________________________________________________14
Sample Java API code_______________________________________________________14
Where to Use the Java API___________________________________________________14
Integration___________________________________________________________________15
Keys()_____________________________________________________________________15
Setting Proxy Information____________________________________________________16
KeyTransfer()______________________________________________________________17
iii
Retrieve Achex public key from Achex._________________________________________17
Sending Public Key to Achex__________________________________________________17
DigitalSignature()___________________________________________________________17Generating a Digital Signatures_______________________________________________17
ClearanceGenerator()________________________________________________________18
FileTransfer()______________________________________________________________19
SettlementProcessor()_________________________________________________________21
iv
Preface
Intended Audience
This guide is a technical reference for the Java version of the Achex Payment System Application Programming Interface (API). This guide is intended for persons installing and deploying the Achex Payment System on a Merchant e-commerce platform.
How This Guide is Organized
This guide serves as the primary information source for Achex Java APIs contained in the Merchant Integration Kit. Topics include:
The Java API
Describes the contents of the Merchant Integration Kit and the Java API components.
Requirements
Lists assumptions, hardware and software requirements.
Installing and Integrating the Java API
5
Chapter 1 The Java API
Chapter Contents
In this chapter:
The Java API
Additional Resources
The Java API
Achex provides an Application Programming Interface (API) for Java-based eCommerce platforms. There are two kits available to Merchants from Achex, one supporting JDK 1.1 and one supporting JDK 1.2. Both MIKs are identical excluding three JDK dependent Java classes. Methods, constructors, and errors within each class share the same names and can be called and implemented similarly.
Developers should be aware that while each Java MIK is only compatible with its respective JDK, the APIs are called and implemented the same way for each Java MIK.
Please make sure that you are installing the correct version of the Java MIK to support your installed version of the JDK.
JDK Supported UseJDK 1.1.8 JavaMIK 1.1JDK 1.2and above JavaMIK 1.2
The following files are included in the Java MIK:
6
File Name Contains Descriptionachex_logo.gif n/a Used on the Merchant siteachexmik11.jar OR achexmik12.jar Depending on JDKversion in use by Merchant
Achex Java classes Contains all Achex Java classes used to support authorization and Clearing/Settlement transactions, as well as generate public/private keys and digital signatures.
jaxp.jar version 1.0 Third-party Java classes Third-party Java classes used for XML parsing
parser.jar version 1.0 Third-party Java classes Third-party Java classes used for XML parsing
jce.zip version 1.1 OR jce.zip version 1.2
Third-party Java classes JDK dependent Java Cryptography Extension. Contains encryption/decryption used by the Achex Java API.
javadocs directory HTML javadoc files containing detailed documentation about Java classes found within the Java APIs
HTML files
readme.txt n/a Release notes and important last minute in-formation about the MIK.
Java API Reference Guide.pdf
n/a This document
Merchant Integration Guide.pdf
n/a A high-level overview of how to integrate the Achex Payment System.
JavaScript API A JavaScript API used to call the Achex Authorization window during the Authorization process.
n/a
achexmik<VERSION NUMBER>test.jar
testing APIs Contains JDK dependent version of testing APIs, including Junit, a freeware API to perform post-installation testing of the Achex Java APIs, as well as test files.
public_license.doc n/a A Microsoft Word file containing the licensing agreement for Junit.
Achex provides six core Java classes within the achexmik.jar file, with each core class supported by a helper class. A core class is called directly by the Merchant’s system. A helper class is not directly implemented or called by the Merchant system, but is called by an Achex API to handle error exceptions or to interact with other APIs.
Installing and Integrating the Java API 7
Name DescriptionClearanceGenerator API Core class. The ClearanceGenerator API
provides methods for creating XML Clearing files.
XMLException XML exception class.DigitalSignature API Core class. The DigitalSignature API
provides methods for generating and verifying digital signatures.
SignatureException DigitalSignature exception classFileTransfer API Core class. The FileTransfer API provides
methods for sending a Clearing file and requesting a Settlement file. Requires Merchant file transfer password to communicate with Achex.
FileTransferException A helper file to handle FileTransfer API errors.
Keys API Core class. The Keys API provides methods for generating a public/private key pair. Achex and Merchants use keys to digitally sign and verify the authenticity of passed information. A public key can be made public and given to others. Merchants must never distribute a private key to anyone outside of the organization that owns the key.
KeyException Keys exception class.KeyTransfer API The KeyTransfer API provides methods
for transferring public keys. Use this API to obtain Achex public keys and to send Merchant public keys to Achex. Requires Merchant password to communicate with Achex.
KeyTransferException KeyTransfer exception class.SettlementProcessor API Core class. The SettlementProcessor API
provides methods for processing XML Settlement files.
SettlementException API A helper file to handle Settlement API errors.
Additional Resources
For more information about the Achex Java APIs, including constructor, method, and error descriptions, please refer to the JavaDocs included with the Java MIK.
The Java MIK includes sample API code.
For more information about the JCE API, go to:
http://www.openjce.org/
For more information about the jaxp and parser APIs, go to:
http://java.sun.com/xml/download.html
8 Requirements
Chapter 2 Requirements
Chapter Contents
In this chapter:
Assumptions
Software
Hardware
Assumptions
Installing the Java API requires both back office and website integration on the merchant’s eCommerce system. This document assumes that the person or persons installing the kit have:
Read and understood the Merchant Integration Guide Part Number M-3021
Knowledge of Java, JavaScript, and HTML development
Knowledge of the Merchant’s payment process and system
Access to any web and application servers used by the Merchant
Knowledge of and access to the Merchant’s database
Software
This document assumes that either the Java Development Kit (JDK) version 1.1.8 or version 1.2 and above is installed and running on the Merchant’s system. For more information about the JVM 1.1, please refer to:
http://java.sun.com/products/jdk/1.1
For more information about the JVM 1.2, please refer to:
http://java.sun.com/products/jdk/1.2
Depending on which JDK version in use by the Merchant, Achex will provide the appropriate Merchant Integration Kit (MIK) containing Java APIs to support JDK 1.1.8 or JDK 1.2 and above.
Installing and Integrating the Java API 9
Hardware
While the Java API in itself imposes no hardware requirements, other required software, such as the installed JDK, may specify requirements for different platforms. Please refer to your JDK documentation for specific hardware requirements.
10 Requirements
Chapter 3 Installing and Integrating the Java API
Chapter Contents
In this chapter:
Pre-Installation Steps
Installation Steps
Post-Installation Steps
How to Use the Java API
Integration
Pre-Installation Steps
Each Java MIK includes API components that must be installed on the Merchant’s eCommerce system. Before installing the Achex components, the Merchant needs to perform the following pre-installation steps:
1. Read and understand the ReadMe First file enclosed with the Java MIK for release notes and any important last minute information.
2. Identify the integration points within the Merchant eCommerce application where the Java MIK is to be installed. Integration points can include web pages on the Merchant site and code to be installed on the Merchant’s application server. Since each Merchant’s eCommerce configuration may be different, it is the Merchant’s responsibility to identify how best to install the Java MIK on their system.
3. Satisfy all data modeling requirements as defined in the Merchant Integration Guide Part Number M-3021.
4. Provide Merchant passwords to Achex. Merchant passwords are required for FileTransfer and KeyTransfer APIs.
Installation Steps
Since eCommerce systems may vary considerably from Merchant to Merchant, the instructions in this chapter describe only general instructions and in some cases recommendations for installation. This document presents the following instructions as recommended guidelines. Your own system or policies may differ from Achex’s recommended installation instructions. Before installing the MIK, the Merchant should decide where on the system the Java components will reside and how to modify the CLASSPATH environment variable
11
accordingly. Please refer to your platform specific documentation on how to create folders, copy files, and set environment variables.
Achex API InstallationTo install the Achex API:
1. Copy the utility jar files and the main Achex jar file located in the lib directory of the MIK CD to the appropriate location within your environment.
2. Include the following jar files into your system's CLASSPATH variables.
jaxp.jar
jce.zip
achexmik1x.jar (x is dependant upon version)
parser.jar
Install DocumentationAchex includes the following documentation in the Achex MIK:
Java API Reference Guide Part Number M-3030 (this document)
Merchant Integration Guide Part Number M-3021
JavaDoc
The JavaDoc is included within the doc/javadoc directory on the MIK CD. The JavaDoc is provided as a technical tool to assist in the integration of Achex's API into your environment. You can view the documentation directly from the CD or copy it locally.
Install the JavaScript APIDuring the transaction process, an Authorization window launches from the Merchant page in order to transmit transaction information and required data fields from the Merchant site to Achex. The Authorization window remains resident until the customer completes the transaction. Achex provides the JavaScript API that generates the Authorization window from the Merchants site. The JavaScript API should be added to the Merchant system, integrated where the customer submits a request for an Achex payment authorization.
Post-Installation Steps
Generating Public/Private Key PairMerchants generate a public/private key pair using the Achex Keys API before using the Achex Payment System. Once generated, Achex strongly advises that the Merchant securely store the private key.
A private key that is stolen or made in any way public compromises the security of transactions between Achex and the Merchant. Securely store all private keys and never distribute outside of your secure environment.
TestingAchex includes in the MIK a freeware utility called JUnit. The Achex implementation of JUnit:
12
Automates testing of basic API installation
Tests functionality of Achex APIs within the Merchant environment
Ensures that the CLASSPATH variable has been properly configured
To install the Achex test framework:
Copy the files located in the test directory of the CD to the appropriate location within your environment.
The Jar files will be included and will need to be incorporated into your systems CLASSPATH variables
test.jar
achexmik1xtest.jar
To run JUnit within a Microsoft Windows environment:
1. From the command line, change to the directory path where the test files are located.
2. Type in the following command:
java test.ui.TestRunner test.com.achex.merchant.security.KeysTest
and press Enter.
Within a few seconds a graphical interface appears. The interface presents a window with the following:
a field in which to type the name of a class with a suite method
a Run button to start the test
a progress indicator that reports the number of test runs, errors, and failures
a list of failed tests
in the case of an unsuccessful test, JUnit reports the failed tests in a list at the bottom of the window. To find out more about a failure or an error, select the item in the list and click Show to display a stack trace for each of the failure. Make sure to review and document each trace to help determine where the error resides.
a Quit button, when you are finished reviewing the test results
3. Type in the following command:
java test.ui.TestRunner test.com.achex.merchant.security.DigSigTest
and press Enter.
4. Review the results and click the Quit button when finished reviewing the test results.
Installing and Integrating the Java API 13
5. Type in the following command:
java test.ui.TestRunner test.com.achex.merchant.xml.GenerateClearanceTest
and press Enter.
6. Review the results and click the Quit button when finished reviewing the test results.
7. Type in the following command:
java test.ui.TestRunner test.com.achex.merchant.xml.ProcessSettlementTest
and press Enter.
8. Review the results and click the Quit button when finished reviewing the test results.
How to Use the Java API
JavaDocsThe most current documentation describing the constructors, methods, and errors for the Achex Java API is found in javadoc.zip, included within the Java MIK.
Sample Java API codeThe most recent sample API code is included within the Java MIK.
Where to Use the Java APIWhile most of the Java API performs transparently in the background of an Achex transaction, it is useful to understand where in the transaction process the Java API is called and it is used. The following table describes the Authorization and Clearing/Settlement processes in relation to the Java API.
14 Installing and Integrating the Java API
Step Component ActionPost-installation of MIK Keys API KeyTransfer API Generate and transfer
Merchant public/private key pair.
Authorization: Merchant generates In Progress page. Hidden fields submitted to Achex.
DigitalSignature API Merchant generates a digital signature for the authorization and sends the digital signature to Achex.
Authorization: Achex generates Authorization window
JavaScript API Launches Authorization window.
Authorization: Achex verifies authorization and sends response to Merchant.
DigitalSignature API Merchant receives and verifies Achex digital signature.
Authorization: Achex sends confirmation of authorization to Merchant.
DigitalSignature API Merchant receives and verifiesAchex digital signature.
Authorization: Achex sends an invalid authorization error to Merchant.
DigitalSignature API Merchant receives and verifies Achex digital signature.
Clearing: Merchant generates and transmits XML Clearing files to Achex.
DigitalSignature API ClearanceGenerator API FileTransfer API
Merchant generates a digital signature and an XML Clearing file, and transmits to Achex.
Settlement: The Merchant retrieves Settlement files from Achex with a list of failures.
DigitalSignature API SettlementProcessor API FileTranfer API
Merchant receives and verifies Achex digital signature, receives and parses Settlement files.
Integration
A sample file for each API is located in the samples directory of the MIK. Achex recommends that the Merchant review the JavaDoc included in the MIK, and that the Merchant use the exception handling provided with each API.
If you should need assistance, please contact Achex Merchant Services at 1-887-55Achex.
Keys()The Merchant generates a public/private key pair using the Achex Keys API. A public/private key set uses encryption technology which ensures no one but the Merchant can interact with Achex and which protects against message interception.
The following is a brief example of the java code that will produce the Merchant’s public and private key. KeySample.java is included in the MIK in the samples directory.
Keys keys = new Keys()
// Display the public and private keys
System.out.println(keys.getPublicKey());
Installing and Integrating the Java API 15
System.out.println(keys.getPrivateKey());
The Merchant will need to store the strings in appropriate location with their environment.
Each key is structured in the following format:
VersionID | KeyVersionID | DSAPublicKey | RSAPublicKey
VersionID contains either “J1.1” or “J1.2” – refers to the version of source code used to create public key
KeyVersionID is a time/date stamp when the key() is created
DSAPublicKey is the digital signature algorithm
RSAPublicKey is the encryption algorithm
Once the public and private keys have been produced, the Merchant stores both keys within their environment.
A private key that is stolen or made in any way public compromises the security of transactions between Achex and the Merchant. Securely store all private keys and never distribute outside of your secure environment.
Setting Proxy InformationFor both the KeyTransfer() and the FileTransfer() APIs, the Merchant may need to set the proxy information. Below is an example of the setting the Merchant may have to set. This code is also contained with the sample Java for KeyTransfer() and FileTransfer() provided in the MIK.
Set proxy information
// Socks4
props.put("socksProxySet", "true");
props.put("socksProxyHost", "put.proxy.host.name.here");
props.put("socksProxyPort", "put.proxy.host.port.here");
// Non-Socks4
props.put("proxySet", "true");
props.put("proxyHost", "put.proxy.host.name.here");
props.put("proxyPort", "put.proxy.host.port.here");
To set the proxy username and password, the following can be used as example:
String unamePassword = "put_username_here:put_password_here"; // colon-
16 Installing and Integrating the Java API
KeyTransfer()The Merchant retrieves Achex public key using the KeyTransfer API. The Merchant sends the Merchant’s public key to Achex using the KeyTransfer API. Key transfer must happen in this order. To provide additional security, Achex requires a Merchant Transfer Password when using the KeyTransfer API to validate the Merchant’s identity.
Retrieve Achex public key from Achex.The Achex Public Key verifies that the information the Merchant receives is coming from Achex and has not been altered.
The Merchant will need to use the setGetKeyURL method to set the appropriate URL to retrieve Achex Public Key.
Using the following method retrieve the Achex Public Key and store within their data environment:
publicjava.lang.String getAchexPublicKey(java.lang.String merchantPublicKey).
Sending Public Key to AchexAchex uses the public key produced through the Keys() API to verify that the data the Merchant submits has not been altered.
Use the setSendKeyURL method to set the appropriate URL to send the Merchant’s public key.
The Merchant will provide the following parameters to submit the key to Achex including the Merchant Public Key, Achex Public Key and a Key Transfer Password. The following of the java code and structure:
public void sendMerchantPublicKey(java.lang.String merchantPublicKey, java.lang.String achexPublicKey, java.lang.String keyTransferPassword)
DigitalSignature()The Merchant creates a digital signature every time information is submitted to Achex.
Generating a Digital SignaturesTo generate a digital signature, the Merchant uses the Merchant Private Key, a message, and specifies whether sort is on or off. During Authorization the Merchant must to set the sort value to true. During Clearance the Merchant can set the sort order to on or off.
The first example uses an authorization request as the message. When creating a digital signature, the message or data that needs to be incorporated is the value of the form field. The second example uses the Java method as a base while the third example shows the method with the appropriate parameters specified.
Example One
<INPUT TYPE="HIDDEN" NAME="trackingID" VALUE="10">
<INPUT TYPE="HIDDEN" NAME="merchantID" VALUE="10">
Installing and Integrating the Java API 17
<INPUT TYPE="HIDDEN" NAME="amount" VALUE="10">
<INPUT TYPE="HIDDEN" NAME="returnURL" VALUE="http://10.10.10.108/merchant/jsp/AuthReturn.jsp">
<INPUT TYPE="HIDDEN" NAME="authType" VALUE="10">
<INPUT TYPE="HIDDEN" NAME="authAction" VALUE="20">
Example Two
DigitalSignature sigGen = new DigitalSignature();
sigGen.addData("data item 1");
sigGen.addData("data item 2");
sigGen.addData("data item ...");
Sig = sigGen.generateSignature(keys.getPrivateKey(), true);
Example Three
DigitalSignature sigGen = new DigitalSignature();
sigGen.addData(trackingID);
sigGen.addData(merchantID);
sigGen.addData(amount);
sigGen.addData(returnURL);
sigGen.addData(authType);
sigGen.addData(authAction);
Sig = sigGen.generateSignature(keys.getPrivateKey(), true);
ClearanceGenerator()The Merchant generates Clearance files using the ClearanceGenerator() API.
To generate a clearance file:
1. Create the object:
ClearanceGenerator cg = new ClearanceGenerator("test.xml");
18 Installing and Integrating the Java API
2. To create transaction within the XML file, call the "set" methods to set the data, and then add the transaction:
ClearanceTransaction trans = new ClearanceTransaction();
trans.setMerchantID(merchantID); // (for example)
3. The Merchant can add as many transactions to the file as necessary by using the following methods:
cg.addTransaction(trans);
4. After the Merchant adds all transactions, set the clearance header along with the ClearerID (also referred to as MerchantID):
ClearanceHeader header = new ClearanceHeader();
header.setClearerID(clearerID);
5. Set the Digital Signature:
header.setDigitalSignature(cg.generateDigitalSignature(merchantPrivateKey, header));
6. Set the clearance file:
cg.setHeader(header);
7. Get the XML string:
String contents = cg.getContents();
8. Write contents to file:
cg.writeContentsToFile();
FileTransfer()Use FileTransfer() to send and receive files.
To send clearance files to Achex:
1. Set the Upload URL:
public void setUploadURL(java.lang.String uploadURL)
2. The object must be created with all appropriate parameters including ClearerID (MerchantID if no CSP is employed), FileTransfer Password, Achex Public Key, Clearer (Merchant) Public Key and Clearer (Merchant) Private Key:
FileTransfer ft = new FileTransfer(clearerID, merchantPassword, achexPublicKey, merchantPublicKey, merchantPrivateKey);
3. Upload the files:
Installing and Integrating the Java API 19
ft.addFile("clearingFile_1.xml");
ft.addFile("clearingFile_2.xml");
4. Send the files to Achex using the send method:
ft.sendFiles();
5. The system returns either a Success or Failed response
if (ft.getStatus() == FileTransfer.SUCCESS)
System.out.println ("File transfer successful.");
else
System.out.println ("File transfer failed.");
To retrieve Settlement files:
1. Set the download URL:
public void setDownloadURL(java.lang.String downloadURL)
2. To retrieve the files waiting to be downloaded:
Vector fList;
3. Specify the download path, including operating system specific '/' or '\' at end of path string.
ft.setDownloadPath("/home/weblogic/achex/");
4. Use the downloadSettlementFiles method to retrieve the files:
fList = ft.downloadSettlementFiles();
The system lists the files that were downloaded or return a Failed response
if (ft.getStatus() == FileTransfer.SUCCESS)
// List of successfully downloaded files
for (int i=0; i<fList.size(); i++)
else
System.out.println ("File transfer failed...");
20 Installing and Integrating the Java API
SettlementProcessor()The SettlementProcessor() API extracts information from the files received from Achex.
1. Create the object to process an XML file
SettlementProcessor sp = new SettlementProcessor(filename, achexPublicKey);
2. Verify the Achex digital signature:
sp.isValidDigitalSignature()
3. Get all of the transactions:
Vector transactions = sp.getAllTransactions();
if (transactions != null)
int numTrans = transactions.size();
4. Process each of the transactions:
SettlementTransaction trans = (SettlementTransaction)transactions.elementAt(i);
5. Use the "get" methods to access the transaction's data items:
trans.getTrackingID(), trans.getAction(), trans.getAmount(), and so on.
Installing and Integrating the Java API 21