The CCVS TCL language API lets you access the functionality of CCVS from
within TCL or Tk scripts. To take advantage of the API, you have to import
the API module, with a line like this:
load /usr/local/ccvs/lib/tcl/ccvs.so
The exact path may differ if you have installed CCVS in a location other
than the default, but it should always end with lib/tcl/ccvs.so.
Command Results
Most of these functions return a list of key-value pairs, starting
with a status or error code, followed by more information about the
operation.
Prior to using any other commands, you must initialize the system by
using cv_init. The argument configname determines the initialization
file to use; 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 an error occurs, cv_init()
has failed, and the system
is not initialized. Details of the failure are sent to syslog.
The return value includes the CCVS library version number.
At the end of a program you must call cv_done. This
will gracefully terminate the CCVS engine and free up resources.
This is done automatically when the TCL interpreter exits, but if for
example you want to process using more than one configuration in the
same script you must call cv_done before calling
cv_initagain.
The cv_new command creates a blank transaction
for processing.
Its state is 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 command.
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 returns the status (ok or
error), the invoice number, and a description of the error
if one occurred.
The cv_add command 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
new state; the transaction remains in new.
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.
cardnum
Specifies the credit card number being used.
Punctuation (dashes, commas, spaces, etc) are ignored.
expdate
Specifies the card's expiration date, in MM/YY format. The slash is
optional.
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.
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.
address
Specifies the cardholder billing address, to be used in conjunction
with the address verification service of the clearing house.
zipcode
Specifies the zipcode (5 or 9 digit) of the billing address, also to
be used with address verification.
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.)
accountname
The name of the customer, as shown on the credit card account. Some
processors require this attribute in order to generate receipts.
product
The name or description of the product being purchased. Some processors
require this attribute in order to generate receipts.
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.)
tax
The amount of tax in the transaction, in dollars and cents
(for example, "1.16". The format rules are the same as for
amount).
(This information is optional, but specifying it
can improve the rate on your merchant account under some protocols.)
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 comment, not
purchaseorder.
See the CCVS protocol guide in the CCVS on-line documentation
for details.
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.)
shipzipcode
specifies the zip code of the customer's shipping address (as opposed
to the billing address.)
(This information is optional.)
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.)
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
encryption.
(This information is optional, but specifying it
can improve the rate on your e-commerce merchant account under some
protocols.)
setmerchant
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 setcardholder argument.
(This information is optional, but specifying it
can improve the rate on your e-commerce merchant account under some
protocols.)
setcardholder
Specifies the cardholder's SET certificate value. This argument is
only meaningful if setmerchant is also used.
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 returns the status (ok or
error), the invoice number, and a description of the error
if one occurred.
The cv_delete command 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 new, auth, review,
denied, done and 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 returns the status (ok or
error), the invoice number, and a description of the error
if one occurred.
The cv_auth command 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 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 auth, denied, or review
states. See the cv_status command.
cv_auth returns the operation type (auth),
the status (ok or
error), the invoice number, and a description of the error
if one occurred.
The cv_sale command 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 returns the operation type (sale),
the status (ok or
error), the invoice number, and a description of the error
if one occurred.
The cv_return command 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 returns the operation type (return),
the status (ok or
error), the invoice number, and a description of the error
if one occurred.
The cv_reverse command 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 returns the operation type (reverse),
the status (ok or
error), the invoice number, and a description of the error
if one occurred.
The cv_void command 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 returns the operation type (void),
the status (ok or
error), the invoice number, and a description of the error
if one occurred.
The cv_status command 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 the operation type (status),
the transaction status,
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.
The most
important use of cv_status is to determine whether an authorization
was approved or denied. When you use the cv_auth command,
the transaction's state changes from new to unauth.
Background processing will automatically change the state from unauth
to either auth, denied or review.
A state of auth indicates approval, a state of denied
indicates denial, and a state of review indicates a special
case, such as failed AVS verification or a request for voice authorization.
The cv_count command is used to find out how many transactions
of a given type are stored in the system. The types are new,
unauth, auth, denied, review,
ready, done and bad.
The constant all can be used to count everything.
This returns the simple sum of everything counted.
If no type is given at all, cv_count
returns a list of how many transactions there are of each type,
broken down by type.
The cv_lookup command 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
all.)
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 returns
the invoice of the transaction which was found.
The cv_report command returns the status of the background
communication process. Pass in server as the type
argument to check the status of ccvsd (which processes auths
and reversals.) Pass in upload to check the status of
cvupload (which must be run periodically to process sales
and returns).
The cv_command command 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 or the empty string.)
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 "invalid request".
The transaction statuses, as returned by cv_status, are:
none
if the transaction is not in the system,
new
if the transaction has been created and no operations have been performed
on it,
unauth
if the transaction has been subject to a cv_auth but
hasn't been processed yet,
auth
if the transaction has been approved,
denied
if the transaction has been denied,
review
if the transaction requires review by a human (for example if the authorization
requires voice approval),
ready
if the transaction has been subject to a cv_sale or
cv_return but hasn't been processed yet,
done
if the transaction has been subject to a cv_sale or
cv_return and all processing is complete, or
bad
if there was some problem processing a transaction subject to cv_sale
or cv_return.
Most other functions return a list of keys.
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.
For some TCL commands
(eg. cv_auth or cv_sale) this is also used to report the status of that
command; in those cases the return value wil be something like ok
or error.
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
commands.
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 command, this is the task
being performed.
current
For the cv_report command, this is the current item
being worked on (usually an invoice).
time
For the cv_report command, this is the time at
which the action was reported.
