SecureJava User Manual Secure Java4User

User Manual:

Open the PDF directly: View PDF .
Page Count: 43

Commercial-In-Confidence

Document Group Document Category Copy No.

SecurePay Technologies Software User Manual

Document Number Document Version Effective From

SEC-SPT-JAVA-SUM 4.3.1 11 October, 2006

Change and Approval Authority Department Manager

Document Approved for

Issue and Use _________________________

(Name – printed)

______________________

(Signature)

SECUREPAY TECHNOLOGIES

SECUREJAVA API

SOFTWARE USER MANUAL

PREPARED FOR

SECUREJAVA MERCHANTS

Commercial-In-Confidence

Document Number:

SEC-SPT-JAVA-SUM Document Version:

4.3.1 2 of 2 pages

SECUREPAY TECHNOLOGIES © SecurePay Pty Ltd

DOCUMENT REVISION HISTORY

Effective From

Author of

Change Version Change Description

20 Mar 2003 Andrew

McCutcheon 4.0 a Initial release of SecureJava with enhanced functionality to

production system.

16 Apr 2003 Andrew

McCutcheon 4.0.3 a • Added support for card-present payments, and “Track 2” data.

[4.2.1.2.3.7] [4.2.1.2.3.34] [Appendix A: Transaction Types]

• Requirement for password to be sent with all message types.

[4.2.1.1.2.10] [4.2.2.1.2.8]

• Ability to call process() repeatedly on an instance of an object.

[4.2.1.1.2.10] [4.2.2.1.2.8]

• Added Transaction Type Required Field Map to the document.

[4.2.1.2.1]

28 Jul 2003 Tom Dyjak 4.1 • Added support for Direct Entry payments (BSB and account

numbers, account name).

12 Nov 2003 Tom Dyjak 4.1 • Corrected Echo request description.

• Changed URLs in sample code.

19 Jan 2004 Andrew

McCutcheon 4.1.1 • Added support for multi-currency. Payment messages allow the

user to get and set currency codes.

[4.2.1.2.3.3] [4.2.1.2.3.27] [Appendix H: Currency Codes List]

Check with SecurePay for details on which banks are supported

for multi-currency at this time.

01 Jul 2004 Andrew

McCutcheon 4.1.2 • Updated currency code table to include examples of how

different currencies and amounts should be passed. [Appendix

H: Currency Codes List]

• Added method getAdditionalInfo() to Payment object, for future

use. [4.2.1.1.2.16]

• Added section on appropriate usage of Echo messages. [4.2.2.1]

8 Jul 2004 Tom Dyjak 4.1.2.1 • Added clarification on characters allowed in purchase order

number and account name fields for Direct Entry Transactions.

4 Feb 2005 Tom Dyjak 4.3 • Added support for antifraud transaction types

11 Oct 2006 Tom Dyjak 4.3.1 • Added support for cardless refunds

Commercial-In-Confidence

Document Number:

SEC-SPT-JAVA-SUM Document Version:

4.3.1 3 of 3 pages

SECUREPAY TECHNOLOGIES © SecurePay Pty Ltd

TABLE OF CONTENTS

1. INTRODUCTION........................................................................................................................ 5

1.1 SYSTEM OVERVIEW ..................................................................................................................... 5

1.2 DOCUMENT AUDIENCE ................................................................................................................. 5

2. SOFTWARE INTRODUCTION................................................................................................. 5

2.1 FUNCTIONALITY AVAILABLE .......................................................................................................... 5

2.1.1 Payment ............................................................................................................................5

2.1.2 Echo..................................................................................................................................6

2.2 COMMUNICATION & ENCRYPTION ................................................................................................. 6

3. SOFTWARE INSTALLATION................................................................................................... 7

3.1 PREREQUISITES........................................................................................................................... 7

3.2 SOFTWARE INVENTORY................................................................................................................ 7

3.3 INSTALLATION .............................................................................................................................. 7

4. SOFTWARE INTEGRATION.................................................................................................... 8

4.1 CLASSPATH SETUP ...................................................................................................................... 8

4.2 INTERFACE .................................................................................................................................. 8

4.2.1 Payments...........................................................................................................................8

4.2.1.1 securepay.jxa.api.Payment ...........................................................................................8

4.2.1.2 securepay.jxa.api.Txn ................................................................................................ 14

4.2.1.3 Payment Sample Code............................................................................................... 31

4.2.1.4 Refund Sample Code................................................................................................. 32

4.2.2 Echo................................................................................................................................ 34

4.2.2.1 securepay.jxa.api.Echo .............................................................................................. 34

4.2.2.2 Echo Sample Code .................................................................................................... 37

APPENDIX A: TRANSACTION TYPES........................................................................................... 39

APPENDIX B: TRANSACTION SOURCES..................................................................................... 39

APPENDIX C: CARD TYPES........................................................................................................... 40

APPENDIX D: LOCATION OF CVV ................................................................................................. 40

APPENDIX E: TIMESTAMP STRING FORMAT .............................................................................. 40

APPENDIX F: SECUREPAY STATUS CODES............................................................................... 41

APPENDIX G: THINLINK CODES.................................................................................................... 41

G.1 PAYMENT RESULT CODES............................................................................................................. 41

G.2 EVENT STATUS CODES ................................................................................................................. 41

APPENDIX H: CURRENCY CODES LIST ....................................................................................... 42

APPENDIX I: DIRECT ENTRY CHARACTER SET ......................................................................... 43

Commercial-In-Confidence

Document Number:

SEC-SPT-JAVA-SUM Document Version:

4.3.1 4 of 4 pages

SECUREPAY TECHNOLOGIES © SecurePay Pty Ltd

Commercial-In-Confidence

Document Number:

SEC-SPT-JAVA-SUM Document Version:

4.3.1 5 of 5 pages

SECUREPAY TECHNOLOGIES © SecurePay Pty Ltd

1. Introduction

1.1 System Overview

SecurePay‘s Payment Gateway allows SecurePay customers, or “merchants” to process credit card

payments in real time, with any of the six major Australian banks—Westpac (including Challenge Bank and

Bank of Melbourne), Commonwealth Bank, National Australia Bank, St George (including Bank of SA),

BankWest, and ANZ.

SecurePay’s Direct Entry Gateway allows SecurePay merchants to process direct entry payments. The

payments are stored in SecurePay database in real time but the processing between financial institutions

involved doesn’t take place until 5pm each weekday.

SecurePay provide many methods for customers to connect to our system, from hosted payment pages, IVR

telephone access, POS applications, as well as a simple API interface, allowing developers to build their

own products to access SecurePay’s Payment Server directly over an Internet connection.

This API, known as SecureJava, is written in the Sun Java programming language, and can run on any

computer with the Java Runtime Environment installed. Internet communication is done via a secure port

using SSL encryption.

SecureJava supports five (5) credit card transaction types: payment, refund, reversal (or “void”),

preauthorise, and preauthorise complete (or “advice”) and two (2) direct entry transaction types: debit and

credit. SecureJava also allows users to programmatically send an “echo” response to check the server’s

availability.

1.2 Document Audience

This document is intended for developers, integrating SecurePay’s SecureJava API into their own Java

applications, Java-based websites (such as servlets or JSP), or applications that are able to instantiate a

Java object and invoke its methods.

Knowledge of the Java programming language and the Java Virtual Machine is required for some sections of

this document.

2. Software Introduction

2.1 Functionality Available

SecureJava allows access, not only to payments, but various other features of the SecurePay system.

2.1.1 Payment

The Payment command allows merchants to pass financial credit card transaction messages to SecurePay’s

Payment Server, which will authorise the transaction with the merchant’s bank and customer’s card issuer,

and produce a response based on the banks’ authorisation of the transaction. The Payment command also

allows merchants to pass financial direct entry transaction messages to SecurePay’s system.

The Payment object can be used to send transactions of type:

• Credit Card Payment;

• Credit Card Refund;

• Credit Card Reversal (Void);

• Credit Card Preauthorise;

• Credit Card Preauthorise Complete (Advice);

• Antifraud,

• Direct Entry Debit;

Commercial-In-Confidence

Document Number:

SEC-SPT-JAVA-SUM Document Version:

4.3.1 6 of 6 pages

SECUREPAY TECHNOLOGIES © SecurePay Pty Ltd

• Direct Entry Credit.

2.1.2 Echo

The Echo message is used to verify that the SecurePay Payment Server port can be accessed. The Echo

message does not validate any data, but merely sends a request message to SecurePay, and receives a

response message if the SecurePay Server port is open.

2.2 Communication & Encryption

SecurePay’s Payment Server uses TCP/IP for communication with SecureJava.

Communications use SSL to encrypt messages, using SecurePay’s security certificate. When an SSL

connection is negotiated between the client and the server, if the certificates presented do not match, or the

certificate used is not present, has expired, or has been revoked, the connection will not be allowed.

Response messages are also encrypted and passed back via the same secure port, then decrypted by

SecureJava’s security certificate.

Commercial-In-Confidence

