README file for Business-OnlinePayment-CashCow

$Id: README,v 1.2 2005-08-09 09:35:44 jonasbn Exp $

NAME
    Business::OnlinePayment::CashCow - Online payment processing via CashCow

VERSION
    This documentation describes version 0.01 of
    Business::OnlinePayment::CashCow

SYNOPSIS
            my $tx = new Business::OnlinePayment("CashCow");

            my $tx = new Business::OnlinePayment("CashCow", {
                    shopid   => 'cashcowshopid',
            });

            $tx->content(
                    type       => 'Visa',
                    amount     => '1129.50',
                    cardnumber => '123456789012',
                    expiration => '1212',
                    name       => 'Richie Rich',
            );

            $tx->content(
                    type       => 'Visa',
                    amount     => '1129.50',
                    cardnumber => '123456789012',
                    expiration => '1212',
                    name       => 'Richie Rich',
                    currency   => 608, #PHP - Philipine Pesos????
            );

            $tx->submit();

            if ($tx->is_success()) {
                    print "Payment successfull\n";
            } else {
                    print "Error: ".$tx->error_message();
            }

DESCRIPTION
    The CashCow gateway used in this module is the CashCow open source
    project, which is a C library, please see to Business::CashCow.

    The goal of this module is to make a machine to machine credit card
    transactions. CashCow has several options where you can specify URL for
    handling online payments directly using CGI scripts.

    So in order to avoid this layer and still perform transactions this
    module was initiated. At the same time the module attempts to follow the
    defacto standard for the modules in the Business::OnlinePayment
    namespace.

    In order to avoid filtering a HTML response two solutions are doable

    Either you can specify the result URLs on the CashCow gateway using the
    PHP located in the php directory, which output XML, which is more
    structured and more easily parsed.

    If you want to roll your own , please refer to the examples located in
    the xml directory.

    You can also create HTML (or a different XML) output you just need to
    subclass this class and override the _process_response method.

  SUPPORTED TRANSACTION TYPES
            Dankort
            E-Dankort (**)
            VISA/Dankort
            Eurocard
            MasterCard
            Visa
            Visa Electron
            JCB
            Diners (*)
            American Express (*)
            Forbrugsforeningen (*)
            Ikano Finans kort (*)
        
            (*) To accept this, you need a Merchant Agreement with the card provider in 
            question.

            (**) Not supported by this module at this time (SEE: TODO).

  METHODS
   new
    This method is located in the SUPER class Business::OnlinePayment and
    returns a Business::OnlinePayment::CashCow object when called with the
    string CashCow as parameter to the contructor.

   submit
    This method is required to be overloaded by Business::OnlinePayment

    The method uses HTTPS via Net::SSLeay.

   set_defaults
    This method overloads the similar method in Business::OnlinePayment

    It sets possible defaults required by Business::OnlinePayment::CashCow.

   test_transaction
    This method is inherited from Business::OnlinePayment

    It test the TestFlg form field (SEE: 'Original Formfields', below and
    'TODO' below).

   map_fields
    This method overloads the similar method in Business::OnlinePayment

    This method was overloaded for development reasons only and will
    eventually be removed.

   remap_fields
    This method overloads the similar method in Business::OnlinePayment

    This method was overloaded for development reasons only and will
    eventually be removed.

   get_fields
    This method overloads the similar method in Business::OnlinePayment

    This method was overloaded for development reasons only and will
    eventually be removed.

   content
    This method is inherited from Business::OnlinePayment

   is_success
    This method is inherited from Business::OnlinePayment

   result_code
    This method is inherited from Business::OnlinePayment

   require_avs
    This method is inherited from Business::OnlinePayment

   transaction_type
    This method is inherited from Business::OnlinePayment

   error_message
    This method is inherited from Business::OnlinePayment

   authorization
    This method is inherited from Business::OnlinePayment

   server
    This method is inherited from Business::OnlinePayment

   port
    This method is inherited from Business::OnlinePayment

   path
    This method is inherited from Business::OnlinePayment

   _process_response
    This is a private method implemented to handle the response, which the
    author recommends to be and XML formatted response.

