The file "batch.pl" is a Perl script that processes batch input files
in comma-separated text format.  You can call it by executing
"perl batch.pl config infile outfile".

Replace "config" with the name of the CCVS configuration to use.  The
"infile" is the comma-separated text file that contains the batch you
want to process.  The "outfile" is the name of the file you want
output sent to.  If you leave off the outfile, it will write to
standard output; if you leave off both filenames, it will read from
standard input and write to standard output.  Note that for
production use you'll probably want to specify both files, so
there's no chance of warnings or error messages being mixed in with
your response file.

Field #1 is the command, and the other fields depend on that command.
Field #2 is a comment and is usually set to the name of the person who
entered the transaction.  Field #3 is a unique identifier for the
transaction.  This is 8 alphanumeric case-inensitive characters, and
corresponds to the CCVS "invoice".  If you use more the field will be
truncated, and if you use fewer it will be right-padded with the
letter "x".  Field #4 is the credit card number, field #5 is the
expiration date, and field #6 is the ammount in dollars or in dollars
and cents.  You can also add the cardholder's billing zipcode in field
#7 and street address in field #8.  If you do, the AVS fraud
prevention service will be used for that transaction.

The commands are:
C1: Do a full transaction, from preauthorization all the way to moving
    money.  This is the same as a C4 and C5 together.  Fields #2
    through #6 are required, and #7 and #8 are used if present.
C2: Do a reversal, which basically cancels a transaction that has been
    preauthed but not yet postauthed.  This is rarely used.  Only
    fields #2 and #3 are used.
C3: Do a return.  This moves money from the merchant back to the
    cardholder.  This is what you use if someone returns an item after
    you've issued a postauth (C1 or C5) on it.  All fields but #7 and
    #8 are used.
C4: Do a preauthorization.  Ask if the funds are available and place
    them on hold, but don't move money.  Fields #2 through #6 are
    required, and fields #7 and #8 are used if present.
C5: Do a postauthorization.  Move money previously put on hold via a
    preauthorization.  The unique identifier *must* match that used in
    the preauth/C4.  Only fields #2 and #3 are used.
ST: Do end-of-day settlement.  No other fields are used.

This script should be accompanied by the file "input.csv", which is
a sample input file in the correct format.

The ouptut file format is one line per transaction.  Each line
begins with a "Y" or "N", depending on whether the transaction was
succesfull or not, followed by six "0" characters, followed by the
8-character unique identifier for that transaction.  The six "0"
characters will be replaced by the authorization code in a future
version of this script.

If you're using C4, an ambiguous response (such as "AVS address
doesn't match") will be returned as an "N".  However, if you group
the preauth and postauth together by using C1, it's very important
to realize that a succesful postauth will result in a "Y", possibly
hiding the fact that AVS matching failed.  Be careful if you intend
to use AVS.

Also note that the status of any postauth or return transactions isn't
going to be accurate unless you've done a settlement, either by using
the "ST" command or by some other mechanism.  If you want to be sure
of your results, put an "ST" at the bottom of the batch, or wait until
the settlment has been done for the day and use some other CCVS
utility (such as the "cvcli" command line tool, or the "lister.tk"
graphical administration demo) to check the status of the transactions.

If a transaction is in a state it shouldn't be in, the first character
of the response will be '?'.  This should only happen if someone is
using some other program to manipulate your transactions -- for
example if someone deletes a transaction you created, after it was
processed by the clearing house but before the report was generated.

You might notice that the input file format is very similar to
ICVerify's "Request file" format, and the output file format is very
similar to ICVerify's "Answer file" one-line evaluated-response format.

The key differences in the input file format are:
* Our second field can have any value up to 25 characters in length, and
  is used as a comment.  ICVerify uses this field for the name of the
  clerk that entered the transaction, which is reasonable input for
  our software too.
* Our third field must contain an 8-character unique identifier.
  ICVerify uses this field for their comment.  Many merchants will use
  the ICVerify comment field to pass some sort of invoice number into
  the system, so they can match processed transactions with some other
  database.  If you use ICVerify this way, this script will work for
  you with no modification, but if you don't, you'll need to change
  some things.
* Our "date" field must always have the month before the date, either
  in "MM/YY" or "MMYY" format.  ICVerify's date field can be either
  MMYY or YYMM, depending on which you selected when you did your
  initial install of ICVerify.
* For postauth transactions (C5), we use the dollar amount from the
  previous preauth (C4) and not the one supplied with the postauth.
  ICVerify does the opposite.  Note that it's rare for these amounts
  to differ for most merchants, and sometimes when they differ your
  processor will charge you higher rates.

The key differences in the output file format are:
* When the response to a transaction is a "maybe" instead of a clear
  "yes" or "no" (eg. when you use AVS and the billing address doesn't
  match), we default to "no", because there's a possiblity that
  defaulting to "yes" could result in higher fees from your processor.
* We don't currently always return the auth code to the user (our
  software sends it back to the processor automatically when
  apropriate), so where ICVerify returns the auth code, we return six
  zeros.
* The last 8 characters per line we return are the unique identifier
  you specified for that transaction.  ICVerify returns an "8-digit
  reference number" in the same field.

-- 
$Id: batch.txt,v 1.2 1998/10/30 23:14:36 ddj Exp $