Document Number:

SEC-SPT-JAVA-SUM Document Version:

4.3.1 7 of 7 pages

SECUREPAY TECHNOLOGIES © SecurePay Pty Ltd

3. Software Installation

SecureJava has been built using Sun’s Java programming language. Java boasts full software portability,

allowing the same compiled software package to be run independently of the platform on which it is installed.

The SecureJava software package provided can therefore be run on Microsoft Windows, Unix, or Macintosh

platforms without recompiling.

3.1 Prerequisites

1. The installation machine must have the Java Runtime Environment (JRE) installed. SecureJava

currently runs on JRE versions 1.4 and later. The JRE can be downloaded free of charge from the

Sun website: http://java.sun.com

2. The installation machine, and any firewall, etc, in front of it, must be able to create an outbound

socket connection on the communications port, to the SecurePay Payment Server host. Standard

web communication ports will be used initially, however are subject to change in future releases.

Port 80 will be used on SecurePay’s Test Server, and port 443 on SecurePay’s Live Server.

3.2 Software Inventory

The software package contains the following files:

• securepayxmlapi_obf.jar • xmlParserAPIs-2.4.0.jar • xercesImpl-2.4.0.jar

• Base64.jar

3.3 Installation

1. Create a directory on the installation machine called “SecurePayAPI” in a location of your choice.

2. Copy all files listed in the Software Inventory (see 3.2) into this new directory.

Commercial-In-Confidence

Document Number:

SEC-SPT-JAVA-SUM Document Version:

4.3.1 8 of 8 pages

SECUREPAY TECHNOLOGIES © SecurePay Pty Ltd

4. Software Integration

4.1 Classpath Setup

Before running SecureJava, your Java classpath must be set to each of the JAR archives included in this

package. This can be done when executing the Java from the command line, e.g.:

Ø %JAVA_HOME%\bin\java –cp abc.jar;def.jar YourMainClass arg1 arg2

or, by setting the system environment variable “CLASSPATH” before running, e.g.:

Windows:

> set CLASSPATH=abc.jar;def.jar

Unix:

> setenv CLASSPATH abc.jar:def.jar

These commands may also be written in a batch file or shell script for your application.

4.2 Interface

4.2.1 Payments

4.2.1.1 securepay.jxa.api.Payment

The Payment object should be created first, and a Txn object added to it, containing details of the financial

transaction to be processed. The Payment object is then “submitted” to SecurePay to process the

transactions it contains.

4.2.1.1.1 Constructor

public Payment()

Create an empty Payment object to which Txns may be added.

Parameters:

No parameters required by this constructor.

4.2.1.1.2 Public Methods

4.2.1.1.2.1 getMessageId

public String getMessageId()

Returns the unique message identifier created by the API.

Input Parameters:

No input parameters are required by this method.

Return Parameter:

Type Description

String Unique identifier of this Payment object.

4.2.1.1.2.2 getMessageTimestamp

public Date getMessageTimestamp()

Returns the timestamp created by the API for the Payment in a Date object.

Input Parameters:

No input parameters are required by this method.

Commercial-In-Confidence

Document Number:

SEC-SPT-JAVA-SUM Document Version:

4.3.1 9 of 9 pages

SECUREPAY TECHNOLOGIES © SecurePay Pty Ltd

Return Parameter:

Type Description

Date Timestamp of this Payment object.

4.2.1.1.2.3 getMessageTimestampAsString

public String getMessageTimestampAsString()

Returns the timestamp created by the API for the Payment as a string. Refer to Appendix E:

Timestamp String Format for the format returned.

Input Parameters:

No input parameters are required by this method.

Return Parameter:

Type Description

String Timestamp of this Payment object.

4.2.1.1.2.4 getApiVersion

public String getApiVersion()

Returns the version of the API being used to create this object.

Input Parameters:

No input parameters are required by this method.

Return Parameter:

Type Description

String API version used to create this Payment object.

4.2.1.1.2.5 setMerchantId

public void setMerchantId(String id)

Sets the merchant id to be used when processing the payments. The merchant id must be set in

order for SecurePay to determine the bank account to which the funds should be settled.

Input Parameters:

Name Type Description Allowed Values

id String Merchant ID allocated to the

merchant by SecurePay. 7-character string in

format XXXDDDD,

where X is a letter (A-

Z) and D is a digit (0-

9). SecurePay will

supply this value to

you upon application.

For Direct Entry:

5-7 character string in

format XXXDDDD,

where X is a letter (A-

Z) and D is a digit (0-

9). Last two digits

can be ignored.

Return Parameter:

No object returned by this method.

Commercial-In-Confidence

Document Number:

SEC-SPT-JAVA-SUM Document Version:

4.3.1 10 of 10 pages

SECUREPAY TECHNOLOGIES © SecurePay Pty Ltd

4.2.1.1.2.6 setServerURL

public void setServerURL(String url)

Sets the URL of the SecurePay Payment Server to which this object will be sent when process()

is called.

Input Parameters:

Name Type Description Allowed Values

url String URL of SecurePay’s Payment

Server or Direct Entry Server

in case of Direct Entry

payments.

Test:

https://www.securepay.com.au/test/

payment

Live:

https://www.securepay.com.au/xml

api/payment

For Direct Entry:

Test:

https://www.securepay.com.au/test/

directentry

Live:

https://www.securepay.com.au/xml

api/directentry

For Antifraud:

Test:

https://www.securepay.com.au/antif

raud_test/payment

Live:

https://www.securepay.com.au/antif

raud/payment

(Values are subject to change in

future releases.)

Return Parameter:

No object returned by this method.

4.2.1.1.2.7 setProcessTimeout

public void setProcessTimeout(int timeout)

Sets the timeout in seconds to wait for a response message from SecurePay’s server. If no

response is received in this time, a timeout response is returned, and transaction results may be

queried at a later time.

If value is not set, or is set to an integer < 0, default timeout of 80 seconds is used.

Input Parameters:

Name Type Description Allowed Values

timeout int Seconds to wait for SecurePay

response. Int < 0: default value

is used

Int >= 0: supplied

value is used.

Return Parameter:

No object returned by this method.

4.2.1.1.2.8 addTxn

public Txn addTxn(int txnType,

String ponum)

Adds a Txn object to the Payment and returns the object for configuration. If a Txn already exists

with the same txnType and ponum combination, NULL is returned.

Commercial-In-Confidence

Document Number:

SEC-SPT-JAVA-SUM Document Version:

4.3.1 11 of 11 pages

SECUREPAY TECHNOLOGIES © SecurePay Pty Ltd

IMPORTANT NOTE: The current version of SecurePay’s Payment Server allows only Payments containing a

single Txn object. Payments submitted with more than one Txn will be rejected with Status Code “577”.

Multiple transaction batching will be included in a future release, and will be advertised by SecurePay when

available. It is expected that no change will be required to the API to support multi-Txn batches.

As of SecureJava V4.0.3a, it is possible to create a Payment object, add a Txn to it, call process(), then add

another Txn and process() again, as many times as required on a single Payment object.

Since Direct Entry payments are sent to a different URL than credit card payments a separate instance of

Payment Class should be used for processing those payments.

For refunds and reversals the ponum field must be the same as the ponum used for the original payment.

For completes the ponum field must be the same as the ponum used for the original preauthorisation.

Input Parameters:

Name Type Description Allowed Values

TxnType int Integer representing the

transaction type to be

processed.

Refer to Appendix A:

Transaction Types

Ponum String Unique merchant transaction

identifier, typically an invoice

number.

Any alphanumeric string,

up to 60 characters in

length.

For Direct Entry:

Any string using

characters from

Appendix I: Direct Entry

Character set, up to 18

characters in length.

Return Parameter:

Type Description

Txn Instance of the Txn object added to the Payment.

If a Txn with the same identification already exists, then this object is

returned, otherwise a new instance is returned.

4.2.1.1.2.9 getTxn

public Txn getTxn(int txnType, String ponum)

Returns the Txn object from the Payment’s request queue (before calling process()) with a

matching txnType and ponum value. If no such Txn exists, NULL is returned. This method will

always return NULL after a call to process(), as the request queue will be empty.

Input Parameters:

Name Type Description Allowed Values

txnType int Integer representing the

transaction type to be

processed.

Refer to Appendix A:

Transaction Types

ponum String Unique merchant transaction

identifier, typically an invoice

number.

Any alphanumeric string,

up to 60 characters in

length.

Return Parameter:

Type Description

Txn Txn request object matching the txnType and ponum supplied, or NULL if

no such Txn exists.

4.2.1.1.2.10 process

public boolean process(String password)

Commercial-In-Confidence

Document Number:

SEC-SPT-JAVA-SUM Document Version:

4.3.1 12 of 12 pages

SECUREPAY TECHNOLOGIES © SecurePay Pty Ltd

Sends this Payment object and all contained Txns to SecurePay’s Payment Server for processing by

the bank. Method blocks until all transactions contained are processed and a response message is

