Revision as of 20:18, 6 January 2016

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

Gateway modules allow a connection between WHMCS and gateways or credit card processors that aren't natively supported in WHMCS.

This documentation will explain the module's structure and contains everything needed in order to successfully create a gateway module for WHMCS.

Getting Started

To get started, begin by downloading the module development kit from our GitHub site. There are two sample modules available, depending upon the type of gateway being developed:

• Third Party Gateway: https://github.com/WHMCS/sample-gateway-module
• Merchant Gateway: https://github.com/WHMCS/sample-merchant-gateway

Take the gateway module template "template.php" from this download and rename it to "yourgatewayname.php". It should be all lowercase and must start with a letter.

Config Array

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 that the gateway module requires.

The available field types are "text", "dropdown", "textarea" and "yesno" (checkboxes). The sample config array in "template.php" demonstrates how to use each of these types.

The general formula:

1. Specify a system name (all in lowercase for the setting to be referenced by in the module code itself)
2. A FriendlyName
3. Type
4. Any settings specific to that field type.

Any fields defined here will be available in all gateway module functions in the $params array, so avoid common names like currency, invoiceid, etc, as these will conflict with the standard variables.

Module Type

Determine which type of module needs to be created from the 2 core types:

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

For a Third Party gateway go to #Third_Party_Gateway, and for a merchant gateway go to #Merchant_Gateway.

Third Party Gateway

Follow the steps below to create a third party gateway module (one where the customer leaves your site to make the payment on the gateway provider's website):

1. Delete the _capture function from the module template.
2. Enter the gateway-specific code for taking the user to the payment process within the _link function. An example of this step is shown in the gateway module template supplied with the dev kit. Normally, the code output by this function is the HTML for a <form> with a post method.

The available variables 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 information).
2. If your gateway provider doesn't support automated refunds or you won't be including them in the module, then delete the _refund function. Otherwise, refer to the Refund section on page 7.

Merchant Gateway

A merchant gateway module is a module where the customer enters their card details directly via the client area, without leaving the site. To create one:

1. Delete the _link function from the module template.
2. Enter the gateway-specific code for processing the payment into the _capture function. This normally takes the format of an HTTP/Curl request to the gateway provider's API.

The variables available 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)
# but would always be present for client initiated attempts

1. Once the transaction has been processed and a response has been received, an array with the results needs to be returned to WHMCS. For a successful capture, use the following format:

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

1. The status index must be success to tell WHMCS that the capture was successful.
2. The transid index should be passed the value of the transaction ID that came back from the gateway.
3. The rawdata index 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, use the following format:

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

1. The status index can be any value (declined, error, invalid hash, etc). This value is displayed as the reason for failure, in the gateway log.
2. 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.

1. If the gateway supports 3D Secure (Verified by Visa or MasterCard Secure Code) then please refer to page 8.

Refunds

1. If the gateway provider supports automated refunds, then code for processing a refund goes into the _refund function. This is passed all of the same variables as the _capture function, but with an added transaction id:

$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.

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.

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.

In order to submit a listing you'll need a login for whmcs.com/members, if you do not have one please 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.