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.


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


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.



java test.ui.TestRunner test.com.achex.merchant.xml.GenerateClearanceTest

and press Enter.



java test.ui.TestRunner test.com.achex.merchant.xml.ProcessSettlementTest

and press Enter.


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());


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-


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">


<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");


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:


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...");


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.


java api reference guide

Documents