received, or the process timeout expires (refer to 4.2.1.1.2.7).

As of SecureJava V4.0.3a, the password parameter must be passed to this method. Previous

releases of SecureJava V4.0.x which did not pass a password will no longer be compatible with the

SecurePay Payment Server, as it is now required that a password is used for all financial

transactions and echoes. The password can be changed via SecurePay’s Merchant Login website

by logging in as the “admin” user.

If the merchant Id and password sent do not match those stored in SecurePay’s database, the

response message will have a status code of “550”.

Input Parameters:

Name Type Description Allowed Values

password String The password is configured in

SecurePay’s database per

Merchant ID, and must match

the value passed by this

method for the message to be

accepted and processed.

The password is allocated

to you by SecurePay

when you receive this

software, and can be

changed via the Merchant

Return Parameter:

Type Description

boolean true if message was sent to server correctly and processed (regardless of

the transactions’ outcome), and false if client-side errors occurred

preventing the object from being sent.

4.2.1.1.2.11 getStatusCode

public long getStatusCode()

Returns the status code of the Payment. Refer to Appendix F: SecurePay Status Codes for more

information.

Input Parameters:

No input parameters are required by this method.

Return Parameter:

Type Description

long Code representing the status of the Payment object after processing.

4.2.1.1.2.12 getStatusDesc

public String getStatusDesc()

Returns the status description of the Payment. Refer to Appendix F: SecurePay Status Codes for

more information.

Input Parameters:

No input parameters are required by this method.

Return Parameter:

Type Description

String Textual description of the status of the Payment object after processing.

Commercial-In-Confidence

Document Number:

SEC-SPT-JAVA-SUM Document Version:

4.3.1 13 of 13 pages

SECUREPAY TECHNOLOGIES © SecurePay Pty Ltd

4.2.1.1.2.13 toString

public String toString()

Returns the object with its parameters formatted in a readable string.

Input Parameters:

No input parameters are required by this method.

Return Parameter:

Type Description

String Textual representation of the Payment object.

4.2.1.1.2.14 getCount

public int getCount()

Returns the number of Txn objects contained in this Payment object. Before process() is called,

the number of Txn requests is returned. The number of Txn responses is given after a call to

process().

Input Parameters:

No input parameters are required by this method.

Return Parameter:

Type Description

Int Number of Txn objects

4.2.1.1.2.15 getTxn

public Txn getTxn(int index)

Returns the Txn object from the Payment at the indexth position. This method returns a Txn

request before calling process() or a Txn response after calling process().

Input Parameters:

Name Type Description Allowed Values

index int Index to the Txn object required. int between 0 and

getCount() – 1

Return Parameter:

Type Description

Txn Txn object from requested position.

4.2.1.1.2.16 getAdditionalInfo (Available in software v4.1.2, but not currently in use.)

public String getAdditionalInfo(int index, String fieldName)

Note: This field is not currently in use, and will return a null value if called. SecurePay will

release a list of available fields when they become available.

Returns the value of the specified field from the Txn object at the indexth position. If index is –1,

the field returned is from the Payment object itself.

Input Parameters:

Name Type Description Allowed Values

Commercial-In-Confidence

Document Number:

SEC-SPT-JAVA-SUM Document Version:

4.3.1 14 of 14 pages

SECUREPAY TECHNOLOGIES © SecurePay Pty Ltd

index int Index to the Txn object required, or

–1 to reference the Payment object

itself.

int between –1 and

getCount() – 1

fieldName String Name of field to return from the

object specified by index. Valid field name.

Return Parameter:

Type Description

String Value of field requested, or null if the field does not exist in the

message.

4.2.1.2 securepay.jxa.api.Txn

The Txn object is returned when addTxn(…) is called from a Payment object. The required fields of this

object must be set using “set” functions provided, as described below. When the Payment is submitted and

processed, the result parameters of the Txn can be retrieved using the “get” methods described.

4.2.1.2.1 Transaction Type Required Field Map

The following table specifies which transaction parameters must be set for each available Txn type.

Parameters are mandatory, optional, or not required.

Standard

Payment

Refund

Reversal

Preauthorise

Complete

(Advice)

Recurring

Payment

Card-Present

Payment

Direct Entry

Debit Payment

Direct Entry

Credit

Payment

Antifraud

Payment

Antifraud Only

Request

TXN

TYPE

METHOD 0 4 6 10 11 14 19 15 17 21 22

setTxnSource O O O O O O O O O O O

setAmount M M M M M M M M M M M

setCurrencyCode O X X O X O O X X O O

setCardNumber M X X M X M M X X M M

SetCVV O O O O O O O X X O O

setExpiryDate M O O M O O M X X M M

setTrack2Data X X X X X X M X X X X

SetXID O O O O O O O X X X X

SetCAVV O O O O O O O X X X X

SetSLI O O O O O O O X X X X

SetTxnId X M M X X X X X X X X

setPreauthCode X X X X M X X X X X X

setBsbNumber X X X X X X X M M X X

setAccountNumber X X X X X X X M M X X

setAccountName X X X X X X X M M X X

setFirstName X X X X X X X X X O O

setLastName X X X X X X X X X O O

setZipCode X X X X X X X X X O O

setTown X X X X X X X X X O O

setBillingCountry X X X X X X X X X O O

setDeliveryCountry X X X X X X X X X O O

setEmailAddress X X X X X X X X X O O

setIp X X X X X X X X X M M

M = mandatory O = optional X = not required

(ignored if set)

Commercial-In-Confidence

Document Number:

SEC-SPT-JAVA-SUM Document Version:

4.3.1 15 of 15 pages

SECUREPAY TECHNOLOGIES © SecurePay Pty Ltd

IMPORTANT NOTE:

For refunds and reversals the ponum field must be the same as the ponum used for the original

payment.

For completes the ponum field must be the same as the ponum used for the original preauthorisation.

The ponum field is set using addTxn method on the Payment object.

4.2.1.2.2 Constructor

The Txn object cannot be constructed directly. It must be created by calling addTxn(…) in the Payment

object.

4.2.1.2.3 Public Methods

4.2.1.2.3.1 setTxnSource

public void setTxnSource(int value)

Sets the transaction source for this transaction. Source is used for transaction origin tracking. This

field is optional, and is set to 0, “Unknown”, by default.

Input Parameters:

Name Type Description Allowed Values

value int Transaction source Refer to Appendix B:

Transaction Sources

Return Parameter:

No object returned by this method.

4.2.1.2.3.2 setAmount

public void setAmount(String value)

Sets the amount associated with this financial transaction. Amount is supplied with no currency

formatting, in the currency’s smallest denomination. If using the default currency of Australian

Dollars (AUD), the amount is set in Australian cents. E.g. an amount of AU$125.40 would be set

calling:

txn.setAmount(“12540”);

Note for Multi-Currency Users: For examples of how other currency codes affect the value set

in this field, and how many minor units to pass for each currency type, see Appendix H:

Currency Codes List. (You must fulfil certain requirements with your bank and SecurePay

before using the multi-currency features. Contact SecurePay Support for further details.)

Input Parameters:

Name Type Description Allowed Values

Value String Transaction amount in Australian

cents. String representing a

number > 0, with no

whitespace or currency

formatting.

Return Parameter:

No object returned by this method.

4.2.1.2.3.3 setCurrencyCode (Approved Multi-Currency merchants only)

public void setCurrencyCode(String value)

Commercial-In-Confidence

Document Number:

SEC-SPT-JAVA-SUM Document Version:

4.3.1 16 of 16 pages

SECUREPAY TECHNOLOGIES © SecurePay Pty Ltd

Note: Before setting this value, check with SecurePay to find out if we support multi-currency

transactions through your bank, and what currency codes they allow. You may need to open

a special multi-currency account with your bank to allow payments in other currencies.

(Contact SecurePay Support for further details.)

Note: When doing Refunds, Reversals, and Advice (Preauth Complete), the currency code is

not required. The currency will be determined from the original currency used for the

Payment or Preauthorisation transaction.

Sets the 3-character currency code associated with this financial transaction. If this field is not set,

the default currency will be “AUD” (Australian Dollars). To modify the transaction to use Euro, for

example, use the following code:

txn.setCurrencyCode(“EUR”);

Currency codes are in all uppercase. The complete list of supported currencies, and the appropriate

amount field formatting for each currency, is supplied in Appendix H: Currency Codes List.

Input Parameters:

Name Type Description Allowed Values

Value String Transaction currency code. One of the valid 3-letter

codes provided in the

Appendix to this

document.

Return Parameter:

No object returned by this method.

4.2.1.2.3.4 setCardNumber

public void setCardNumber(String value)

Only for Credit Card transactions.

Sets the credit card number for this financial transaction. The card number is not required for

refunds, reversals and complete transactions. As these transaction types can only be performed on

an existing transaction (payment or preauthorisation) SecurePay already has a record of the card

number used.

Input Parameters:

Name Type Description Allowed Values

value String Customer’s credit card number. String of digits, no

