Differences
This shows you the differences between two versions of the page.
| Next revision | Previous revision | ||
|
joomla30:jobsfactory:api [2015/01/05 11:03] mircea created |
joomla30:jobsfactory:api [2017/04/07 11:32] sorin |
||
|---|---|---|---|
| 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: | ||
| - | |||
| \\ | \\ | ||
| - | + | Uploading an already set up payment gateway pack requires you to go to **Components -> Jobs Factory -> Settings -> Payment Gateways** and click on **Install new item** button.\\ | |
| - | * **manifest.xml **- an installation manifest for the Gateway | + | |
| - | * **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 | + | |
| \\ | \\ | ||
| - | + | The payment gateway folder and files will have to be located in **//[SITE_ROOT]\administrator\components\com_jobsfactory\thefactory\payments\plugins\gateways\//** | |
| - | You can download a sample Gateway [[http://thefactory.ro/pay_example.zip|here (a mockup)]] | + | |
| \\ | \\ | ||
| - | === The Manifest File === | + | The main folder will be named "pay_mygateway" and contain the following files: |
| \\ | \\ | ||
| - | <code xml> | + | * controller.php (gateway logic and frontend form) |
| - | <extension folder="pay_example" type="gateway" method="upgrade"> | + | * form.xml (the admin form) |
| - | <name>Example Payment Gateway</name> | + | * logo.png (optional) |
| - | </extension> | + | |
| - | </code> | + | |
| \\ | \\ | ||
| - | The Folder value should match the name you plan to use for your extension. Do not use space or punctuation. | + | ===== controller.php ===== |
| \\ | \\ | ||
| - | === The Admin Settings Form === | + | Must 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> |
| + | defined('_JEXEC') or die('Restricted access'); | ||
| - | \\ | + | require_once(realpath(dirname(__FILE__).DS.'..'.DS.'..'.DS.'..'.DS.'classes'.DS.'gateways.php')); |
| - | + | ||
| - | <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> | </code> | ||
| \\ | \\ | ||
| - | === The Controller === | + | Then a class named after the gateway folder which extends "TheFactoryPaymentGateway" has to be created, it must also contain: |
| \\ | \\ | ||
| <code php> | <code php> | ||
| - | defined('_JEXEC') or die('Restricted access'); | ||
| - | require_once(realpath(dirname(__FILE__).DS.'..'.DS.'..'.DS.'..'.DS.'classes'.DS.'gateways.php')); | + | class Pay_mygateway extends TheFactoryPaymentGateway |
| - | + | ||
| - | class Pay_Example extends TheFactoryPaymentGateway | + | |
| { | { | ||
| - | var $name='pay_paypal'; | + | var $name='pay_mygateway'; //gateway name, used to load gateway parameters saved with form.xml |
| - | var $fullname='Paypal Payment Gateway'; | + | var $fullname='My Payment Gateway'; |
| - | function getPaymentForm($order,$items,$urls,$shipping=null,$tax=null) | + | |
| - | { | + | |
| - | $model=&JModel::getInstance('Gateways','JTheFactoryModel'); | + | |
| - | $params=$model->loadGatewayParams($this->name); | + | |
| - | $result = 'your html for the form payment here'; | ||
| - | |||
| - | return $result; | ||
| - | } | ||
| - | function processIPN() | ||
| - | { | ||
| - | $model=&JModel::getInstance('Gateways','JTheFactoryModel'); | ||
| - | $params=$model->loadGatewayParams($this->name); | ||
| - | |||
| - | $paylog=&JTable::getInstance('PaymentLogTable','JTheFactory'); | ||
| - | //paylog data here | ||
| - | |||
| - | //validate IPN | ||
| - | |||
| - | $paylog->store(); | ||
| - | return $paylog; | ||
| - | } | ||
| - | } | ||
| </code> | </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. | + | ==== controller Functions ==== |
| \\ | \\ | ||
| - | There are several functions you should/could implement: | + | * **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. |
| - | + | ||
| - | + | ||
| - | **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. | + | |
| \\ | \\ | ||
| - | Parameters are: | + | <code php> |
| - | \\ | + | function getPaymentForm($order,$items,$urls,$shipping=null,$tax=null) |
| - | + | { | |
| - | * $order → the Order Object | + | function getPaymentForm($order,$items,$urls,$shipping=null,$tax=null) |
| - | * $items → an array of Items from this particular Order | + | { |
| - | * $urls → an array of URLS specific to gateways - | + | $model=&JModel::getInstance('Gateways','JTheFactoryModel'); //loads TheFactory gateway model |
| - | * $urls['return_url'] - the return url for a successful payment | + | $params=$model->loadGatewayParams($this->name); //loads gateway parameters |
| - | * $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) | + | |
| + | </code> | ||
| \\ | \\ | ||
| - | **function processIPN** - is called when the Payment gateway has processed the payment (instant payment notification) | + | Payment Form Values |
| \\ | \\ | ||
| - | **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 | + | ^Value^Description^ |
| + | |$paypal_address|website paypal email| | ||
| + | |$order|object containing order data| | ||
| + | |$urls|return_url, cancel_url, notify_url| | ||
| \\ | \\ | ||
| - | == for advanced usages you can implement these functions: == | + | $urls |
| \\ | \\ | ||
| - | **function getLogo** - returns the url to the gateway logo (default is the logo.png in your gateway folder) | + | ^ URL ^ Description ^ |
| + | |return_url|The URL where the gateway will redirect after payment is completed| | ||
| + | |cancel_url|The URL where the gateway will redirect if payment is cancelled| | ||
| + | |notify_url|The IPN (Instant Payment Notification) URL| | ||
| - | **function saveAdminForm** - called when the Admin setup form is saved | + | \\ |
| - | **function showAdminForm** - called when the Admin setup form is displayed | + | * 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**. |
| \\ | \\ | ||
| - | ==== Installation ==== | + | The relevant payment statuses are: **ok, error** and **manual_check**. |
| + | These are extension specific and should be used as they are. | ||
| \\ | \\ | ||
| - | Pack all files needed into a zip archive (make sure manifest.xml is in the top folder). This will be the Installation zip. | + | * 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. |
| + | \\ | ||
| - | In Administrator Backend go to Components>Auction Factory>Settings | + | 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. |
| - | + | \\ | |
| - | + | \\ | |
| - | Then click on "Payment Methods Config" and choose "Install New Item" from the toolbar. | + | ---- |
| + | **(!)** Documentation based on **Jobs Factory** version **2.0.0** | ||
| - | Upload the gateway installation zip and then you should see it in the gateways list. | ||