The
cvcli
program lets you use the CCVS system without any development work.
You can use it for debugging purposes, in order to take care of
special cases developers haven't thought of, or even as your main
interface to the functionality of CCVS.
To use
cvcli,
you must specify a particular CCVS configuration when you start it,
either via the -c command-line option or the
CCVS_CONFIG_NAME
environment variable.
When you start
cvcli,
it will print out a welcome message and a prompt. You use it by
typing varous commands at the prompt. You can get a list of these
commands by typing "?", and you can exit the program by typing "."
on a line all by itself.
OVERVIEW
The commands of
cvcli
perform operations relating
to credit card processing.
CCVS operates on transactions. A transaction represents a single
financial operation, such as a sale or a refund.
You create a transaction, endow it with descriptive
data (the amount, the credit card number, and so on) and then
perform some action on it. Sometimes you will want to perform multiple
actions on a single transaction. For example, for a typical credit card
sale, you will first authorize a transaction, and then settle it.
A transaction can be in any of eight states. These are defined by
constants in the CCVS header file:
new, unauth, auth, denied, review,
ready, done, bad.
Their meanings follow shortly.
Creating the transaction is done in several steps. First, you create
a new, "empty" transaction, and give it a name (which we generally
refer to as an "invoice number" or just "invoice"). Then you add
various details, one at a time, to that transaction.
For example, let's say someone wants to use their credit card to make
a purchase. First, make a new transaction, named for example
"ABCD0001". Then, one at a time, add the credit card number,
expiration date and dollar amount to that transaction. That's all
that's required, but you can add other things to the transaction, such
as the cardholder's billing address (which will be matched against the
credit card company's database, to prevent fraud).
Once the transaction is ready, you tell the system what to do with it.
If you want to let somebody pay for something with a credit card, the
first thing you need to do is check for authorization, or issue an
"auth" with the named transaction. This makes sure the funds are
available, and puts them on hold. It does not move money.
When you issue an authorization request, you communicate with whoever
provides your credit card service. CCVS is designed to allow many
transactions to go over the same communications session with your
provider. For this reason, you need to be able to issue a group of
authorizations one after the other, without waiting for the response
to one before sending the next. So, when you issue an authorization,
you don't immediately get a response. In order to see if the
authorization is approved, you need to check the status of the
transaction. You can check the status of the transaction at any time.
To actually move money, you would then issue a "sale", and give it the
name of the same transaction you previously did an "auth" on. This
marks the transaction as ready for settlement at the end of the day;
speak to whoever installed CCVS at your site if you wish to know when
this will happen. When it does happen, this will be reflected in the
transaction's status.
Other things you can do with a transaction include reversing a
previous authorization, giving credit back to a cardholder with a
return, or performing administrative tasks like deleting old
transactions.
There are a few things you can do with CCVS that don't involve a
particular transaction. For example, you can count how many
transactions are in each state (for example, "there are 5 transactions
waiting to be processed, 2 have been denied, 1 is waiting for a human
to review it, and 17 have been authorized").
COMMANDS
The commands that
cvcli
makes available are:
new invoice
To create a transaction, enter
newinvoice,
where
invoice
consists of 8 alphanumeric characters. If you use more than 8
characters, it will be truncated. If you use fewer than 8 characters,
the string will be padded on the right with the letter "x" to a length
of 8.
Invoices are not case-sensitive (and are always displayed in upper case).
add invoice argtype argval
To add data to a transaction, such as a credit card number, a dollar
amount, or a billing address, use the add command. The
argtype
determines what you're adding to the transaction, and the
argval
is the actual data. So, for example, you would type
add abcd0001 amount 9.95
to make the amount for transaction "abcd0001" equal to $9.95. The
various transaction attributes are listed below.
The
argval
value is generally
case-sensitive (see below for exceptions).
Note that spaces in
argval
must be escaped; see the SYNTAX section below.
This command can only be used on a transaction in the
new
state;
the transaction remains in
new.
delete invoice
The 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.
The allowed states are
new, auth, review, denied, done, 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.
auth invoice
The auth command is used to perform a credit
authorization test.
The invoice must refer to a transaction in the
new
state
(previously created with new.)
This only does an authorization
check; no money is actually transferred. To transfer money, after
doing an auth, you must do a sale.
This command 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 status command.
sale invoice
The sale command is used to transfer funds from the credit
card holder to the merchant. The invoice must refer to a
transaction in the
auth
or
review
states (previously authorized with auth).
The transaction is moved to the
ready
state.
return invoice
The return command is used to transfer funds from the
merchant to the credit card holder. Its invoice must refer to a
transaction in the
new
state (previously created with new).
The transaction is moved to the
ready
state.
reverse invoice
The reverse command is used to perform a full reversal on
an already-processed authorization. Its invoice must refer to a
transaction in the
auth
or
review
states (previously processed with auth).
The transaction is moved to the
unauth
state.
void invoice
The void command is used to perform a full reversal on
a completed transaction. Its invoice must refer to a transaction
in the
done
state (previously processed with sale or return).
The transaction is moved to the
ready
state.
status invoice
The 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
none
if the invoice is not in use, or one of the
following transaction states:
new
if the transaction has been created and no operations have been
performed on it,
unauth
if the transaction has been subject to an 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 sale,
return, or void, but hasn't been processed yet,
done
if the transaction has been subject to a sale,
return, or void, and all processing is complete, or
bad
if there was some problem processing a transaction subject to
sale, return, or void.
(Note that the
unauth
and
ready
states indicate that a
transaction has not yet been processed. If you want to wait for the
transaction to be processed, see the wait command below.)
count type
The count command is used to find out how many
transactions of a given type are stored in the system. The types are
new, unauth, review, denied, auth, ready, done, or bad.
You can also use
all
to count everything.
lookup type itemnum
The lookup command can be used to look up an item of
a particular type in the database.
The type argument can be any of the eight types valid for count.
(This may not be
all.)
The itemnum argument
determines which item to look up. (1 indicates the first item of the
given type, 2 the second, and so on.)
report type
The report command returns the status of the background
communication process. Type can be
server
to check the status of ccvsd (which
processes auths and reversals), or
upload
to check the status of cvupload (which must be run periodically
to process sales and returns).
command cmd
command cmd argval
Perform 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 there is no such information, it may be omitted.
See the documentation on your protocol for commands which can be
used with it.
list type
List all the transactions in the given state, where the states are the
same as those listed under
count
above.
wait invoice
This behaves exactly like the
status
command, except that when a transaction has not yet been processed,
it will wait for the transaction to be processed before returning. Be
warned that if you issue a
wait
immediately after every single
auth,
the system will not perform very efficiently.
quit, exit, or .
Exit cvcli.
TRANSACTION ATTRIBUTES
You add attributes to a transaction, such as price or credit card
number, using the "add" command. The attributes that can be used are
listed below by argtype, with a description of what the argval means
in each case.
amount
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
Credit card number. Punctuation
(dashes, commas, spaces, etc) are ignored.
expdate
Credit card 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. (You should use quotes, since the string may contain spaces.
See below.)
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. (You should use quotes, since the string may contain spaces.
See below.)
address
Credit card billing street address, used by Address Verification
Service to prevent fraud. All numbers must be entered as numerals;
"Fifth Avenue" must be entered as "5th Avenue".
zipcode
Credit card billing zip code, used by Address Verification Service to
pervent fraud. You can use a 5 or 9 digit zip code.
type
The type of transaction, one of "mail", "phone", "recurring",
"installment", "retail", "ecommerce", "test", or "unknown".
Some credit card processors give you better rates if you set this
attribute.
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
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
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.
Valid values (case-insensitive) are "merchant" and "customer".
(This information is optional, but specifying it
can improve the rate on your merchant account under some protocols.)
shipzipcode
The zip code of the customer's shipping address (as opposed
to the billing address.)
(This information is optional.)
cvv2
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), or
"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"
or
"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
A comment attached to the transaction. Where possible this is sent
through to the processor; what they do with it is dependent on each
processor. It is always returned with the status of a transaction.
CHECK VERIFICATION MODULE
The CCVS Check Verification Module uses the same interface as the CCVS
credit-card system. However, the transaction attributes used are different;
see below.
Since check verification never involves moving money,
the auth command is the only financial transaction used.
You should not use sale, reverse, return, or void.
After the transaction is authorized, you can immediately use
the delete command to delete it.
These are the transaction attributes used in check verification:
amount
specifies the amount of the check, in dollars and cents (for
example, "29.95").
troutnum
is the transit/routing number of the check. This is a nine-digit number.
bankaccnum
is the bank account number of the check.
checknum
is the check sequence number of the check. This is typically in the upper
right-hand corner.
licensenum
is the driver's license number used in verifying the check. This can consist
of letters, digits, and occasionally an asterisk (*).
Other characters are ignored.
Note: The asterisk is only used in some old Washington state licenses.
licensestate
The state of the driver's license used in verifying the check.
This should be the standard two-letter state abbreviation.
Other transaction attributes are not used by the check verification protocols.
However, you can still set them if you want.
SYNTAX
When you enter commands in a
cvcli
session, they are parsed as words separated by whitespace -- spaces or
tabs. If you want to include a space inside a value, you must either
escape it with a backslash, or enclose the value in single or double
quotes. The following are all equivalent:
Verbose output (default). In this mode, the result of each transaction
is displayed, along with a string containing several text details about
the result.
-q
Quiet output. In this mode, only the result code of each transaction is
displayed.
-qq
Very quiet output. In this mode, nothing is displayed; the result code
is returned as the exit status of the
cvcli
process. (If you run several
transactions in a single session, the exit status will reflect the last
one.)
-c configname
Set the name of the configuration to be used. The configuration name
must be set in order for
cvcli
to run. It can be set either with this option, or with the
CCVS_CONFIG_NAME
environment variable.
-d configdir
Set the configuration directory to be used. If your configurations
are not stored in the default location, you must let the system know
where they are stored. You can use either this option or the
CCVS_CONFIG_DIR
environment variable to do so.
