The CCVS Python language API lets you access the functionality of CCVS
from within Python programs.
Building the CCVS Python Interface
The Python interface to CCVS must sometimes be built after the rest of CCVS
is installed. See the
Python Installation Guide.
Before You Run
To take advantage of the API, you have to import
the API module, with a line like this:
import ccvs
Before you can load the Python module, you must add the directory it is
in to your PYTHONPATH environment variable. If you used the
default installation location, that would be /usr/local/ccvs/lib/python
Function Results
Most of these functions return a short string representing a status or error code.
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 ccvs.textvalue() immediately after the
function call in question.
Prior to using any other functions, you must initialize the system by
calling ccvs.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.)
The return value is a session pointer. This must be passed as the first
argument to all other functions in the library.
If the return value is None, ccvs.init()
has failed, and the system
is not initialized. Details of the failure are sent to syslog.
After calling ccvs.init(), the text return
value contains the CCVS library version number.
Note that the text return value is only available when the
system is initialized. You may not call ccvs.textvalue() if
ccvs.init() fails.
The ccvs.new() function 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 ccvs.add() function.
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".)
ccvs.new() can return:
"OK" (success),
"uninitialized" (session not initialized),
"duplicate invoice" (duplicate invoice),
"data problem" (database error),
"unknown" (unknown error).
The text return value describes the error if one occurred.
The ccvs.add() function 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.
ccvs.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.)
ccvs.add() can return:
"OK" (success),
"uninitialized" (session not initialized),
"bad invoice" (bad invoice),
"syntax error" (syntax error in arguments),
"data problem" (database error),
"unknown" (unknown error).
The text return value describes the error if one occurred.
The ccvs.delete() function 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 ccvs.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.
ccvs.delete() can return:
"OK" (success),
"uninitialized" (session not initialized),
"bad invoice" (bad invoice),
"unknown" (unknown error).
The text return value describes the error if one occurred.
The ccvs.auth() function is used to perform a credit authorization
test. The invoice
must refer to a transaction previously created with ccvs.new().
This only does an authorization check; no money is actually transferred.
To transfer money, after doing a ccvs.auth(), you must do a
ccvs.sale().
ccvs.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 ccvs.status() function.
ccvs.auth() can return:
"OK" (success),
"uninitialized" (session not initialized),
"bad invoice" (bad invoice),
"duplicate invoice" (already done to this transaction),
"invalid request" (invalid action for this transaction),
"unknown" (unknown error).
The text return value describes the error if one occurred.
The ccvs.sale() function is used to transfer funds from the
credit card holder to the merchant. The invoice must refer to
a transaction previously authorized with ccvs.auth().
ccvs.sale() can return:
"OK" (success),
"uninitialized" (session not initialized),
"bad invoice" (bad invoice),
"duplicate invoice" (already done to this transaction),
"invalid request" (invalid action for this transaction),
"unknown" (unknown error).
The text return value describes the error if one occurred.
The ccvs.return_() function is used to transfer funds from
the merchant to the credit card holder. Its invoice must refer
to a transaction previously created with ccvs.new().
Note: This is called "return_", instead of "return", to avoid
conflict with the Python reserved word.
ccvs.return_() can return:
"OK" (success),
"uninitialized" (session not initialized),
"bad invoice" (bad invoice),
"duplicate invoice" (already done to this transaction),
"invalid request" (invalid action for this transaction),
"unknown" (unknown error).
The text return value describes the error if one occurred.
The ccvs.reverse() function is used to perform a full reversal
on an already-processed authorization. Its invoice must refer
to a transaction previously processed with ccvs.auth().
ccvs.reverse() can return:
"OK" (success),
"uninitialized" (session not initialized),
"bad invoice" (bad invoice),
"duplicate invoice" (already done to this transaction),
"invalid request" (invalid action for this transaction),
"unknown" (unknown error).
The text return value describes the error if one occurred.
The ccvs.void() function is used to perform a full reversal
on a completed transaction. Its invoice must refer to a transaction
previously processed with ccvs.sale() or ccvs.return_().
ccvs.void() can return:
"OK" (success),
"uninitialized" (session not initialized),
"bad invoice" (bad invoice),
"duplicate invoice" (already done to this transaction),
"invalid request" (invalid action for this transaction),
"unknown" (unknown error).
The text return value describes the error if one occurred.
The ccvs.status() function 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 transaction states:
"new", "unauth", "auth",
"denied", "review",
"ready", "done", "bad".
The text return value shows the state too,
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.
ccvs.status() can also return "unknown",
indicating that an error occured. In this case, you must check the
text return value to get more information about the error.
The most
important use of ccvs.status() is to determine whether an authorization
was approved or denied. When you use the ccvs.auth() function,
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 ccvs.count() function 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.
The numeric return value will be the simple sum of everything
counted. The text return value (accessed via ccvs.textvalue())
will give a breakdown of how many transactions of each type are in the
system.
The ccvs.lookup() function 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 ccvs.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.)
ccvs.lookup() can return:
"OK" (success),
"uninitialized" (session not initialized),
"syntax error" (syntax error in arguments).
The textvalue will be a string that contains the
invoice of the transaction which was found.
The ccvs.report() function 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).
ccvs.report() can return:
"OK" (success),
"uninitialized" (session not initialized),
"syntax error" (syntax error in arguments),
"unknown" (unknown error).
The report itself
is returned in the library's text value.
The ccvs.command() function 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 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, ccvs.command()
will return "invalid request".
ccvs.command() can return:
"OK" (success),
"uninitialized" (session not initialized),
"invalid request" (invalid action for this transaction or this protocol),
"syntax error" (syntax error in arguments),
"unknown" (unknown error).
The text return value may contain more information, depending on the
command you are performing.
Various functions return both numeric and text values. The numeric values
are the return values of the functions. To get the text values, call ccvs.textvalue()
immediately after the related function call.
The transaction statuses, as returned by ccvs.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 ccvs.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 ccvs.sale() or
ccvs.return_() but hasn't been processed yet,
"done"
if the transaction has been subject to a ccvs.sale() or
ccvs.return_() and all processing is complete, or
"bad"
if there was some problem processing a transaction subject to ccvs.sale()
or ccvs.return_().
The text return value is formatted as a set of key-value pairs.
Calling ccvs.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 ccvs.new().
authtime
When present, this is the time and date at which a ccvs.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 ccvs.sale() or ccvs.return_()
functions.
donetime
For protocols other than ETC+, this is the time and date at which a
transaction processed by either ccvs.sale() or ccvs.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 ccvs.report() function, this is the task
being performed.
current
For the ccvs.report() function, this is the current item
being worked on (usually an invoice).
time
For the ccvs.report() function, this is the time at
which the action was reported.