whitespace.

13-16 characters.

String must pass

Luhn algorithm.

Return Parameter:

No object returned by this method.

4.2.1.2.3.5 setCVV

public void setCVV(String value)

Only for Credit Card transactions.

Sets the Card Verification Value for this financial transaction. This field is optional. The CVV value

assists the bank with detecting fraudulent transactions based on automatically generated card

numbers, as the CVV number is printed on the physical card and cannot be generated in conjunction

with a card number. If passed, the bank may check the supplied value against the value recorded

against the card. See Appendix D: Location of CVV.

Commercial-In-Confidence

Document Number:

SEC-SPT-JAVA-SUM Document Version:

4.3.1 17 of 17 pages

SECUREPAY TECHNOLOGIES © SecurePay Pty Ltd

Input Parameters:

Name Type Description Allowed Values

value String Customer’s credit card CVV

number. 3 or 4 digit string, no

whitespace.

NULL or empty string

is also valid.

Return Parameter:

No object returned by this method.

4.2.1.2.3.6 setExpiryDate

public void setExpiryDate(String value)

Only for Credit Card transactions.

Sets the credit card expiry date for this financial transaction. The expiry date is optional for refunds,

reversals, recurring payments and complete transactions. As refunds, reversals and completes are

transaction types that can only be performed on an existing transaction (payment or

preauthorisation) SecurePay already has a record of the expiry date used. Expiry date can be set if

the credit card has been re-issued with a new expiry date.

Input Parameters:

Name Type Description Allowed Values

value String Customer’s credit card expiry date. 5-character string in

format MM/YY, where

MM is a 2 digit month

value (January = 01),

YY is a 2 digit year

value (2003 = 03).

NULL or empty string

is also valid for

Recurring

transactions.

Return Parameter:

No object returned by this method.

4.2.1.2.3.7 setTrack2Data (Card-Present transactions only)

public void setTrack2Data(String value)

Only for Credit Card transactions.

Set the data read from Track 2 of the magnetic strip on the customer’s physical credit card by a

card-reading device. Track 2 data is required only for merchants using a card-reading device to

perform card-present transactions. For card-present transactions, the Transaction Type must also

be set to Card Present (see

Commercial-In-Confidence

Document Number:

SEC-SPT-JAVA-SUM Document Version:

4.3.1 18 of 18 pages

SECUREPAY TECHNOLOGIES © SecurePay Pty Ltd

Appendix A: Transaction Types).

Input Parameters:

Name Type Description Allowed Values

value String Data retrieved from “track 2” on the

credit card’s magnetic strip.

Return Parameter:

No object returned by this method.

4.2.1.2.3.8 setXID (3D-Secure merchants only)

public void setXID(String value)

Only for Credit Card transactions.

Set the 3D-Secure XID (transacion ID) for this financial transaction. The XID is required only for

merchants enrolled in the 3D-Secure program. The XID field must be a 20-byte String, matching the

unique XID passed to the card issuer before sending this transaction, using any 3D-Secure-enabled

software.

Input Parameters:

Name Type Description Allowed Values

Value String Transaction’s XID, as supplied to

card issuer prior to sending the

financial transaction.

Any 20-byte String

Return Parameter:

No object returned by this method.

4.2.1.2.3.9 setCAVV (3D-Secure merchants only)

public void setCAVV(String value)

Only for Credit Card transactions.

Set the 3D-Secure Cardholder Authorisation Verification Value for this financial transaction. The

CAVV is required only for merchants enrolled in the 3D-Secure program. The CAVV field must be a

28-character Base-64-encoded string, matching the CAVV generated by 3D-Secure-enabled

software before sending this financial transaction.

Input Parameters:

Name Type Description Allowed Values

Value String Transaction’s CAVV, as supplied

by card issuer prior to sending the

financial transaction.

28-character Base-

64-encoded string.

Return Parameter:

No object returned by this method.

4.2.1.2.3.10 setSLI (3D-Secure merchants only)

public void setSLI(String value)

Only for Credit Card transactions.

Set the 3D-Secure Service Level Indicator for this financial transaction. The SLI is required only for

merchants enrolled in the 3D-Secure program. The SLI field must be a 2-digit string, matching the

SLI (or ECI) returned by the 3D-Secure-enabled software, prior to sending this financial transaction.

Commercial-In-Confidence

Document Number:

SEC-SPT-JAVA-SUM Document Version:

4.3.1 19 of 19 pages

SECUREPAY TECHNOLOGIES © SecurePay Pty Ltd

Input Parameters:

Name Type Description Allowed Values

Value String Transaction’s SLI, as supplied by

card issuer prior to sending the

financial transaction.

2-digit String.

Return Parameter:

No object returned by this method.

4.2.1.2.3.11 setTxnId

public void setTxnId()

Only for Credit Card transactions.

For Refunds and Reversals only.

Set the original bank transaction ID of a payment in order to refund or reverse the payment. Field

must be set for refunds or reversals to work, and must match the original payment transaction ID.

Input Parameters:

Name Type Description Allowed Values

value String Bank transaction ID of the original

payment transaction. 6-30 character string

Return Parameter:

No object returned by this method.

4.2.1.2.3.12 setPreauthCode

public void setPreauthCode()

Only for Credit Card transactions.

For Preauth Completes (Advice) only.

Set the original authorisation code of a preauth in order to complete the payment. Field must be set

for preauth complete to work, and must match the original preauth authorisation ID.

Input Parameters:

Name Type Description Allowed Values

Value String Preauth ID of the original preauth

transaction. 6 character string

Return Parameter:

No object returned by this method.

4.2.1.2.3.13 setBsbNumber

public void setBsbNumber()

Only for Direct Entry transactions.

Sets BSB number for financial institution.

Input Parameters:

Name Type Description Allowed Values

value String BSB number Numerical.

6 character string

Return Parameter:

Commercial-In-Confidence

Document Number:

SEC-SPT-JAVA-SUM Document Version:

4.3.1 20 of 20 pages

SECUREPAY TECHNOLOGIES © SecurePay Pty Ltd

No object returned by this method.

4.2.1.2.3.14 setAccountNumber

public void setAccountNumber()

Only for Direct Entry transactions.

Sets account number for financial institution.

Input Parameters:

Name Type Description Allowed Values

value String Account number Numerical.

4-9 character string

Return Parameter:

No object returned by this method.

4.2.1.2.3.15 setAccountName

public void setAccountName()

Only for Direct Entry transactions.

Sets account name for financial institution.

Input Parameters:

Name Type Description Allowed Values

Value String Account name String using

characters from

Appendix I: Direct

Entry Character

set, up to 32

characters in length.

Return Parameter:

No object returned by this method.

4.2.1.2.3.16 setFirstName

public void setFirstName()

Only for antifraud transactions.

Sets customer’s first name.

Input Parameters:

Name Type Description Allowed Values

Value String Customer’s first name String, max length 40.

Return Parameter:

No object returned by this method.

4.2.1.2.3.17 setLastName

public void setFirstName()

Only for antifraud transactions.

Sets customer’s last name.

Commercial-In-Confidence

Document Number:

SEC-SPT-JAVA-SUM Document Version:

4.3.1 21 of 21 pages

SECUREPAY TECHNOLOGIES © SecurePay Pty Ltd

Input Parameters:

Name Type Description Allowed Values

Value String Customer’s last name String, max length 40.

Return Parameter:

No object returned by this method.

4.2.1.2.3.18 setZipCode

public void setZipCode()

Only for antifraud transactions.

Sets customer’s address zip code or postal code.

Input Parameters:

Name Type Description Allowed Values

Value String Customer’s address zip code or

postal code String, max length 30.

Return Parameter:

No object returned by this method.

4.2.1.2.3.19 setTown

public void setTown()

Only for antifraud transactions.

Sets billing or delivery town of the buyer.

Input Parameters:

Name Type Description Allowed Values

Value String Billing or delivery town of the buyer String, max length 60.

Return Parameter:

No object returned by this method.

4.2.1.2.3.20 setBillingCountry

public void setBillingCountry()

Only for antifraud transactions.

Sets ISO country code of the billing address.

Input Parameters:

Name Type Description Allowed Values

Value String ISO country code of the billing

address. 3 digit numeric ISO

code or 2 or 3 alpha

character ISO code.

Return Parameter:

No object returned by this method.

4.2.1.2.3.21 setDeliveryCountry

public void setDeliveryCountry()

Commercial-In-Confidence

Document Number:

SEC-SPT-JAVA-SUM Document Version:

4.3.1 22 of 22 pages

SECUREPAY TECHNOLOGIES © SecurePay Pty Ltd

Only for antifraud transactions.

Sets ISO country code of the delivery address.

Input Parameters:

Name Type Description Allowed Values

Value String ISO country code of the delivery

address. 3 digit numeric ISO

code or 2 or 3 alpha

character ISO code.

Return Parameter:

No object returned by this method.

4.2.1.2.3.22 setEmailAddress

public void setEmailAddress()

