Secure Java API Integration Guide
User Manual:
Open the PDF directly: View PDF 
.
Page Count: 49
| Download | |
| Open PDF In Browser | View PDF |
Secure Java API Integration Guide
Page 1 of 49
Table of Contents
1 Introduction..................................................................... 4
1.1
1.2
About this Guide .................................................... 4
Intended Audience ................................................ 4
2 System Overview............................................................. 5
3 Secure Java Payments ................................................... 7
3.1
3.2
Payment ................................................................. 7
Authentication, Communication & Encryption..... 7
4 Java Installation .............................................................. 8
4.1
4.2
4.3
Prerequisites ......................................................... 8
Java Inventory........................................................ 8
Installation ............................................................. 8
5 Java Integration .............................................................. 9
5.1
Classpath Setup .................................................... 9
5.2
Interface................................................................. 9
5.2.1
Payments
9
5.2.2
Echo
36
Appendix A: Transaction Types .......................................... 41
Appendix B: Transaction Sources ...................................... 42
Appendix C: Card Types ..................................................... 43
Appendix D: Location of CVV.............................................. 44
Appendix E: Timestamp String Format .............................. 45
Appendix F: SecurePay Status Codes................................ 46
Appendix G: Thinlink Codes ............................................... 47
G.1 Payment Result Codes .............................................47
G.2 Event Status Codes ..................................................47
Appendix H: Currency Codes List ....................................... 48
Appendix I: Direct Entry Character set............................... 49
Page 2 of 49
© SecurePay Pty Ltd
SecurePay Java API integration Guide Version 1.3
Document Control
This is a control document
DESCRIPTION
Secure Java API Integration Guide
CREATION DATE
02/05/2007
CREATED BY
SecurePay
VERSION
1.4
DATE UPDATED
22/09/2010
Page 3 of 49
© SecurePay Pty Ltd
SecurePay Java API integration Guide Version 1.4
1
Introduction
1.1 About this Guide
This guide provides technical information about
installing and configuring Secure Java within your
environment.
Secure Java is written in the Sun Java programming
language, and can run on any computer with the
Java Runtime Environment installed. Messages are
transported via a HTTP protocol using SSL.
Secure Java integrates into a web site via the Java
programming language. The merchant’s web site
captures the credit card information and then posts
the details in a Java message format over a secure
connection to the SecurePay Payment Gateway for
authorisation. The authorisation response is then
returned as a Java message over the same secure
connection.
1.2 Intended Audience
This document is intended for developers,
integrating SecurePay’s Secure Java interface 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.
Page 4 of 49
© SecurePay Pty Ltd
SecurePay Java API integration Guide Version 1.4
2
System Overview
SecurePay’s Payment Gateway provides merchants
with the ability to process credit card and direct entry
payments in a secure environment.
SecurePay partners with the following major banks
and financial institutions in the provision of the
SecurePay Payment Gateway:
• ANZ
• American Express
• BankWest
Secure Java supports four payment transaction types:
•
•
•
•
Payments
Refunds
Preauthorise
Preauthorise Complete
Secure Java is written in the Sun Java programming
language, and can run on any computer with the Java
Runtime Environment installed. Messages are
transported via a HTTP protocol using SSL.
• Commonwealth Bank
• Diners Club
• National Australia Bank
• St George (including Bank of SA)
• Westpac (including Challenge Bank and Bank of
Melbourne)
Direct entry payments are not processed in real time;
they are stored in SecurePay’s database and
processed daily at 4.30pm EST.
Page 5 of 49
© SecurePay Pty Ltd
SecurePay Java API integration Guide Version 1.4
Page 6 of 49
© SecurePay Pty Ltd
SecurePay Java API integration Guide Version 1.4
3
Secure Java Payments
3.1 Payment
The Payment command is used 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 can be used to send following
credit card transaction types:
•
•
•
•
•
Credit Card Payment
Credit Card Refund
Credit Card Reversal (Void)
Credit Card Preauthorise
Credit Card Preauthorise
(Advice)
Complete
SecurePay’s payment server is also capable of
processing direct entry transactions. Direct entry
transactions are not processed real time. The
SecurePay payment server stores direct entry
transaction in a database and processes them daily
at 4.30pm Melbourne time.
3.2 Authentication,
Encryption
Communication
&
To ensure security, each merchant is issued with
transaction password. This password is authenticated
with each request before it is processed. This makes
sure that unauthorised users will be unable to use the
interface.
The password can be changed by the merchant via
SecurePay’s Merchant Management facility.
The Secure Java interface uses HTTP protocol and
SSL for communication with SecurePay’s servers.
Merchants using Secure Java will automatically use
SecurePay’s security certificate to encrypt requests
and
decrypt
responses
from
SecurePay.
The Payment command can be used to send following
direct entry transaction types:
• Direct Debit
• Direct Credit
Page 7 of 49
© SecurePay Pty Ltd
SecurePay Java API integration Guide Version 1.4
4
Java Installation
Secure Java 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 Secure Java software package provided can therefore be run on Microsoft Windows, Unix,
or Macintosh platforms without recompiling.
4.1 Prerequisites
1.
The installation machine must have the Java Runtime Environment (JRE) installed. Secure Java
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.
4.2 Java Inventory
The Secure Java Software package contains the following files:
• securepayxmlapi_obf.jar
• xmlParserAPIs-2.4.0.jar
• xercesImpl-2.4.0.jar
• Base64.jar
4.3 Installation
Secure Java
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 4.2) into this new directory.
Secure Java Software - Periodic and Triggered add in
1. Create a directory on the installation machine called “SecurePayPeriodicAPI” in a location of your
choice.
2. Copy all files listed in the Software Inventory (see 3.2) into this new directory
Page 8 of 49
© SecurePay Pty Ltd
SecurePay Java API integration Guide Version 1.3
5
Java Integration
5.1 Classpath Setup
Before running Secure Java, 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
arg2
–cp
abc.jar;def.jar
YourMainClass
arg1
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.
5.2 Interface
5.2.1
5.2.1.1
Payments
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.
5.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.
5.2.1.1.2 Public Methods
5.2.1.1.3 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
String
Description
Unique identifier of this Payment object.
Page 9 of 49
© SecurePay Pty Ltd
SecurePay Java API integration Guide Version 1.3
5.2.1.1.3.1
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.
Return Parameter:
Type
Date
5.2.1.1.3.2
Description
Timestamp of this Payment object.
getMessageTimestampAsString
public String getMessageTimestampAsString()
Returns the timestamp created by the API for the Payment as a string. Refer to Appendix E for the
format returned.
Input Parameters:
No input parameters are required by this method.
Return Parameter:
Type
String
5.2.1.1.3.3
Description
Timestamp of this Payment object.
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
String
5.2.1.1.3.4
Description
API version used to create this Payment object.
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
id
Type
String
Description
Merchant ID allocated to the
merchant by SecurePay.
Allowed Values
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.
Page 10 of 49
© SecurePay Pty Ltd
SecurePay Java API integration Guide Version 1.3
Return Parameter:
No object returned by this method.
5.2.1.1.3.5
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
url
Type
String
Description
URL of SecurePay’s Payment
Server or Direct Entry Server in
case of Direct Entry payments.
Allowed Values
Test:
https://test.securepay.com.au/xmlapi/payment
http://test.securepay/com.au/xmlapi/payment
Live:
https://api.securepay.com.au/xmlapi/payment
For Direct Entry:
Test:
https://test.securepay.com.au/xmlapi/directentry
http://test.securepay.com.au/xmlapi/directentry
Live:
https://api.securepay.com.au/xmlapi/directentry
For Antifraud:
Test:
https://test.securepay.com.au/antifraud/payment
http://test.securepay.com.au/antifraud/payment
Live:
https://www.securepay.com.au/antifraud/payment
(Values are subject to change in future releases.)
Return Parameter:
No object returned by this method.
5.2.1.1.3.6
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
timeout
Type
int
Description
Seconds to wait for SecurePay
response.
Allowed Values
Int < 0: default value is used
Int >= 0: supplied value is used.
Return Parameter:
No object returned by this method.
Page 11 of 49
© SecurePay Pty Ltd
SecurePay Java API integration Guide Version 1.3
5.2.1.1.3.7
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.
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 Secure Java 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
TxnType
Type
int
Ponum
String
Description
Integer representing the transaction
type to be processed.
Unique merchant transaction
identifier, typically an invoice
number.
Allowed Values
Refer to Appendix A
Any alphanumeric string, up to 60
characters in length.
For Direct Entry:
Any string using characters from,
Appendix I up to 18 characters in
length.
Return Parameter:
Type
Txn
5.2.1.1.3.8
Description
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.
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
txnType
Type
int
ponum
String
Description
Integer representing the transaction
type to be processed.
Unique merchant transaction
identifier, typically an invoice
number.
Allowed Values
Any alphanumeric string, up to 60
characters in length.
Return Parameter:
Page 12 of 49
© SecurePay Pty Ltd
SecurePay Java API integration Guide Version 1.3
Type
Txn
Description
Txn request object matching the txnType and ponum supplied, or NULL if no such Txn
exists.
5.2.1.1.3.9
Process
public boolean process(String password)
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 5.2.1.1.3.6).
As of Secure Java V4.0.3a, the password parameter must be passed to this method. Previous
releases of Secure Java 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
password
Type
String
Description
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.
Allowed Values
The password is allocated to you by
SecurePay when you receive this
software, and can be changed via
the Merchant Login website.
Return Parameter:
Type
boolean
Description
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.
5.2.1.1.3.10 getStatusCode
public long getStatusCode()
Returns the status code of the Payment. Refer Appendix F for more information.
Input Parameters:
No input parameters are required by this method.
Return Parameter:
Type
long
Description
Code representing the status of the Payment object after processing.
Page 13 of 49
© SecurePay Pty Ltd
SecurePay Java API integration Guide Version 1.3
5.2.1.1.3.11 getStatusDesc
public String getStatusDesc()
Returns the status description of the Payment. Refer to Appendix F for more information.
Input Parameters:
No input parameters are required by this method.
Return Parameter:
Type
String
Description
Textual description of the status of the Payment object after processing.
5.2.1.1.3.12 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
String
Description
Textual representation of the Payment object.
5.2.1.1.3.13 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
Int
Description
Number of Txn objects
5.2.1.1.3.14 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
index
Type
int
Description
Index to the Txn object required.
Allowed Values
int between 0 and getCount() – 1
Return Parameter:
Type
Txn
Description
Txn object from requested position.
Page 14 of 49
© SecurePay Pty Ltd
SecurePay Java API integration Guide Version 1.3
5.2.1.1.3.15 getAdditionalInfo (Available in software v4.1.2, but not currently in use.)
public String getAdditionalInfo(int index, String fieldName)
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
index
Type
int
fieldName
String
Description
Index to the Txn object required,
or –1 to reference the Payment
object itself.
Name of field to return from the
object specified by index.
Allowed Values
int between –1 and getCount() – 1
Valid field name.
Return Parameter:
Type
String
5.2.1.2
Description
Value of field requested, or null if the field does not exist in the message.
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.
Page 15 of 49
© SecurePay Pty Ltd
SecurePay Java API integration Guide Version 1.3
5.2.1.2.1 Transaction Type Required Field Map
6
O
M
X
X
O
O
X
O
O
O
M
X
X
X
X
X
X
X
X
X
X
X
X
15
17
21
O
O
O
M
M
M
X
X
O
X
X
M
X
X
O
X
X
M
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
M
M
X
M
M
X
M
M
X
X
X
O
X
X
O
X
X
O
X
X
O
X
X
O
X
X
O
X
X
O
X
X
M
X = not required
(ignored if set)
Antifraud Only
Request
Antifraud
Payment
19
O
M
O
M
O
M
M
O
O
O
X
X
X
X
X
X
X
X
X
X
X
X
X
Direct
Entry
Credit Payment
14
O
M
O
M
O
O
X
O
O
O
X
X
X
X
X
X
X
X
X
X
X
X
X
Direct
Entry
Debit Payment
Complete
(Advice)
Preauthorise
10
11
O
O
M
M
O
X
M
X
O
O
M
O
X
X
O
O
O
O
O
O
X
X
X
M
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
O = optional
Card-Present
Payment
4
0
setTxnSource
O
O
setAmount
M
M
setCurrencyCode
O
X
setCardNumber
M
X
SetCVV
O
O
setExpiryDate
M
O
setTrack2Data
X
X
SetXID
O
O
SetCAVV
O
O
SetSLI
O
O
SetTxnId
X
M
setPreauthCode
X
X
setBsbNumber
X
X
setAccountNumber
X
X
setAccountName
X
X
setFirstName
X
X
setLastName
X
X
setZipCode
X
X
setTown
X
X
setBillingCountry
X
X
setDeliveryCountry
X
X
setEmailAddress
X
X
setIp
X
X
M = mandatory
Recurring
Payment
METHOD
Reversal
TYPE
Refund
TXN
Standard
Payment
The following table specifies which transaction parameters must be set for each available Txn type.
Parameters are mandatory, optional, or not required.
22
O
M
O
M
O
M
X
X
X
X
X
X
X
X
X
O
O
O
O
O
O
O
M
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.
5.2.1.2.2 Constructor
The Txn object cannot be constructed directly. It must be created by calling addTxn(…) in the
Payment object.
Page 16 of 49
© SecurePay Pty Ltd
SecurePay Java API integration Guide Version 1.3
5.2.1.2.3 Public Methods
5.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
value
Type
int
Description
Transaction source
Allowed Values
Refer to Appendix B
Return Parameter:
No object returned by this method.
5.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 HError! Reference
source not found.. (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
Value
Type
String
Description
Transaction amount in Australian
cents.
Allowed Values
String representing a
number > 0, with no
whitespace or currency
formatting.
Return Parameter:
No object returned by this method.
5.2.1.2.3.3
setCurrencyCode (Approved Multi‐Currency merchants only)
public void setCurrencyCode(String value)
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 multicurrency account with your bank to allow payments in other currencies. (Contact SecurePay
Support for further details.)
Page 17 of 49
© SecurePay Pty Ltd
SecurePay Java API integration Guide Version 1.3
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 the Appendix H.
Input Parameters:
Name
Value
Type
String
Description
Transaction currency code.
Allowed Values
One of the valid 3-letter codes
provided in the Appendix H to
this document.
Return Parameter:
No object returned by this method.
5.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
value
Type
String
Description
Customer’s credit card number.
Allowed Values
String of digits, no whitespace.
13-16 characters.
String must pass Luhn algorithm.
Return Parameter:
No object returned by this method.
5.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.
Input Parameters:
Name
value
Type
String
Description
Customer’s credit card CVV
number.
Allowed Values
3 or 4 digit string, no whitespace.
NULL or empty string is also
valid.
Page 18 of 49
© SecurePay Pty Ltd
SecurePay Java API integration Guide Version 1.3
Return Parameter:
No object returned by this method.
5.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
value
Type
String
Description
Customer’s credit card expiry
date.
Allowed Values
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.
5.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.
Input Parameters:
Name
value
Type
String
Description
Data retrieved from “track 2” on
the credit card’s magnetic strip.
Allowed Values
Return Parameter:
No object returned by this method.
5.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
Value
Type
String
Description
Transaction’s XID, as supplied
Allowed Values
Any 20-byte String
Page 19 of 49
© SecurePay Pty Ltd
SecurePay Java API integration Guide Version 1.3
to card issuer prior to sending
the financial transaction.
Return Parameter:
No object returned by this method.
5.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
Value
Type
String
Description
Transaction’s CAVV, as
supplied by card issuer prior to
sending the financial
transaction.
Allowed Values
28-character Base-64-encoded
string.
Return Parameter:
No object returned by this method.
5.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.
Input Parameters:
Name
Value
Type
String
Description
Transaction’s SLI, as supplied
by card issuer prior to sending
the financial transaction.
Allowed Values
2-digit String.
Return Parameter:
No object returned by this method.
5.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
value
Type
String
Description
Bank transaction ID of the
Allowed Values
6-30 character string
Page 20 of 49
© SecurePay Pty Ltd
SecurePay Java API integration Guide Version 1.3
original payment transaction.
Return Parameter:
No object returned by this method.
5.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
Value
Type
String
Description
Preauth ID of the original
preauth transaction.
Allowed Values
6 character string
Return Parameter:
No object returned by this method.
5.2.1.2.3.13 setBsbNumber
public void setBsbNumber()
Only for Direct Entry transactions.
Sets BSB number for financial institution.
Input Parameters:
Name
value
Type
String
Description
BSB number
Allowed Values
Numerical.
6 character string
Return Parameter:
No object returned by this method.
5.2.1.2.3.14 setAccountNumber
public void setAccountNumber()
Only for Direct Entry transactions.
Sets account number for financial institution.
Input Parameters:
Name
value
Type
String
Description
Account number
Allowed Values
Numerical.
4-9 character string
Return Parameter:
No object returned by this method.
Page 21 of 49
© SecurePay Pty Ltd
SecurePay Java API integration Guide Version 1.3
5.2.1.2.3.15 setAccountName
public void setAccountName()
Only for Direct Entry transactions.
Sets account name for financial institution.
Input Parameters:
Name
Value
Type
String
Description
Account name
Allowed Values
String using characters from
Appendix I up to 32 characters
in length.
Return Parameter:
No object returned by this method.
5.2.1.2.3.16 setFirstName
public void setFirstName()
Only for antifraud transactions.
Sets customer’s first name.
Input Parameters:
Name
Value
Type
String
Description
Customer’s first name
Allowed Values
String, max length 40.
Return Parameter:
No object returned by this method.
5.2.1.2.3.17 setLastName
public void setFirstName()
Only for antifraud transactions.
Sets customer’s last name.
Input Parameters:
Name
Value
Type
String
Description
Customer’s last name
Allowed Values
String, max length 40.
Return Parameter:
No object returned by this method.
5.2.1.2.3.18 setZipCode
public void setZipCode()
Only for antifraud transactions.
Sets customer’s address zip code or postal code.
Page 22 of 49
© SecurePay Pty Ltd
SecurePay Java API integration Guide Version 1.3
Input Parameters:
Name
Value
Type
String
Description
Customer’s address zip code or
postal code
Allowed Values
String, max length 30.
Return Parameter:
No object returned by this method.
5.2.1.2.3.19 setTown
public void setTown()
Only for antifraud transactions.
Sets billing or delivery town of the buyer.
Input Parameters:
Name
Value
Type
String
Description
Billing or delivery town of the
buyer
Allowed Values
String, max length 60.
Return Parameter:
No object returned by this method.
5.2.1.2.3.20 setBillingCountry
public void setBillingCountry()
Only for antifraud transactions.
Sets ISO country code of the billing address.
Input Parameters:
Name
Value
Type
String
Description
ISO country code of the billing
address.
Allowed Values
3 digit numeric ISO code or 2 or
3 alpha character ISO code.
Return Parameter:
No object returned by this method.
5.2.1.2.3.21 setDeliveryCountry
public void setDeliveryCountry()
Only for antifraud transactions.
Sets ISO country code of the delivery address.
Input Parameters:
Name
Value
Type
String
Description
ISO country code of the delivery
address.
Allowed Values
3 digit numeric ISO code or 2 or
3 alpha character ISO code.
Return Parameter:
No object returned by this method.
5.2.1.2.3.22 setEmailAddress
public void setEmailAddress()
Only for antifraud transactions.
Page 23 of 49
© SecurePay Pty Ltd
SecurePay Java API integration Guide Version 1.3
Sets email address of the customer.
Input Parameters:
Name
Value
Type
String
Description
Customer’s email address.
Allowed Values
String, max length 100.
Return Parameter:
No object returned by this method.
5.2.1.2.3.23 setIp
public void setTown()
Only for antifraud transactions.
IP address from which the transaction originated.
Input Parameters:
Name
Value
Type
String
Description
IP address from which the
transaction originated.
Allowed Values
String, max length 15, must
contain 3 p
Return Parameter:
No object returned by this method.
5.2.1.2.3.24 getTxnType
public int getTxnType()
Returns the transaction type for the transaction. Refer to Appendix A for values of this field.
Input Parameters:
No input parameters are required by this method.
Return Parameter:
Type
int
Description
Integer representing the transaction type of this Txn.
5.2.1.2.3.25 getTxnSource
public int getTxnSource()
Returns the transaction source for this transaction. Refer to Appendix B for values of this field.
Input Parameters:
No input parameters are required by this method.
Return Parameter:
Type
int
Description
Integer representing the source of the transaction.
5.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
Page 24 of 49
© SecurePay Pty Ltd
SecurePay Java API integration Guide Version 1.3
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
String
Description
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.
5.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 H.
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 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
String
Description
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.
5.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
String
Description
The purchase order number referring to the transaction.
Page 25 of 49
© SecurePay Pty Ltd
SecurePay Java API integration Guide Version 1.3
NULL if the purchase order number has not been set.
5.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
String
Description
The truncated credit card number or BSB and account numbers of this
financial transaction.
NULL if the card number has not been set.
5.2.1.2.3.30 getCardType
public int getCardType()
Only for Credit Card transactions.
Returns an integer representing the type of card used. Refer to Appendix C.
Input Parameters:
No input parameters are required by this method.
Return Parameter:
Type
int
Description
The credit card type code of the card number used.
5.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.
Page 26 of 49
© SecurePay Pty Ltd
SecurePay Java API integration Guide Version 1.3
Input Parameters:
No input parameters are required by this method.
Return Parameter:
Type
String
Description
Description of the type of credit card used.
5.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
String
Description
The Card Verification Value of this financial transaction.
NULL if the value has not been set, or if the transaction has been processed.
5.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
String
Description
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.
5.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
Page 27 of 49
© SecurePay Pty Ltd
SecurePay Java API integration Guide Version 1.3
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.
5.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
String
Description
The 3D-Secure XID of this financial transaction.
NULL if the value has not been set, or if the transaction has already been
processed.
5.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
String
Description
The 3D-Secure CAVV of this financial transaction.
NULL if the value has not been set, or if the transaction has already been
processed.
5.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:
Page 28 of 49
© SecurePay Pty Ltd
SecurePay Java API integration Guide Version 1.3
No input parameters are required by this method.
Return Parameter:
Type
String
Description
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.
5.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
String
Description
The BSB number referring to the transaction.
NULL if the BSB number has not been set.
5.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
String
Description
The account number referring to the transaction.
NULL if the account number has not been set.
5.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.
Return Parameter:
Type
String
Description
The account name referring to the transaction.
NULL if the account name has not been set.
Page 29 of 49
© SecurePay Pty Ltd
SecurePay Java API integration Guide Version 1.3
5.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
String
Description
3-digit SecurePay / gateway response.
5.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
String
Description
Description of antifraud response received.
5.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
boolean
Description
true if the payment was authorised by the merchant bank and customer card
issuer, or false in any other case.
5.2.1.2.3.44 getResponseCode
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)
Page 30 of 49
© SecurePay Pty Ltd
SecurePay Java API integration Guide Version 1.3
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
String
Description
2-digit bank response or 3-digit SecurePay / gateway response.
5.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
String
Description
Description of response received from API, SecurePay, or bank.
NULL if the transaction has not yet been processed.
5.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 Appendix G.1 Payment Result Codes for details of codes returned.
Input Parameters:
No input parameters are required by this method.
Return Parameter:
Type
String
Description
3-digit Thinlink Payment Result Code
5.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:
Type
String
Description
3-digit Thinlink Payment Result Description (“000”).
Page 31 of 49
© SecurePay Pty Ltd
SecurePay Java API integration Guide Version 1.3
5.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 Appendix
G.2 Event Status Codes for details of codes returned.
Input Parameters:
No input parameters are required by this method.
Return Parameter:
Type
String
Description
3-digit Thinlink Event Status Code
5.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
String
Description
Textual description of the Event Status Code.
5.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
String
Description
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.
Page 32 of 49
© SecurePay Pty Ltd
SecurePay Java API integration Guide Version 1.3
5.2.1.2.3.51 getTxnId
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
String
Description
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.
5.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
String
5.2.1.3
Description
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.
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());
+
Page 33 of 49
© SecurePay Pty Ltd
SecurePay Java API integration Guide Version 1.3
// Set Payment values
payment.setServerURL(
“http://fakeurl.com/payment”);
//
Dummy
payment
please use the URL supplied by SecurePay Support
payment.setProcessTimeout(80);
// 80 seconds
payment.setMerchantId(“XYZ9999”);
//
ID
allocated
SecurePay
URL,
by
// Add a Txn to the container
//
type = 0 (payment)
//
ponum = “SecurePayTest”
Txn txn = payment.addTxn(0, “SecurePayTest”);
// Set the Txn values
txn.setTxnSource(8);
txn.setAmount(“1000”);
txn.setCurrencyCode(“AUD”);
txn.setCardNumber(“4444333322221111”);
txn.setCVV(“456”);
txn.setExpiryDate(“03/06”);
// API source
// A$10.00
// Australian Dollars
// dummy card number
// dummy CVV (optional)
// 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);
queue
//
First
Txn
in
response
// 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();
}
}
Page 34 of 49
© SecurePay Pty Ltd
SecurePay Java API integration Guide Version 1.3
5.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());
+
// Set Payment values
payment.setServerURL(
“http://fakeurl.com/payment”);
//
Dummy
payment
please use the URL supplied by SecurePay Support
payment.setProcessTimeout(80);
// 80 seconds
payment.setMerchantId(“XYZ9999”);
//
ID
allocated
SecurePay
URL,
by
// 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);
txn.setAmount(“1000”);
txn.setCurrencyCode(“AUD”);
txn.setTxnId(“123123”);
// API source
// A$10.00
// Australian Dollars
// 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);
queue
//
First
Txn
in
response
// 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());
Page 35 of 49
© SecurePay Pty Ltd
SecurePay Java API integration Guide Version 1.3
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();
}
}
5.2.2
5.2.2.1
Echo
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.
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.
5.2.2.2
Constructor
public Echo()
Create an empty Echo object.
Parameters:
No parameters required by this constructor.
5.2.2.2.1 Public Methods
5.2.2.2.1.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
String
5.2.2.2.1.2
Description
Unique identifier of this Echo object.
getMessageTimestamp
public Date getMessageTimestamp()
Returns the timestamp created by the API for the Echo in a Date object.
Input Parameters:
Page 36 of 49
© SecurePay Pty Ltd
SecurePay Java API integration Guide Version 1.3
No input parameters are required by this method.
Return Parameter:
Type
Date
5.2.2.2.1.3
Description
Timestamp of this Echo object.
getMessageTimestampAsString
public String getMessageTimestampAsString()
Returns the timestamp created by the API for the Echo as a string. Refer to Appendix E for the
format of the string returned.
Input Parameters:
No input parameters are required by this method.
Return Parameter:
Type
String
5.2.2.2.1.4
Description
Timestamp of this Echo object.
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
String
5.2.2.2.1.5
Description
API version used to create this Echo object.
setMerchantId
public void setMerchantId(String id)
Sets the merchant id to be used when processing the echo request.
Input Parameters:
Name
id
Type
String
Description
Merchant ID allocated
merchant by SecurePay.
to
the
Allowed Values
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).
Page 37 of 49
© SecurePay Pty Ltd
SecurePay Java API integration Guide Version 1.3
Last two digits can be
ignored.
Return Parameter:
No object returned by this method.
5.2.2.2.1.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
url
Type
String
Description
URL of SecurePay’s server.
Allowed Values
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.
5.2.2.2.1.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
timeout
Type
int
Description
Seconds to
response.
wait
for
SecurePay
Allowed Values
Int < 0: default value is
used
Int >= 0: supplied
value is used.
Return Parameter:
No object returned by this method.
5.2.2.2.1.8
Process
public boolean process(String password)
Page 38 of 49
© SecurePay Pty Ltd
SecurePay Java API integration Guide Version 1.3
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 Secure Java V4.0.3a, the password parameter must be passed to this method. Previous
releases of Secure Java 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”.
Input Parameters:
Name
password
Type
String
Description
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.
Allowed Values
The password is allocated
to you by SecurePay when
you receive this software,
and can be changed via the
Merchant Login website.
Return Parameter:
Type
Boolean
5.2.2.2.1.9
Description
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.
getStatusCode
public long getStatusCode()
Returns the status code of the Echo. Refer to Appendix F for more details.
Input Parameters:
No input parameters are required by this method.
Return Parameter:
Type
long
Description
Code representing the status of the Echo object after processing.
5.2.2.2.1.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
String
Description
Textual description of the status of the Echo object after processing.
Page 39 of 49
© SecurePay Pty Ltd
SecurePay Java API integration Guide Version 1.3
5.2.2.3
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(
“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();
}
}
Page 40 of 49
© SecurePay Pty Ltd
SecurePay Java API integration Guide Version 1.3
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
0
1
2
3
4
5
6
10
11
14
15
17
19
20
21
22
Description
Standard Payment
Mobile Payment
Batch Payment
Periodic Payment
Refund
Error Reversal (Void)
Client Reversal (Void)
Preauthorise
Preauth Complete (Advice)
Recurring Payment
Direct Entry Debit
Direct Entry Credit
Card-Present Payment
IVR Payment
Antifraud payment
Antifraud (only) request
Page 41 of 49
© SecurePay Pty Ltd
SecurePay Java API integration Guide Version 1.3
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
0
1
2
3
4
5
7
8
9
10
11
12
13
14
16
18
19
23
24
25
90
Description
Unknown (default)
SecureLink
Merchant Login
SATM
SecureBill Portal
SecureBill Link
SecurePOS
API (Secure Java)
Call Centre Payment Switch
Batch Server
IVR1
IVR2
SecureMobile
Reconciliation Engine
Helpdesk Login
eSec Interface
Periodic Server
SecureXML
DirectOne Interface
Antifraud Server
Reserved
Page 42 of 49
© SecurePay Pty Ltd
SecurePay Java API integration Guide Version 1.3
Appendix C: Card Types
SecurePay uses numeric codes to refer to credit card types in our system.
Code
0
1
2
3
4
5
6
Description
Unknown
JCB
American Express (Amex)
Diners Club
Bankcard
MasterCard
Visa
Page 43 of 49
© SecurePay Pty Ltd
SecurePay Java API integration Guide Version 1.3
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
Visa
MasterCard
Bankcard
Amex
Diners Club
JCB
Location
Signature strip on back of card. Last digits of card
printed in reverse italics, followed by 3-digit CVV.
Signature strip on back of card. Last digits of card
printed in reverse italics, followed by 3-digit CVV.
Signature strip on back of card. Last digits of card
printed in reverse italics, followed by 3-digit CVV.
4 digit CVV above card number on front of card.
Signature strip on back of card. Last digits of card
printed in reverse italics, followed by 3-digit CVV.
Not used
number are renumber are renumber are renumber are re-
Page 44 of 49
© SecurePay Pty Ltd
SecurePay Java API integration Guide Version 1.3
Appendix E: Timestamp String Format
The format of the Timestamp or Log Time strings returned by Secure Java 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 =0)
•
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:
20022406171216789000+600
Page 45 of 49
© SecurePay Pty Ltd
SecurePay Java API integration Guide Version 1.3
Appendix F: SecurePay Status Codes
Status
Code
0
504
Response Text
Normal
Invalid Merchant ID
505
510
Invalid URL
Unable To Connect To Server
511
Server Connection Aborted
During Transaction
Transaction timed out By
Client
512
513
514
General Database Error
Error loading properties file
515
Fatal Unknown Error
516
517
Request type unavailable
Message Format Error
524
545
Response not received
System
maintenance
in
progress
Invalid password
Not implemented
Too Many Records for
Processing
Process method has not been
called
Merchant Disabled
550
575
577
580
595
Description
Message processed correctly (check transaction response for details).
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.
The URL passed to either Echo, or Payment object is invalid.
Produced by SecurePay Client API when unable to establish connection to
SecurePay Payment Gateway
Produced by SecurePay Client API when connection to SecurePay Payment
Gateway is lost after the payment transaction has been sent
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)
Unable to read information from the database.
Payment Gateway encountered an error while loading configuration
information for this transaction
Transaction could not be processed by the Payment Gateway due to unknown
reasons
SecurePay system doesn’t support the requested transaction type
SecurePay Payment Gateway couldn’t correctly interpret the transaction
message sent
The client could not receive a response from the server.
The system maintenance is in progress and the system is currently unable to
process transactions
The merchant has attempted to process a request with an invalid password.
This functionality has not yet been implemented
The maximum number of allowed events in a single message has been
exceeded.
The process() method on either Echo, or Payment object has not been called
SecurePay has disabled the merchant and the requests from this merchant
will not be processed.
Page 46 of 49
© SecurePay Pty Ltd
SecurePay Java API integration Guide Version 1.3
Appendix G: Thinlink Codes
G.1 Payment Result Codes
Code
100
200
300
400
999
Description
Payment approved
Payment declined
Payment incomplete – Unable to process, try again later
Scheduled – Execution pending
Unknown status
G.2 Event Status Codes
Code
000
002
980
981
982
984
Description
Normal Completion
No event to process
Error – Bad Card Number
Error – Expired Card
Error – Invalid Transaction Type
Error – Formatting Error
Code
986
988
990
991
992
999
Description
Error – Invalid Email Address
Error – Unknown Currency
Error – Invalid Amount
Error – Invalid MTID
Error – Duplicate Invoice Number
Error – Unspecified
Page 47 of 49
© SecurePay Pty Ltd
SecurePay Java API integration Guide Version 1.3
Appendix H: Currency Codes List
IMPORTNANT NOTICE:
You must meet certain requirements with your bank and SecurePay before using SecurePay’s multicurrency 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.
Code
AUD
CAD
CHF
DEM
EUR
FRF
GBP
GRD
HKD
ITL
JPY
NZD
SGD
USD
Description
Australian Dollar
Canadian Dollar
Swiss Franc
German Deutschmark
Euro
French Franc
English Pound
Greek Drachma
Hong Kong Dollar
Italian Lira
Japanese Yen
New Zealand Dollar
Singapore Dollar
US Dollar
Minor Units
2
2
2
2
2
2
2
0
2
0
0
2
2
2
Example*
Amount Pass As
$20
2000
$20
2000
20
2000
20
2000
€20
2000
20
2000
£20
2000
20
20
$20
2000
L20
20
¥20
20
$20
2000
$20
2000
$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”);
Page 48 of 49
© SecurePay Pty Ltd
SecurePay Java API integration Guide Version 1.3
Appendix I: Direct Entry Character set
Description
Numeric
Alphabetic
Oblique slash
Hyphen
Ampersand
Period
Asterisk
Apostrophe
Blank space
Characters allowed
0-9
a – z, A - Z
/
&
.
*
‘
Page 49 of 49
© SecurePay Pty Ltd
SecurePay Java API integration Guide Version 1.3
Source Exif Data:
File Type : PDF File Type Extension : pdf MIME Type : application/pdf PDF Version : 1.4 Linearized : No XMP Toolkit : Adobe XMP Core 4.0-c316 44.253921, Sun Oct 01 2006 17:14:39 Creator Tool : PScript5.dll Version 5.2.2 Modify Date : 2011:05:09 12:12:32+09:30 Create Date : 2011:05:09 12:11:30+09:30 Metadata Date : 2011:05:09 12:12:32+09:30 Format : application/pdf Title : Secure Java API Integration Guide Creator : SecurePay Description : Secure Java API Integration Guide Producer : Acrobat Distiller 8.1.0 (Windows) Document ID : uuid:509f7fab-91b4-4890-a757-782889efcd43 Instance ID : uuid:622b40e2-6c96-4556-a505-051caac59c77 Page Count : 49 Subject : Secure Java API Integration Guide Author : SecurePay Warning : [Minor] Ignored duplicate Info dictionaryEXIF Metadata provided by EXIF.tools