Gateway Module Developer Docs - Revision history

Matt: Replaced content with "This page has moved to https://developers.whmcs.com/payment-gateways/"

2017-01-28T17:56:57Z

Replaced content with "This page has moved to https://developers.whmcs.com/payment-gateways/"

Show changes

John: /* App Store */

2016-03-22T11:15:48Z

‎App Store

Cole at 20:03, 15 January 2016

2016-01-15T20:03:10Z

Nicolas: /* App Store */

2016-01-06T20:50:50Z

‎App Store

Nicolas: /* Blank Screen/Errors */

2016-01-06T20:49:54Z

‎Blank Screen/Errors

Nicolas: /* Installation & Activation */

2016-01-06T20:47:51Z

‎Installation & Activation

Nicolas: /* Tokenised Remote Storage */

2016-01-06T20:44:04Z

‎Tokenised Remote Storage

Nicolas: /* 3D Secure Process */

2016-01-06T20:39:17Z

‎3D Secure Process

Nicolas: /* Callbacks */

2016-01-06T20:35:51Z

‎Callbacks

Nicolas: /* Card Details */

2016-01-06T20:19:33Z

‎Card Details

@@ Line 326: / Line 326: @@
 This enables PHP error reporting and should show the cause of any issues. Remove this line once testing has completed.
-==App Store==
+==WHMCS Marketplace==
-WHMCS offers an app store in which completed gateway modules can be submitted.  The listings are displayed under the Addons tab within the administration area and online at http://www.whmcs.com/appstore . This is a great way to make WHMCS users aware of your module!
+WHMCS offers a Marketplace which accepts submission of the completed module. Displayed listed are found under the Addons tab within the administration area and online at http://marketplace.whmcs.com . This is a great way to make WHMCS users aware of the module.
-In order to submit a listing you'll need a login for whmcs.com/members, if you do not have one please [https://www.whmcs.com/members/submitticket.php?step=2&deptid=5 Contact Us]. Once logged in, visit the app store page at the above URL and click the "Submit your Addon" link. We aim to review submissions in 1-2 weeks.
+For help using the Marketplace please refer to https://marketplace.whmcs.com/help . We aim to review submissions in 1-2 weeks.
 {{Developer_Links}}

@@ Line 1: / Line 1: @@
-Creating a gateway module allows you to connect WHMCS to third party payment and credit card processors that aren’t natively supported in WHMCS as standard.
+Creating a gateway module allows you to connect WHMCS to third party payment and credit card processors that aren’t natively supported in WHMCS in a default installation.
-There are 2 core types of gateway module:
+There are 2 core types of gateway modules:
-#'''Third Party Gateways''' – this is where the customer leaves your site to pay and is returned once the payment process is completed
+#'''Third Party Gateways''' – this is where the customer leaves your site to pay and is returned once the payment process is completed.
-#'''Merchant Gateways''' – this is where the customer enters credit card details directly on your website and the payment is then processed in the background (can also include 3D Secure where the user leaves your site)
+#'''Merchant Gateways''' – this is where the customer enters credit card details directly on your website and the payment is then processed in the background (can also include 3D Secure where the user leaves your site).
 {{Developer_Links}}
-So the first decision you need to make before starting your module for WHMCS is which type of gateway module you will be creating.  Once you have that, you're ready to begin.
+The first decision you need to make before starting development of your module for WHMCS is which type of gateway module you will be creating.  Once you have that, you're ready to begin.
@@ Line 25: / Line 25: @@
 <div class="docs-alert-info">
-All functions within a gateway module must be prefixed with the filename.  Open the file and replace all occurrences of '''template_''' with '''yougatewayname_'''
+All functions within a gateway module must be prefixed with the filename.  Open the file and replace all occurrences of '''template_''' with '''yourgatewayname_'''
 </div>
@@ Line 72: / Line 72: @@
 ===Client Variables===
 <source lang="php">
-$params['clientdetails']['firstname'] # Clients First Name
+$params['clientdetails']['firstname'] # Client's First Name
-$params['clientdetails']['lastname'] # Clients Last Name
+$params['clientdetails']['lastname'] # Client's Last Name
-$params['clientdetails']['email'] # Clients Email Address
+$params['clientdetails']['email'] # Client's Email Address
-$params['clientdetails']['address1'] # Clients Address
+$params['clientdetails']['address1'] # Client's Address
 $params['clientdetails']['address2']
 $params['clientdetails']['city']
@@ Line 116: / Line 116: @@
 ===Client Variables===
 <source lang = "php">
