Table of Contents
Handling Management
Currently, we have several payment methods like invoice, entrance, cash, authorize_aim, cc and paypal etc. Some of them need to have extra handling procedures to handle the payment and others will be handled by Fusion Ticket itself. These extra handlings are handled inside the Extended Payment Modules or short EPM classes.
How it is now
When I looked at the payment system, I found that different parts of the payment methods where spread over different folders within fusion ticket. To configure the payment methods the codes were found inside the include/admin folder. For the shopping part, the code is spread between the include/classes folder and the templates. Also each EPH has their own way to tell if a payment transaction was accepted or not. Some of them were in code, others used in different template files. When the EPH used the template the control of the payment was very different between the EPH's and was done through an unclear method call through the smarty handling block.
Conclusion
I found this difficult to be maintained and unclear how the methods work at all. When I started working on BETA4, I decided to changes that by integrating this part, so far as possible. And make it one class that handles the admin section and the shopping section. Also, I wanted to remove the template part of the payment system when it has anything to do with calling the payment provider. This must, IMHO, be done inside that class, also. The method of handling needs to be made uniform, with one set of basic templates that are used for all the EPH's. The communication must be done only through the handling module and will be almost transparent from the outside.
The New Checkout
The next picture shows how the Payment will be handled, after checkout, for the order the user created. This is not a new diagram, but now it is worked out. New is that all communication will be done between the controller and the Handling model. The Handling model will be the only class that is talking to the extended payment classes/modules.
The Structure
Every payment method (paypal etc) has their own class that handles the administration side and will handle the real payment transaction for the web-shop or POS system. This makes developing new payment systems much simpler. This new extended payment classes are a combination of the old pm_*.php files in the includes/admin folder and the pm_*.php in the includes/classes folder.
When the user(patron) selects one of the defined payment methods in the checkout form in the shop, or in the POS, Fusion Ticket will add a handling class to the mycart basket. This handling class will automatically load the selected payment load as part of this class.
The rest of the program will only talk to the handling class, when needed the handling class will talk to the selected payment class to get the needed results.
The Payment Classes
The Payment classes need to be an extension of the class Base and have one or more of the the next variables and functions defined. The base class helps interaction with the dynamic class values.
public $extras = array ();
has all the fields that are used inside the payment method. These fields will automatically be saved in the field Extras of the table handling.
public $mandatory = array();
tells the system which fields need to be filled before the record can be saved.
function admin_view ( );
depricated
is used inside the admin section of the system and need to be added to the Payment class when you have fields that must be shown when the user views the handling settings.
- return: string; with html code to be shown inside the view handlings screen.
function admin_form ( );
is used inside the admin section of the system and needs to be added to the Payment class when fields must be filled by the user when adding or editing the handling settings.
- return: a string with htmlscript to be showed inside the add and edit handlings screen.
function admin_init ( );
is called when the user has created a new handling record. It allows you to fill the extra fields before the user can add this field.
- return: Nothing.
function admin_check ($arr);
will be called before the handling is actually saved to the database. It can be added to the payment class when you have to check other to do before the record can be saved.
- var $arr: this array has all the fields/values that can be checked.
- return: Boolean; when true the handling record can be saved.
function on_handle(&$order, $new_status, $old_status, $field);
is called when the order status is changed by the user.
- var $order has the current order that is changed by the user.
- var $new_status has the new value.
- var $old_status has the old value.
- var $field gives the name of the changed table field.
- return: Boolean; true when the status change is allowed.
function on_order_delete($order_id);
is automatically called when the order is deleted. It can be used to do some actions that are needed to cancel the payment transaction.
- var $order_id has the order_id that will be deleted.
- return: Boolean; true when the order can be deleted.
function on_confirm(&$order);
is called when the user selects a handling that uses the payment. You can use this method to start the transaction or you can return a string with extra input fields to be entered by the user. The method on_submit() is then used to validate this new input.
- var $order has the current order that is changed by the user.
- return: String; Optional with extra input in html. This string does not need to have a <form> element, this will be handled by the template.
function on_submit(&$order );
is called when you have returned a extra input string on the on_confirm() event.
- var $order has the current order that is changed by the user.
- return: array of
- approved: Boolean
- response: String with payment information.
- transaction_id: string with the payment transaction number received from the payment service.
function on_return(&$order, $accepted );
is called when you have returned from an external page through checkout_accept.php or checkout_cancel.php as result from bv. PayPal etc.
- var $order has the current order that is changed by the user.
- return: array of
- approved: Boolean
- response: String with payment information.
- transaction_id: string with the payment transaction number received from the payment service.
function on_notify(&$order);
is optionally used as a back door for the payment service to confirm the payment at there service. Inside this function you can validate if an order is really paid or not. When so, you can safely set the order to paid and send the tickets.
- var $order has the current order that is changed by the user.
- return: Noting.
Using the Secure Order Reverence (SOR)
Every time you want to call checkout actions you need to send the SOR with the request. This SOR value is generated by order::DecodeSecureCode( $order); it will return a hash code that is used but the checkout actions to check of the call is valid. within the eph you do not need to act on it any future. In case you can only us a fixed url as return page we have create the Secure Action Request this does almost the same but it does not have the order as reverence and exist of an fixed id that is unique for the used order handler. Look at the eph_google.php how this is used.
New File Structure
In the past there were for every payment system their own script files and templates. This will be removed in favor for one set of new checkout scripts:
checkout.php: → checkout.tpl this is the same as the old kasse.php. This template will navigate between the different checkout sub screens.
- checkout_preview.tpl: this template will show the checkout screen with the possibility to choose the payment.
- checkout_confirm.tpl: this screen is shown when the user needs to enter some extra information before the payment can be executed. Or has only a button to jump to an external payment system.
- checkout_result.tpl: will be shown when the payment is accepted or canceled.
To handle payments like PayPal there are 3 scripts.
- checkout_approved.php: This tells the system that the payment is accepted and results in a call of checkout_result.tpl showing the accepted information.
- checkout_canceled.php: This tells the system that the payment is canceled and results in a call of checkout_result.tpl showing the cancel massage and reason.
- checkout_notify.php: This is a back door function for the payment systems that are allowed. This script will try to call the payment's notify event. There are no visible actions for this call. The notify method need to validate the information received from the caller. Also this will not go through the templates at all.
