The functions of the CCVS C library 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: CV_NEW, CV_UNAUTH, CV_AUTH,
CV_DENIED, CV_REVIEW, CV_READY, CV_DONE, CV_BAD. Their meanings
follow shortly.
Most of the CCVS 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.
STARTING UP AND SHUTTING DOWN
void *cv_init(char *initfilename);
Prior to using any other functions, you must initialize the system by
calling cv_init(). The argument initfilename 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 CV_SESS_BAD,
then cv_init() has failed, and the system
is not initialized. Details of the failure are sent to syslog.
After calling cv_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 cv_textvalue() if
cv_init() fails, or after calling cv_done().
void cv_done(void *sess);
At the end of a program you should call cv_done(), which will
gracefully terminate the CCVS engine. There is no return value.
BUILDING TRANSACTIONS
int cv_new(void *sess, char *invoice);
The cv_new() function 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() 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".)
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.
int cv_add(void *sess, char *invoice, int argtype, char *argval);
The cv_add() function adds a single attribute to a transaction.
See the list of attribute types, below. The argval value is generally
case-sensitive (see below for exceptions).
cv_add() can only be used on a transaction in the CV_NEW state;
the transaction remains in CV_NEW.
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.
int cv_create(void *sess, char *invoice, int argtype, char *argval, ...);
The cv_create() function combines cv_new() and a set
of cv_add() calls. This function is deprecated; it remains
in CCVS only for backwards compatibility.
Specify the attributes by passing a list of
int argtype, char *argval
pairs to the function, ending the list with an argtype of
CV_ARG_END.
The transaction is created in the CV_NEW state.
cv_create() can return any of the errors returned by
cv_new() or cv_add().
The argument types and values are as follows.
Note that not all arguments are meaningful for every protocol.
CV_ARG_END
specifies the end of the argument list of cv_create().
Do not use this with cv_add().
This is not followed by an argval.
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.
CV_ARG_CARDNUM
specifies the credit card number being used. Punctuation
(dashes, commas, spaces, etc) are ignored.
CV_ARG_EXPDATE
specifies the card's expiration date, in MM/YY format. The slash is optional.
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.
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.
CV_ARG_AVS_ADDRESS
specifies the billing address of the credit card, to be used in
conjunction with the address verification service of the clearing
house.
CV_ARG_AVS_ZIPCODE
specifies the zipcode (5 or 9 digit) of the billing address, also to
be used with address verification.
CV_ARG_TYPE
specifies the type of the transaction. Valid values (case-insensitive)
are
mail,
phone,
recurring,
installment,
retail,
ecommerce,
test,
and
unknown.
(This information is optional, but specifying it
can improve the rate on your merchant account under some protocols.)
CV_ARG_ACCOUNTNAME
specifies the name of the customer, as shown on the credit card account.
Some processors require this attribute in order to generate receipts.
CV_ARG_PRODUCT
specifies the name or description of the product being purchased.
Some processors require this attribute in order to generate receipts.
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.)
CV_ARG_TAX
specifies 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.)
CV_ARG_PURCHASEORDER
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.
CV_ARG_ENTRYSOURCE
specifies 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.)
CV_ARG_SHIP_ZIPCODE
specifies the zip code of the customer's shipping address (as opposed
to the billing address.)
(This information is optional.)
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), or
none
(intentionally not provided).
(This information is optional, but specifying it
can improve the rate on your merchant account under some protocols.)
CV_ARG_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
CV_ARG_ENCRYPTION.
(This information is optional, but specifying it
can improve the rate on your e-commerce merchant account under some protocols.)
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.)
CV_ARG_SET_CARDHOLDER
specifies the cardholder's SET certificate value. This argument is only
meaningful if
CV_ARG_SET_MERCHANT
is also used.
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.)
DELETING TRANSACTIONS
int cv_delete(void *sess, char *invoice);
The cv_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 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.
FINANCIAL OPERATIONS
int cv_auth(void *sess, char *invoice);
The cv_auth() function is used to perform a credit
authorization test.
The invoice must refer to a transaction in the CV_NEW state
(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() function.
int cv_sale(void *sess, char *invoice);
The cv_sale() function is used to transfer funds from the credit
card holder to the merchant. The invoice must refer to a
transaction in the CV_AUTH or CV_REVIEW states (previously
authorized with cv_auth()).
The transaction is moved to the CV_READY state.
int cv_return(void *sess, char *invoice);
The cv_return() function is used to transfer funds from the
merchant to the credit card holder. Its invoice must refer to a
transaction in the CV_NEW state (previously created with cv_new()).
The transaction is moved to the CV_READY state.
int cv_reverse(void *sess, char *invoice);
The cv_reverse() function is used to perform a full reversal on
an already-processed authorization. Its invoice must refer to a
transaction in the CV_AUTH or CV_REVIEW states (previously
processed with cv_auth()).
The transaction is moved to the CV_UNAUTH state.
int cv_void(void *sess, char *invoice);
The cv_void() function is used to perform a full reversal on
a completed transaction. Its invoice must refer to a transaction
in the CV_DONE state (previously processed with
cv_sale() or cv_return()).
The transaction is moved to the CV_READY state.
All of these functions -- cv_auth(),
cv_sale(), cv_return(), cv_reverse(),
and 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.
HOUSEKEEPING OPERATIONS
int cv_status(void *sess, char *invoice);
The cv_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 CV_NONE if the invoice is not in use, or one of the
transaction states.
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.
The transaction states are:
CV_NONE
The transaction is not in the system.
CV_NEW
The transaction has been created and no operations have been
performed on it (except cv_add()).
CV_UNAUTH
The transaction has been subject to a cv_auth() but hasn't
been processed yet.
CV_AUTH
The transaction has been approved.
CV_DENIED
The transaction has been denied.
CV_REVIEW
The transaction requires review by a human (for example if the
authorization requires voice approval).
CV_READY
The transaction has been subject to a cv_sale(),
cv_return(), or cv_void(), but hasn't been processed yet.
CV_DONE
The transaction has been subject to a cv_sale(),
cv_return(), or cv_void(), and all processing is complete.
CV_BAD
There was some problem processing a transaction subject to
cv_sale(), cv_return(), or cv_void().
The most important use of cv_status() is to determine whether an
authorization was approved or denied. When you use the
cv_auth() function, 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.
int cv_count(void *sess, int type);
The cv_count() function 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,
cv_count(sess, CV_AUTH|CV_DENIED|CV_REVIEW)
will count the authorizations that have already been handled by the
background processor. The macro 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.
int cv_lookup(void *sess, int type, int itemnum);
The cv_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 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.
int cv_report(void *sess, int type);
The cv_report() function 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 text return value.
int cv_command(void *sess, int cmd, char *argval);
The cv_command() function performs commands which are peculiar
to individual protocols, and thus are not available in the general CCVS
API.
The argval argument is additional information which pertains
to the command. (It is generally case-sensitive.
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.
char *cv_textvalue(void *sess);
The cv_textvalue() function retrieves the text return value
from the most recent CCVS function call.
This 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(). It is represented in standard Unix ctime() format:
"Wed Jun 30 21:49:08 1993".
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 the cv_sale(), cv_return(), or cv_void()
functions.
donetime
When present, this is the time and date at which a transaction
processed by cv_sale(), cv_return(), or cv_void()
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 zip code 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() function, this is the task being performed.
current
For the cv_report() function, this is the current item being
worked on (usually an invoice).
time
For the cv_report() function, this is the time at which the
action was reported.
CHECK VERIFICATION MODULE
The CCVS Check Verification Module uses the same interface as the CCVS
credit card system. However, the argtypes used are different;
see below.
Since check verification never involves moving money,
cv_auth() is the only financial transaction used.
You should not use cv_sale(), cv_reverse(),
cv_return(), or cv_void().
After the transaction is authorized, you can immediately call
cv_delete() to delete it.
These are the argtypes used in check verification:
CV_ARG_AMOUNT
specifies the amount of the check, in dollars and cents (for
example, "29.95").
CV_ARG_TROUTNUM
is the transit/routing number of the check. This is a nine-digit number.
CV_ARG_BANKACCNUM
is the bank account number of the check.
CV_ARG_CHECKNUM
is the check sequence number of the check. This is typically in the upper
right-hand corner.
CV_ARG_DVS_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.
CV_ARG_DVS_LICENSESTATE
The state of the driver's license used in verifying the check.
This should be the standard two-letter state abbreviation.
Other argtypes are not used by the check verification protocols.
You can still set them, but they will be ignored.
ERRORS
This is a summary of the error codes that can be returned by CCVS
library functions.
CV_OK
On successful completion, most of these functions return CV_OK.
CV_E_SYNTAXERROR
This is returned when one of the functions is called incorrectly
(eg. a cv_create() without an amount).
CV_E_INVALID
This is returned when a function is called which is not implemented,
or not meaningful, for the protocol being used.
CV_E_DUPINVOICE
This is returned when an attempt is made to inappropriately use an
invoice that's already in use by the system.
CV_E_BADINVOICE
This is returned when an operation is illegal on a given invoice for
some reason.
This can happen if, for example, your disk becomes full.
CV_E_DATA
This is returned if an error occurs in CCVS's transaction database.
CV_E_UNKNOWN
This is returned if an otherwise unclassifiable error occurs.
CV_E_UNINIT
This is returned when the session object is not initialized with
cv_init() before other functions are called.