Only for antifraud transactions.

Sets email address of the customer.

Input Parameters:

Name Type Description Allowed Values

Value String Customer’s email address. String, max length

100.

Return Parameter:

No object returned by this method.

4.2.1.2.3.23 setIp

public void setTown()

Only for antifraud transactions.

IP address from which the transaction originated.

Input Parameters:

Name Type Description Allowed Values

Value String IP address from which the

transaction originated. String, max length 15,

must contain 3 p

Return Parameter:

No object returned by this method.

4.2.1.2.3.24 getTxnType

public int getTxnType()

Returns the transaction type for this transaction. Refer to

Commercial-In-Confidence

Document Number:

SEC-SPT-JAVA-SUM Document Version:

4.3.1 23 of 23 pages

SECUREPAY TECHNOLOGIES © SecurePay Pty Ltd

Appendix A: Transaction Types for values of this field.

Input Parameters:

No input parameters are required by this method.

Return Parameter:

Type Description

int Integer representing the transaction type of this Txn.

4.2.1.2.3.25 getTxnSource

public int getTxnSource()

Returns the transaction source for this transaction. Refer to Appendix B: Transaction Sources for

values of this field.

Input Parameters:

No input parameters are required by this method.

Return Parameter:

Type Description

int Integer representing the source of the transaction.

4.2.1.2.3.26 getAmount

public String getAmount()

Returns the amount associated with this financial transaction. Amount is returned with no currency

formatting, in the smallest denomination of the transaction’s specified currency. The currency of the

transaction is determined using getCurrencyCode(), described below. If no currency was

specified when making the payment, the default is Australian Dollars (AUD). E.g. an amount of

AUD$125.40 would be returned in Australian cents, as “12540”.

Input Parameters:

No input parameters are required by this method.

Return Parameter:

Type Description

String The amount of the financial transaction with no currency formatting, in the

smallest denomination of its specified currency.

NULL if the amount has not been set.

4.2.1.2.3.27 getCurrencyCode

public String getCurrencyCode()

Returns the 3-character currency identifier associated with this financial transaction.

If process() has not yet been called on this Payment, this method will only return a value if

setCurrencyCode() has been called; otherwise it will return NULL, implying the default value of

“AUD” (Australian Dollars).

If process() has been called, this method will return the currency code that was used for the

payment. If the currency code was not set, the default of “AUD” (Australian Dollars) will be returned.

See valid currency code table in Appendix J.

Note: If process() has been called and the payment was approved AND this method still

returns NULL, then the payment was sent to a SecurePay URL which does not yet support

Commercial-In-Confidence

Document Number:

SEC-SPT-JAVA-SUM Document Version:

4.3.1 24 of 24 pages

SECUREPAY TECHNOLOGIES © SecurePay Pty Ltd

multi-currency, and the payment has been processed in Australian Dollars. You will need to

refund the payment in Australian Dollars if this was done in error.

Input Parameters:

No input parameters are required by this method.

Return Parameter:

Type Description

String The 3-letter currency code of the financial transaction.

NULL if the currency has not been set and process() has not yet been

called, indicating Australian Dollars will be used by default; or if the

payment HAS been processed but the SecurePay URL does not support

multi-currency yet.

4.2.1.2.3.28 getPonum

public String getPonum()

Returns the purchase order number for this transaction.

Input Parameters:

No input parameters are required by this method.

Return Parameter:

Type Description

String The purchase order number referring to the transaction.

NULL if the purchase order number has not been set.

4.2.1.2.3.29 getCardNumber

public String getCardNumber()

For Credit Card transactions:

Returns the truncated credit card number, as stored in SecurePay’s database. This is the first 6 and

last 3 digits of the original card number, separated by “…”. E.g. Setting a card number as:

txn.setCardNumber(“4444333322221111”);

then a call to:

txn.getCardNumber();

returns “444433...111”.

For Direct Entry transactions in Payment requests:

Returns NULL.

Input Parameters:

No input parameters are required by this method.

Return Parameter:

Type Description

String The truncated credit card number or BSB and account numbers of this

financial transaction.

NULL if the card number has not been set.

4.2.1.2.3.30 getCardType

public int getCardType()

Commercial-In-Confidence

Document Number:

SEC-SPT-JAVA-SUM Document Version:

4.3.1 25 of 25 pages

SECUREPAY TECHNOLOGIES © SecurePay Pty Ltd

Only for Credit Card transactions.

Returns an integer representing the type of card used. Refer to Appendix C: Card Types for values

of this field.

Input Parameters:

No input parameters are required by this method.

Return Parameter:

Type Description

int The credit card type code of the card number used.

4.2.1.2.3.31 getCardDescription

public int getCardDescription()

Only for Credit Card transactions.

Returns a textual description of card used, or NULL if transaction has not been processed yet.

Input Parameters:

No input parameters are required by this method.

Return Parameter:

Type Description

String Description of the type of credit card used.

4.2.1.2.3.32 getCVV

public String getCVV()

Only for Credit Card transactions.

Returns the Card Verification Value of the financial transaction. After the transaction has been

processed, this method will return NULL, as this value should not be logged, and is not stored by

SecurePay.

Input Parameters:

No input parameters are required by this method.

Return Parameter:

Type Description

String The Card Verification Value of this financial transaction.

NULL if the value has not been set, or if the transaction has been

processed.

4.2.1.2.3.33 getExpiryDate

public String getExpiryDate()

Only for Credit Card transactions.

Returns the credit card expiry date of the financial transaction.

Input Parameters:

No input parameters are required by this method.

Return Parameter:

Type Description

String

The credit card expiry date of this financial transaction.

NULL if the value has not been set, or if the expiry date was not sent with

a recurring payment.

Commercial-In-Confidence

Document Number:

SEC-SPT-JAVA-SUM Document Version:

4.3.1 26 of 26 pages

SECUREPAY TECHNOLOGIES © SecurePay Pty Ltd

a recurring payment.

4.2.1.2.3.34 getTrack2Data (Card-Present transactions only)

public void getTrack2Data()

Only for Credit Card transactions.

Track 2 of the magnetic strip on the customer’s physical credit card, as passed in by

setTrack2Data(). After the transaction has been processed, this method will return NULL, as

SecurePay does not store this data.

Input Parameters:

No input parameters are required by this method.

Return Parameter:

Type Description

String The Track 2 data from the magnetic strip on the customer’s credit card.

NULL if the value has not been set, or if the transaction has already been

processed.

4.2.1.2.3.35 getXID (3D-Secure merchants only)

public String getXID()

Only for Credit Card transactions.

Returns the 3D-Secure XID (transaction id) of the financial transaction. After the transaction has

been processed, this method will return NULL, as this value should not be logged, and is not stored

by SecurePay.

Input Parameters:

No input parameters are required by this method.

Return Parameter:

Type Description

String The 3D-Secure XID of this financial transaction.

NULL if the value has not been set, or if the transaction has already been

processed.

4.2.1.2.3.36 getCAVV (3D-Secure merchants only)

public String getCAVV()

Only for Credit Card transactions.

Returns the 3D-Secure Cardholder Authorisation Verification Value of the financial transaction. After

the transaction has been processed, this method will return NULL, as this value should not be

logged, and is not stored by SecurePay.

Input Parameters:

No input parameters are required by this method.

Return Parameter:

Type Description

String The 3D-Secure CAVV of this financial transaction.

NULL if the value has not been set, or if the transaction has already been

processed.

Commercial-In-Confidence

Document Number:

SEC-SPT-JAVA-SUM Document Version:

4.3.1 27 of 27 pages

SECUREPAY TECHNOLOGIES © SecurePay Pty Ltd

4.2.1.2.3.37 getSLI (3D-Secure merchants only)

public String getSLI()

Only for Credit Card transactions.

Returns the 3D-Secure Service Level Indicator (or ECI, E-Commerce Indicator) of the financial

transaction. After the transaction has been processed, this method will return NULL, as this value

should not be logged, and is not stored by SecurePay.

Input Parameters:

No input parameters are required by this method.

Return Parameter:

Type Description

String The 3D-Secure SLI (or ECI) of this financial transaction.

NULL if the value has not been set, or if the transaction has already been

processed.

4.2.1.2.3.38 getBsbNumber

public String getBsbNumber()

Only for Direct Entry transactions in Payment request.

Returns the BSB number for this transaction.

Input Parameters:

No input parameters are required by this method.

Return Parameter:

Type Description

String The BSB number referring to the transaction.

NULL if the BSB number has not been set.

4.2.1.2.3.39 getAccountNumber

public String getAccountNumber()

Only for Direct Entry transactions in Payment request.

Returns the account number for this transaction.

Input Parameters:

No input parameters are required by this method.

Return Parameter:

Type Description

String The account number referring to the transaction.

NULL if the account number has not been set.

4.2.1.2.3.40 getAccountName

public String getAccountName()

Only for Direct Entry transactions in Payment request.

Returns the account name for this transaction.

Input Parameters:

No input parameters are required by this method.