-$params['clientdetails']['firstname'] # Clients First Name
+$params['clientdetails']['firstname'] # Client's First Name
-$params['clientdetails']['lastname'] # Clients Last Name
+$params['clientdetails']['lastname'] # Client's Last Name
-$params['clientdetails']['email'] # Clients Email Address
+$params['clientdetails']['email'] # Client's Email Address
-$params['clientdetails']['address1'] # Clients Address
+$params['clientdetails']['address1'] # Client's Address
 $params['clientdetails']['address2']
 $params['clientdetails']['city']

@@ Line 327: / Line 327: @@
 ==App Store==
-WHMCS offers an app store in which completed gateway modules can be submitted.  The listings are displayed under the Addons tab within the administration area and online at http://www.whmcs.com/appstore . This is a great way to make WHMCS users aware of your module.
+WHMCS offers an app store in which completed gateway modules can be submitted.  The listings are displayed under the Addons tab within the administration area and online at http://www.whmcs.com/appstore . This is a great way to make WHMCS users aware of your module!
 In order to submit a listing you'll need a login for whmcs.com/members, if you do not have one please [https://www.whmcs.com/members/submitticket.php?step=2&deptid=5 Contact Us]. Once logged in, visit the app store page at the above URL and click the "Submit your Addon" link. We aim to review submissions in 1-2 weeks.

@@ Line 318: / Line 318: @@
 ==Blank Screen/Errors==
-If you get a blank page or errors in the Setup > Payment Gateways page after uploading your new module file then this indicates there is a syntax error in your code. To debug that, you can add the following line to your WHMCS configuration.php file to turn on error reporting:
+If there is a blank page or error within the ''Setup'' > ''Payment Gateways'' page after uploading the new module file, then there is a syntax error within the new code. To debug that, add the following line to the '''configuration.php''' file to turn on error reporting:
 <source lang="php">
 $display_errors = true;
 </source>
-That will enable PHP error reporting and should show you the cause of any issues. Once you are done testing you must remember to remove that line again.
+This enables PHP error reporting and should show the cause of any issues. Remove this line once testing has completed.
 ==App Store==

@@ Line 310: / Line 310: @@
 ==Installation & Activation==
-To install the module you’ve created, simply upload it to the /modules/gateways/ folder and then go to Setup > Payment Gateways to activate. If you have create a callback file as well then that should also be uploaded but to the /modules/gateways/callback/ folder.
+To install the new module, upload it to the '''/modules/gateways/''' folder and then go to ''Setup'' > ''Payment Gateways'' to activate. If there is a callback file,  then that should be uploaded to the '''/modules/gateways/callback/''' folder.
-'''Important:''' It is important that you do not activate your gateway module until you have
+<div class="docs-alert-warning">
-completed step 1 of either the third party gateway or merchant gateway module
+'''Important:''' It is important that the gateway is not activated until step 1 has been completed for both the third party gateway or the merchant gateway modules, because the type of module created is stored in the database upon activation.
-documentation steps to remove the appropriate functions as it’s at the time of activation
+</div>
 ==Blank Screen/Errors==

@@ Line 270: / Line 270: @@
 ==Tokenised Remote Storage==
-These days, with the increasing rules & requirements surrounding the storing of credit card details, many merchant gateways are offering services where you can perform repeat rebills without needing to store credit card details locally on your own system. And with WHMCS, gateway modules can utilise this functionality when available.
+With the increasing rules & requirements surrounding the storing of credit card details, many merchant gateways are offering services where repeat rebills can be performed without needing to store credit card details locally, on the system.  Gateway modules can utilize this functionality:
-The basic logic behind token gateways in WHMCS is that clients must either have a credit card number or a token stored in order for recurring billing to be attempted. So if you create a function named _storeremote in your custom gateway module, this function will then override the default local storage when new credit card details are entered. And instead of
+The basic logic behind token gateways in WHMCS is that clients must either have a credit card number or a token stored in order for recurring billing to be attempted. So if you create a function named '''_storeremote''' in your custom gateway module, this function will then override the default local storage when new credit card details are entered. And instead of
 saving in the database, that function then needs to communicate with the gateways API, and return the token that gets assigned to WHMCS.
-The variables passed into the _storeremote function are as follows:
+The variables passed into the '''_storeremote''' function are as follows:
 <source lang ="php">
@@ Line 289: / Line 289: @@
 details has been requested.
-Once the card details have been updated or stored remotely, you need to return either a success or failure response to tell WHMCS if it worked, and if it did, the token that has been assigned:
+Once the card details have been updated or stored remotely, return either a success or failure response to tell WHMCS if it worked, and if it did, the token that has been assigned:
 <source lang ="php">
