The CCVS Java language API lets you access the functionality of CCVS
from within Java programs.
The Java API consists of two classes, net.hks.Ccvs and
net.hks.CcvsException. The Ccvs object is
instantiated for each session, and then all commands are performed by
invoking methods of that session object.
Building the CCVS Java Interface
The Java interface to CCVS must sometimes be built after the rest of CCVS
is installed. See the
Java Installation Guide.
Before You Run
Before you can load the CCVS class, you must add the pathname of the
ccvs.jar file to your CLASSPATH environment variable.
If you used the default installation location, that would be
/usr/local/ccvs/class/ccvs.jar
You must also add the directory containing the libccvsjni.so
file to your LD_LIBRARY_PATH environment variable. The default
installation location is
/usr/local/ccvs/class
Note that CLASSPATH must contain a file, whereas LD_LIBRARY_PATH
must contain a directory.
Method Results
Most of these functions return a numeric value.
However, there may
also be a "text return value", which contains more information about
the status of the last operation. To get the text return value of an
operation, call cv_textvalue() immediately after the
function call in question.
public net.hks.Ccvs(java.lang.String configname)
throws net.hks.CcvsException
Usage
Prior to using any other functions, you must instantiate a
net.hks.Ccvs session object. The constructor takes one
argument, the name of the configuration; this sets various parameters
such as the phone number to call to process transactions, and the
merchant number to transfer funds to.
(If the configuration directory is not at its default location,
you must set the CCVS_CONFIG_DIR environment variable to point
to it.)
If the CCVS library cannot be initialized for any reason, the exception
net.hks.CcvsException will be thrown. (More specific information
about the error will be logged to syslog() through the user facility.)
Once the session object exists, you can use the standard CCVS
function calls, which are its methods. (There is no equivalent to
cv_done(); the regular finalize method of
the Ccvs class takes care of terminating the CCVS
engine.)
Immediately after the session object is constructed, its text return
value contains the CCVS library version number. You can access this with
the cv_textvalue() method.
For example, to use a demonstration protocol configuration,
one could use the code:
The cv_new() method creates a blank transaction
for processing.
Its state is CV_NEW.
Since there are many possible attributes a transaction can
have, and most of them are optional, you must then add them one at a time
with the cv_add() method.
The invoice is a label which you will use to refer to the
transaction. Invoices are not case-sensitive (and are always displayed in
upper case). The invoice is limited to eight alphanumeric characters.
Characters beyond the eighth will be truncated. If you enter an
invoice shorter than eight characters, it will be padded on the
right with "X" characters. (For example, if you enter an invoice of "abc",
it will be stored as "ABCXXXXX", although you can still refer to it as
"abc" or "ABC".)
cv_new() can return:
CV_OK (success),
CV_E_UNINIT (session not initialized),
CV_E_DUPINVOICE (duplicate invoice),
CV_E_DATA (database error),
CV_E_UNKNOWN (unknown error).
The text return value describes the error if one occurred.
public int cv_add(java.lang.String invoice,
int argtype, java.lang.String argval)
Usage
The cv_add() method adds data to a transaction, such as
a credit card number, a dollar amount, or a billing address. The argtype
determines what you're adding to the transaction, and the argval
is the actual data. The argument types and values are as follows. Note that
not all arguments are meaningful for every protocol.
cv_add() can only be used on a transaction in the
CV_NEW state; the transaction remains in CV_NEW.
net.hks.Ccvs.CV_ARG_AMOUNT
Specifies the amount of the transaction, in dollars and cents (for
example, "29.95").
You may enter a whole dollar amount ("29" and "29.00"
mean the same thing), but if you use a decimal point it must be followed
by two digits. (Leading spaces and dollar signs are ignored. Trailing
spaces are ignored. Other punctuation is illegal.)
This should be the total amount, including tax if any.
Note that "0" or "0.00" is usually an illegal
amount.
net.hks.Ccvs.CV_ARG_CARDNUM
Specifies the credit card number being used.
Punctuation (dashes, commas, spaces, etc) are ignored.
net.hks.Ccvs.CV_ARG_EXPDATE
Specifies the card's expiration date, in MM/YY format. The slash is
optional.
net.hks.Ccvs.CV_ARG_TRACK1
Specifies data read from track 1 of a credit card, using a magnetic
stripe reader. You must include the entire data string read, including
delimiters.
net.hks.Ccvs.CV_ARG_TRACK2
Specifies data read from track 2 of a credit card, using a magnetic
stripe reader. You must include the entire data string read, including
delimiters.
net.hks.Ccvs.CV_ARG_AVS_ADDRESS
Specifies the cardholder billing address, to be used in conjunction
with the address verification service of the clearing house.
net.hks.Ccvs.CV_ARG_AVS_ZIPCODE
Specifies the zipcode (5 or 9 digit) of the billing address, also to
be used with address verification.
net.hks.Ccvs.CV_ARG_TYPE
Specifies the type of the transaction. Valid values
are:
mail
phone
recurring
installment
retail
ecommerce
test
unknown
(This information is optional, but specifying it
can improve the rate on your merchant account under some protocols.)
net.hks.Ccvs.CV_ARG_ACCOUNTNAME
The name of the customer, as shown on the credit card account. Some
processors require this attribute in order to generate receipts.
net.hks.Ccvs.CV_ARG_PRODUCT
The name or description of the product being purchased. Some processors
require this attribute in order to generate receipts.
net.hks.Ccvs.CV_ARG_ACODE
Specifies an authorization code for a transaction. You can use this
to settle a transaction that CCVS has not authorized -- for example,
if you do a voice authorization. (CCVS does not support this
procedure for all protocols.)
net.hks.Ccvs.CV_ARG_TAX
The amount of tax in the transaction, in dollars and cents
(for example, "1.16". The format rules are the same as for
CV_ARG_AMOUNT).
(This information is optional, but specifying it
can improve the rate on your merchant account under some protocols.)
net.hks.Ccvs.CV_ARG_PURCHASEORDER
This specifies a purchase order number, which some protocols
require for purchase card support. Note that
in some protocols, you should enter a purchase
order number in CV_ARG_COMMENT, not
CV_ARG_PURCHASEORDER.
See the CCVS protocol guide in the CCVS on-line documentation
for details.
net.hks.Ccvs.CV_ARG_ENTRYSOURCE
The source of the cardholder information -- that is, who
was responsible for entering the data in this transaction.
merchant
customer
(This information is optional, but specifying it
can improve the rate on your merchant account under some protocols.)
net.hks.Ccvs.CV_ARG_SHIP_ZIPCODE
specifies the zip code of the customer's shipping address (as opposed
to the billing address.)
(This information is optional.)
net.hks.Ccvs.CV_ARG_CVV2
Specifies the CVV2 (Card Verification Value 2) code of the credit card.
This can be a number of up to four digits, or one of the
following (case-insensitive) strings:
notprinted
(no value printed on card)
illegible
(value printed but unreadable)
none
(intentionally not provided)
(This information is optional, but specifying it
can improve the rate on your merchant account under some protocols.)
net.hks.Ccvs.CV_ARG_ENCRYPTION
Indicates whether the customer-to-merchant communication channel was
encrypted. The (case-insensitive) value can be:
yes
no
Note that there are also argument types for more specific types of
encryption, such as SET. If you specify one of those, CCVS assumes
that encryption is used, regardless of the value of
CV_ARG_ENCRYPTION.
(This information is optional, but specifying it
can improve the rate on your e-commerce merchant account under some
protocols.)
net.hks.Ccvs.CV_ARG_SET_MERCHANT
Specifies that SET encryption was used for the customer-to-merchant
communication channel, and gives the merchant's certificate value.
If a cardholder certificate was also used, you should also include
the CV_ARG_SET_CARDHOLDER argument.
(This information is optional, but specifying it
can improve the rate on your e-commerce merchant account under some
protocols.)
net.hks.Ccvs.CV_ARG_SET_CARDHOLDER
Specifies the cardholder's SET certificate value. This argument is
only meaningful if CV_ARG_SET_MERCHANT is also used.
net.hks.Ccvs.CV_ARG_COMMENT
Specifies a comment, up to 25 characters (case insensitive), that will
be attached to the transaction and sent with it to the clearing house.
(This is not used by all protocols.)
cv_add() can return:
CV_OK (success),
CV_E_UNINIT (session not initialized),
CV_E_BADINVOICE (bad invoice),
CV_E_SYNTAXERROR (syntax error in arguments),
CV_E_DATA (database error),
CV_E_UNKNOWN (unknown error).
The text return value describes the error if one occurred.
The cv_delete() method is used to delete a transaction
when you no longer want it to be stored in the system. Transactions can
only be deleted if they're in certain states (see cv_status()).
The allowed states are CV_NEW, CV_AUTH, CV_REVIEW,
CV_DENIED, CV_DONE and CV_BAD.
Note that it's important to delete transactions after you're completely
done with them. Since invoices must be unique, you can't reuse them until
the old transaction is deleted. In addition, each transaction consumes
a small amount of system resources; given enough transactions, it's possible
for this to eventually become a problem.
cv_delete() can return:
CV_OK (success),
CV_E_UNINIT (session not initialized),
CV_E_BADINVOICE (bad invoice),
CV_E_UNKNOWN (unknown error).
The text return value describes the error if one occurred.
The cv_auth() method is used to perform a credit authorization
test. The invoice
must refer to a transaction previously created with cv_new().
This only does an authorization check; no money is actually transferred.
To transfer money, after doing a cv_auth(), you must do a
cv_sale().
cv_auth() does not wait for the authorization to
complete; it moves the transaction to the CV_UNAUTH state
and returns immediately. To determine if the authorization was
approved or denied, you need to watch for the transaction to move to
the CV_AUTH, CV_DENIED, or CV_REVIEW
states. See the cv_status() method.
cv_auth() can return:
CV_OK (success),
CV_E_UNINIT (session not initialized),
CV_E_BADINVOICE (bad invoice),
CV_E_DUPINVOICE (already done to this transaction),
CV_E_INVALID (invalid action for this transaction),
CV_E_UNKNOWN (unknown error).
The text return value describes the error if one occurred.
The cv_sale() method is used to transfer funds from the
credit card holder to the merchant. The invoice must refer to
a transaction previously authorized with cv_auth().
cv_sale() can return:
CV_OK (success),
CV_E_UNINIT (session not initialized),
CV_E_BADINVOICE (bad invoice),
CV_E_DUPINVOICE (already done to this transaction),
CV_E_INVALID (invalid action for this transaction),
CV_E_UNKNOWN (unknown error).
The text return value describes the error if one occurred.
The cv_return() method is used to transfer funds from
the merchant to the credit card holder. Its invoice must refer
to a transaction previously created with cv_new().
cv_return() can return:
CV_OK (success),
CV_E_UNINIT (session not initialized),
CV_E_BADINVOICE (bad invoice),
CV_E_DUPINVOICE (already done to this transaction),
CV_E_INVALID (invalid action for this transaction),
CV_E_UNKNOWN (unknown error).
The text return value describes the error if one occurred.
The cv_reverse() method is used to perform a full reversal
on an already-processed authorization. Its invoice must refer
to a transaction previously processed with cv_auth().
cv_reverse() can return:
CV_OK (success),
CV_E_UNINIT (session not initialized),
CV_E_BADINVOICE (bad invoice),
CV_E_DUPINVOICE (already done to this transaction),
CV_E_INVALID (invalid action for this transaction),
CV_E_UNKNOWN (unknown error).
The text return value describes the error if one occurred.
The cv_void() method is used to perform a full reversal
on a completed transaction. Its invoice must refer to a transaction
previously processed with cv_sale() or cv_return().
cv_void() can return:
CV_OK (success),
CV_E_UNINIT (session not initialized),
CV_E_BADINVOICE (bad invoice),
CV_E_DUPINVOICE (already done to this transaction),
CV_E_INVALID (invalid action for this transaction),
CV_E_UNKNOWN (unknown error).
The text return value describes the error if one occurred.
The cv_status() method is used to check the status of
an invoice. You can use this to determine if a given
invoice is in use, and if it is, to examine the transaction
it names.
It returns CV_NONE if the invoice
is not in use, or one of the transaction states:
CV_NEW, CV_UNAUTH, CV_AUTH,
CV_DENIED, CV_REVIEW,
CV_READY, CV_DONE, CV_BAD.
The text return value shows the state as a string,
and also other information about the transaction: invoice, amount, the
timestamps which show when it was created and processed, and so on.
Sensitive information, such as the credit-card number, will not
be included.
cv_status() can also return one of the CV_E_...
error codes described elsewhere in this document.
In this case, you may check the
text return value to get more information about the error.
The most
important use of cv_status() is to determine whether an authorization
was approved or denied. When you use the cv_auth() method,
the transaction's state changes from CV_NEW to CV_UNAUTH.
Background processing will automatically change the state from CV_UNAUTH
to either CV_AUTH, CV_DENIED or CV_REVIEW.
A state of CV_AUTH indicates approval, a state of CV_DENIED
indicates denial, and a state of CV_REVIEW indicates a special
case, such as failed AVS verification or a request for voice authorization.
The cv_count() method is used to find out how many transactions
of a given type are stored in the system. The types are CV_NEW,
CV_UNAUTH, CV_AUTH, CV_DENIED, CV_REVIEW,
CV_READY, CV_DONE and CV_BAD.
You can use the bitwise "or" operator to combine these.
For example,
ccvsSession.cv_count(CV_AUTH|CV_DENIED|CV_REVIEW)
will count the authorizations that have already been handled by the
background processor.
The constant CV_ALL can be used to count everything.
The numeric return value will be the simple sum of everything
counted. The text return value (accessed via cv_textvalue())
will give a breakdown of how many transactions of each type are in the
system.
The cv_lookup() method can be used to look up an item of
a particular type in the database.
Its type argument can be any of the
eight types valid for cv_count(). (This may not be
CV_ALL, or a combination of more than one type.)
Its itemnum argument determines which item to look
up. (1 indicates the first item of the given type, 2 the second, and
so on.)
cv_lookup() can return:
CV_OK (success),
CV_E_UNINIT (session not initialized),
CV_E_SYNTAXERROR (syntax error in arguments).
The textvalue will be a string that contains the
invoice of the transaction which was found.
The cv_report() method returns the status of the background
communication process. Pass in CV_REP_SERVER as the type
argument to check the status of ccvsd (which processes auths
and reversals.) Pass in CV_REP_UPLOAD to check the status of
cvupload (which must be run periodically to process sales
and returns).
cv_report() can return:
CV_OK (success),
CV_E_UNINIT (session not initialized),
CV_E_SYNTAXERROR (syntax error in arguments),
CV_E_UNKNOWN (unknown error).
The report itself
is returned in the library's text value.
public int cv_command(int cmd, java.lang.String argval)
Usage
The cv_command() method performs a command which is peculiar
to a single protocol, and thus is not available in the general CCVS API.
The argval argument is additional information which pertains
to the command. (If none is necessary, you should pass in null.)
See the documentation on your protocol for commands which can be used with
it.
If you pass a command to a protocol which does not understand it, cv_command()
will return CV_E_INVALID.
cv_command() can return:
CV_OK (success),
CV_E_UNINIT (session not initialized),
CV_E_INVALID (invalid action for this transaction or this protocol),
CV_E_SYNTAXERROR (syntax error in arguments),
CV_E_UNKNOWN (unknown error).
The text return value may contain more information, depending on the
command you are performing.
Various methods return both numeric and text values. The numeric values
are the return values of the methods. To get the text values, call cv_textvalue()
immediately after the related method call.
public static java.lang.String errorString(int stat)
Usage
This method converts an integer CCVS error code to a String equivalent.
For example, it turns hks.net.Ccvs.CV_E_INVALID to the string
"invalid request".
The transaction statuses, as returned by cv_status(), are:
net.hks.Ccvs.CV_NONE
if the transaction is not in the system,
net.hks.Ccvs.CV_NEW
if the transaction has been created and no operations have been performed
on it,
net.hks.Ccvs.CV_UNAUTH
if the transaction has been subject to a cv_auth() but
hasn't been processed yet,
net.hks.Ccvs.CV_AUTH
if the transaction has been approved,
net.hks.Ccvs.CV_DENIED
if the transaction has been denied,
net.hks.Ccvs.CV_REVIEW
if the transaction requires review by a human (for example if the authorization
requires voice approval),
net.hks.Ccvs.CV_READY
if the transaction has been subject to a cv_sale() or
cv_return() but hasn't been processed yet,
net.hks.Ccvs.CV_DONE
if the transaction has been subject to a cv_sale() or
cv_return() and all processing is complete, or
net.hks.Ccvs.CV_BAD
if there was some problem processing a transaction subject to cv_sale()
or cv_return().
The text return value is formatted as a set of key-value pairs.
Calling cv_textvalue()
returns a string of the form "key {value} key {value} ...".
These are the keys which can appear:
text
For online transactions, this is the text returned by the clearing
house.
invoice
When returned, this is the invoice of the corresponding
transaction.
status
When returned, this is the status of the transaction.
It can be any of the possible status values,
represented as a lower-case string: "new", "unauth",
"review", "auth", "denied", "ready", "bad", "done", or "none" to
indicate that the transaction does not exist at all.
amount
This is the amount of the transaction, in dollars and cents. A pending
return transaction shows a negative amount.
newtime
This is the time and date at which a transaction was created via cv_new().
authtime
When present, this is the time and date at which a cv_auth()
operation was done on the transaction in question.
readytime
When present, this is the time and date at which the transaction was
processed by either the cv_sale() or cv_return()
methods.
donetime
For protocols other than ETC+, this is the time and date at which a
transaction processed by either cv_sale() or cv_return()
was actually handled by the clearing house.
avs
This describes the success or failure of address verification for the
transaction. It can be "ok", "fail", or any of a number of
other strings representing various processing errors. (It is impossible
to give a complete list, as these errors vary from processor to processor.
However, you may take them all to indicate that no AVS information was
available for the transaction.)
If the avs field is "ok" or "fail", the avs_addr
and avs_zip fields will also be present.
avs_addr
This describes the success or failure of the address component of the
address verification feature. It can be "ok" or "fail".
avs_zip
This describes the success or failure of the zipcode component of the
address verification feature. It can be "ok", "fail", or
"partial". ("partial" indicates that only part of the zip
code matched -- for example, a five-digit match when an extended
nine-digit zip code was available.)
acode
This is the authorization code returned for a successful authorization.
result_text
This is human-readable text that the processor intends to be displayed
on the LCD display of a hardware POS terminal. This varies
considerably from processor to processor, and each processor generally
reserves the right to change the allowed values without notification.
It's still very useful, as it often contains the approval code even
when the acode field cannot be set. It can also contain information
outside the scope of other fields, such as "call center"
or "card stolen".
authchar
This describes the authorization characteristics of some transactions.
For example, if you attempt to use address verification and the clearing
house doesn't support it for the transaction in question, this field will
say so.
cvv2
This describes the success or failure of CVV2 verification for the
transaction. It can be "ok", "fail", or any of a
number of other strings representing various processing errors.
(You may take them all to indicate that no CVV2 information was
available for the transaction.)
task
For the cv_report() method, this is the task
being performed.
current
For the cv_report() method, this is the current item
being worked on (usually an invoice).
time
For the cv_report() method, this is the time at
which the action was reported.
