Gateway Aide Memoire


Vince's aide memoire to making gateway mini-components for Jomres

This is a series of notes to indicate what each of the files in the gateway plugins do.

For a long time Jomres was stuck with having a small handful of gateways. Partly because due to time I was unable to create more and partly because each new gateway would require a fresh version of Jomres to release it. V2 has changed that because of it's mini-component handling functionality. Gateways are now handled like mini-components in that they are freely installable (although Jomres has the basic "form" and "paypal" options available by default).

The components of a payment module in Jomres:

j00509_GATEWAYNAME_.class.php
j00510_GATEWAYNAME_.class.php
j00510_GATEWAYNAME_.gif
j00510_GATEWAYNAME_.html
j00600_GATEWAYNAME_.class.php
j00600_GATEWAYNAME_.html
j00605_GATEWAYNAME_.class.php
j00610_GATEWAYNAME_.class.php
j03108_GATEWAYNAME_.class.php


Obviously _GATEWAYNAME_ is substituted with the name of the gateway in question. Gateways are only triggered at the Confirm Booking stage when the user doing the booking is not an authorised manager.

Brief explanation of each file and what it does

j00509_GATEWAYNAME_.class.php


Purpose: To acknowledge existence of the module to the configuration panel "gateways".
Notes: When the gateways config panel is generated this file is called. It generates the link seen in the config panel that is clicked to enable the gateway module configuration popup.


 

j00510_GATEWAYNAME_.class.php


Purpose: Compiles configuration options that the user can edit.
Notes: N/A

 


 

 

j00510_GATEWAYNAME_.gif


 Purpose: The gateway image
 Notes:N/A


 

j00510_GATEWAYNAME_.html


 Purpose: patTemplate file used when generating module configuration popup
 Notes: N/A


 

j00600_GATEWAYNAME_.class.php


 Purpose: 00600 plugin interrupt.
 Notes: function showBookingConfirmation in jomres_bookingroom_functions.php lists active gateway plugins. When a gateway is chosen and the customer clicks submit to proceed to payment the module designer is able to program an 'interrupt' that will be triggered before the customer is sent off-site to perform payment. This enables data collection that the system has not collected elsewhere that the module specifically requires. This file is optional, if it doesn't exist then Jomres will skip it and go straight to the 00605 eventTrigger.


 

j00600_GATEWAYNAME_.html


 Purpose: patTemplate file for generating input/output for j00600 class file.
 Notes: N/A


 

j00605_GATEWAYNAME_.class.php

 Called by: jomres.php
 Purpose: Sends any required postage data to payment gateway, eg paypal. and redirects the user to the payment gateway's interface.
 Notes: Is triggered after 00605, or if 00605 doesn't exist then is called straight away.


 

j00610_GATEWAYNAME_.class.php

 Purpose: Is called by payment gateways confirming receipt of payment, and when customers are redirected back to the jomres site after payment.
 Notes: It is worth noting that the payment data is still only stored in the temporary session data at this point. It is only when the insertInternetBooking function is specifically called, normally by this file but there are other places it can be called, that the booking is transferred from the temporary data to the contracts table. If the process is not completed then the booking is technically lost. Available but liable to be overwritten if the guest should return to the booking form). Also note that in some cases this file may be optional, eg. the cheque (or offline payment) module doesn't use it, the insertInternetBooking function is called by 00605cheque.class.php as there's no extra processing required.

Because the temporary data is stored in session variables it's not unheard of for Paypal's IPN to take so long returning it's information that the session has expired and the data lost, therefore it's advised that you up the Joomla session timeout from the pretty short timescale configured by the CMS's to something a little more reasonable. I can't suggest what's reasonable because that's down to you to decide what's best, but I wouldn't be surprised if many people set their timeouts to an hour or more.


 

j03108_GATEWAYNAME_.class.php


 Purpose: Reports file path to the calling function.
 Notes: Provides the calling function with the path to the gateway gif.


 


