This is documentation for Kohana v2.3.x. For v3.x documentation, see http://kohanaframework.org/guide .

Table of Contents
StatusDraft
TodoNeeds 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:

  1. An extremely easy API (only one method required to process a transaction!)
  2. Detailed error reporting
  3. Extensible with backend drivers to connect to many different payment gateways
  4. 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.

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

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

$payment = new Payment();

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().

$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
}

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:

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

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.

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.

$payment = new Payment();
 
$attributes = array
(
    'card_num' => '1234567890123456',
    'exp_date' => '0510'
);
 
$payment->set_fields($attributes);

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:

  1. Trident Gateway

Authorize.net

Required Fields

  1. card_num
  2. exp_date
  3. 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

  1. card_num
  2. exp_date
  3. amount

TrustCommerce

Required Fields

  1. card_num
  2. exp_date
  3. amount

YourPay.net

Required Fields

  1. card_num
  2. exp_date
  3. amount
  4. tax
  5. shipping
  6. 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

  1. amount
  2. 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.

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);
	}
}

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:

  1. Add a new entry in config/payment.php with your driver details. Use the previous entries as an example.
  2. Copy the Trident Gateway driver and rename it to *Gateway Name*.php
  3. Alter the required fields array as instructed in the gateway's API manual (You have this, right? ;)
  4. Modify the fields array to include all the available relevant fields for the gateway
  5. Modify the constructor to set default values from the config file (API username/password for example)
  6. 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.)
  7. Modify the $post_url ternary statement to include the correct test and live mode API URLs
  8. Modify how the return statement handles success and error based on what the specific gateway status message is (Look in you API manual)
addons/payment.txt · Last modified: 2010/02/14 22:51 by rowanparker