Differences
This shows you the differences between the selected revision and the current version of the page.
development:gateways 2008/08/24 09:52 | development:gateways 2008/10/24 10:06 current | ||
---|---|---|---|
Line 1: | Line 1: | ||
====== Payment Gateways ====== | ====== Payment Gateways ====== | ||
+ | Instructions for adding a new payment gateway. All payment gateway code is located in includes/paymentapi/ folder. Inside this folder you will need to create a new folder to house your custom code created below. | ||
===== Config.php ===== | ===== Config.php ===== | ||
Line 22: | Line 23: | ||
= $data['gateway']['extra2Txt'] : (string) An additional extra parameter. It is included in case your gateway requires two forms of authentication. | = $data['gateway']['extra2Txt'] : (string) An additional extra parameter. It is included in case your gateway requires two forms of authentication. | ||
= $data['gateway']['cconsite'] : (string) This variable is either Y or N. Y means you are going to take the credit card on site and the site must have an SSL certificate installed. N means the gateway will handle this. | = $data['gateway']['cconsite'] : (string) This variable is either Y or N. Y means you are going to take the credit card on site and the site must have an SSL certificate installed. N means the gateway will handle this. | ||
+ | |||
+ | ===== readme.php ===== | ||
+ | The readme.php file is required so you can add any instructions for using the Payment Gateway. It will be accessible through the administration in a pop up window. | ||
+ | |||
+ | ===== sr.php ===== | ||
+ | The file sr.php or send and receive is used to handle setting up the form and handling the post back. | ||
+ | |||
+ | This file includes two php functions and they are: | ||
+ | - function check_createForm($params) | ||
+ | - function check_processTransaction($params) | ||
+ | |||
+ | These functions include the name of your gateway then the function name. The first portion comes from the $data['gateway']['name'] variable set in the config file. | ||
+ | |||
+ | So if you named your gateway "kingarthur" then your functions would be: | ||
+ | - function kingarthur_createForm($params) | ||
+ | - function kingarthur_processTransaction($params) | ||
+ | |||
+ | These methods are used by the core files to tell the difference from each gateway. | ||
+ | |||
+ | Now that the function names are out of the way we will move on to the $params array that is passed to the functions. | ||
+ | |||
+ | ==== Create Form ==== | ||
+ | |||
+ | The createform function has these available $params. | ||
+ | |||
+ | * $params['oID'] - Order ID | ||
+ | * $params['extra'] - The extra info | ||
+ | * $params['extra2'] - The second extra info | ||
+ | * $params['oProduct'] - The product name ordered | ||
+ | * $params['oTotal'] - The total price | ||
+ | * $params['userinfo'] ? An array of all the users details. | ||
+ | |||
+ | If you wish to see all of the available params you can add the following php inside the function: | ||
+ | <code php>print_r($params); die;</code> | ||
+ | Then a list of variables will be printed when you place a test ad. | ||
+ | |||
+ | ==== Process Transaction ==== | ||
+ | |||
+ | The processTransaction function has these available $params. | ||
+ | |||
+ | * $params['gatewayid'] - The id of the gateway | ||
+ | * $params['approved'] - Y or N depending on if it is approved. | ||
+ | * $params['extra'] - The extra data defined in administration | ||
+ | * $params['extra2'] - Same as above. | ||
+ | |||
+ | Plus any others from your Payment Gateway. You will need to refer to their documentation on what they are. | ||
+ | Since the check / money order gateway doesn't include the post back information you will probably need, we will use the processTransaction function from the Paymate gateway: | ||
+ | <code php> | ||
+ | function paymate_processTransaction($params) | ||
+ | { | ||
+ | global $db,$Orders,$userid; | ||
+ | |||
+ | $orderid = (int)@$params['ref']; | ||
+ | switch ($params['responseCode']) | ||
+ | { | ||
+ | case "PA": | ||
+ | $Orders->logTransaction($params['gatewayid'], $orderid, 'Payment is approved', $userid, $params['transactionID'], $params['paymentAmount']); | ||
+ | if($Orders->updateOrder($orderid, 'Y')) | ||
+ | { | ||
+ | return TRUE; | ||
+ | } | ||
+ | else | ||
+ | { | ||
+ | //an error occured | ||
+ | return "Payment was made but your order has not been approved. Please contact support for help."; | ||
+ | } | ||
+ | break; | ||
+ | case "PD": | ||
+ | $Orders->logTransaction($params['gatewayid'], $orderid, 'Payment is declined', $userid, $params['transactionID'], $params['paymentAmount']); | ||
+ | return "Payment is declined"; | ||
+ | break; | ||
+ | case "PP": | ||
+ | $Orders->logTransaction($params['gatewayid'], $orderid, 'Payment is processing', $userid, $params['transactionID'], $params['paymentAmount']); | ||
+ | return "Payment is processing"; | ||
+ | break; | ||
+ | default: | ||
+ | $Orders->logTransaction($params['gatewayid'], $orderid, 'An error occured', $userid, $params['transactionID'], $params['paymentAmount']); | ||
+ | return "We are sorry but an occured."; | ||
+ | break; | ||
+ | } | ||
+ | } | ||
+ | </code> | ||
+ | |||
+ | Starting from the top we include global $db, $Orders, $userid. I will not go into details what the global does but you can find out from php.net. | ||
+ | |||
+ | Next we have $orderid = (int)@$params['ref']; | ||
+ | |||
+ | The $params['ref'] comes from Paymate and that is the internal reference for 68 Classifieds so it knows what order to approve. | ||
+ | |||
+ | After that comes a switch statement which is the response code Paymate sent. | ||
+ | Through each case we call the logtransaction function so the administrator knows they tried to complete the payment but something happened. | ||
+ | |||
+ | Finally if the order is approved. Paymate uses the PA which I assume means PAID. | ||
+ | |||
+ | We then update the order with this call: | ||
+ | <code php> | ||
+ | if($Orders->updateOrder($orderid, 'Y')) | ||
+ | { | ||
+ | return TRUE; | ||
+ | } | ||
+ | else | ||
+ | { | ||
+ | //an error occured | ||
+ | return "Payment was made but your order has not been approved. Please contact support for help."; | ||
+ | } | ||
+ | </code> | ||
+ | |||
+ | If it returns true then the order was successfully updated if not it returns an error and something happened inside the Orders class to make the order not be updated. | ||
+ | |||
+ | As you can see creating a custom gateway is not a simple process and as such is not supported by us. A lot of things can go wrong and it will take some trial and error getting it setup properly. | ||
+ | |||
+ | ===== External Resources ===== | ||
+ | * [[http://php.net|PHP Website]] | ||
+ | * [[http://www.68classifieds.com/forums|68 Classifieds Forums]] | ||
+ | |||
Have more questions? Visit our community forums.