Using CyberCash

### Index Up << >>

## Using CyberCash

MiniVend will directly interface with Perl libraries provided by CyberCash, Inc. This allows direct card billing at the time the order is placed. If using CyberCash 2, the module is called CCLib.pm and its version should be 1.3 or greater. If the library is found at startup, the message ``CyberCash 2 module found'' will be displayed.

MiniVend 3.11 and above support CyberCash 3; see the section below for differences when using CyberCash 3.

To use CyberCash 2, you must first have a CyberCash Secure Merchant Payment Server (SMPS) running on your system. It must be fully enabled, and should be tested OK with the CyberCash test suite. This capability has been tested to work with SMPS-2.1.x in `mauthcapture` and `mauthonly` modes. Any modes supported by CyberCash should work.

The special mode `minivend_test` will cause the transaction to complete successfully and the information that would have been sent to the CyberCash server to be logged in the catalog `error.log` file.

The CyberCash Perl library module must be available to MiniVend -- if you cannot install it in the main Perl library then the Minivend software directory lib/ will suffice. If it is found at MiniVend startup, a message will be displayed.

MiniVend only will charge CyberCash in the final phase of the order process, i.e. at the time the receipt and order report are generated. The full amount as shown by the `[total-cost]` tag will be billed -- if you need to do partial charges you will have to manage multiple shopping carts.

The process of enabling CyberCash processing is something like this:

1. Turn off CreditCardAuto by setting the catalog directive to No. This would normally be done right in catalog.cfg, but it also can be done in a mv_click subroutine if you wish to mix transaction types:

           <INPUT TYPE=checkbox NAME=mv_click VALUE=CyberCash> Use CyberCash
           [set CyberCash]
               [perl]
                   $Config->{CreditCardAuto} = 0;
                   $Config->{CyberCash} = 1;
                   return '';
               [/perl]
           mv_cyber_mode=mauthcapture
           [/set]

2. Enable the CyberCash directive in catalog.cfg (or with the technique above). Also set the catalog Variable value CYBER_SECRET to the ``secret'' for your payment server. If you are not using the default values of localhost and 8000 for your server and port, set the Variables CYBER_HOST and CYBER_PORT as well. In the catalog.cfg file it would look like:

           CreditCardAuto   No
           CyberCash        Yes
           Variable         CYBER_SECRET  first-natl
           Variable         CYBER_PORT    8000
           Variable         CYBER_HOST    localhost

3. Set your final order screen to accept the user form fields mv_credit_card_number (contains the actual card number), mv_credit_card_exp_month and mv_credit_card_exp_year (the expiration date month and year), and the fields containing name, address, city, state, and country. And you must define the form field `mv_cyber_mode` on the submitting form to enable the processing.

   The order mode must be final, either by omitting an order profile entirely or by defining an order profile that contains &final=yes.

The fields containing name and address information should be the same as on the standard MiniVend demo order pages:

        b_name       Billing name      takes priority
        name         Shipping name     used if b_name empty
        b_address    Billing address   takes priority
        address      Shipping address  used if b_address empty
        b_city       Billing city      takes priority
        city         Shipping city     used if b_city empty
        b_state      Billing state     takes priority
        state        Shipping state    used if b_state empty
        b_country    Billing country   takes priority
        country      Shipping country  used if b_country empty

If you must use other values, they can be redefined in catalog.cfg with the Variable CYBER_REMAP like so:

        Variable CYBER_REMAP  name=my_name address=my_address

or like so:

        Variable <<EOF
        CYBER_REMAP
        b_name   my_bname
        name     my_name
        address  processed_address
        city     parsed_city
        EOF

NOTE: As always when using the <<EOF (here document) capability, the EOF must be on a line by itself, with no leading or trailing white space. That includes carriage returns, Windows devotees. Upload in ASCII mode!

If you have defined the directive EncryptProgram to be something containing the value pgp, then the CreditCardAuto method will be used to encrypt the mv_credit_card_number value before it is wiped from memory. (Errors in that process will be silently ignored.) It will never be written to the user session, at least by MiniVend itself, so attempts to recall it on future forms will be in vain.

If the authorization fails, the special page failed will be displayed, and passed the CyberCash error message for display with the `[subject]` tag. The order will not complete, i.e. the cart will still be intact and no receipt or order report will be generated. The error itself is always available as `[data session cybercash_error]`.

If successful, the receipt page will be displayed, the order report emailed, and the cart will be emptied. If you wish to display the order-id returned from CyberCash on the receipt, it is available in `[data session cybercash_id]`. If the order is successful, but is detected as a ``success-duplicate'', `[data session cybercash_error]` will contain the message returned from CyberCash.

### Index Up << >>