Revision as of 20:03, 15 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 in a default installation.

There are 2 core types of gateway modules:

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

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.

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'] # Client's First Name
$params['clientdetails']['lastname'] # Client's Last Name
$params['clientdetails']['email'] # Client's Email Address
$params['clientdetails']['address1'] # Client's 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'] # Client's First Name
$params['clientdetails']['lastname'] # Client's Last Name
$params['clientdetails']['email'] # Client's Email Address
$params['clientdetails']['address1'] # Client's 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.

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 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:

1. Rename it to match the gateway module.
2. Modify the variables within it, as per the comments in the code.
3. Modify it to match the variables that the specific gateway returns.

These are some helper functions within the sample:

$GATEWAY = getGatewayVariables(‘yourgatewayname’);

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

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

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.

checkCbTransID($transid);

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.

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 or status to show in the log.

3D Secure Process

If the merchant gateway supports 3D Secure (also known as Verified by Visa or MasterCard Secure Code), then it can be utilized within WHMCS.

1. Add a function to the module named yourgatewayname_3dsecure
2. Return the HTML for the <form> post method 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). The 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

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

Installation & Activation

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.

Blank Screen/Errors

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:

$display_errors = true;

This enables PHP error reporting and should show the cause of any issues. Remove this line once testing has completed.

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.