DEVELOPERS NOTES
  CashCow
    The CashCow system is quite flexible and therefore it is not possible to
    say what fields are mandatory and which are optional, since
    configurations may differ from shop to shop (SEE: TODO).

  Processor Options
    * shopid

   shopid
    This is the string holding the shopid for the shop configured on the
    CashCow gateway for the shop you want to access.

    This field is regarded to be mandatory hence it is needed to complete a
    transaction - all requests to a CashCow gateway without a shopid is
    responded to with an HTTP response code of 304.

  Original CashCow Formfields
    These fields are the ones provided by the CashCow gateway. This module
    complies with the Business::OnlinePayment API v2. so the API described
    in this module should be used. But fields listed below can be added to
    the content dataset (SEE: SYNOPSIS) if some extra information is needed
    - use of some fields however is not recommended since these are
    redundant with the fields specified in the Business::OnlinePayment API.

    * foreignorderid
    * sessionid
    * cust_name
    * cust_street
    * cust_zip
    * cust_phone
    * cust_email
    * cardnum
    * emonth
    * eyear
    * cvc
    * amount
    * currency

   foreignorderid
    This field can be use to hold your own orderid for reference.

    This field is regarded as defaulting to optional. Can be used freely.

   sessionid
    This field can be use to hold a sessionid.

    This field is regarded as defaulting to optional. Can be used freely.

   cust_name
    The customer name (full name) - concatenation might be necessary.
    Cardholders name should go in this field.

    This field is regarded as defaulting to optional. Please use: name
    instead.

   cust_street
    The street of the customer address.

    This field is regarded as defaulting to optional. Please use: address
    instead.

   cust_zip
    The zip code of the customers address.

    This field is regarded as defaulting to optional. Please use: zip
    instead.

   cust_phone
    The phonenumber of the customer.

    This field is regarded as defaulting to optional. Please use: phone
    instead.

   cust_email
    This is the customer email adresse. CashCow has some different options
    for this parameter. It can either be optional or mandatory and you can
    even have the CashCow gateway evaluate the email address with the
    configuration parameter strict which can be set on the gateway.

    This field is regarded as defaulting to optional. Please use: email
    instead.

   cardnum
    This field is regarded as defaulting to mandatory. Please use:
    card_number instead.

   emonth
    The expiration month in two digits, listed on the front of the
    creditcard.

    This field is regarded as defaulting to mandatory. Please use:
    expiration instead.

   eyear
    The expiration year in two digits, listed on the front of the
    creditcard.

    This field is regarded as defaulting to mandatory. Please use:
    expiration instead.

   cvc
    The 3- or 4-digit control number on the back of a creditcard. The
    CashCow gateway refers to this as CVC, but the name actually depends on
    the card in question, but this module sticks to the name CVC eventhough
    it might be used for:

    * CVV2 (Visa)
    * CVC2 (Mastercard)
    * CID (American Express)

    This field is regarded as defaulting to mandatory.

   amount
    The amount should be provided in english notation, do not use locale if
    it differs from the using . (dot) as separator. (SEE: SYNOPSIS).

    This field is regarded as defaulting to mandatory.

   currency
    This argument can be used to specify the currency. The currency defaults
    to 208, which is the numeric currency code for DKK - Danish Krone.

    The numeric codes are defined in: ISO4217

    See, SEE ALSO section for references.

TODO
    * Implement handling of e-dankort card type
    * Implement handling of ecredit transactions (default is PBS)
    * Implement handling of subscribtions
    * Investigate return values and use of: authorization() and
    result_code()
    * Investigate test flags (TestFlg)
    * Make it possible to control what fields are mandatory and optional.
    This could be done via the optional processor info parameter to the
    constructor (SEE: new).
    * The tests reveal a warning of sorts from Net::SSLeay - it would be
    nice to have this warning eliminated.
    * Some warnings are issued due to redefinition of autoloaded subs built
    by the SUPER class, this would be nice to get out of the way aswell

            t/Submit..........ok 1/6Subroutine shopid redefined at (eval 36) line 1.     
            Subroutine testflg redefined at (eval 37) line 1.

BUGS
    Please report issues via CPAN RT:

      http://rt.cpan.org/NoAuth/Bugs.html?Dist=Business-OnlinePayment-CashCow

    or by sending mail to

      bug-Business-OnlinePayment-CashCow@rt.cpan.org

CAVEATS
    * Please be aware that the CashCow gateways URLs are not RFC 2396
    compliant, '~' in URLs are not currently supported - might tease during
    development or similar.

SEE ALSO
    * Business::OnlinePayment
    * Net::SSLeay
    * <http://www.cashcowgateway.com/>
    * <http://www.cashcow.dk/>
    * <http://420.am/business-onlinepayment/>
    * Business::CashCow
    * <http://www.sti.nasa.gov/cvv.html>
    *
    <http://search.cpan.org/src/JASONK/Business-OnlinePayment-2.01/notes_for
    _module_writers>
    * Locale::Currency
    * <http://en.wikipedia.org/wiki/ISO_4217>
    *
    <http://www.iso.org/iso/en/prods-services/popstds/currencycodeslist.html
    >

AUTHOR
    Jonas B. Nielsen, (jonasbn) - "<jonasbn@cpan.org>"

COPYRIGHT
    CashCowGateWay is copyright of CashCow ApS

    CashCow is copyright of the CashCow association

    Business-OnlinePayment-CashCow is (C) by logicLAB 2005

    Business-OnlinePayment-CashCow is released under the artistic license

    The distribution is licensed under the Artistic License, as specified by
    the Artistic file in the standard perl distribution
    (http://www.perl.com/language/misc/Artistic.html).