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:

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)

Developer Resources
Provisioning Module Docs] | Gateway Module Docs] | Registrar Module Docs] | Addon Modules
Template Syntax | Database Interactions | Addon Modules | Creating Pages | Action Hooks] | API

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:

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 us 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['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

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

Being Updated for Version 5

Please check back soon...