Gateway Module Developer Docs

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:

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)

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.

Getting Started

To get started, begin by taking 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:

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)

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 us one where the customer leaves your site to make payment on the gateway providers website, simply follow the steps below.

Begin by deleting the _capture function from the module template (important: you must do this before activating your new module in WHMCS)
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['invoiceif'] - 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['clientsdetails']['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

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