Revision as of 08:32, 17 October 2013

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.

There are 2 core types of gateway module:

1. Third Party Gateways – this is where the customer leaves your site to pay and is returned once the payment process is completed
2. 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)

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.

Introduction

Creating a gateway module allows you to connect WHMCS to gateways and credit card processors that aren’t natively supported in WHMCS.

We have made the gateway module structure as simple and straightforward as possible and this documentation should explain everything you need in order to successfully create your new module.

If you have any feedback on the documentation then please do let us know.

Getting Started

To get started, begin by downloading the module development kit from http://www.whmcs.com/members/dl.php?type=d&id=15 . Take the gateway module template "template.php" from this download and rename to "yourgatewayname.php". it should be all lowercase and must start with a letter.

All functions within a gateway module must be prefixed with the filename also so once you've chosen a name, open the file and replace all occurrences of "template_" with "yourgatewayname_

Config Array

Next you can configure the yourgatewayname_config array. This function is the primary function required by all gateway modules and defines both the friendly display name for the module and any custom fields/options/settings your gateway module requires.

The available field types are "text", "dropdown", "textarea" and "yesno" (checkboxes) the same as with all modules in WHMCS and the sample config array in "template.php" demonstrates how to use each of these types. The general format is that you specify a system name, all in lowercase for the setting to be referenced by in the module code itself, and then a FriendlyName, Type, and any settings specific to that field type.

Any fields you define here will be available in all gateway module's functions in the $params array so you should avoid common names like currency, invoiceid, etc... that will conflict with the standard variables.

Module Type

Now you need to determine what type of module you are creating. There are 2 core types of gateway module:

1. Third Party Gateways – this is where the customer leaves your site to pay and is returned once the payment process is completed
2. 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)

Once you know the of module you are creating then you can proceed. For a Third Party gateway go to page 5, and for a merchant gateway go to page 5, and for a merchant gateway go to page 6.

Third Party Gateway

To create a third party gateway module, which is one where the customer leaves your site to make payment on the gateway providers website, simply follow the steps below.

1. Begin by deleting the _capture function from the module template (important: you must do this before activating your new module in WHMCS)
2. Next, enter your gateway specific code for taking the user to the payment process in the _link function - an example for how to do this is shown in the gateway module template supplied with this dev kit. This should normally take the format of a form post and you simply need to return the HTML code for the form from this function.

The variables available to you are:

Invoice Variables

$params['invoiceid'] # Invoice ID Number
$params['description'] # Description (eg. Company Name - Invoice #xxx)
$params['amount'] # Format: xxx.xx
$params['currency'] # Currency Code (eg. GBD, USD, etc...)

Client Variables

$params['clientdetails']['firstname'] # Clients First Name
$params['clientdetails']['lastname'] # Clients Last Name
$params['clientdetails']['email'] # Clients Email Address
$params['clientdetails']['address1'] # Clients Address
$params['clientdetails']['address2'] 
$params['clientdetails']['city']
$params['clientdetails']['state']
$params['clientdetails']['postcode']
$params['clientdetails']['country']
$params['clientdetails']['phonenumber']

#System Variables

$params['companyname'] # your Company Name setting in WHMCS
$params['systemurl'] # the url to the Client Area

1. The processing of a payment is handled by a callback file separate from the module (see page 9 for more info on that).
2. If your gateway provider dosen't support automated refunds or you won't be including them in the module then you should delete the _refund function as well, otherwise refer to the Refund section on page 7.

Merchant Gateway

To create a merchant gateway module, where the customer enters their card details directly via the client area without leaving the site, simply follow the steps below.

1. Begin by deleting the _link function from the module template (important: you must do this before activating your new gateway module in WHMCS)
2. Next, enter your gateway specific code for processing the payment into the _capture function. This normally takes the format of an HTTP/Curl request to the gateway providers API.

The variables available to you are:

Invoice Variables

$params['invoiceid'] # Invoice ID Number
$params['description'] # Description (eg. Company Name - Invoice #xxx)
$params['amount'] # Format: xxx.xx
$params['currency'] # Currency Code (eg. GBP, USD, etc...)

Client Variables

$params['clientdetails']['firstname'] # Clients First Name
$params['clientdetails']['lastname'] # Clients Last Name
$params['clientdetails']['email'] # Clients Email Address
$params['clientdetails']['address1'] # Clients Address
$params['clientdetails']['address2']
$params['clientdetails']['city']
$params['clientdetails']['state']
$params['clientdetails']['postcode']
$params['clientdetails']['country']
$params['clientdetails']['phonenumber']

# System Variables

$params['companyname'] # your Company Name setting in WHMCS
$params['systemurl'] – the url to the Client Area

Card Details

$params['cardtype'] # the Card Type (Visa, MasterCard, etc…)
$params['cardnum'] # the Card Number
$params['cardexp'] # the Card’s Expiry Date (Format: MMYY)
$params['cardstart'] # the Card’s Start Date (Format: MMYY)
$params['cardissuenum'] # the Card’s Issue Number (Switch/Solo Cards)
$params['cccvv'] #Not always present (recurring transactions) <br />but would always be present for client initiated attempts