Final notes to gateway developers

If you do

$tmpBookingHandler =jomres_getSingleton('jomres_temp_booking_handler');

and do

var_dump($tmpBookingHandler->tmpguest);exit;

you'll see that you've got access to all the guest's details there.


In your 610 file, please make sure, after you've confirmed the payment was successful, use this line :

$tmpBookingHandler->updateBookingField('depositpaidsuccessfully',true);

before you do the insert otherwise Jomres will mark the deposit as unpaid.

Finally, don't attempt to clean up any data stored in $tmpBookingHandler unless you specifically put it there yourself (you probably won't need to), I had another gateway developer do the same and it caused Jomres to behave in some very weird and wonderful ways until I took it out. Jomres will clean up that variable itself in the "insertInternetBooking" function.

 

Jomres 9 changes

In Jomres 9 we are introducing functionality that will allow invoices to be paid directly, as opposed to paying for bookings, which will require some changes to payment gateways if gateway developers wish to support this functionality.

Existing booking payment functionality is not affected, you can treat this as code that is independant of booking payments.

j10509paypal.class.php

Example :

        $plugin = "paypal";
        $this->retVals= array ("name" => "paypal" , "friendlyname" => $gatewayname=jr_gettext('_JOMRES_CUSTOMTEXT_GATEWAYNAME'.$plugin,ucwords($plugin),false,false) );

Allows the gateway to be listed in the administrator area List Gateways page.


 

j10510paypal.class.php

Builds the settings that are used to build the administrator area gateway settings page.

Example :

        $settingArray['client_id'] = array (
            "default" => "",
            "setting_title" => jr_gettext('_JOMRES_CUSTOMTEXT_GATEWAY_CONFIG_PAYPAL_CLIENT_ID'.$plugin,'Client ID'),
            "setting_description" => "",
            "format" => "input"
            ) ;

        $settingArray['pendingok'] = array (
            "default" => "1",
            "setting_title" => jr_gettext('_JOMRES_JR_GATEWAY_CONFIG_PAYPAL_PENDINGOK'.$plugin,'Pending ok?'),
            "setting_description" => jr_gettext('_JOMRES_JR_GATEWAY_CONFIG_PAYPAL_PENDINGOK_DESC'.$plugin,'In some instances it is acceptable to receive a payment status of "Pending". '),
            "format" => "boolean"
            ) ;


        $settingArray['currencycode'] = array (
            "default" => "1",
            "setting_title" => jr_gettext('_JOMRES_JR_GATEWAY_CONFIG_PAYPAL_CURRENCYCODE'.$plugin,'Currency code (eg EUR) '),
            "setting_description" => "",
            "format" => "currencycode"
            ) ;

        $siteConfig = jomres_singleton_abstract::getInstance( 'jomres_config_site_singleton' );
        $jrConfig   = $siteConfig->get();
        
        $index = 'gateway_setting_'.$plugin.'_checkbox';
        $checkbox_value = $jrConfig[$index];
        
        $settingArray['checkbox'] = array (
            "html" => '<input type="checkbox" name=\"gateway_setting_paypal_checkbox\" value="'.$checkbox_value.'"/>',
            "setting_title" => "Checkbox",
            "setting_description" => "Description",
            "format" => "html"
            ) ;



There are two more files, which actually send and receive to the remote gateway servers. Their filenames should always be as follows :

invoice_payment_send.class.php

invoice_payment_receive.class.php

They're used to send and receive information from the remote gateway, the filenames should be self-explanatory. They are passed an object that contains information about the invoice, ( $invoice_obj ), the payment reference ( required to allow us to cross reference invoice ids and the processing gateway plugin ) the value of the invoice plus the invoice line items. It also contains the specific gateway's settings as that were saved in j10510paypal.class.php.

If you're in any doubt, it's always best to look at how the Core Gateway Paypal does things, as it contains all of the code mentioned above.