README - DirDepo

Direct Deposit Payment Method add-on for VirtueMart (http://www.virtuemart.com/)

General notes - see this README
Installation and user manual - see /doc/user/index.html
Class documentation for developers - see /doc/class/index.html
Changelog - see CHANGELOG
License (GNU GPL) - see LICENSE

Direct deposit as a payment method:
1. Customer selects products to his online shopping basket.
2. During the checkout process he is given a selection of different payment
   methods.
3. If he selects direct deposit, the online shop software (VirtueMart in this
   case) shows him a 'confirmation/thank you' message at the final step of
   checkout process. A confirmation message and order details are also send
   to customer's email address.
   DirDepo, as a payment method add-on, adds a table of information necessary
   for the direct deposit to the end of 'confirmation/thank you' message at the
   final step of checkout process. An other separate email, containing the
   direct deposit information, is also sent to the customer's email address.
   Direct deposit information contains info about the online vendor, the
   customer, the order and the invoicer.
   The vendor and the invoicer don't have to be the one and same party of the
   business transaction. For example 'the vendor', an online shop, might be
   just a marketing name for company, which is the actual invoicer, who
   should receive the direct deposit. On the other hand, the vendor and the
   invoicer can be the very same company or person.
   Most important pieces of direct deposit information are the name of invoicer,
   invoicers's bank and bank account number, bank reference number (or some other
   unique identifier of the deposit) and the total sum of the order.
4. VirtueMart records the order as a 'pending order' into the database. DirDepo
   adds the bank reference number into the order's payment history.
5. Sometime during the following days the customer makes a direct deposit
   to the invoicer's bank account for the sum of the order.
6. The invoicer notes that a deposit has been received and informs the vendor
   about it. The deposit can be linked to a particular order by the bank reference
   number.
7. The vendor updates the order status from 'pending' to 'confirmed'. VirtueMart
   is capable to send a status update notification to the customer if the vendor
   choses so.
8. Vendor finishes the order process (collects items of the order, packs them and
   sends the packet to the customer).

Some notes about the pitfalls of direct deposit as a payment method:
- The customer needs to trust the online vendor, because he is not protected by
  a third party like a credit card company.
  The vendor needs a good reputation, or the customer has to be protected for
  example by a law. Or - the customer has to just take his changes of being
  fooled by a rogue online vendor.
- The customer might never make the deposit.
  The vendor needs to keep book about the pending deposits and their age.
  Maybe the order has to be canceled after certain amount of time? Maybe the
  vendor has to contact the customer before the order can be concidered as
  'canceled'?
  Does the vendor procure or manufacture the order items before the deposit is
  received? Is vendor capable to sell them to some other customer, if this
  particular deposit is never received?
  Does the vendor even send the order to the customer before the deposit is
  received? What if the vendor is fooled by a rogue customer?
  Propably most vendors choose to keep the order pending and don't process the
  order any further before the deposit is received.
- The customer might use wrong bank reference number or no reference at all.
  The invoicer notes he has received a deposit, but can't link it to any
  particular order, because bank reference is wrong or missing. Maybe even
  the sum of deposit is wrong, and maybe the deposit doesn't contain any
  information about its originator? In that case the vendor doesn't have any
  way to know who's order should be completed. Will this upset the customer,
  even if it is actually his fault?
  The importance of bank reference is strongly underlined at DirDepo messages.
  At least finnish bank reference numbers have a checksum that greatly reduce
  the risk of incorrect reference numbers, since the bank validates the
  number before the customer is able to make his deposit. Do all countries have
  a similar bank reference standard? I guess not. How about international bank
  transactions? AFAIK, no. In those cases you may be able to use a message text
  in the deposit as a reference information field, but as an informal message
  it is not validated by a bank.
- Keeping eye on the received transactions does require some labor, especially
  if the reference numbers are wrong or missing very often.
  At least some finnish banks offer their online customers a possibility to
  download an ASCII-file containing a list of lately received deposits and
  their related information like the reference number. Maybe DirDepo or some
  other piece of software will some day include functionality to import such
  a list to VirtueMart and update related orders accordingly?
- I've red how some people are terrified of publishing their online shop's bank
  account number on the internet. If it is insecure to reveal your shop's bank
  account number to a customer during checkout or in the information email,
  then direct deposit isn't for you.
  In Finland it is a normal everyday routine to publish the bank account number
  of a invoicing company to a customer who is being invoiced, and I don't see
  any real risks in it.

