^Status|Draft|
^Todo|Needs updating from library to module|

====== Payment Module ======

===== Overview =====

The payment module allows you to easily process e-commerce transactions without having to worry about all the backend details of connecting and setting up the cURL options. It has many features:

  - An extremely easy API (only one method required to process a transaction!)
  - Detailed error reporting
  - Extensible with backend drivers to connect to many different payment gateways
  - Support for credit card gateways as well as PayPal-like gateways

===== Loading the payment module =====

This can be done in the application/config/config.php file using the 'modules' setting.

<code php>$config['modules'] => array
(
    'modules/auth',
    'modules/payment'
)
</code>

Then you just have to instantiate the module to use it. For example:

<code php>
$payment = new Payment();
</code>

===== Usage example =====

Using it is very simple. The code below shows how to use the payment module, just set the fields required by your driver, and process().

<code php>
$payment = new Payment();
$payment->card_num = '1234567890123456';
$payment->exp_date = '0510';

if ($status = $payment->process() === TRUE)
{
     // Report successful transaction
}
else
{
    // $status has the error message, so display an error page based on it
}
</code>

===== Configuration =====

In system/config/payment.php there is a sample config for each payment gateway we support. Simply copy this file to your application directory, and remove the drivers you are not using. The module can support using more than one driver per application by passing the driver name to the constructor:

<code php>

$paypal_payment = new Payment('Paypal');
$authorize_payment = new Payment('Authorize');

</code>

After you remove the non-required config lines, modify your driver config as needed. Usually this will include some sort of API username/password combination, but it differs for each driver.

===== Attributes =====

The payment module has a set of default attributes it uses to send payments to the gateway. These attributes are fairly self explanatory and are listed below.

  *  card_num
  *  exp_date
  *  cvv
  *  description
  *  amount
  *  tax
  *  shipping
  *  first_name
  *  last_name
  *  company
  *  address
  *  city
  *  state
  *  zip
  *  email
  *  phone
  *  fax	
  *  ship_to_first_name
  *  ship_to_last_name
  *  ship_to_company
  *  ship_to_address
  *  ship_to_city
  *  ship_to_state
  *  ship_to_zip

Specific drivers may require some or all of these fields. They may also have driver specific fields that are noted in the Driver section.

===== Methods =====

The payment module has a minimal set of methods to use:

==== set_fields() ====

This method allows you to set bulk payment attributes with an array.

<code php>
$payment = new Payment();

$attributes = array
(
    'card_num' => '1234567890123456',
    'exp_date' => '0510'
);

$payment->set_fields($attributes);
</code>

==== process() ====

This method does the magic. After you set your attributes, simply call this method in an if test. The method returns TRUE on successful payment transaction or an error string on failure. It is up to you how to handle the failure.

===== Drivers =====

The payment module uses drivers much like the Database library does in order to keep the API consistent between payment gateways. It currently supports the following gateways:

  - [[http://www.authorize.net/|Authorize.net]]
  - [[http://checkout.google.com|Google Checkout]]
  - [[http://www.moneybookers.com/|Moneybookers]]
  - Trident Gateway
  - [[http://www.trustcommerce.com/|TrustCommerce]]
  - [[http://YourPay.net|YourPay.net]]
  - [[http://www.paypal.com|PayPal/Paypal Pro]]

==== Authorize.net ====

=== Required Fields ===

  - card_num
  - exp_date
  - amount

=== Note ===

Only enable test_mode in the config if you have a Authorize.net developer test account. If you have a regular account that is in test mode (set on your Authorize.net web portal) then disable test mode.

==== Trident Gateway ====

=== Required Fields ===

  - card_num
  - exp_date
  - amount

==== TrustCommerce ====

=== Required Fields ===

  - card_num
  - exp_date
  - amount

==== YourPay.net ====

=== Required Fields ===

  - card_num
  - exp_date
  - amount
  - tax
  - shipping
  - cvv

=== Driver Specific Details ===
The amount above is the subtotal. Tax and Shipping get added to the amount to form the grand total inside the driver.
==== PayPal ====

=== Required Fields ===

  - amount
  - payerid (after paypal authentication)

=== Driver Specific Details ===

Using the PayPal driver is a little different than a normal credit card transaction. It requires two process() commands to be run. The first one will send the user to PayPal to authenticate, and the second one will actually run the transaction. Below is an example of this.

<code php>
class Paypal_Controller extends Controller {

	// This will demo a simple paypal transaction. It really only comes down to two steps.
	function __construct()
	{
		parent::__construct();

		$this->paypal = new Payment();
	}

	// This will set up the transaction and redirect the user to paypal to login
	function index()
	{
		// Delete any existing payment attempts
		Session::instance()->delete('paypal_token');
		$this->paypal->amount = 5;
		$this->paypal->process();
	}

	// Once the user logs in, paypal redirects them here (set in the config file), which processes the payment
	function return_test()
	{
		$this->paypal->amount = 5;
		$this->paypal->payerid = $this->input->get('payerid'); 
		echo ($this->paypal->process()) ? "WORKED" : "FAILED";
	}

	// This is the cancel URL (set from the config file)
	function cancel_test()
	{
		echo 'cancelled';
	}

	// Just some utility functions.
	function reset_session()
	{
		$this->session->destroy();
		url::redirect('paypal/index');
	}

	function session_status()
	{
		echo '<pre>'.print_r($this->session->get(), true);
	}
}
</code>

===== Writing Your Own Driver =====

There are many more payment gateways than there are drivers provided by Kohana. We encourage you to write your own when you encounter a gateway not supported by the module. An easy way to do it is like so:

  - Add a new entry in config/payment.php with your driver details. Use the previous entries as an example.
  - Copy the Trident Gateway driver and rename it to *Gateway Name*.php
  - Alter the required fields array as instructed in the gateway's API manual (You have this, right? ;)
  - Modify the fields array to include all the available relevant fields for the gateway
  - Modify the constructor to set default values from the config file (API username/password for example)
  - Modify the set_fields() method to do variable translation (for example if your gateway names cc_num something different. Look in your API manual for details.)
  - Modify the $post_url ternary statement to include the correct test and live mode API URLs
  - Modify how the return statement handles success and error based on what the specific gateway status message is (Look in you API manual)