Commercial-In-Confidence

Document Number:

SEC-SPT-JAVA-SUM Document Version:

4.3.1 28 of 28 pages

SECUREPAY TECHNOLOGIES © SecurePay Pty Ltd

Return Parameter:

Type Description

String The account name referring to the transaction.

NULL if the account name has not been set.

4.2.1.2.3.41 getAntiFraudResponseCode

public String getAntiFraudResponseCode()

Only for antifraud transactions in Payment request.

Returns the response code of the antifraud verification. This will be a 3-digit response from

SecurePay’s server or API. The method getAntiFraudResponseText() provides more details in

a textual format.

Refer to the SecurePay Payment Response Codes document for details of codes returned. This

document may be downloaded from SecurePay’s Merchant Login website, or provided via email by

SecurePay Merchant Support.

If the antifraud verification failed, the transaction will not be sent to the bank and therefore there will

be no values returned by methods such as getResponseCode(), getResponseText(),

getSettlementDate(), isApproved(), getTxnId().

Input Parameters:

No input parameters are required by this method.

Return Parameter:

Type Description

String 3-digit SecurePay / gateway response.

4.2.1.2.3.42 getAntiFraudResponseText

public String getAntiFraudResponseText()

Returns a textual description of the antifraud response code received.

Input Parameters:

No input parameters are required by this method.

Return Parameter:

Type Description

String Description of antifraud response received.

4.2.1.2.3.43 getApproved

public boolean getApproved()

Returns a boolean representing the financial result of the transaction.

Input Parameters:

No input parameters are required by this method.

Return Parameter:

Type Description

boolean true if the payment was authorised by the merchant bank and customer

card issuer, or false in any other case.

4.2.1.2.3.44 getResponseCode

Commercial-In-Confidence

Document Number:

SEC-SPT-JAVA-SUM Document Version:

4.3.1 29 of 29 pages

SECUREPAY TECHNOLOGIES © SecurePay Pty Ltd

public String getResponseCode()

Returns the response code of the transaction. This is either a 2-digit response (00-99) from the

bank, a 3-digit response (100-299) from SecurePay’s server or API, or a 3-digit response (900-999)

mapped from SecurePay’s bank link responses. The method getResponseText() provides more

details in a textual format.

Refer to the SecurePay Payment Response Codes document for details of codes returned. This

document may be downloaded from SecurePay’s Merchant Login website, or provided via email by

SecurePay Merchant Support.

Input Parameters:

No input parameters are required by this method.

Return Parameter:

Type Description

String 2-digit bank response or 3-digit SecurePay / gateway response.

4.2.1.2.3.45 getResponseText

public String getResponseText()

Returns a textual description of the response code received for the transaction.

Input Parameters:

No input parameters are required by this method.

Return Parameter:

Type Description

String Description of response received from API, SecurePay, or bank.

NULL if the transaction has not yet been processed.

4.2.1.2.3.46 getThinlinkResponseCode

public String getThinlinkResponseCode()

Only for Credit Card transactions.

Maps SecurePay’s response code field to a Westpac Thinlink Payment Result Code for ex-Thinlink

users. Refer to G.1 Payment Result Codes for details of codes returned.

Input Parameters:

No input parameters are required by this method.

Return Parameter:

Type Description

String 3-digit Thinlink Payment Result Code

4.2.1.2.3.47 getThinlinkResponseText

public String getThinlinkResponseText()

Only for Credit Card transactions.

In accordance with Thinlink, this method always returns “000”, meaning “No further information

available”. Additional codes may be added in future.

Input Parameters:

No input parameters are required by this method.

Return Parameter:

Commercial-In-Confidence

Document Number:

SEC-SPT-JAVA-SUM Document Version:

4.3.1 30 of 30 pages

SECUREPAY TECHNOLOGIES © SecurePay Pty Ltd

Type Description

String 3-digit Thinlink Payment Result Description (“000”).

4.2.1.2.3.48 getThinlinkEventStatusCode

public String getThinlinkEventStatusCode()

Only for Credit Card transactions.

Maps SecurePay’s response code field to a Westpac Thinlink Event Status Code for ex-Thinlink

users. Refer to G.2 Event Status Codes for details of codes returned.

Input Parameters:

No input parameters are required by this method.

Return Parameter:

Type Description

String 3-digit Thinlink Event Status Code

4.2.1.2.3.49 getThinlinkEventStatusText

public String getThinlinkEventStatusText()

Only for Credit Card transactions.

Textual description of the Thinlink Event Status Code for ex-Thinlink users.

Input Parameters:

No input parameters are required by this method.

Return Parameter:

Type Description

String Textual description of the Event Status Code.

4.2.1.2.3.50 getSettlementDate

public String getSettlementDate()

Returns the bank settlement date when the funds will be settled into the merchant’s account. This

will be the current date mostly, however after the bank’s daily cut-off time, or on non-banking days,

the settlement date will be the next business day. The format of the settlement date is

“YYYYMMDD”.

In case of Direct Entry transactions this will be the current date.

Input Parameters:

No input parameters are required by this method.

Return Parameter:

Type Description

String Bank settlement date in “YYYYMMDD” format.

NULL if the bank did not receive the transaction. (A settlement date may

be returned for declined transactions.)

NULL for direct entry transactions if the transaction could not be stored in

SecurePay system.

4.2.1.2.3.51 getTxnId

Commercial-In-Confidence

Document Number:

SEC-SPT-JAVA-SUM Document Version:

4.3.1 31 of 31 pages

SECUREPAY TECHNOLOGIES © SecurePay Pty Ltd

public String getTxnId()

Returns the Bank Transaction ID of the transaction. The format of this string depends on the

merchant’s bank, and ranges between 6 and 30 characters.

Note: The transaction ID of a payment transaction must be sent back with a request for a refund or

reversal of that transaction.

Input Parameters:

No input parameters are required by this method.

Return Parameter:

Type Description

String Bank transaction ID of the transaction.

NULL if the transaction has not been processed, or in some cases if it

was not received by the bank.

4.2.1.2.3.52 getPreauthId

public String getPreauthId()

Only for Credit Card transactions.

Only for Preauth transactions.

Returns the preauthorisation ID of the transaction (for Preauth transaction types only). NULL is

returned for any other transaction type, or if the preauthorisation was not received by the bank.

Note: The preauth ID of a preauth transaction must be sent back with a request for a preauth

complete (advice) of that transaction.

Input Parameters:

No input parameters are required by this method.

Return Parameter:

Type Description

String Preauth ID of the transaction.

NULL if the transaction is not a Preauth type, or has not been processed,

or in some cases if the preauth was not received by the bank.

4.2.1.3 Payment Sample Code

// Import required classes

import securepay.jxa.api.Payment;

import securepay.jxa.api.Txn;

class SecurePayPaymentTest