Benefits of direct deposit (at least in Finland):
- Cheap. Doesn't require any contracts with third parties, like credit card
  companies, banks or post office, and thus no monthly payments, service fees
  or provisions. A normal bank account is all that is needed.
- Technically simple. No complicated electronic payment gateway transactions.
- Customers are familiar with the basic concept (paying invoices thru a bank).
  Most customers have online banking account, and are thus likely to make
  the deposit quickly after the order.
- Deposits are transfered fairly fast between banks. If customer and invoicer
  use the same bank group, the transaction takes place within a day.
  Transactions between different bank groups takes two to three days.
- Customers don't have to give credit card numbers or any other sensitive
  information to the vendor.

Known limitations of DirDepo:
- At the moment DirDepo is still in alpla state, meaning that it hasn't been
  widely tested in live online shops.
- Only one invoicer per VirtueMart:
  VirtueMart can have several vendors operating under one online shop. At
  the moment it is impossible to configure different invoicer settings for
  different vendors. All vendors need to share the same invoicer settings.
- VirtueMart can have several different instances of any particular payment
  method. It is possible to use DirDepo for several different direct deposit
  payment method instances, but they all need to share the same invoicer
  settings. If this is a problem for your online shop, you need to duplicate
  DirDepo by renaming one file and the subclass in it.
AFAIK, these two limitations above would require changes to the core code of
VirtueMart, or the vendorId and method code would have to duplicated on
configuration form and so on.
- DirDepo doesn't validate its input. This isn't a big problem or a security
  risk, because none of its input is directly from the customer. All
  DirDepo's input comes thru VirtueMart, which validates the user input. But
  the shop administrator needs to think carefully of what he inserts into the
  configuration settings.
This limitation shouldn't be difficult to fix, but it does require some labor.
At the moment the limitations above are not a top priority on my todo list,
because I don't need them personally on my own VirtueMart installation.
- My native language is finnish and my english isn't very good. So the
  DirDepo code and documentation is full of terrible english and bad
  terminology ;) I do how ever feel that it is more beneficial to the
  Joomla/VirtueMart OSS community if I publish DirDepo in english instead of
  finnish. I also feel that it is more beneficial to myself as a learning
  experience and as a peer review and code contributions.
For example corrected english output template file are very welcome.

Benefits of DirDepo:
- Fairly easy to install.
- Doesn't require any modifications to Joomla/VirtueMart core code.
- Support for multiple output languages.
- Output template files easily modified to suit each invoicers needs.
- Ease to extend to fit different banking processes.
- Free of charge. Open source.

At the moment DirDepo add-on includes a subclass which implements direct
deposit process suitable to finnish banking standards. This implementation is
in english and finnish.
Since DirDepo add-on is programmed in Object Oriented fashion, it should be
fairly simple to write other subclasses, which implement slightly different
banking processes for other banking standards. Other languages should be easy
to implement as well.
Please consider to contribute your subclasses, modifications and translations
to the public in the spirit of free and open source software.

As DirDepo is free (free as in speech, see http://www.fsf.org/) and
open source (see http://www.opensource.org/) software, it is free
(free as in beer) of charge.
If you feel that DirDepo is a great add-on to your VirtueMart online shop, and
that you have benefited financially of it, and if you feel you would like to
make a monetary donation, please donate a suitable amount to VirtueMart
(see http://www.virtuemart.com/).

function makeBankRef()
{
    $refNum = date('Y').
    str_pad($this->ddInfo['user_id'], 5, '0', STR_PAD_LEFT).
    str_pad($this->ddInfo['order_id'], 7, '0', STR_PAD_LEFT);
    $this->ddInfo['bank_ref'] = $refNum.$this->countBankRefCheckSum($refNum);
}

- - - - - 0.1.1 - - - - -

2006-11-14 Teemu Mäntynen <teemu.mantynen@tyovaline.fi>
  * ps_dirdepo_fi.php / ps_dirdepo_fi::makeBankRef()
    - User ID is no longer part of the bank reference number, and Order Id is
      padded to 6 characers instead of 7. Changed because 15 characters is too
      long and might cause too much typing errors for customers.
    - Reference number is split into chunks of five characters to make the number
      more easily readable for the customers and to follow the Finnsh Bankers'
      Association's standard.

  * README
    - Added information about development envinroment (Joomla! 1.0.11,
      VirtueMart 1.0.7 etc.).

  * /doc/user/index.html
    - Added more detailed information about installation directories.

  * ZIP-package
    - Included installation directory structure.