Differences

This shows you the differences between two versions of the page.

--- joomla30:jobsfactory:api [2015/01/05 11:03]
mircea created
+++ joomla30:jobsfactory:api [2015/10/19 10:28]
mircea
@@ Line 1: / Line 1: @@
-====== theFactory auction API for 3rd party Payment Gateways integration. ======
+====== API for 3rd party Payment Gateway Integration ======
 \\
-Implementing a Payment Gateway requires PHP knowledge and is not part of support, this documentation is written for programmers. Already available Gateways can be seen [[joomla25:auction:payment_plugins#gateways|here]].
+Implementing a Payment Gateway requires PHP knowledge and is not part of support, this documentation is written for programmers. Already available Gateways can be seen [[joomla30:jobsfactory:gateways.listing|here]].
 \\
-For your basic Payment Gateway you will need to create at least the following files:
+The payment gateway folder and files will have to be located in **//[SITE_ROOT]\administrator\components\com_jobsfactory\thefactory\payments\plugins\gateways\//**
 \\
-    * **manifest.xml **- an installation manifest for the Gateway
+The main folder will be named "pay_mygateway" and contain the following files:
-    * **form.xml**     - the administration settings for the Gateway in [[http://docs.joomla.org/XML_JForm_form_definitions|Joomla XML JForm format]]
-    * **controller.php**     - a PHP File containing the controller that extends **TheFactoryPaymentGateway**
-    * **logo.png**     - a logo for the payment gateway
 \\
-You can download a sample Gateway [[http://thefactory.ro/pay_example.zip|here (a mockup)]]
+  * controller.php (gateway logic and frontend form)
+  * form.xml (the admin form)
+  * logo.png (optional)
 \\
-=== The Manifest File ===
+===== controller.php =====
 \\
-<code xml>
+Must contain:
-<extension folder="pay_example" type="gateway" method="upgrade">
-<name>Example Payment Gateway</name>
-</extension>
-</code>
 \\
-The Folder value should match the name you plan to use for your extension. Do not use space or punctuation.
+<code php>
+defined('_JEXEC') or die('Restricted access');
+require_once(realpath(dirname(__FILE__).DS.'..'.DS.'..'.DS.'..'.DS.'classes'.DS.'gateways.php'));
+</code>
 \\
-=== The Admin Settings Form ===
+Then a class named after the gateway folder which extends "TheFactoryPaymentGateway" has to be created, it must also contain:
 \\
-Use the Joomla Form XML Standards to set up witch fields you need the user to setup in order to post payments to the gateway. For instance you might need the Seller email:
+<code php>
-\\
+class Pay_mygateway extends TheFactoryPaymentGateway
+{
+    var $name='pay_mygateway';  //gateway name, used to load gateway parameters saved with form.xml
+    var $fullname='My Payment Gateway';
-<code xml>
-<?xml version="1.0" encoding="UTF-8"?>
-<form>
-  <fieldset>
-    <field default="change@me.com" required="true" size="30" class="inputbox" description="" label="Paypal Email" type="text" name="selleremail"/>
-  </fieldset>
-</form>
 </code>
 \\
-=== The Controller ===
+==== controller Functions ====
+\\
+  * **getPaymentForm** //function// is required in each gateway and **must be overwritten** in the class. This function contains the Gateway specific part, in it you display the Payment form specific for each Payment Processor.
 \\
 <code php>
-defined('_JEXEC') or die('Restricted access');
-require_once(realpath(dirname(__FILE__).DS.'..'.DS.'..'.DS.'..'.DS.'classes'.DS.'gateways.php'));
-class Pay_Example extends TheFactoryPaymentGateway
-{
-    var $name='pay_paypal';
-    var $fullname='Paypal Payment Gateway';
     function getPaymentForm($order,$items,$urls,$shipping=null,$tax=null)
     {
-        $model=&JModel::getInstance('Gateways','JTheFactoryModel');
+           function getPaymentForm($order,$items,$urls,$shipping=null,$tax=null)
-        $params=$model->loadGatewayParams($this->name);
-        $result = 'your html for the form payment here';
-        return $result;
-    }
-    function processIPN()
     {
-        $model=&JModel::getInstance('Gateways','JTheFactoryModel');
+        $model=&JModel::getInstance('Gateways','JTheFactoryModel');  //loads TheFactory gateway model
-        $params=$model->loadGatewayParams($this->name);
+        $params=$model->loadGatewayParams($this->name);  //loads gateway parameters
+    ...
-        $paylog=&JTable::getInstance('PaymentLogTable','JTheFactory');
-        //paylog data here
+</code>
-        //validate IPN
-        $paylog->store();
-        return $paylog;
-    }
-}
-</code>
+\\
-Your Controller Class must be named exactly as the **folder value**    in the Manifest File. This is why it is important to use only acceptable characters for a class name.
+Payment Form Values
 \\
-There are several functions you should/could implement:
+^Value^Description^
+|$paypal_address|website paypal email|
+|$order|object containing order data|
-**function getPaymentForm**    - should return the HTML code for the payment gateway. This will be displayed when an user checks out an order using this particular gateway.
+|$urls|return_url, cancel_url, notify_url|
 \\
-Parameters are:
+$urls
 \\
-    * $order → the Order Object
+^  URL  ^  Description  ^
-    * $items → an array of Items from this particular Order
+|return_url|The URL where the gateway will redirect after payment is completed|
-    * $urls → an array of URLS specific to gateways -
+|cancel_url|The URL where the gateway will redirect if payment is cancelled|
-      * $urls['return_url'] - the return url for a successful payment
+|notify_url|The IPN (Instant Payment Notification) URL|
-      * $urls['cancel_url'] - the return url for a canceled or failed payment
-      * $urls['notify_url'] - the instant notification url (is used by gateways similar to paypal)
-\\
-**function processIPN**    - is called when the Payment gateway has processed the payment (instant payment notification)
 \\
-**function processTask  **- function is called for the frontend task orderprocessor.gateway with your gateway as parameter. Used for instance in multi step processings check the Bankwire Gateway
+  * The **processIPN** //function// is also included in the class and must be overwritten with Gateway Specific data. This function must process the Gateway IPN and return a status for the Payment in the Jobs system, stored in the **$paylog**.
 \\
-== for advanced usages you can implement these functions: ==
+The relevant payment statuses are: **ok, error** and **manual_check**.
+These are extension specific and should be used as they are.
 \\
-**function getLogo**   - returns the url to the gateway logo (default is the logo.png in your gateway folder)
+  * The **processTask** //function// is the entry point for the "gateway" task of the Payments Processor controller. See the Bank Transfer gateway implementation as an example.
-**function saveAdminForm**   - called when the Admin setup form is saved
-**function showAdminForm**   - called when the Admin setup form is displayed
 \\
-==== Installation ====
+Any number of functions can be created depending on the Payment Processor's features and requirements, an example of such a function is the **validate_ipn()** used in the Pay Pal implementation. Use their specific documentation to see where //something more// is needed.
 \\
+\\
+----
+**(!)** Documentation based on **Jobs Factory** version **1.6.3**
-Pack all files needed into a zip archive (make sure manifest.xml is in the top folder). This will be the Installation zip.
-In Administrator Backend go to Components>Auction Factory>Settings
-Then click on "Payment Methods Config" and choose "Install New Item" from the toolbar.
-Upload the gateway installation zip and then you should see it in the gateways list.