CCVS Programmer's Guide Perl Language API Version 3.3 Revised February 15, 2025 Red Hat, Inc. 2600 Meridian Pkwy Durham, NC 27713 919-547-0012 Back to main Documentation page Back to Programmer's Guide   Table of Contents Introduction Building the CCVS Perl Interface Before You Run Function Results Functions CCVS::init CCVS::done CCVS::new CCVS::add CCVS::delete CCVS::auth CCVS::sale CCVS::return CCVS::reverse CCVS::void CCVS::status CCVS::count CCVS::lookup CCVS::report CCVS::command CCVS::textvalue Return Values Errors   Introduction The CCVS Perl language API lets you access the functionality of CCVS from within Perl scripts.   Building the CCVS Perl Interface The Perl interface to CCVS must sometimes be built after the rest of CCVS is installed. See the Perl Installation Guide.   Before You Run To take advantage of the API, you have to import the API module, with a line like this: use CCVS;   Function 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 CCVS::textvalue() immediately after the function call in question. Table of Contents   Functions CCVS::init Prototype CCVS::init(configname) Usage 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 0 (zero), 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. Table of Contents   CCVS::done Prototype CCVS::done(sess) Usage At the end of a program you must call CCVS::done(). This will gracefully terminate the CCVS engine and free up resources. There is no return value. Table of Contents   CCVS::new Prototype CCVS::new(sess, invoice) Usage The CCVS::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 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: 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. Table of Contents   CCVS::add Prototype CCVS::add(sess, invoice, argtype, argval) Usage 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 CV_NEW state; the transaction remains in CV_NEW. 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 cardholder billing address, 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 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.) 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. CV_ARG_PRODUCT 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 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 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. 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.) 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) 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 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.) CCVS::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. Table of Contents   CCVS::delete Prototype CCVS::delete(sess, invoice) Usage 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 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. CCVS::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. Table of Contents   CCVS::auth Prototype CCVS::auth(sess, invoice) Usage 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 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 CCVS::status() function. CCVS::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. Table of Contents   CCVS::sale Prototype CCVS::sale(sess, invoice) Usage 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: 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. Table of Contents   CCVS::return Prototype CCVS::return(sess, invoice) Usage 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(). CCVS::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. Table of Contents   CCVS::reverse Prototype CCVS::reverse(sess, invoice) Usage 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: 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. Table of Contents   CCVS::void Prototype CCVS::void(sess, invoice) Usage 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: 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. Table of Contents   CCVS::status Prototype CCVS::status(sess, invoice) Usage 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 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. CCVS::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 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 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. Table of Contents   CCVS::count Prototype CCVS::count(sess, type) Usage The CCVS::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, CCVS::count(sess, 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 CCVS::textvalue()) will give a breakdown of how many transactions of each type are in the system. Table of Contents   CCVS::lookup Prototype CCVS::lookup(sess, type, itemnum) Usage 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 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.) CCVS::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. Table of Contents   CCVS::report Prototype CCVS::report(sess, type) Usage The CCVS::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). CCVS::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. Table of Contents   CCVS::command Prototype CCVS::command(sess, cmd, argval) Usage 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 NULL or an 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 CV_E_INVALID. CCVS::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. Table of Contents   CCVS::textvalue Prototype CCVS::textvalue(sess) Usage 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. Table of Contents   Return Values The transaction statuses, as returned by CCVS::status(), are: CV_NONE if the transaction is not in the system, CV_NEW if the transaction has been created and no operations have been performed on it, CV_UNAUTH if the transaction has been subject to a CCVS::auth() but hasn't been processed yet, CV_AUTH if the transaction has been approved, CV_DENIED if the transaction has been denied, CV_REVIEW if the transaction requires review by a human (for example if the authorization requires voice approval), CV_READY if the transaction has been subject to a CCVS::sale() or CCVS::return() but hasn't been processed yet, CV_DONE if the transaction has been subject to a CCVS::sale() or CCVS::return() and all processing is complete, or CV_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. Table of Contents   Errors 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. 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. CV_E_COMMERROR This indicates that there was a communications error of some sort. CV_E_DATA This indicates a problem using the internal database. This can happen if, for example, your disk becomes full. CV_E_UNINIT This is returned when the session object is not initialized with CCVS::init() before other functions are called. Table of Contents   Revised February 15, 2025 Red Hat, Inc. 2600 Meridian Pkwy Durham, NC 27713 919-547-0012 Back to main Documentation page Back to Programmer's Guide