1. Once you have processed the transaction and got a response, you need to return an array to WHMCS with the results. The return for a successful capture should be as follows:

return array("status"=>"success","transid"=>$results["transid"],"rawdata"=>$results);

Within this array, the status must be success to tell WHMCS the capture was successful, transid should be passed the value of the transaction ID that came back from the gateway, and the rawdata variable should be passed an array of the data returned from the gateway to be stored in the WHMCS Gateway Log.

If the transaction were to fail then the response should instead be as follows:

return array("status"=>"declined","rawdata"=>$results);

In this response, the status can be any value you want, declined, error, invalid hash, etc… and will be what staff get to see as the failure reason within the gateway log. The rawdata variable should again be passed an array of the data returned from the gateway to be stored in the WHMCS Gateway Log for debugging purposes.

1. If your gateway supports 3D Secure (Verified by Visa or MasterCard Secure Code) then please refer to page 8 for information on how to do handle that.

Refunds

1. If your gateway provider supports automated refunds then you should add your code for processing a refund into the _refund function which is passed all the same variables as capture but with one additional variable:

$params['transid'] # the transaction ID of the original transaction to be refunded

The return arrays for a success or failure should be done exactly the same as described above for the capture function.

If your gateway provider does not support refunds, then the _refund function should be deleted from the module file.

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.

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.

These are some helper functions within the sample that you might find useful:

$GATEWAY = getGatewayVariables(‘yourgatewayname’);

This function can be used to retrieve the configuration data for your module as specified in the _config array. For example you might need it to get a gateway username or secret key to validate a callback.

$invoiceid = checkCbInvoiceID($invoiceid,$GATEWAY[‘name’]);

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.

checkCbTransID($transid);

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.

logTransaction($GATEWAY[‘name’],$_POST,"Successful");

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.

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.

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.

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)

Example

function yourgatewayname_3dsecure($params) {
$code = '<form method="post" action="https://www.gateway.com/3dsecure/">
<input type="hidden" name="gwlogin" value="'.$params["loginid"].'">
<input type="hidden" name="invoiceid" value="'.$params["invoiceid"].'">
<input type="hidden" name="amount" value="'. $params["amount"].'">
<input type="hidden" name="firstname" value="'. $params["clientdetails"]["firstname"].'">
<input type="hidden" name="lastname" value="'. $params["clientdetails"]["lastname"].'">
<input type="hidden" name="address" value="'. $params["clientdetails"]["address1"].'">
<input type="hidden" name="city" value="'. $params["clientdetails"]["city"].'">
<input type="hidden" name="state" value="'. $params["clientdetails"]["state"].'">
<input type="hidden" name="postcode" value="'. $params["clientdetails"]["postcode"].'">
<input type="hidden" name="country" value="'. $params["clientdetails"]["country"].'">
<input type="hidden" name="phonenumber" value="'. $params["clientdetails"]["phonenumber"].'">
<input type="hidden" name="email" value="'. $params["clientdetails"]["email"].'">
<input type="hidden" name="ccnumber" value="'. $params["cardnum"].'">
<input type="hidden" name="expirymonth" value="'.substr($params['cardexp'],0,2).'">
<input type="hidden" name="expiryyear" value="'.substr($params['cardexp'],2,2).'">
<input type="hidden" name="cvv2" value="'. $params["cccvv"].'">
<input type="hidden" name="return_url" value="'.
$params['systemurl'].'/modules/gateways/callback/yourgatewayname.php">
<noscript>
<div class="errorbox"><b>JavaScript is currently disabled or is not supported by your
browser.</b><br />Please click the continue button to proceed with the processing of your
transaction.</div>
<p align="center"><input type="submit" value="Continue >>" /></p>
</noscript>
</form>';
      return $code;
}

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.

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:

$params['gatewayid'] # the token stored for the client
$params['cardtype'] #the Card Type (Visa, MasterCard, etc…)
$params['cardnum'] # the Card Number
$params['cardexp'] # the Card’s Expiry Date (Format: MMYY)
$params['cardstart'] # the Card’s Start Date (Format: MMYY)
$params['cardissuenum'] # the Card’s Issue Number (Switch/Solo Cards)

On the first call, the gatewayid will be empty. So when empty you need to create a new profile at the gateway. On subsequent calls the gatewayid that was originally created and stored will be passed in and the existing profile simply needs to be updated. And if the cardnum variable is empty, this indicates that deleting/removal of the stored credit card 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:

return array("status"=>"success","gatewayid"=>$results["token"],"rawdata"=>$results);

return array("status"=>"failed","rawdata"=>$results);

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.

Then within the capture function, instead of $params[‘cardnum’] you will be passed $params[‘gatewayid’] with which to perform the capture.

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.

Important: It is important that you do not activate your gateway module until you have completed step 1 of either the third party gateway or merchant gateway module documentation steps to remove the appropriate functions as it’s at the time of activation that the type of module you are setting up gets stored in the system.

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:

$display_errors = true;

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.

Being Updated for Version 5

Please check back soon...