{ public SecurePayPaymentTest()

{ // Create Payment container object

Payment payment = new Payment();

// Print generated values

System.out.println(“Message ID: “ + payment.getMessageId());

System.out.println(“Timestamp: “ + payment.getMessageTimestampAsString());

System.out.println(“API Version: “ + payment.getApiVersion());

// Set Payment values

payment.setServerURL(

“http://fakeurl.com/payment”); // Dummy payment URL, please use

the URL supplied by SecurePay Support

payment.setProcessTimeout(80); // 80 seconds

payment.setMerchantId(“XYZ9999”); // ID allocated by SecurePay

// Add a Txn to the container

Commercial-In-Confidence

Document Number:

SEC-SPT-JAVA-SUM Document Version:

4.3.1 32 of 32 pages

// type = 0 (payment)

// ponum = “SecurePayTest”

Txn txn = payment.addTxn(0, “SecurePayTest”);

// Set the Txn values

txn.setTxnSource(8); // API source

txn.setAmount(“1000”); // A$10.00

txn.setCurrencyCode(“AUD”); // Australian Dollars

txn.setCardNumber(“4444333322221111”); // dummy card number

txn.setCVV(“456”); // dummy CVV (optional)

txn.setExpiryDate(“03/06”); // March, 2006

// Send payment to SecurePay for processing

boolean processed = payment.process(“password”);

// If payment was not sent to SecurePay, print status and exit

if (!processed)

{

System.out.println(“Payment was not sent to server.”);

System.out.println(“Status: “ + payment.getStatusCode());

System.out.println(“Desc: “ + payment.getStatusDesc());

}

else // Payment was processed correctly

{

System.out.println(“Response Received.”);

if (payment.getCount() == 1)

{

// Get the Txn response object

Txn resp = payment.getTxn(0);// First Txn in response queue

// Print response variables

System.out.println(“Transaction response parameters:”);

System.out.println(“Status: “ + payment.getStatusCode());

System.out.println(“Desc: “ + payment.getStatusDesc());

System.out.println(“Approved: ” + resp.getApproved());

System.out.println(“RespCode: ” + resp.getResponseCode());

System.out.println(“RespText: ” + resp.getResponseText());

System.out.println(“SettDate: ” + resp.getSettlementDate());

System.out.println(“TxnID: ” + resp.getTxnId());

}

else

{

System.out.println(“No Txn object returned.”);

System.out.println(“Check status code for error details.”);

}

public static void main(String[] args)

{

SecurePayPaymentTest test = new SecurePayPaymentTest();

}

4.2.1.4 Refund Sample Code

// Import required classes

import securepay.jxa.api.Payment;

import securepay.jxa.api.Txn;

class SecurePayRefundTest

{ public SecurePayRefundTest()

{ // Create Payment container object

Payment payment = new Payment();

// Print generated values

System.out.println(“Message ID: “ + payment.getMessageId());

System.out.println(“Timestamp: “ + payment.getMessageTimestampAsString());

System.out.println(“API Version: “ + payment.getApiVersion());

Commercial-In-Confidence

Document Number:

SEC-SPT-JAVA-SUM Document Version:

4.3.1 33 of 33 pages

// Set Payment values

payment.setServerURL(

“http://fakeurl.com/payment”); // Dummy payment URL, please use

the URL supplied by SecurePay Support

payment.setProcessTimeout(80); // 80 seconds

payment.setMerchantId(“XYZ9999”); // ID allocated by SecurePay

// Add a Txn to the container

// type = 4 (refund)

// ponum of the original payment = “SecurePayTest”

Txn txn = payment.addTxn(4, “SecurePayTest”);

// Set the Txn values

txn.setTxnSource(8); // API source

txn.setAmount(“1000”); // A$10.00

txn.setCurrencyCode(“AUD”); // Australian Dollars

txn.setTxnId(“123123”); // Transaction Id returned for the

// original payment

// Send refund to SecurePay for processing

boolean processed = payment.process(“password”);

// If refund was not sent to SecurePay, print status and exit

if (!processed)

{

System.out.println(“Refund was not sent to server.”);

System.out.println(“Status: “ + payment.getStatusCode());

System.out.println(“Desc: “ + payment.getStatusDesc());

}

else // Refund was processed correctly

{

System.out.println(“Response Received.”);

if (payment.getCount() == 1)

{

// Get the Txn response object

Txn resp = payment.getTxn(0);// First Txn in response queue

// Print response variables

System.out.println(“Transaction response parameters:”);

System.out.println(“Status: “ + payment.getStatusCode());

System.out.println(“Desc: “ + payment.getStatusDesc());

System.out.println(“Approved: ” + resp.getApproved());

System.out.println(“RespCode: ” + resp.getResponseCode());

System.out.println(“RespText: ” + resp.getResponseText());

System.out.println(“SettDate: ” + resp.getSettlementDate());

System.out.println(“TxnID: ” + resp.getTxnId());

}

else

{

System.out.println(“No Txn object returned.”);

System.out.println(“Check status code for error details.”);

}

public static void main(String[] args)

{

SecurePayRefundTest test = new SecurePayRefundTest();

}

Commercial-In-Confidence

Document Number:

SEC-SPT-JAVA-SUM Document Version:

4.3.1 34 of 34 pages

4.2.2 Echo

4.2.2.1 securepay.jxa.api.Echo

The Echo object can be created and sent to any of the SecurePay service URLs (Payment or DirectEntry) to

ensure the SecurePay service is available, and to confirm the status of the service.

IMPORTANT NOTE:

Echo messages must be used appropriately. If you use this method to poll SecurePay services,

polls should be no less than 5 minutes apart. An Echo should not be sent if a transaction with a

bank response code (00-99) has been processed by your system within the last 5 minutes.

4.2.2.1.1 Constructor

public Echo()

Create an empty Echo object.

Parameters:

No parameters required by this constructor.

4.2.2.1.2 Public Methods

4.2.2.1.2.1 getMessageId

public String getMessageId()

Returns the unique message identifier created by the API.

Input Parameters:

No input parameters are required by this method.

Return Parameter:

Type Description

String Unique identifier of this Echo object.

4.2.2.1.2.2 getMessageTimestamp

public Date getMessageTimestamp()

Returns the timestamp created by the API for the Echo in a Date object.

Input Parameters:

No input parameters are required by this method.

Return Parameter:

Type Description

Date Timestamp of this Echo object.

4.2.2.1.2.3 getMessageTimestampAsString

public String getMessageTimestampAsString()

Returns the timestamp created by the API for the Echo as a string. Refer to Appendix E:

Timestamp String Format for the format of the string returned.

Commercial-In-Confidence

Document Number:

SEC-SPT-JAVA-SUM Document Version:

4.3.1 35 of 35 pages

Input Parameters:

No input parameters are required by this method.

Return Parameter:

Type Description

String Timestamp of this Echo object.

4.2.2.1.2.4 getApiVersion

public String getApiVersion()

Returns the version of the API being used to create this object.

Input Parameters:

No input parameters are required by this method.

Return Parameter:

Type Description

String API version used to create this Echo object.

4.2.2.1.2.5 setMerchantId

public void setMerchantId(String id)

Sets the merchant id to be used when processing the echo request.

Input Parameters:

Name Type Description Allowed Values

id String Merchant ID allocated to the

merchant by SecurePay. 7-character string in

format XXXDDDD,

where X is a letter (A-

Z) and D is a digit (0-

9). SecurePay will

supply this value to

you upon application.

For Direct Entry

Echo Request:

5-7 character string in

format XXXDDDD,

where X is a letter (A-

Z) and D is a digit (0-

9). Last two digits

can be ignored.

Return Parameter:

No object returned by this method.

Commercial-In-Confidence

Document Number:

SEC-SPT-JAVA-SUM Document Version:

4.3.1 36 of 36 pages

4.2.2.1.2.6 setServerURL

public void setServerURL(String url)

Sets the URL of the SecurePay service to which this Echo will be sent when process() is called.

Input Parameters:

Name Type Description Allowed Values

url String URL of SecurePay’s server. Test:

https://www.securepay.com.au/test

/payment

Live:

https://www.securepay.com.au/xml

api/payment

For Direct Entry:

Test:

https://www.securepay.com.au/test

/directentry

Live:

https://www.securepay.com.au/xml

api/directentry

Return Parameter:

No object returned by this method.

4.2.2.1.2.7 setProcessTimeout

public void setProcessTimeout(int timeout)

Sets the timeout in seconds to wait for a response message from SecurePay’s server. If no

response is received in this time, a timeout response is returned, and transaction results may be

queried at a later time.

If value is not set, or is set to an integer < 0, default timeout of 80 seconds is used.

Input Parameters:

Name Type Description Allowed Values

timeout int Seconds to wait for SecurePay

response. Int < 0: default value

is used

Int >= 0: supplied

value is used.

Return Parameter:

No object returned by this method.

4.2.2.1.2.8 process

public boolean process(String password)

Sends this Echo object to SecurePay’s Server. This method may be called multiple times on the

same instance of the Echo object.

As of SecureJava V4.0.3a, the password parameter must be passed to this method. Previous

releases of SecureJava V4.0.x which did not pass a password will no longer be compatible with the

SecurePay Payment Servers, as it is now required that a password is used for all financial

transactions and echoes. The password can be changed via SecurePay’s Merchant Login website

by logging in as the “admin” user.

If the merchant Id and password sent do not match those stored in SecurePay’s database, the

response message will have a status code of “550”.

Commercial-In-Confidence

Document Number:

SEC-SPT-JAVA-SUM Document Version:

4.3.1 37 of 37 pages

Input Parameters:

Name Type Description Allowed Values

password String The password is configured in

SecurePay’s database per

Merchant ID, and must match

the value passed by this

method for the message to be

accepted and processed.

The password is allocated

to you by SecurePay

when you receive this

software, and can be

changed via the Merchant

Return Parameter:

Type Description

Boolean true if message was sent to server correctly and a response received,

and false if client-side errors occurred preventing the object from being be

sent.

4.2.2.1.2.9 getStatusCode

public long getStatusCode()

Returns the status code of the Echo. Refer to Appendix F: SecurePay Status Codes for more

details.

Input Parameters:

No input parameters are required by this method.

Return Parameter:

Type Description

long Code representing the status of the Echo object after processing.

4.2.2.1.2.10 getStatusDesc

public String getStatusDesc()

Returns the status description of the Echo response.

Input Parameters:

No input parameters are required by this method.

Return Parameter:

Type Description

String Textual description of the status of the Echo object after processing.

4.2.2.2 Echo Sample Code

// Import required classes

import securepay.jxa.api.Echo;

class SecurePayEchoTest

{ public SecurePayEchoTest()

{

// Create Payment container object

Echo echo = new Echo();

// Print generated values

System.out.println(“Message ID: “ + echo.getMessageId());

System.out.println(“Timestamp: “ + echo.getMessageTimestampAsString());

System.out.println(“API Version: “ + echo.getApiVersion());

// Set Payment values

echo.setServerURL(

Commercial-In-Confidence

Document Number:

SEC-SPT-JAVA-SUM Document Version:

4.3.1 38 of 38 pages

“http://fakeurl.com/payment”); // Dummy payment URL, please use

URL supplied by SecurePay Support

echo.setProcessTimeout(80); // 80 seconds

echo.setMerchantId(“XYZ9999”); // ID allocated by SecurePay

// Send echo to SecurePay

boolean processed = echo.process(“password”);

if (!processed)

{

System.out.println(“Payment was not sent to server.”);

}

else // Payment was processed correctly

{

System.out.println(“Response Received.”);

}

// Print status of Echo

System.out.println(“Status: “ + echo.getStatusCode());

System.out.println(“Desc: “ + echo.getStatusDesc());

}

public static void main(String[] args)

{

SecurePayEchoTest test = new SecurePayEchoTest();

}

Commercial-In-Confidence

Document Number:

SEC-SPT-JAVA-SUM Document Version:

4.3.1 39 of 39 pages

Appendix A: Transaction Types

Transaction type codes define the type of financial transaction processed by SecurePay.

Codes with shaded background are permitted in Payment transactions from this API. All other codes are

provided for completeness.

Code Description

0 Standard Payment

1 Mobile Payment

2 Batch Payment

3 Periodic Payment

4 Refund

5 Error Reversal (Void)

6 Client Reversal (Void)

10 Preauthorise

11 Preauth Complete (Advice)

14 Recurring Payment

15 Direct Entry Debit

17 Direct Entry Credit

19 Card-Present Payment

20 IVR Payment

21 Antifraud payment

22 Antifraud (only) request

Appendix B: Transaction Sources

Transaction source codes track the origin of financial transaction processed by SecurePay.

Codes with shaded background are permitted in Payment transactions from this API. All other codes are

provided for completeness.

Other source codes may be used, with the permission of SecurePay. Contact SecurePay Support for more

information.

Code Description

0 Unknown (default)

1 SecureLink

2 Merchant Login

3 SATM

4 SecureBill Portal

5 SecureBill Link

7 SecurePOS

8 API (SecureJava)

9 Call Centre Payment Switch

10 Batch Server

11 IVR1

12 IVR2

13 SecureMobile

14 Reconciliation Engine

16 Helpdesk Login

18 eSec Interface

19 Periodic Server

23 SecureXML

24 DirectOne Interface

25 Antifraud Server

Commercial-In-Confidence

Document Number:

SEC-SPT-JAVA-SUM Document Version:

4.3.1 40 of 40 pages

90 Reserved

Appendix C: Card Types

SecurePay uses numeric codes to refer to credit card types in our system.

Code Description

0 Unknown

1 JCB

2 American Express (Amex)

3 Diners Club

4 Bankcard

5 MasterCard

6 Visa

Appendix D: Location of CVV

The Card Verification Value is an anti-fraud measure used by some banks to prevent payments from

generated card numbers. The CVV number is printed on the physical card, and is randomly assigned,

therefore cannot be auto-generated.

The CVV number can be found in the following places:

Card Type Location

Visa Signature strip on back of card. Last digits of card number are re-

printed in reverse italics, followed by 3-digit CVV.

MasterCard Signature strip on back of card. Last digits of card number are re-

printed in reverse italics, followed by 3-digit CVV.

Bankcard Signature strip on back of card. Last digits of card number are re-

printed in reverse italics, followed by 3-digit CVV.

Amex 4 digit CVV above card number on front of card.

Diners Club Signature strip on back of card. Last digits of card number are re-

printed in reverse italics, followed by 3-digit CVV.

JCB Not used

Appendix E: Timestamp String Format

The format of the Timestamp or Log Time strings returned by SecureJava is:

YYYYDDMMHHNNSSKKK000sOOO

where:

YYYY is a 4-digit year

DD is a 2-digit zero-padded day of month

MM is a 2-digit zero-padded month of year (January = 01)

HH is a 2-digit zero-padded hour of day in 24-hour clock format (midnight = 00)

NN is a 2-digit zero-padded minute of hour

SS is a 2-digit zero-padded second of minute

KKK is a 3-digit zero-padded millisecond of second

000 is a Static 0 characters, as SecurePay does not store nanoseconds

sOOO is a Time zone offset, where s is “+” or “-“, and OOO = minutes, from GMT.

E.g. June 24, 2002 5:12:16.789 PM, Australian EST is:

Commercial-In-Confidence

Document Number:

SEC-SPT-JAVA-SUM Document Version:

4.3.1 41 of 41 pages

20022406171216789000+600

Appendix F: SecurePay Status Codes

Status

Code Response Text Description

0 Normal Message processed correctly (check transaction response for details).

504 Invalid Merchant ID If Merchant ID does not follow the format XXXDDDD, where X is a letter

and D is a digit, or Merchant ID is not found in SecurePay’s database.

505 Invalid URL The URL passed to either Echo, or Payment object is invalid.

510 Unable To Connect To

Server Produced by SecurePay Client API when unable to establish connection

to SecurePay Payment Gateway

511 Server Connection Aborted

During Transaction Produced by SecurePay Client API when connection to SecurePay

Payment Gateway is lost after the payment transaction has been sent

512 Transaction timed out By

Client Produced by SecurePay Client API when no response to payment

transaction has been received from SecurePay Payment Gateway within

predefined time period (default 80 seconds)

513 General Database Error Unable to read information from the database.

514 Error loading properties file Payment Gateway encountered an error while loading configuration

information for this transaction

515 Fatal Unknown Error Transaction could not be processed by the Payment Gateway due to

unknown reasons

516 Request type unavailable SecurePay system doesn’t support the requested transaction type

517 Message Format Error SecurePay Payment Gateway couldn’t correctly interpret the transaction

message sent

524 Response not received The client could not receive a response from the server.

545 System maintenance in

progress The system maintenance is in progress and the system is currently

unable to process transactions

550 Invalid password The merchant has attempted to process a request with an invalid

password.

575 Not implemented This functionality has not yet been implemented

577 Too Many Records for

Processing The maximum number of allowed events in a single message has been

exceeded.

580 Process method has not

been called The process() method on either Echo, or Payment object has not been

called

595 Merchant Disabled SecurePay has disabled the merchant and the requests from this

merchant will not be processed.

Appendix G: Thinlink Codes

G.1 Payment Result Codes

Code Description

100 Payment approved

200 Payment declined

300 Payment incomplete – Unable to process, try again later

400 Scheduled – Execution pending

999 Unknown status

G.2 Event Status Codes

Code Description Code Description

000 Normal Completion 986 Error – Invalid Email Address

002 No event to process 988 Error – Unknown Currency

980 Error – Bad Card Number 990 Error – Invalid Amount

Commercial-In-Confidence

Document Number:

SEC-SPT-JAVA-SUM Document Version:

4.3.1 42 of 42 pages

981 Error – Expired Card 991 Error – Invalid MTID

982 Error – Invalid Transaction Type 992 Error – Duplicate Invoice Number

984 Error – Formatting Error 999 Error – Unspecified

Appendix H: Currency Codes List

IMPORTNANT NOTICE:

You must meet certain requirements with your bank and SecurePay before using SecurePay’s multi-

currency features. Please ask SecurePay if we support multi-currency payments through your bank,

and if so, what currency types are available. You may also need to open multi-currency accounts

with your bank for each currency you propose to transact in. Contact SecurePay Support or your

SecurePay Account Manager for full details.

Example*

Code Description Minor Units Amount Pass As

AUD Australian Dollar 2 $20 2000

CAD Canadian Dollar 2 $20 2000

CHF Swiss Franc 2 20 2000

DEM German Deutschmark 2 20 2000

EUR Euro 2 €20 2000

FRF French Franc 2 20 2000

GBP English Pound 2 £20 2000

GRD Greek Drachma 0 20 20

HKD Hong Kong Dollar 2 $20 2000

ITL Italian Lira 0 L20 20

JPY Japanese Yen 0 ¥20 20

NZD New Zealand Dollar 2 $20 2000

SGD Singapore Dollar 2 $20 2000

USD US Dollar 2 $20 2000

* To pass a multicurrency payment to SecurePay, call setCurrencyCode(…) with the value from the Code

column, and call setAmount(…) with the amount to be charged, ensuring you set the correct number of

Minor Units for the selected currency, as shown in the examples.

E.g. For US Dollars, $4,125.90 is set using:

txn.setAmount(“412590”);

txn.setCurrencyCode(“USD”);

or for Japanese Yen, ¥67,925 is set using:

txn.setAmount(“67925”);

txn.setCurrencyCode(“JPY”);

Commercial-In-Confidence

Document Number:

SEC-SPT-JAVA-SUM Document Version:

4.3.1 43 of 43 pages

Appendix I: Direct Entry Character set

Description Characters allowed

Numeric 0 - 9

Alphabetic a – z, A - Z

Oblique slash /

Hyphen -

Ampersand &

Period .

Asterisk *

Apostrophe ‘

Blank space

SecureJava User Manual Secure Java4User

Navigation menu

Versions of this User Manual:

Views

Navigation