-return array("status"=>"success","gatewayid"=>$results["token"],"rawdata"=>$results);
+return array(
-return array("status"=>"failed","rawdata"=>$results);
+return array(
 </source>
-When this function exists in a gateway module, WHMCS will only store the card type, expiry date and the last 4 digits (only) locally in the WHMCS database. So you and your clients will still be able to see exactly what card is stored remotely from within WHMCS.
+When this function exists in a gateway module, WHMCS will only store the card type, expiry date and the last 4 digits locally in the database. So you and your clients will still be able to see exactly what card is stored remotely from within WHMCS.
 Then within the capture function, instead of $params[‘cardnum’] you will be passed $params[‘gatewayid’] with which to perform the capture.

@@ Line 226: / Line 226: @@
 == 3D Secure Process ==
-If your merchant gateway supports 3D Secure (also known as Verified by Visa or MasterCard Secure Code) and you want to implement that then you can as WHMCS fully supports 3D Secured payments.
+If the merchant gateway supports 3D Secure (also known as ''Verified by Visa'' or ''MasterCard Secure Code''), then it can be utilized within WHMCS.
-To do this you need to add a function to your module named yourgatewayname_3dsecure and then similar to the _link function of a third party gateway module, you need to return the HTML for the form post to take the user to the 3D Secure process. An example of this is below.
+# Add a function to the module named '''yourgatewayname_3dsecure'''
-The _3dsecure function is passed all the same variables that the _capture function is (see page 6). Your return url should be a callback file to handle the response (see page 9)
+An example of this is below:
 ==Example==

@@ Line 188: / Line 188: @@
 ==Callbacks==
-If your gateway provider supports notifying a script when a payment is successful, then you can create a callback file in WHMCS to detect and apply those calls as payments inside WHMCS.
+If the gateway provider supports notifying a script when a payment is successful, then a callback file can be created to detect and apply those calls as payments inside WHMCS.
-A sample callback file is included in the dev kit for this purpose named “callback.php”. To utilise this script, you simply need to rename it to match your gateway module, and modify the variables within it as per the comments in the code, and to match the variables your specific gateway returns.
+A sample callback file is included in the dev kit for this purpose named '''callback.php''':
-These are some helper functions within the sample that you might find useful:
+# Rename it to match the gateway module.
 <source lang="php">
@@ Line 198: / Line 202: @@
 </source>
-This function can be used to retrieve the configuration data for your module as specified in
+This function can be used to retrieve the configuration data for the module as specified in
-the _config array. For example you might need it to get a gateway username or secret key to
+the '''_config''' array. For example, it might be needed to get a gateway username or secret key to
 validate a callback.
 <source lang="php">
-$invoiceid = checkCbInvoiceID($invoiceid,$GATEWAY[‘name’]);
+$invoiceid = checkCbInvoiceID($invoiceid, $GATEWAY[‘name’]);
 </source>
-This function can be used to check the invoice ID received back is valid. You should simply pass the $invoiceid into this function and your gateway name and if a valid invoice number the script will continue executing, otherwise the script will be halted and an appropriate gateway log entry created.
+This function can be used to check that the invoice ID received back is valid. Pass the $invoiceid and the gateway name into the function.  If the invoice number is valid, the script will continue executing.  Otherwise, the script will be halted and an appropriate gateway log entry will be created.
 <source lang ="php">
@@ Line 212: / Line 216: @@
 </source>
-This function can be used to check for any existing transactions already recorded for a given transaction ID. This can be useful for protecting against duplicate callbacks as if the transaction ID is already found in the database, the callback script execution will be halted.
+This function can be used to check for any existing transactions already recorded for a given transaction ID, which protects against duplicate callbacks.  If the transaction ID is already in the database, the callback script execution will be halted.
 <source lang="php">
-logTransaction($GATEWAY[‘name’],$_POST,"Successful");
+logTransaction($GATEWAY[‘name’], $_POST, "Successful");
 </source>
-This function can be used to create a gateway log entry. The first variable needs to be the name of the gateway module, the second should be an array of data, such as the $_POST or $_REQUEST super globals, and the last variable should be the result/status to show in the log.
+This function can be used to create a gateway log entry. The first variable needs to be the name of the gateway module, the second should be an array of data, such as the '''$_POST''' or '''$_REQUEST''' super globals, and the last variable should be the result or status to show in the log.
 == 3D Secure Process ==

@@ Line 171: / Line 171: @@
 # The rawdata index should be passed an array of the data returned from the gateway to be stored in the WHMCS Gateway Log for debugging purposes.
-# If the gateway supports 3D Secure (Verified by Visa or MasterCard Secure Code) then please refer to page 8.
+If the gateway supports 3D Secure (Verified by Visa or MasterCard Secure Code) then please refer to page 8.
 ===Refunds===