WHMCS Documentation - User contributions [en]

Client Area Template Files

2016-08-09T14:12:32Z

Nicolas: /* Using GitHub */

=Intro=
WHMCS always endeavours to make the system as customisable as possible so that users can always tailor it to their exact needs. With that in mind, all pages of the WHMCS client area use templates. This allows a user to add/remove and change the look and feel of everything. In WHMCS, use of the powerful [[Template Syntax|Smarty template system]] allows you to:

*Customise the layout and content of the client area fully.
*Make use of file includes for common elements shared between pages.
*Make use of many other powerful features Smarty has to offer.

Most pages use three templates that combine to make up the output. These combine in this order:

#'''Header Template (header.tpl)'''
#'''Main Content Template (homepage.tpl, clientareahome.tpl, etc...)'''
#'''Footer Template (footer.tpl)'''

The header and footer are common to every page displayed as a wrapper around the content. Within the template folders you will see many other template files. These take the place of 'The Page Template' above. These templates define the output on each page. The templates are also named so that you can identify which relates to which page. For example, the template that defines the WHMCS homepage at (yoursite.com/whmcs/) is homepage.tpl. The main client area page is clientareahome.tpl and so on.

'''Before starting''', please refer to the '''[[Template Syntax]]''' section of the docs. This provides information on how to work with the templates in WHMCS.

==Creating a Custom Template==

When customising any WHMCS templates, the first step is to create another template folder. The default templates should never be edited directly. To do this, perform the following steps:

#Duplicate one of the standard folders in the templates folder (six, five) and rename it to a custom name.
#The directory name should be all one word and consist of just lowercase letters and numbers.
#Now make your customisations and changes as desired. See section below for more details on this.
#Once complete, upload the new templates folder to the templates directory of WHMCS.
#Preview the new template by specifying it using an URL "on the fly". For example, www.yourdomain.com/whmcs/?systpl=xxxxx where xxxxx is the name of the new template. See [[Linking to WHMCS]] for more information.
#Once happy with it, set it live by going to '''Setup > General Settings'''. On the first tab, choose the new custom template name from the Template's dropdown menu.

The template selected here will be referred to throughout the documentation as the active template folder. Likewise, the order form template selected in Setup > General Settings > Ordering.

==Customising to Match Your Website==

What most people want to do with customisation is integrate WHMCS to match the rest of their website. This can be a daunting task but it is fairly straightforward. Following on from the above, begin by copying the HTML which controls the top of your website design. Paste this into the header.tpl file of your custom template folder. Make sure to preserve the <head> section of code in the default WHMCS template. This contains the necessary CSS, Javascript Code & File Includes for WHMCS to function. Then copy and paste the footer code from your website design into footer.tpl.

[[File:Videotutorial.png‎|center|link=https://www.youtube.com/watch?v=9VkbPoVTHYg&hd=1|Watch Video Tutorial]]

===Customising how payment gateways are displayed===
There may be occasion where it's desirable to customise the way payment gateways display. For example, you may wish to add formatting, display images such as card logos, or any other code of your own.

Due to security considerations, it isn't possible to enter HTML into the display name or payment instruction fields. Instead, you can customise the relevant template to display your desired code.

For example, to display credit card logos when the PayPal is the payment method on the printable invoice, use the following code. This will be in /templates/*your active template*/'''viewinvoice.tpl''':

<source lang="php">
{if $paymentmodule eq 'paypal'}
<img src="/images/creditcardlogos.png">
{/if}
</source>

The image tag could be replaced with any code you wanted to display there. Replace 'paypal' with the name of your payment module. The exact value can be obtained from the tblpaymentgateways table.

==Customising the Six theme==

Six is the name of the default client area template that ships with WHMCS 6.0 and later. With this template we have introduced a number of new resources that you can use to further customise your WHMCS installation. Two of these new features are briefly addressed below and detailed information on how to customise the Six theme can be found in the [[Customising the Six Theme]] documentation.

===Navigation and Sidebar Customisation===

In the Six theme the look and feel of the navigation bar and sidebar elements can customised via the header.tpl and sidebar.tpl (located in /includes/) template files.

To make changes to the layout of the menus (i.e. adding, removing, and modifying items) please refer to the [[Editing Client Area Menus|Editing Client Area Menus]] documentation.

===Using GitHub===

The Six theme is made available via GitHub and provides version-by-version changes of the “Six” template as published in WHMCS. The WHMCS "Six" template repository can be found at [[https://github.com/WHMCS/templates-six]].

Interacting With The Database

2016-07-11T18:07:15Z

Nicolas: /* External Links */

=Database connectivity changes in WHMCS 6.0=

The mysql PHP extension was deprecated when PHP 5.5 was released in June 2013<ref>http://php.net/ChangeLog-5.php#5.5.0</ref> and is scheduled to be removed in PHP 7<ref>https://wiki.php.net/rfc/remove_deprecated_functionality_in_php7</ref>. WHMCS 6.0 introduces a new database connection and library to ensure compatibility with modern PHP environments and best practices.

==New functionality==

WHMCS 6.0 incorporates the Laravel framework 4.1's database component (''WHMCS 7.0 incorporates 5.2''). This library includes a Database Abstraction Layer (DBAL) called "Capsule" and an Object Relational Mapping (ORM) library called "Eloquent". The new DBAL is based on the PHP Data Objects (PDO MySQL) extension and uses WHMCS's existing <tt>configuration.php</tt> file. No configuration file changes are required to use the new database connection.

The Capsule DBAL component introduces two libraries to WHMCS, a query manager for running database queries and a schema manager for an abstracted API to table management. Capsule's underlying PDO connection is also available for advanced database usage. Capsule has three static methods to get to these components:

* '''Capsule::table(string $tableName)''': Access the query manager for the given table.
* '''Capsule::schema()''': Access the schema manager for the WHMCS database.
* '''Capsule::connection()''': Access the connection manager to interact with the underlying database connection.

'''Note:''' WHMCS 6.0 makes two connections to the database. One connection is made through the legacy mysql extension to handle existing hooks, modules, and other customizations. The other connection is made by PDO to drive new DBAL and model based functionality in the program.

==Deprecated functionality==

The current [[SQL Helper Functions]] are present in WHMCS 6.0 and above, but are now deprecated and may be removed in a later version of the product:
* '''select_query()'''
* '''update_query()'''
* '''insert_query()'''
* '''full_query()'''

The mysql extension driven database connection is now deprecated and may be discontinued in a later version of the product. WHMCS encourages all third party developers to use the Capsule DBAL and PDO connection for all new database interaction.

'''Note:''' WHMCS 7.0 incorporates the Laravel framework's 5.2 database component, which deprecates as well as removes many features present in 4.1 Please see the upgrade guide for more information:
* [https://laravel.com/docs/5.2/upgrade- Laravel 5.2 Upgrade Guide]

=Using Capsule=

Declare an alias to Laravel's database manager in your project file's <tt>use</tt> block to access Capsule:

<syntaxhighlight lang="php">
<?php

use Illuminate\Database\Capsule\Manager as Capsule;

// Run queries or modify tables as you like.
</syntaxhighlight>

==The Query Manager==

: ''Please see [https://laravel.com/docs/5.2/queries Laravel's query documentation] for more information.''

The '''Capsule::table(string $tableName)''' method provides access to the query manager. Declare it with the name of the table you wish to query as it's first parameter to interact with that table. The query manager has a wide range of functionality to perform advanced select, join, insert, update, and delete statements. Capsule's select calls return rows as ''stdClass'' objects.

Capsule escapes all input, so it is not necessary to add escaping slashes to variables passed to these methods.

All of Capsule's methods throw an exception on failure. Please place Capusle calls in <tt>try</tt>/<tt>catch</tt> blocks for graceful error handling and to avoid potential fatal errors in your hook, module, or other customization.

<syntaxhighlight lang="php">
<?php

use Illuminate\Database\Capsule\Manager as Capsule;

// Print all client first names using a simple select.

/** @var stdClass $client */
foreach (Capsule::table('tblclients')->get() as $client) {
echo $client->firstname . PHP_EOL;
}

// Rename all clients named "John Deo" to "John Doe" using an update statement.
try {
$updatedUserCount = Capsule::table('tblclients')
->where('firstname', 'John')
->where('lastname', 'Deo')
->update(
[
'lastname' => 'Doe',
]
);

echo "Fixed {$updatedUserCount} misspelled last names.";
} catch (\Exception $e) {
echo "I couldn't update client names. {$e->getMessage()}";
}
</syntaxhighlight>

==The Schema Manager==

Use the '''Capsule::schema()''' method to access the schema manager to modify table schema if necessary. The schema manager has support for creating, dropping and truncating tables and for modifying columns, indexes, and keys.

'''Note''': WHMCS does not recommend changing default table schema as that can affect product functionality.

<syntaxhighlight lang="php">
<?php

use Illuminate\Database\Capsule\Manager as Capsule;

// Create a new table.
try {
Capsule::schema()->create(
'my_table',
function ($table) {
/** @var \Illuminate\Database\Schema\Blueprint $table */
$table->increments('id');
$table->string('name');
$table->integer('serial_number');
$table->boolean('is_required');
$table->timestamps();
}
);
} catch (\Exception $e) {
echo "Unable to create my_table: {$e->getMessage()}";
}
</syntaxhighlight>

==The Connection Manager==

The '''Capsule::connection()''' method provides low-level access to the database connection itself. Use it to initiate transactions with automatic commit and rollback or to access the underlying PDO connection to perform manual database queries outside the DBAL. The connection manager also has methods to retrieve query and schema managers.

<syntaxhighlight lang="php">
<?php

use Illuminate\Database\Capsule\Manager as Capsule;

// Perform potentially risky queries in a transaction for easy rollback.
try {
Capsule::connection()->transaction(
function ($connectionManager)
{
/** @var \Illuminate\Database\Connection $connectionManager */
$connectionManager->table('my_table')->insert(
[
'name' => $_POST['name'],
'serial_number' => $_POST['serialNumber'],
'is_required' => (int)(bool) $_POST['isRequired'],
]
);
}
);
} catch (\Exception $e) {
echo "Uh oh! Inserting didn't work, but I was able to rollback. {$e->getMessage()}";
}
</syntaxhighlight>

===Getting to PDO===

Use the connection manager's '''getPdo()''' method to retrieve the underlying PDO connection instance. Use the PDO connection to perform manual queries and advanced database usage.

<syntaxhighlight lang="php">
<?php

use Illuminate\Database\Capsule\Manager as Capsule;

// Perform potentially risky queries in a transaction for easy rollback.
$pdo = Capsule::connection()->getPdo();
$pdo->beginTransaction();

try {
$statement = $pdo->prepare(
'insert into my_table (name, serial_number, is_required) values (:name, :serialNumber, :isRequired)'
);

$statement->execute(
[
':name' => $_POST['name'],
':serialNumber' => $_POST['serialNumber'],
':isRequired' => (bool) $_POST['isRequired'],
]
);

$pdo->commit();
} catch (\Exception $e) {
echo "Uh oh! {$e->getMessage()}";
$pdo->rollBack();
}
</syntaxhighlight>

=Troubleshooting=

==Exceptions==

All Capsule methods throw an exception on failure. Catch these exceptions and analyze their messages and stack traces to help determine the nature of the failure. WHMCS recommends placing all database interactivity in <tt>try</tt>/<tt>catch</tt> blocks for graceful error handling.

==The Capsule Query Log==

The connection manager's '''getQueryLog()''' method returns an array of all queries made during the life of the page request. Queries are stored in the log as an array containing the query run, the parameter bindings passed to the query, and the time it took for the query to execute, measured in milliseconds.

<syntaxhighlight lang="php">
<?php

use Illuminate\Database\Capsule\Manager as Capsule;

// Loop through each Capsule query made during the page request.
foreach (Capsule::connection()->getQueryLog() as $query) {
echo "Query: {$query['query']}" . PHP_EOL;
echo "Execution Time: {$query['time']}ms" . PHP_EOL;
echo "Parameters: " . PHP_EOL;

foreach ($query['bindings'] as $key => $value) {
echo "{$key} => {$value}" . PHP_EOL;
}
}
</syntaxhighlight>

==The WHMCS Activity Log==

All uncaught PDO-based query failures, including those made by Capsule and manual PDO queries, are written to to the WHMCS activity log. View the system activity log to view the details of these failed queries.

=See Also=
* [[SQL Helper Functions]] (functional, but deprecated in WHMCS 6.0)

=External Links=
* [http://laravel.com/docs/4.2/queries Query Builder - Laravel 4.2]
* [http://laravel.com/docs/5.2/queries Query Builder - Laravel 5.2]
* [http://laravel.com/docs/4.2/schema Schema Builder - Laravel 4.2]
* [https://laravel.com/docs/5.0/schema Schema Builder - Laravel 5.0]
* [http://php.net/manual/en/book.pdo.php PHP: PDO]

=References=
<references />

Interacting With The Database

2016-07-11T18:06:54Z

Nicolas: /* External Links */

=Database connectivity changes in WHMCS 6.0=

The mysql PHP extension was deprecated when PHP 5.5 was released in June 2013<ref>http://php.net/ChangeLog-5.php#5.5.0</ref> and is scheduled to be removed in PHP 7<ref>https://wiki.php.net/rfc/remove_deprecated_functionality_in_php7</ref>. WHMCS 6.0 introduces a new database connection and library to ensure compatibility with modern PHP environments and best practices.

==New functionality==

WHMCS 6.0 incorporates the Laravel framework 4.1's database component (''WHMCS 7.0 incorporates 5.2''). This library includes a Database Abstraction Layer (DBAL) called "Capsule" and an Object Relational Mapping (ORM) library called "Eloquent". The new DBAL is based on the PHP Data Objects (PDO MySQL) extension and uses WHMCS's existing <tt>configuration.php</tt> file. No configuration file changes are required to use the new database connection.

The Capsule DBAL component introduces two libraries to WHMCS, a query manager for running database queries and a schema manager for an abstracted API to table management. Capsule's underlying PDO connection is also available for advanced database usage. Capsule has three static methods to get to these components:

* '''Capsule::table(string $tableName)''': Access the query manager for the given table.
* '''Capsule::schema()''': Access the schema manager for the WHMCS database.
* '''Capsule::connection()''': Access the connection manager to interact with the underlying database connection.

'''Note:''' WHMCS 6.0 makes two connections to the database. One connection is made through the legacy mysql extension to handle existing hooks, modules, and other customizations. The other connection is made by PDO to drive new DBAL and model based functionality in the program.

==Deprecated functionality==

The current [[SQL Helper Functions]] are present in WHMCS 6.0 and above, but are now deprecated and may be removed in a later version of the product:
* '''select_query()'''
* '''update_query()'''
* '''insert_query()'''
* '''full_query()'''

The mysql extension driven database connection is now deprecated and may be discontinued in a later version of the product. WHMCS encourages all third party developers to use the Capsule DBAL and PDO connection for all new database interaction.

'''Note:''' WHMCS 7.0 incorporates the Laravel framework's 5.2 database component, which deprecates as well as removes many features present in 4.1 Please see the upgrade guide for more information:
* [https://laravel.com/docs/5.2/upgrade- Laravel 5.2 Upgrade Guide]

=Using Capsule=

Declare an alias to Laravel's database manager in your project file's <tt>use</tt> block to access Capsule:

<syntaxhighlight lang="php">
<?php

use Illuminate\Database\Capsule\Manager as Capsule;

// Run queries or modify tables as you like.
</syntaxhighlight>

==The Query Manager==

: ''Please see [https://laravel.com/docs/5.2/queries Laravel's query documentation] for more information.''

The '''Capsule::table(string $tableName)''' method provides access to the query manager. Declare it with the name of the table you wish to query as it's first parameter to interact with that table. The query manager has a wide range of functionality to perform advanced select, join, insert, update, and delete statements. Capsule's select calls return rows as ''stdClass'' objects.

Capsule escapes all input, so it is not necessary to add escaping slashes to variables passed to these methods.

All of Capsule's methods throw an exception on failure. Please place Capusle calls in <tt>try</tt>/<tt>catch</tt> blocks for graceful error handling and to avoid potential fatal errors in your hook, module, or other customization.

<syntaxhighlight lang="php">
<?php

use Illuminate\Database\Capsule\Manager as Capsule;

// Print all client first names using a simple select.

/** @var stdClass $client */
foreach (Capsule::table('tblclients')->get() as $client) {
echo $client->firstname . PHP_EOL;
}

// Rename all clients named "John Deo" to "John Doe" using an update statement.
try {
$updatedUserCount = Capsule::table('tblclients')
->where('firstname', 'John')
->where('lastname', 'Deo')
->update(
[
'lastname' => 'Doe',
]
);

echo "Fixed {$updatedUserCount} misspelled last names.";
} catch (\Exception $e) {
echo "I couldn't update client names. {$e->getMessage()}";
}
</syntaxhighlight>

==The Schema Manager==

Use the '''Capsule::schema()''' method to access the schema manager to modify table schema if necessary. The schema manager has support for creating, dropping and truncating tables and for modifying columns, indexes, and keys.

'''Note''': WHMCS does not recommend changing default table schema as that can affect product functionality.

<syntaxhighlight lang="php">
<?php

use Illuminate\Database\Capsule\Manager as Capsule;

// Create a new table.
try {
Capsule::schema()->create(
'my_table',
function ($table) {
/** @var \Illuminate\Database\Schema\Blueprint $table */
$table->increments('id');
$table->string('name');
$table->integer('serial_number');
$table->boolean('is_required');
$table->timestamps();
}
);
} catch (\Exception $e) {
echo "Unable to create my_table: {$e->getMessage()}";
}
</syntaxhighlight>

==The Connection Manager==

The '''Capsule::connection()''' method provides low-level access to the database connection itself. Use it to initiate transactions with automatic commit and rollback or to access the underlying PDO connection to perform manual database queries outside the DBAL. The connection manager also has methods to retrieve query and schema managers.

<syntaxhighlight lang="php">
<?php

use Illuminate\Database\Capsule\Manager as Capsule;

// Perform potentially risky queries in a transaction for easy rollback.
try {
Capsule::connection()->transaction(
function ($connectionManager)
{
/** @var \Illuminate\Database\Connection $connectionManager */
$connectionManager->table('my_table')->insert(
[
'name' => $_POST['name'],
'serial_number' => $_POST['serialNumber'],
'is_required' => (int)(bool) $_POST['isRequired'],
]
);
}
);
} catch (\Exception $e) {
echo "Uh oh! Inserting didn't work, but I was able to rollback. {$e->getMessage()}";
}
</syntaxhighlight>

===Getting to PDO===

Use the connection manager's '''getPdo()''' method to retrieve the underlying PDO connection instance. Use the PDO connection to perform manual queries and advanced database usage.

<syntaxhighlight lang="php">
<?php

use Illuminate\Database\Capsule\Manager as Capsule;

// Perform potentially risky queries in a transaction for easy rollback.
$pdo = Capsule::connection()->getPdo();
$pdo->beginTransaction();

try {
$statement = $pdo->prepare(
'insert into my_table (name, serial_number, is_required) values (:name, :serialNumber, :isRequired)'
);

$statement->execute(
[
':name' => $_POST['name'],
':serialNumber' => $_POST['serialNumber'],
':isRequired' => (bool) $_POST['isRequired'],
]
);

$pdo->commit();
} catch (\Exception $e) {
echo "Uh oh! {$e->getMessage()}";
$pdo->rollBack();
}
</syntaxhighlight>

=Troubleshooting=

==Exceptions==

All Capsule methods throw an exception on failure. Catch these exceptions and analyze their messages and stack traces to help determine the nature of the failure. WHMCS recommends placing all database interactivity in <tt>try</tt>/<tt>catch</tt> blocks for graceful error handling.

==The Capsule Query Log==

The connection manager's '''getQueryLog()''' method returns an array of all queries made during the life of the page request. Queries are stored in the log as an array containing the query run, the parameter bindings passed to the query, and the time it took for the query to execute, measured in milliseconds.

<syntaxhighlight lang="php">
<?php

use Illuminate\Database\Capsule\Manager as Capsule;

// Loop through each Capsule query made during the page request.
foreach (Capsule::connection()->getQueryLog() as $query) {
echo "Query: {$query['query']}" . PHP_EOL;
echo "Execution Time: {$query['time']}ms" . PHP_EOL;
echo "Parameters: " . PHP_EOL;

foreach ($query['bindings'] as $key => $value) {
echo "{$key} => {$value}" . PHP_EOL;
}
}
</syntaxhighlight>

==The WHMCS Activity Log==

All uncaught PDO-based query failures, including those made by Capsule and manual PDO queries, are written to to the WHMCS activity log. View the system activity log to view the details of these failed queries.

=See Also=
* [[SQL Helper Functions]] (functional, but deprecated in WHMCS 6.0)

=External Links=
* [http://laravel.com/docs/4.2/queries Query Builder - Laravel 4.2]
* [http://laravel.com/docs/5.2/queries Query Builder - Laravel 5.2]
* [http://laravel.com/docs/4.2/schema Schema Builder - Laravel 4.2]
* [https://laravel.com/docs/5.0/schema Schema Builder Laravel 5.0]
* [http://php.net/manual/en/book.pdo.php PHP: PDO]

=References=
<references />

Interacting With The Database

2016-07-11T18:06:32Z

Nicolas: /* External Links */

=Database connectivity changes in WHMCS 6.0=

The mysql PHP extension was deprecated when PHP 5.5 was released in June 2013<ref>http://php.net/ChangeLog-5.php#5.5.0</ref> and is scheduled to be removed in PHP 7<ref>https://wiki.php.net/rfc/remove_deprecated_functionality_in_php7</ref>. WHMCS 6.0 introduces a new database connection and library to ensure compatibility with modern PHP environments and best practices.

==New functionality==

WHMCS 6.0 incorporates the Laravel framework 4.1's database component (''WHMCS 7.0 incorporates 5.2''). This library includes a Database Abstraction Layer (DBAL) called "Capsule" and an Object Relational Mapping (ORM) library called "Eloquent". The new DBAL is based on the PHP Data Objects (PDO MySQL) extension and uses WHMCS's existing <tt>configuration.php</tt> file. No configuration file changes are required to use the new database connection.

The Capsule DBAL component introduces two libraries to WHMCS, a query manager for running database queries and a schema manager for an abstracted API to table management. Capsule's underlying PDO connection is also available for advanced database usage. Capsule has three static methods to get to these components:

* '''Capsule::table(string $tableName)''': Access the query manager for the given table.
* '''Capsule::schema()''': Access the schema manager for the WHMCS database.
* '''Capsule::connection()''': Access the connection manager to interact with the underlying database connection.

'''Note:''' WHMCS 6.0 makes two connections to the database. One connection is made through the legacy mysql extension to handle existing hooks, modules, and other customizations. The other connection is made by PDO to drive new DBAL and model based functionality in the program.

==Deprecated functionality==

The current [[SQL Helper Functions]] are present in WHMCS 6.0 and above, but are now deprecated and may be removed in a later version of the product:
* '''select_query()'''
* '''update_query()'''
* '''insert_query()'''
* '''full_query()'''

The mysql extension driven database connection is now deprecated and may be discontinued in a later version of the product. WHMCS encourages all third party developers to use the Capsule DBAL and PDO connection for all new database interaction.

'''Note:''' WHMCS 7.0 incorporates the Laravel framework's 5.2 database component, which deprecates as well as removes many features present in 4.1 Please see the upgrade guide for more information:
* [https://laravel.com/docs/5.2/upgrade- Laravel 5.2 Upgrade Guide]

=Using Capsule=

Declare an alias to Laravel's database manager in your project file's <tt>use</tt> block to access Capsule:

<syntaxhighlight lang="php">
<?php

use Illuminate\Database\Capsule\Manager as Capsule;

// Run queries or modify tables as you like.
</syntaxhighlight>

==The Query Manager==

: ''Please see [https://laravel.com/docs/5.2/queries Laravel's query documentation] for more information.''

The '''Capsule::table(string $tableName)''' method provides access to the query manager. Declare it with the name of the table you wish to query as it's first parameter to interact with that table. The query manager has a wide range of functionality to perform advanced select, join, insert, update, and delete statements. Capsule's select calls return rows as ''stdClass'' objects.

Capsule escapes all input, so it is not necessary to add escaping slashes to variables passed to these methods.

All of Capsule's methods throw an exception on failure. Please place Capusle calls in <tt>try</tt>/<tt>catch</tt> blocks for graceful error handling and to avoid potential fatal errors in your hook, module, or other customization.

<syntaxhighlight lang="php">
<?php

use Illuminate\Database\Capsule\Manager as Capsule;

// Print all client first names using a simple select.

/** @var stdClass $client */
foreach (Capsule::table('tblclients')->get() as $client) {
echo $client->firstname . PHP_EOL;
}

// Rename all clients named "John Deo" to "John Doe" using an update statement.
try {
$updatedUserCount = Capsule::table('tblclients')
->where('firstname', 'John')
->where('lastname', 'Deo')
->update(
[
'lastname' => 'Doe',
]
);

echo "Fixed {$updatedUserCount} misspelled last names.";
} catch (\Exception $e) {
echo "I couldn't update client names. {$e->getMessage()}";
}
</syntaxhighlight>

==The Schema Manager==

Use the '''Capsule::schema()''' method to access the schema manager to modify table schema if necessary. The schema manager has support for creating, dropping and truncating tables and for modifying columns, indexes, and keys.

'''Note''': WHMCS does not recommend changing default table schema as that can affect product functionality.

<syntaxhighlight lang="php">
<?php

use Illuminate\Database\Capsule\Manager as Capsule;

// Create a new table.
try {
Capsule::schema()->create(
'my_table',
function ($table) {
/** @var \Illuminate\Database\Schema\Blueprint $table */
$table->increments('id');
$table->string('name');
$table->integer('serial_number');
$table->boolean('is_required');
$table->timestamps();
}
);
} catch (\Exception $e) {
echo "Unable to create my_table: {$e->getMessage()}";
}
</syntaxhighlight>

==The Connection Manager==

The '''Capsule::connection()''' method provides low-level access to the database connection itself. Use it to initiate transactions with automatic commit and rollback or to access the underlying PDO connection to perform manual database queries outside the DBAL. The connection manager also has methods to retrieve query and schema managers.

<syntaxhighlight lang="php">
<?php

use Illuminate\Database\Capsule\Manager as Capsule;

// Perform potentially risky queries in a transaction for easy rollback.
try {
Capsule::connection()->transaction(
function ($connectionManager)
{
/** @var \Illuminate\Database\Connection $connectionManager */
$connectionManager->table('my_table')->insert(
[
'name' => $_POST['name'],
'serial_number' => $_POST['serialNumber'],
'is_required' => (int)(bool) $_POST['isRequired'],
]
);
}
);
} catch (\Exception $e) {
echo "Uh oh! Inserting didn't work, but I was able to rollback. {$e->getMessage()}";
}
</syntaxhighlight>

===Getting to PDO===

Use the connection manager's '''getPdo()''' method to retrieve the underlying PDO connection instance. Use the PDO connection to perform manual queries and advanced database usage.

<syntaxhighlight lang="php">
<?php

use Illuminate\Database\Capsule\Manager as Capsule;

// Perform potentially risky queries in a transaction for easy rollback.
$pdo = Capsule::connection()->getPdo();
$pdo->beginTransaction();

try {
$statement = $pdo->prepare(
'insert into my_table (name, serial_number, is_required) values (:name, :serialNumber, :isRequired)'
);

$statement->execute(
[
':name' => $_POST['name'],
':serialNumber' => $_POST['serialNumber'],
':isRequired' => (bool) $_POST['isRequired'],
]
);

$pdo->commit();
} catch (\Exception $e) {
echo "Uh oh! {$e->getMessage()}";
$pdo->rollBack();
}
</syntaxhighlight>

=Troubleshooting=

==Exceptions==

All Capsule methods throw an exception on failure. Catch these exceptions and analyze their messages and stack traces to help determine the nature of the failure. WHMCS recommends placing all database interactivity in <tt>try</tt>/<tt>catch</tt> blocks for graceful error handling.

==The Capsule Query Log==

The connection manager's '''getQueryLog()''' method returns an array of all queries made during the life of the page request. Queries are stored in the log as an array containing the query run, the parameter bindings passed to the query, and the time it took for the query to execute, measured in milliseconds.

<syntaxhighlight lang="php">
<?php

use Illuminate\Database\Capsule\Manager as Capsule;

// Loop through each Capsule query made during the page request.
foreach (Capsule::connection()->getQueryLog() as $query) {
echo "Query: {$query['query']}" . PHP_EOL;
echo "Execution Time: {$query['time']}ms" . PHP_EOL;
echo "Parameters: " . PHP_EOL;

foreach ($query['bindings'] as $key => $value) {
echo "{$key} => {$value}" . PHP_EOL;
}
}
</syntaxhighlight>

==The WHMCS Activity Log==

All uncaught PDO-based query failures, including those made by Capsule and manual PDO queries, are written to to the WHMCS activity log. View the system activity log to view the details of these failed queries.

=See Also=
* [[SQL Helper Functions]] (functional, but deprecated in WHMCS 6.0)

=External Links=
* [http://laravel.com/docs/4.2/queries Query Builder - Laravel 4.2]
* [http://laravel.com/docs/5.2/queries Query Builder - Laravel 5.2]
* [http://laravel.com/docs/4.2/schema Schema Builder - Laravel 4.2]
* [https://laravel.com/docs/5.0/schema - Schema Builder 5.0]
* [http://php.net/manual/en/book.pdo.php PHP: PDO]

=References=
<references />

Interacting With The Database

2016-07-11T17:54:41Z

Nicolas:

=Database connectivity changes in WHMCS 6.0=

The mysql PHP extension was deprecated when PHP 5.5 was released in June 2013<ref>http://php.net/ChangeLog-5.php#5.5.0</ref> and is scheduled to be removed in PHP 7<ref>https://wiki.php.net/rfc/remove_deprecated_functionality_in_php7</ref>. WHMCS 6.0 introduces a new database connection and library to ensure compatibility with modern PHP environments and best practices.

==New functionality==

WHMCS 6.0 incorporates the Laravel framework 4.1's database component (''WHMCS 7.0 incorporates 5.2''). This library includes a Database Abstraction Layer (DBAL) called "Capsule" and an Object Relational Mapping (ORM) library called "Eloquent". The new DBAL is based on the PHP Data Objects (PDO MySQL) extension and uses WHMCS's existing <tt>configuration.php</tt> file. No configuration file changes are required to use the new database connection.

The Capsule DBAL component introduces two libraries to WHMCS, a query manager for running database queries and a schema manager for an abstracted API to table management. Capsule's underlying PDO connection is also available for advanced database usage. Capsule has three static methods to get to these components:

* '''Capsule::table(string $tableName)''': Access the query manager for the given table.
* '''Capsule::schema()''': Access the schema manager for the WHMCS database.
* '''Capsule::connection()''': Access the connection manager to interact with the underlying database connection.

'''Note:''' WHMCS 6.0 makes two connections to the database. One connection is made through the legacy mysql extension to handle existing hooks, modules, and other customizations. The other connection is made by PDO to drive new DBAL and model based functionality in the program.

==Deprecated functionality==

The current [[SQL Helper Functions]] are present in WHMCS 6.0 and above, but are now deprecated and may be removed in a later version of the product:
* '''select_query()'''
* '''update_query()'''
* '''insert_query()'''
* '''full_query()'''

The mysql extension driven database connection is now deprecated and may be discontinued in a later version of the product. WHMCS encourages all third party developers to use the Capsule DBAL and PDO connection for all new database interaction.

'''Note:''' WHMCS 7.0 incorporates the Laravel framework's 5.2 database component, which deprecates as well as removes many features present in 4.1 Please see the upgrade guide for more information:
* [https://laravel.com/docs/5.2/upgrade- Laravel 5.2 Upgrade Guide]

=Using Capsule=

Declare an alias to Laravel's database manager in your project file's <tt>use</tt> block to access Capsule:

<syntaxhighlight lang="php">
<?php

use Illuminate\Database\Capsule\Manager as Capsule;

// Run queries or modify tables as you like.
</syntaxhighlight>

==The Query Manager==

: ''Please see [https://laravel.com/docs/5.2/queries Laravel's query documentation] for more information.''

The '''Capsule::table(string $tableName)''' method provides access to the query manager. Declare it with the name of the table you wish to query as it's first parameter to interact with that table. The query manager has a wide range of functionality to perform advanced select, join, insert, update, and delete statements. Capsule's select calls return rows as ''stdClass'' objects.

Capsule escapes all input, so it is not necessary to add escaping slashes to variables passed to these methods.

All of Capsule's methods throw an exception on failure. Please place Capusle calls in <tt>try</tt>/<tt>catch</tt> blocks for graceful error handling and to avoid potential fatal errors in your hook, module, or other customization.

<syntaxhighlight lang="php">
<?php

use Illuminate\Database\Capsule\Manager as Capsule;

// Print all client first names using a simple select.

/** @var stdClass $client */
foreach (Capsule::table('tblclients')->get() as $client) {
echo $client->firstname . PHP_EOL;
}

// Rename all clients named "John Deo" to "John Doe" using an update statement.
try {
$updatedUserCount = Capsule::table('tblclients')
->where('firstname', 'John')
->where('lastname', 'Deo')
->update(
[
'lastname' => 'Doe',
]
);

echo "Fixed {$updatedUserCount} misspelled last names.";
} catch (\Exception $e) {
echo "I couldn't update client names. {$e->getMessage()}";
}
</syntaxhighlight>

==The Schema Manager==

Use the '''Capsule::schema()''' method to access the schema manager to modify table schema if necessary. The schema manager has support for creating, dropping and truncating tables and for modifying columns, indexes, and keys.

'''Note''': WHMCS does not recommend changing default table schema as that can affect product functionality.

<syntaxhighlight lang="php">
<?php

use Illuminate\Database\Capsule\Manager as Capsule;

// Create a new table.
try {
Capsule::schema()->create(
'my_table',
function ($table) {
/** @var \Illuminate\Database\Schema\Blueprint $table */
$table->increments('id');
$table->string('name');
$table->integer('serial_number');
$table->boolean('is_required');
$table->timestamps();
}
);
} catch (\Exception $e) {
echo "Unable to create my_table: {$e->getMessage()}";
}
</syntaxhighlight>

==The Connection Manager==

The '''Capsule::connection()''' method provides low-level access to the database connection itself. Use it to initiate transactions with automatic commit and rollback or to access the underlying PDO connection to perform manual database queries outside the DBAL. The connection manager also has methods to retrieve query and schema managers.

<syntaxhighlight lang="php">
<?php

use Illuminate\Database\Capsule\Manager as Capsule;

// Perform potentially risky queries in a transaction for easy rollback.
try {
Capsule::connection()->transaction(
function ($connectionManager)
{
/** @var \Illuminate\Database\Connection $connectionManager */
$connectionManager->table('my_table')->insert(
[
'name' => $_POST['name'],
'serial_number' => $_POST['serialNumber'],
'is_required' => (int)(bool) $_POST['isRequired'],
]
);
}
);
} catch (\Exception $e) {
echo "Uh oh! Inserting didn't work, but I was able to rollback. {$e->getMessage()}";
}
</syntaxhighlight>

===Getting to PDO===

Use the connection manager's '''getPdo()''' method to retrieve the underlying PDO connection instance. Use the PDO connection to perform manual queries and advanced database usage.

<syntaxhighlight lang="php">
<?php

use Illuminate\Database\Capsule\Manager as Capsule;

// Perform potentially risky queries in a transaction for easy rollback.
$pdo = Capsule::connection()->getPdo();
$pdo->beginTransaction();

try {
$statement = $pdo->prepare(
'insert into my_table (name, serial_number, is_required) values (:name, :serialNumber, :isRequired)'
);

$statement->execute(
[
':name' => $_POST['name'],
':serialNumber' => $_POST['serialNumber'],
':isRequired' => (bool) $_POST['isRequired'],
]
);

$pdo->commit();
} catch (\Exception $e) {
echo "Uh oh! {$e->getMessage()}";
$pdo->rollBack();
}
</syntaxhighlight>

=Troubleshooting=

==Exceptions==

All Capsule methods throw an exception on failure. Catch these exceptions and analyze their messages and stack traces to help determine the nature of the failure. WHMCS recommends placing all database interactivity in <tt>try</tt>/<tt>catch</tt> blocks for graceful error handling.

==The Capsule Query Log==

The connection manager's '''getQueryLog()''' method returns an array of all queries made during the life of the page request. Queries are stored in the log as an array containing the query run, the parameter bindings passed to the query, and the time it took for the query to execute, measured in milliseconds.

<syntaxhighlight lang="php">
<?php

use Illuminate\Database\Capsule\Manager as Capsule;

// Loop through each Capsule query made during the page request.
foreach (Capsule::connection()->getQueryLog() as $query) {
echo "Query: {$query['query']}" . PHP_EOL;
echo "Execution Time: {$query['time']}ms" . PHP_EOL;
echo "Parameters: " . PHP_EOL;

foreach ($query['bindings'] as $key => $value) {
echo "{$key} => {$value}" . PHP_EOL;
}
}
</syntaxhighlight>

==The WHMCS Activity Log==

All uncaught PDO-based query failures, including those made by Capsule and manual PDO queries, are written to to the WHMCS activity log. View the system activity log to view the details of these failed queries.

=See Also=
* [[SQL Helper Functions]] (functional, but deprecated in WHMCS 6.0)

=External Links=
* [http://laravel.com/docs/4.2/queries Query Builder - Laravel 4.2]
* [http://laravel.com/docs/5.2/queries Query Builder - Laravel 5.2]
* [http://laravel.com/docs/4.2/schema Schema Builder - Laravel 4.2]
* [https://laravel.com/docs/5.0/schema - Laravel 5.0]
* [http://php.net/manual/en/book.pdo.php PHP: PDO]

=References=
<references />

Interacting With The Database

2016-07-11T17:35:36Z

Nicolas: /* External Links */

=Database connectivity changes in WHMCS 6.0=

The mysql PHP extension was deprecated when PHP 5.5 was released in June 2013<ref>http://php.net/ChangeLog-5.php#5.5.0</ref> and is scheduled to be removed in PHP 7<ref>https://wiki.php.net/rfc/remove_deprecated_functionality_in_php7</ref>. WHMCS 6.0 introduces a new database connection and library to ensure compatibility with modern PHP environments and best practices.

==New functionality==

WHMCS 6.0 incorporates the Laravel framework 4.1's database component (''WHMCS 7.0 incorporates 5.2''). This library includes a Database Abstraction Layer (DBAL) called "Capsule" and an Object Relational Mapping (ORM) library called "Eloquent". The new DBAL is based on the PHP Data Objects (PDO MySQL) extension and uses WHMCS's existing <tt>configuration.php</tt> file. No configuration file changes are required to use the new database connection.

The Capsule DBAL component introduces two libraries to WHMCS, a query manager for running database queries and a schema manager for an abstracted API to table management. Capsule's underlying PDO connection is also available for advanced database usage. Capsule has three static methods to get to these components:

* '''Capsule::table(string $tableName)''': Access the query manager for the given table.
* '''Capsule::schema()''': Access the schema manager for the WHMCS database.
* '''Capsule::connection()''': Access the connection manager to interact with the underlying database connection.

'''Note:''' WHMCS 6.0 makes two connections to the database. One connection is made through the legacy mysql extension to handle existing hooks, modules, and other customizations. The other connection is made by PDO to drive new DBAL and model based functionality in the program.

==Deprecated functionality==

The current [[SQL Helper Functions]] are present in WHMCS 6.0 and above, but are now deprecated and may be removed in a later version of the product:
* '''select_query()'''
* '''update_query()'''
* '''insert_query()'''
* '''full_query()'''

The mysql extension driven database connection is now deprecated and may be discontinued in a later version of the product. WHMCS encourages all third party developers to use the Capsule DBAL and PDO connection for all new database interaction.

=Using Capsule=

Declare an alias to Laravel's database manager in your project file's <tt>use</tt> block to access Capsule:

<syntaxhighlight lang="php">
<?php

use Illuminate\Database\Capsule\Manager as Capsule;

// Run queries or modify tables as you like.
</syntaxhighlight>

==The Query Manager==

: ''Please see [https://laravel.com/docs/5.2/queries Laravel's query documentation] for more information.''

The '''Capsule::table(string $tableName)''' method provides access to the query manager. Declare it with the name of the table you wish to query as it's first parameter to interact with that table. The query manager has a wide range of functionality to perform advanced select, join, insert, update, and delete statements. Capsule's select calls return rows as ''stdClass'' objects.

Capsule escapes all input, so it is not necessary to add escaping slashes to variables passed to these methods.

All of Capsule's methods throw an exception on failure. Please place Capusle calls in <tt>try</tt>/<tt>catch</tt> blocks for graceful error handling and to avoid potential fatal errors in your hook, module, or other customization.

<syntaxhighlight lang="php">
<?php

use Illuminate\Database\Capsule\Manager as Capsule;

// Print all client first names using a simple select.

/** @var stdClass $client */
foreach (Capsule::table('tblclients')->get() as $client) {
echo $client->firstname . PHP_EOL;
}

// Rename all clients named "John Deo" to "John Doe" using an update statement.
try {
$updatedUserCount = Capsule::table('tblclients')
->where('firstname', 'John')
->where('lastname', 'Deo')
->update(
[
'lastname' => 'Doe',
]
);

echo "Fixed {$updatedUserCount} misspelled last names.";
} catch (\Exception $e) {
echo "I couldn't update client names. {$e->getMessage()}";
}
</syntaxhighlight>

==The Schema Manager==

Use the '''Capsule::schema()''' method to access the schema manager to modify table schema if necessary. The schema manager has support for creating, dropping and truncating tables and for modifying columns, indexes, and keys.

'''Note''': WHMCS does not recommend changing default table schema as that can affect product functionality.

<syntaxhighlight lang="php">
<?php

use Illuminate\Database\Capsule\Manager as Capsule;

// Create a new table.
try {
Capsule::schema()->create(
'my_table',
function ($table) {
/** @var \Illuminate\Database\Schema\Blueprint $table */
$table->increments('id');
$table->string('name');
$table->integer('serial_number');
$table->boolean('is_required');
$table->timestamps();
}
);
} catch (\Exception $e) {
echo "Unable to create my_table: {$e->getMessage()}";
}
</syntaxhighlight>

==The Connection Manager==

The '''Capsule::connection()''' method provides low-level access to the database connection itself. Use it to initiate transactions with automatic commit and rollback or to access the underlying PDO connection to perform manual database queries outside the DBAL. The connection manager also has methods to retrieve query and schema managers.

<syntaxhighlight lang="php">
<?php

use Illuminate\Database\Capsule\Manager as Capsule;

// Perform potentially risky queries in a transaction for easy rollback.
try {
Capsule::connection()->transaction(
function ($connectionManager)
{
/** @var \Illuminate\Database\Connection $connectionManager */
$connectionManager->table('my_table')->insert(
[
'name' => $_POST['name'],
'serial_number' => $_POST['serialNumber'],
'is_required' => (int)(bool) $_POST['isRequired'],
]
);
}
);
} catch (\Exception $e) {
echo "Uh oh! Inserting didn't work, but I was able to rollback. {$e->getMessage()}";
}
</syntaxhighlight>

===Getting to PDO===

Use the connection manager's '''getPdo()''' method to retrieve the underlying PDO connection instance. Use the PDO connection to perform manual queries and advanced database usage.

<syntaxhighlight lang="php">
<?php

use Illuminate\Database\Capsule\Manager as Capsule;

// Perform potentially risky queries in a transaction for easy rollback.
$pdo = Capsule::connection()->getPdo();
$pdo->beginTransaction();

try {
$statement = $pdo->prepare(
'insert into my_table (name, serial_number, is_required) values (:name, :serialNumber, :isRequired)'
);

$statement->execute(
[
':name' => $_POST['name'],
':serialNumber' => $_POST['serialNumber'],
':isRequired' => (bool) $_POST['isRequired'],
]
);

$pdo->commit();
} catch (\Exception $e) {
echo "Uh oh! {$e->getMessage()}";
$pdo->rollBack();
}
</syntaxhighlight>

=Troubleshooting=

==Exceptions==

All Capsule methods throw an exception on failure. Catch these exceptions and analyze their messages and stack traces to help determine the nature of the failure. WHMCS recommends placing all database interactivity in <tt>try</tt>/<tt>catch</tt> blocks for graceful error handling.

==The Capsule Query Log==

The connection manager's '''getQueryLog()''' method returns an array of all queries made during the life of the page request. Queries are stored in the log as an array containing the query run, the parameter bindings passed to the query, and the time it took for the query to execute, measured in milliseconds.

<syntaxhighlight lang="php">
<?php

use Illuminate\Database\Capsule\Manager as Capsule;

// Loop through each Capsule query made during the page request.
foreach (Capsule::connection()->getQueryLog() as $query) {
echo "Query: {$query['query']}" . PHP_EOL;
echo "Execution Time: {$query['time']}ms" . PHP_EOL;
echo "Parameters: " . PHP_EOL;

foreach ($query['bindings'] as $key => $value) {
echo "{$key} => {$value}" . PHP_EOL;
}
}
</syntaxhighlight>

==The WHMCS Activity Log==

All uncaught PDO-based query failures, including those made by Capsule and manual PDO queries, are written to to the WHMCS activity log. View the system activity log to view the details of these failed queries.

=See Also=
* [[SQL Helper Functions]] (functional, but deprecated in WHMCS 6.0)

=External Links=
* [http://laravel.com/docs/4.2/queries Query Builder - Laravel 4.2]
* [http://laravel.com/docs/5.2/queries Query Builder - Laravel 5.2]
* [http://laravel.com/docs/4.2/schema Schema Builder - Laravel 4.2]
* [https://laravel.com/docs/5.0/schema - Laravel 5.0]
* [http://php.net/manual/en/book.pdo.php PHP: PDO]

=References=
<references />

Interacting With The Database

2016-07-11T17:35:21Z

Nicolas: /* External Links */

=Database connectivity changes in WHMCS 6.0=

The mysql PHP extension was deprecated when PHP 5.5 was released in June 2013<ref>http://php.net/ChangeLog-5.php#5.5.0</ref> and is scheduled to be removed in PHP 7<ref>https://wiki.php.net/rfc/remove_deprecated_functionality_in_php7</ref>. WHMCS 6.0 introduces a new database connection and library to ensure compatibility with modern PHP environments and best practices.

==New functionality==

WHMCS 6.0 incorporates the Laravel framework 4.1's database component (''WHMCS 7.0 incorporates 5.2''). This library includes a Database Abstraction Layer (DBAL) called "Capsule" and an Object Relational Mapping (ORM) library called "Eloquent". The new DBAL is based on the PHP Data Objects (PDO MySQL) extension and uses WHMCS's existing <tt>configuration.php</tt> file. No configuration file changes are required to use the new database connection.

The Capsule DBAL component introduces two libraries to WHMCS, a query manager for running database queries and a schema manager for an abstracted API to table management. Capsule's underlying PDO connection is also available for advanced database usage. Capsule has three static methods to get to these components:

* '''Capsule::table(string $tableName)''': Access the query manager for the given table.
* '''Capsule::schema()''': Access the schema manager for the WHMCS database.
* '''Capsule::connection()''': Access the connection manager to interact with the underlying database connection.

'''Note:''' WHMCS 6.0 makes two connections to the database. One connection is made through the legacy mysql extension to handle existing hooks, modules, and other customizations. The other connection is made by PDO to drive new DBAL and model based functionality in the program.

==Deprecated functionality==

The current [[SQL Helper Functions]] are present in WHMCS 6.0 and above, but are now deprecated and may be removed in a later version of the product:
* '''select_query()'''
* '''update_query()'''
* '''insert_query()'''
* '''full_query()'''

The mysql extension driven database connection is now deprecated and may be discontinued in a later version of the product. WHMCS encourages all third party developers to use the Capsule DBAL and PDO connection for all new database interaction.

=Using Capsule=

Declare an alias to Laravel's database manager in your project file's <tt>use</tt> block to access Capsule:

<syntaxhighlight lang="php">
<?php

use Illuminate\Database\Capsule\Manager as Capsule;

// Run queries or modify tables as you like.
</syntaxhighlight>

==The Query Manager==

: ''Please see [https://laravel.com/docs/5.2/queries Laravel's query documentation] for more information.''

The '''Capsule::table(string $tableName)''' method provides access to the query manager. Declare it with the name of the table you wish to query as it's first parameter to interact with that table. The query manager has a wide range of functionality to perform advanced select, join, insert, update, and delete statements. Capsule's select calls return rows as ''stdClass'' objects.

Capsule escapes all input, so it is not necessary to add escaping slashes to variables passed to these methods.

All of Capsule's methods throw an exception on failure. Please place Capusle calls in <tt>try</tt>/<tt>catch</tt> blocks for graceful error handling and to avoid potential fatal errors in your hook, module, or other customization.

<syntaxhighlight lang="php">
<?php

use Illuminate\Database\Capsule\Manager as Capsule;

// Print all client first names using a simple select.

/** @var stdClass $client */
foreach (Capsule::table('tblclients')->get() as $client) {
echo $client->firstname . PHP_EOL;
}

// Rename all clients named "John Deo" to "John Doe" using an update statement.
try {
$updatedUserCount = Capsule::table('tblclients')
->where('firstname', 'John')
->where('lastname', 'Deo')
->update(
[
'lastname' => 'Doe',
]
);

echo "Fixed {$updatedUserCount} misspelled last names.";
} catch (\Exception $e) {
echo "I couldn't update client names. {$e->getMessage()}";
}
</syntaxhighlight>

==The Schema Manager==

Use the '''Capsule::schema()''' method to access the schema manager to modify table schema if necessary. The schema manager has support for creating, dropping and truncating tables and for modifying columns, indexes, and keys.

'''Note''': WHMCS does not recommend changing default table schema as that can affect product functionality.

<syntaxhighlight lang="php">
<?php

use Illuminate\Database\Capsule\Manager as Capsule;

// Create a new table.
try {
Capsule::schema()->create(
'my_table',
function ($table) {
/** @var \Illuminate\Database\Schema\Blueprint $table */
$table->increments('id');
$table->string('name');
$table->integer('serial_number');
$table->boolean('is_required');
$table->timestamps();
}
);
} catch (\Exception $e) {
echo "Unable to create my_table: {$e->getMessage()}";
}
</syntaxhighlight>

==The Connection Manager==

The '''Capsule::connection()''' method provides low-level access to the database connection itself. Use it to initiate transactions with automatic commit and rollback or to access the underlying PDO connection to perform manual database queries outside the DBAL. The connection manager also has methods to retrieve query and schema managers.

<syntaxhighlight lang="php">
<?php

use Illuminate\Database\Capsule\Manager as Capsule;

// Perform potentially risky queries in a transaction for easy rollback.
try {
Capsule::connection()->transaction(
function ($connectionManager)
{
/** @var \Illuminate\Database\Connection $connectionManager */
$connectionManager->table('my_table')->insert(
[
'name' => $_POST['name'],
'serial_number' => $_POST['serialNumber'],
'is_required' => (int)(bool) $_POST['isRequired'],
]
);
}
);
} catch (\Exception $e) {
echo "Uh oh! Inserting didn't work, but I was able to rollback. {$e->getMessage()}";
}
</syntaxhighlight>

===Getting to PDO===

Use the connection manager's '''getPdo()''' method to retrieve the underlying PDO connection instance. Use the PDO connection to perform manual queries and advanced database usage.

<syntaxhighlight lang="php">
<?php

use Illuminate\Database\Capsule\Manager as Capsule;

// Perform potentially risky queries in a transaction for easy rollback.
$pdo = Capsule::connection()->getPdo();
$pdo->beginTransaction();

try {
$statement = $pdo->prepare(
'insert into my_table (name, serial_number, is_required) values (:name, :serialNumber, :isRequired)'
);

$statement->execute(
[
':name' => $_POST['name'],
':serialNumber' => $_POST['serialNumber'],
':isRequired' => (bool) $_POST['isRequired'],
]
);

$pdo->commit();
} catch (\Exception $e) {
echo "Uh oh! {$e->getMessage()}";
$pdo->rollBack();
}
</syntaxhighlight>

=Troubleshooting=

==Exceptions==

All Capsule methods throw an exception on failure. Catch these exceptions and analyze their messages and stack traces to help determine the nature of the failure. WHMCS recommends placing all database interactivity in <tt>try</tt>/<tt>catch</tt> blocks for graceful error handling.

==The Capsule Query Log==

The connection manager's '''getQueryLog()''' method returns an array of all queries made during the life of the page request. Queries are stored in the log as an array containing the query run, the parameter bindings passed to the query, and the time it took for the query to execute, measured in milliseconds.

<syntaxhighlight lang="php">
<?php

use Illuminate\Database\Capsule\Manager as Capsule;

// Loop through each Capsule query made during the page request.
foreach (Capsule::connection()->getQueryLog() as $query) {
echo "Query: {$query['query']}" . PHP_EOL;
echo "Execution Time: {$query['time']}ms" . PHP_EOL;
echo "Parameters: " . PHP_EOL;

foreach ($query['bindings'] as $key => $value) {
echo "{$key} => {$value}" . PHP_EOL;
}
}
</syntaxhighlight>

==The WHMCS Activity Log==

All uncaught PDO-based query failures, including those made by Capsule and manual PDO queries, are written to to the WHMCS activity log. View the system activity log to view the details of these failed queries.

=See Also=
* [[SQL Helper Functions]] (functional, but deprecated in WHMCS 6.0)

=External Links=
* [http://laravel.com/docs/4.2/queries Query Builder - Laravel 4.2]
* [http://laravel.com/docs/5.2/queries Query Builder - Laravel 5.2]
* [http://laravel.com/docs/4.2/schema Schema Builder - Laravel 4.2]
* [https://laravel.com/docs/5.0/schema - Laravel 5.2]
* [http://php.net/manual/en/book.pdo.php PHP: PDO]

=References=
<references />

Interacting With The Database

2016-07-11T17:22:10Z

Nicolas: /* External Links */

=Database connectivity changes in WHMCS 6.0=

The mysql PHP extension was deprecated when PHP 5.5 was released in June 2013<ref>http://php.net/ChangeLog-5.php#5.5.0</ref> and is scheduled to be removed in PHP 7<ref>https://wiki.php.net/rfc/remove_deprecated_functionality_in_php7</ref>. WHMCS 6.0 introduces a new database connection and library to ensure compatibility with modern PHP environments and best practices.

==New functionality==

WHMCS 6.0 incorporates the Laravel framework 4.1's database component (''WHMCS 7.0 incorporates 5.2''). This library includes a Database Abstraction Layer (DBAL) called "Capsule" and an Object Relational Mapping (ORM) library called "Eloquent". The new DBAL is based on the PHP Data Objects (PDO MySQL) extension and uses WHMCS's existing <tt>configuration.php</tt> file. No configuration file changes are required to use the new database connection.

The Capsule DBAL component introduces two libraries to WHMCS, a query manager for running database queries and a schema manager for an abstracted API to table management. Capsule's underlying PDO connection is also available for advanced database usage. Capsule has three static methods to get to these components:

* '''Capsule::table(string $tableName)''': Access the query manager for the given table.
* '''Capsule::schema()''': Access the schema manager for the WHMCS database.
* '''Capsule::connection()''': Access the connection manager to interact with the underlying database connection.

'''Note:''' WHMCS 6.0 makes two connections to the database. One connection is made through the legacy mysql extension to handle existing hooks, modules, and other customizations. The other connection is made by PDO to drive new DBAL and model based functionality in the program.

==Deprecated functionality==

The current [[SQL Helper Functions]] are present in WHMCS 6.0 and above, but are now deprecated and may be removed in a later version of the product:
* '''select_query()'''
* '''update_query()'''
* '''insert_query()'''
* '''full_query()'''

The mysql extension driven database connection is now deprecated and may be discontinued in a later version of the product. WHMCS encourages all third party developers to use the Capsule DBAL and PDO connection for all new database interaction.

=Using Capsule=

Declare an alias to Laravel's database manager in your project file's <tt>use</tt> block to access Capsule:

<syntaxhighlight lang="php">
<?php

use Illuminate\Database\Capsule\Manager as Capsule;

// Run queries or modify tables as you like.
</syntaxhighlight>

==The Query Manager==

: ''Please see [https://laravel.com/docs/5.2/queries Laravel's query documentation] for more information.''

The '''Capsule::table(string $tableName)''' method provides access to the query manager. Declare it with the name of the table you wish to query as it's first parameter to interact with that table. The query manager has a wide range of functionality to perform advanced select, join, insert, update, and delete statements. Capsule's select calls return rows as ''stdClass'' objects.

Capsule escapes all input, so it is not necessary to add escaping slashes to variables passed to these methods.

All of Capsule's methods throw an exception on failure. Please place Capusle calls in <tt>try</tt>/<tt>catch</tt> blocks for graceful error handling and to avoid potential fatal errors in your hook, module, or other customization.

<syntaxhighlight lang="php">
<?php

use Illuminate\Database\Capsule\Manager as Capsule;

// Print all client first names using a simple select.

/** @var stdClass $client */
foreach (Capsule::table('tblclients')->get() as $client) {
echo $client->firstname . PHP_EOL;
}

// Rename all clients named "John Deo" to "John Doe" using an update statement.
try {
$updatedUserCount = Capsule::table('tblclients')
->where('firstname', 'John')
->where('lastname', 'Deo')
->update(
[
'lastname' => 'Doe',
]
);

echo "Fixed {$updatedUserCount} misspelled last names.";
} catch (\Exception $e) {
echo "I couldn't update client names. {$e->getMessage()}";
}
</syntaxhighlight>

==The Schema Manager==

Use the '''Capsule::schema()''' method to access the schema manager to modify table schema if necessary. The schema manager has support for creating, dropping and truncating tables and for modifying columns, indexes, and keys.

'''Note''': WHMCS does not recommend changing default table schema as that can affect product functionality.

<syntaxhighlight lang="php">
<?php

use Illuminate\Database\Capsule\Manager as Capsule;

// Create a new table.
try {
Capsule::schema()->create(
'my_table',
function ($table) {
/** @var \Illuminate\Database\Schema\Blueprint $table */
$table->increments('id');
$table->string('name');
$table->integer('serial_number');
$table->boolean('is_required');
$table->timestamps();
}
);
} catch (\Exception $e) {
echo "Unable to create my_table: {$e->getMessage()}";
}
</syntaxhighlight>

==The Connection Manager==

The '''Capsule::connection()''' method provides low-level access to the database connection itself. Use it to initiate transactions with automatic commit and rollback or to access the underlying PDO connection to perform manual database queries outside the DBAL. The connection manager also has methods to retrieve query and schema managers.

<syntaxhighlight lang="php">
<?php

use Illuminate\Database\Capsule\Manager as Capsule;

// Perform potentially risky queries in a transaction for easy rollback.
try {
Capsule::connection()->transaction(
function ($connectionManager)
{
/** @var \Illuminate\Database\Connection $connectionManager */
$connectionManager->table('my_table')->insert(
[
'name' => $_POST['name'],
'serial_number' => $_POST['serialNumber'],
'is_required' => (int)(bool) $_POST['isRequired'],
]
);
}
);
} catch (\Exception $e) {
echo "Uh oh! Inserting didn't work, but I was able to rollback. {$e->getMessage()}";
}
</syntaxhighlight>

===Getting to PDO===

Use the connection manager's '''getPdo()''' method to retrieve the underlying PDO connection instance. Use the PDO connection to perform manual queries and advanced database usage.

<syntaxhighlight lang="php">
<?php

use Illuminate\Database\Capsule\Manager as Capsule;

// Perform potentially risky queries in a transaction for easy rollback.
$pdo = Capsule::connection()->getPdo();
$pdo->beginTransaction();

try {
$statement = $pdo->prepare(
'insert into my_table (name, serial_number, is_required) values (:name, :serialNumber, :isRequired)'
);

$statement->execute(
[
':name' => $_POST['name'],
':serialNumber' => $_POST['serialNumber'],
':isRequired' => (bool) $_POST['isRequired'],
]
);

$pdo->commit();
} catch (\Exception $e) {
echo "Uh oh! {$e->getMessage()}";
$pdo->rollBack();
}
</syntaxhighlight>

=Troubleshooting=

==Exceptions==

All Capsule methods throw an exception on failure. Catch these exceptions and analyze their messages and stack traces to help determine the nature of the failure. WHMCS recommends placing all database interactivity in <tt>try</tt>/<tt>catch</tt> blocks for graceful error handling.

==The Capsule Query Log==

The connection manager's '''getQueryLog()''' method returns an array of all queries made during the life of the page request. Queries are stored in the log as an array containing the query run, the parameter bindings passed to the query, and the time it took for the query to execute, measured in milliseconds.

<syntaxhighlight lang="php">
<?php

use Illuminate\Database\Capsule\Manager as Capsule;

// Loop through each Capsule query made during the page request.
foreach (Capsule::connection()->getQueryLog() as $query) {
echo "Query: {$query['query']}" . PHP_EOL;
echo "Execution Time: {$query['time']}ms" . PHP_EOL;
echo "Parameters: " . PHP_EOL;

foreach ($query['bindings'] as $key => $value) {
echo "{$key} => {$value}" . PHP_EOL;
}
}
</syntaxhighlight>

==The WHMCS Activity Log==

All uncaught PDO-based query failures, including those made by Capsule and manual PDO queries, are written to to the WHMCS activity log. View the system activity log to view the details of these failed queries.

=See Also=
* [[SQL Helper Functions]] (functional, but deprecated in WHMCS 6.0)

=External Links=
* [http://laravel.com/docs/4.2/queries Query Builder - Laravel 4.2]
* [http://laravel.com/docs/5.2/queries Query Builder - Laravel 5.2]
* [http://laravel.com/docs/4.2/schema Schema Builder - Laravel 4.2]
* [http://php.net/manual/en/book.pdo.php PHP: PDO]

=References=
<references />

Creating Pages

2016-07-11T17:01:31Z

Nicolas: /* Page with a Sidebar */

Creating your own custom pages for WHMCS is simple. Use this to extend the client area. For example, building the whole site around WHMCS, or creating custom pages to provide extra functionality to clients.

==Standard Page==

To get started, copy & paste the code below into a new PHP file and save it in the main WHMCS directory.

<source lang="php">
<?php

use WHMCS\Database\Capsule;

define("CLIENTAREA", true);
//define("FORCESSL", true); // Uncomment to force the page to use https://

require("init.php");

$ca = new WHMCS_ClientArea();

$ca->setPageTitle("Your Page Title Goes Here");

$ca->addToBreadCrumb('index.php', Lang::trans('globalsystemname'));
$ca->addToBreadCrumb('mypage.php', 'Your Custom Page Name');

$ca->initPage();

//$ca->requireLogin(); // Uncomment this line to require a login to access this page

# To assign variables to the template system use the following syntax.
# These can then be referenced using {$variablename} in the template.

$ca->assign('variablename', $value);

# Check login status
if ($ca->isLoggedIn()) {

# User is logged in - put any code you like here

# Here's an example to get the currently logged in clients first name

$clientName = Capsule::table('tblclients')
->where('id', '=', $ca->getUserID())->pluck('firstname');
// 'pluck' was renamed within WHMCS 7.0. Replace it with 'value' instead.
// ->where('id', '=', $ca->getUserID())->value('firstname');

$ca->assign('clientname', $clientName);

} else {

# User is not logged in

}

# Define the template filename to be used without the .tpl extension

$ca->setTemplate('mypage');

$ca->output();
</source>

This example above shows you the required layout of a custom page. It demonstrates:

*How to initiate the page
*How to force the page to use SSL (FORCESSL)
*How to reference the language file variables (Lang::trans)
*How to check if a user is logged in ($ca->isLoggedIn())
*How to define template variables ($ca->assign)
*How to set the template to use and then output it

The template file should be a filename in the active WHMCS system template folder. So, for the example above the path would be /templates/default/mypage.tpl.

Now when ready to test, upload both the PHP and TPL file to the appropriate folders. Then visit the PHP file in the root WHMCS directory to run.

==Page with a Sidebar==
It is possible to define a [[Editing_Client_Area_Menus|sidebar]] display on a custom page. The following shows how to create a custom page, and also define a sidebar to display alongside. It demonstrates:

*How to set contact for the sidebar, thereby influencing what data passes to the menu
*How to define both the primary and secondary sidebars for display

<source lang="php">
<?php

use WHMCS\ClientArea;
use WHMCS\Database\Capsule;

define('CLIENTAREA', true);
//define('FORCESSL', true); // Uncomment to force the page to use https://

require __DIR__ . '/init.php';

$ca = new ClientArea();

$ca->setPageTitle('Your Page Title Goes Here');

$ca->addToBreadCrumb('index.php', Lang::trans('globalsystemname'));
$ca->addToBreadCrumb('mypage.php', 'Your Custom Page Name');

$ca->initPage();

//$ca->requireLogin(); // Uncomment this line to require a login to access this page

// To assign variables to the template system use the following syntax.
// These can then be referenced using {$variablename} in the template.

//$ca->assign('variablename', $value);

// Check login status
if ($ca->isLoggedIn()) {

/**
* User is logged in - put any code you like here
*
* Here's an example to get the currently logged in clients first name
*/

$clientName = Capsule::table('tblclients')
->where('id', '=', $ca->getUserID())->pluck('firstname');
// 'pluck' was renamed within WHMCS 7.0. Replace it with 'value' instead.
// ->where('id', '=', $ca->getUserID())->value('firstname');
$ca->assign('clientname', $clientName);

} else {

// User is not logged in
$ca->assign('clientname', 'Random User');

}

/**
* Set a context for sidebars
*
* @link http://docs.whmcs.com/Editing_Client_Area_Menus#Context
*/
Menu::addContext();

/**
* Setup the primary and secondary sidebars
*
* @link http://docs.whmcs.com/Editing_Client_Area_Menus#Context
*/
Menu::primarySidebar('announcementList');
Menu::secondarySidebar('announcementList');

# Define the template filename to be used without the .tpl extension

$ca->setTemplate('mypage');

$ca->output();
</source>

{{Developer_Links}}

Creating Pages

2016-07-11T17:00:35Z

Nicolas: /* Standard Page */

Creating your own custom pages for WHMCS is simple. Use this to extend the client area. For example, building the whole site around WHMCS, or creating custom pages to provide extra functionality to clients.

==Standard Page==

To get started, copy & paste the code below into a new PHP file and save it in the main WHMCS directory.

<source lang="php">
<?php

use WHMCS\Database\Capsule;

define("CLIENTAREA", true);
//define("FORCESSL", true); // Uncomment to force the page to use https://

require("init.php");

$ca = new WHMCS_ClientArea();

$ca->setPageTitle("Your Page Title Goes Here");

$ca->addToBreadCrumb('index.php', Lang::trans('globalsystemname'));
$ca->addToBreadCrumb('mypage.php', 'Your Custom Page Name');

$ca->initPage();

//$ca->requireLogin(); // Uncomment this line to require a login to access this page

# To assign variables to the template system use the following syntax.
# These can then be referenced using {$variablename} in the template.

$ca->assign('variablename', $value);

# Check login status
if ($ca->isLoggedIn()) {

# User is logged in - put any code you like here

# Here's an example to get the currently logged in clients first name

$clientName = Capsule::table('tblclients')
->where('id', '=', $ca->getUserID())->pluck('firstname');
// 'pluck' was renamed within WHMCS 7.0. Replace it with 'value' instead.
// ->where('id', '=', $ca->getUserID())->value('firstname');

$ca->assign('clientname', $clientName);

} else {

# User is not logged in

}

# Define the template filename to be used without the .tpl extension

$ca->setTemplate('mypage');

$ca->output();
</source>

This example above shows you the required layout of a custom page. It demonstrates:

*How to initiate the page
*How to force the page to use SSL (FORCESSL)
*How to reference the language file variables (Lang::trans)
*How to check if a user is logged in ($ca->isLoggedIn())
*How to define template variables ($ca->assign)
*How to set the template to use and then output it

The template file should be a filename in the active WHMCS system template folder. So, for the example above the path would be /templates/default/mypage.tpl.

Now when ready to test, upload both the PHP and TPL file to the appropriate folders. Then visit the PHP file in the root WHMCS directory to run.

==Page with a Sidebar==
It is possible to define a [[Editing_Client_Area_Menus|sidebar]] display on a custom page. The following shows how to create a custom page, and also define a sidebar to display alongside. It demonstrates:

*How to set contact for the sidebar, thereby influencing what data passes to the menu
*How to define both the primary and secondary sidebars for display

<source lang="php">
<?php

use WHMCS\ClientArea;
use WHMCS\Database\Capsule;

define('CLIENTAREA', true);
//define('FORCESSL', true); // Uncomment to force the page to use https://

require __DIR__ . '/init.php';

$ca = new ClientArea();

$ca->setPageTitle('Your Page Title Goes Here');

$ca->addToBreadCrumb('index.php', Lang::trans('globalsystemname'));
$ca->addToBreadCrumb('mypage.php', 'Your Custom Page Name');

$ca->initPage();

//$ca->requireLogin(); // Uncomment this line to require a login to access this page

// To assign variables to the template system use the following syntax.
// These can then be referenced using {$variablename} in the template.

//$ca->assign('variablename', $value);

// Check login status
if ($ca->isLoggedIn()) {

/**
* User is logged in - put any code you like here
*
* Here's an example to get the currently logged in clients first name
*/

$clientName = Capsule::table('tblclients')
->where('id', '=', $ca->getUserID())->pluck('firstname');
$ca->assign('clientname', $clientName);

} else {

// User is not logged in
$ca->assign('clientname', 'Random User');

}

/**
* Set a context for sidebars
*
* @link http://docs.whmcs.com/Editing_Client_Area_Menus#Context
*/
Menu::addContext();

/**
* Setup the primary and secondary sidebars
*
* @link http://docs.whmcs.com/Editing_Client_Area_Menus#Context
*/
Menu::primarySidebar('announcementList');
Menu::secondarySidebar('announcementList');

# Define the template filename to be used without the .tpl extension

$ca->setTemplate('mypage');

$ca->output();
</source>

{{Developer_Links}}

Interacting With The Database

2016-07-11T16:43:22Z

Nicolas: /* Database connectivity changes in WHMCS 6.0 */

=Database connectivity changes in WHMCS 6.0=

The mysql PHP extension was deprecated when PHP 5.5 was released in June 2013<ref>http://php.net/ChangeLog-5.php#5.5.0</ref> and is scheduled to be removed in PHP 7<ref>https://wiki.php.net/rfc/remove_deprecated_functionality_in_php7</ref>. WHMCS 6.0 introduces a new database connection and library to ensure compatibility with modern PHP environments and best practices.

==New functionality==

WHMCS 6.0 incorporates the Laravel framework 4.1's database component (''WHMCS 7.0 incorporates 5.2''). This library includes a Database Abstraction Layer (DBAL) called "Capsule" and an Object Relational Mapping (ORM) library called "Eloquent". The new DBAL is based on the PHP Data Objects (PDO MySQL) extension and uses WHMCS's existing <tt>configuration.php</tt> file. No configuration file changes are required to use the new database connection.

The Capsule DBAL component introduces two libraries to WHMCS, a query manager for running database queries and a schema manager for an abstracted API to table management. Capsule's underlying PDO connection is also available for advanced database usage. Capsule has three static methods to get to these components:

* '''Capsule::table(string $tableName)''': Access the query manager for the given table.
* '''Capsule::schema()''': Access the schema manager for the WHMCS database.
* '''Capsule::connection()''': Access the connection manager to interact with the underlying database connection.

'''Note:''' WHMCS 6.0 makes two connections to the database. One connection is made through the legacy mysql extension to handle existing hooks, modules, and other customizations. The other connection is made by PDO to drive new DBAL and model based functionality in the program.

==Deprecated functionality==

The current [[SQL Helper Functions]] are present in WHMCS 6.0 and above, but are now deprecated and may be removed in a later version of the product:
* '''select_query()'''
* '''update_query()'''
* '''insert_query()'''
* '''full_query()'''

The mysql extension driven database connection is now deprecated and may be discontinued in a later version of the product. WHMCS encourages all third party developers to use the Capsule DBAL and PDO connection for all new database interaction.

=Using Capsule=

Declare an alias to Laravel's database manager in your project file's <tt>use</tt> block to access Capsule:

<syntaxhighlight lang="php">
<?php

use Illuminate\Database\Capsule\Manager as Capsule;

// Run queries or modify tables as you like.
</syntaxhighlight>

==The Query Manager==

: ''Please see [https://laravel.com/docs/5.2/queries Laravel's query documentation] for more information.''

The '''Capsule::table(string $tableName)''' method provides access to the query manager. Declare it with the name of the table you wish to query as it's first parameter to interact with that table. The query manager has a wide range of functionality to perform advanced select, join, insert, update, and delete statements. Capsule's select calls return rows as ''stdClass'' objects.

Capsule escapes all input, so it is not necessary to add escaping slashes to variables passed to these methods.

All of Capsule's methods throw an exception on failure. Please place Capusle calls in <tt>try</tt>/<tt>catch</tt> blocks for graceful error handling and to avoid potential fatal errors in your hook, module, or other customization.

<syntaxhighlight lang="php">
<?php

use Illuminate\Database\Capsule\Manager as Capsule;

// Print all client first names using a simple select.

/** @var stdClass $client */
foreach (Capsule::table('tblclients')->get() as $client) {
echo $client->firstname . PHP_EOL;
}

// Rename all clients named "John Deo" to "John Doe" using an update statement.
try {
$updatedUserCount = Capsule::table('tblclients')
->where('firstname', 'John')
->where('lastname', 'Deo')
->update(
[
'lastname' => 'Doe',
]
);

echo "Fixed {$updatedUserCount} misspelled last names.";
} catch (\Exception $e) {
echo "I couldn't update client names. {$e->getMessage()}";
}
</syntaxhighlight>

==The Schema Manager==

Use the '''Capsule::schema()''' method to access the schema manager to modify table schema if necessary. The schema manager has support for creating, dropping and truncating tables and for modifying columns, indexes, and keys.

'''Note''': WHMCS does not recommend changing default table schema as that can affect product functionality.

<syntaxhighlight lang="php">
<?php

use Illuminate\Database\Capsule\Manager as Capsule;

// Create a new table.
try {
Capsule::schema()->create(
'my_table',
function ($table) {
/** @var \Illuminate\Database\Schema\Blueprint $table */
$table->increments('id');
$table->string('name');
$table->integer('serial_number');
$table->boolean('is_required');
$table->timestamps();
}
);
} catch (\Exception $e) {
echo "Unable to create my_table: {$e->getMessage()}";
}
</syntaxhighlight>

==The Connection Manager==

The '''Capsule::connection()''' method provides low-level access to the database connection itself. Use it to initiate transactions with automatic commit and rollback or to access the underlying PDO connection to perform manual database queries outside the DBAL. The connection manager also has methods to retrieve query and schema managers.

<syntaxhighlight lang="php">
<?php

use Illuminate\Database\Capsule\Manager as Capsule;

// Perform potentially risky queries in a transaction for easy rollback.
try {
Capsule::connection()->transaction(
function ($connectionManager)
{
/** @var \Illuminate\Database\Connection $connectionManager */
$connectionManager->table('my_table')->insert(
[
'name' => $_POST['name'],
'serial_number' => $_POST['serialNumber'],
'is_required' => (int)(bool) $_POST['isRequired'],
]
);
}
);
} catch (\Exception $e) {
echo "Uh oh! Inserting didn't work, but I was able to rollback. {$e->getMessage()}";
}
</syntaxhighlight>

===Getting to PDO===

Use the connection manager's '''getPdo()''' method to retrieve the underlying PDO connection instance. Use the PDO connection to perform manual queries and advanced database usage.

<syntaxhighlight lang="php">
<?php

use Illuminate\Database\Capsule\Manager as Capsule;

// Perform potentially risky queries in a transaction for easy rollback.
$pdo = Capsule::connection()->getPdo();
$pdo->beginTransaction();

try {
$statement = $pdo->prepare(
'insert into my_table (name, serial_number, is_required) values (:name, :serialNumber, :isRequired)'
);

$statement->execute(
[
':name' => $_POST['name'],
':serialNumber' => $_POST['serialNumber'],
':isRequired' => (bool) $_POST['isRequired'],
]
);

$pdo->commit();
} catch (\Exception $e) {
echo "Uh oh! {$e->getMessage()}";
$pdo->rollBack();
}
</syntaxhighlight>

=Troubleshooting=

==Exceptions==

All Capsule methods throw an exception on failure. Catch these exceptions and analyze their messages and stack traces to help determine the nature of the failure. WHMCS recommends placing all database interactivity in <tt>try</tt>/<tt>catch</tt> blocks for graceful error handling.

==The Capsule Query Log==

The connection manager's '''getQueryLog()''' method returns an array of all queries made during the life of the page request. Queries are stored in the log as an array containing the query run, the parameter bindings passed to the query, and the time it took for the query to execute, measured in milliseconds.

<syntaxhighlight lang="php">
<?php

use Illuminate\Database\Capsule\Manager as Capsule;

// Loop through each Capsule query made during the page request.
foreach (Capsule::connection()->getQueryLog() as $query) {
echo "Query: {$query['query']}" . PHP_EOL;
echo "Execution Time: {$query['time']}ms" . PHP_EOL;
echo "Parameters: " . PHP_EOL;

foreach ($query['bindings'] as $key => $value) {
echo "{$key} => {$value}" . PHP_EOL;
}
}
</syntaxhighlight>

==The WHMCS Activity Log==

All uncaught PDO-based query failures, including those made by Capsule and manual PDO queries, are written to to the WHMCS activity log. View the system activity log to view the details of these failed queries.

=See Also=
* [[SQL Helper Functions]] (functional, but deprecated in WHMCS 6.0)

=External Links=
* [http://laravel.com/docs/4.2/queries Query Builder - Laravel 4.2]
* [http://laravel.com/docs/4.2/schema Schema Builder - Laravel 4.2]
* [http://php.net/manual/en/book.pdo.php PHP: PDO]

=References=
<references />

Interacting With The Database

2016-07-11T16:01:43Z

Nicolas: /* The Query Manager */

=Database connectivity changes in WHMCS 6.0=

The mysql PHP extension was deprecated when PHP 5.5 was released in June 2013<ref>http://php.net/ChangeLog-5.php#5.5.0</ref> and is scheduled to be removed in PHP 7<ref>https://wiki.php.net/rfc/remove_deprecated_functionality_in_php7</ref>. WHMCS 6.0 introduces a new database connection and library to ensure compatibility with modern PHP environments and best practices.

==New functionality==

WHMCS 6.0 incorporates the Laravel framework 4.1's database component. This library includes a Database Abstraction Layer (DBAL) called "Capsule" and an Object Relational Mapping (ORM) library called "Eloquent". The new DBAL is based on the PHP Data Objects (PDO MySQL) extension and uses WHMCS's existing <tt>configuration.php</tt> file. No configuration file changes are required to use the new database connection.

The Capsule DBAL component introduces two libraries to WHMCS, a query manager for running database queries and a schema manager for an abstracted API to table management. Capsule's underlying PDO connection is also available for advanced database usage. Capsule has three static methods to get to these components:

* '''Capsule::table(string $tableName)''': Access the query manager for the given table.
* '''Capsule::schema()''': Access the schema manager for the WHMCS database.
* '''Capsule::connection()''': Access the connection manager to interact with the underlying database connection.

'''Note:''' WHMCS 6.0 makes two connections to the database. One connection is made through the legacy mysql extension to handle existing hooks, modules, and other customizations. The other connection is made by PDO to drive new DBAL and model based functionality in the program.

==Deprecated functionality==

The current [[SQL Helper Functions]] are present in WHMCS 6.0 and above, but are now deprecated and may be removed in a later version of the product:
* '''select_query()'''
* '''update_query()'''
* '''insert_query()'''
* '''full_query()'''

The mysql extension driven database connection is now deprecated and may be discontinued in a later version of the product. WHMCS encourages all third party developers to use the Capsule DBAL and PDO connection for all new database interaction.

=Using Capsule=

Declare an alias to Laravel's database manager in your project file's <tt>use</tt> block to access Capsule:

<syntaxhighlight lang="php">
<?php

use Illuminate\Database\Capsule\Manager as Capsule;

// Run queries or modify tables as you like.
</syntaxhighlight>

==The Query Manager==

: ''Please see [https://laravel.com/docs/5.2/queries Laravel's query documentation] for more information.''

The '''Capsule::table(string $tableName)''' method provides access to the query manager. Declare it with the name of the table you wish to query as it's first parameter to interact with that table. The query manager has a wide range of functionality to perform advanced select, join, insert, update, and delete statements. Capsule's select calls return rows as ''stdClass'' objects.

Capsule escapes all input, so it is not necessary to add escaping slashes to variables passed to these methods.

All of Capsule's methods throw an exception on failure. Please place Capusle calls in <tt>try</tt>/<tt>catch</tt> blocks for graceful error handling and to avoid potential fatal errors in your hook, module, or other customization.

<syntaxhighlight lang="php">
<?php

use Illuminate\Database\Capsule\Manager as Capsule;

// Print all client first names using a simple select.

/** @var stdClass $client */
foreach (Capsule::table('tblclients')->get() as $client) {
echo $client->firstname . PHP_EOL;
}

// Rename all clients named "John Deo" to "John Doe" using an update statement.
try {
$updatedUserCount = Capsule::table('tblclients')
->where('firstname', 'John')
->where('lastname', 'Deo')
->update(
[
'lastname' => 'Doe',
]
);

echo "Fixed {$updatedUserCount} misspelled last names.";
} catch (\Exception $e) {
echo "I couldn't update client names. {$e->getMessage()}";
}
</syntaxhighlight>

==The Schema Manager==

Use the '''Capsule::schema()''' method to access the schema manager to modify table schema if necessary. The schema manager has support for creating, dropping and truncating tables and for modifying columns, indexes, and keys.

'''Note''': WHMCS does not recommend changing default table schema as that can affect product functionality.

<syntaxhighlight lang="php">
<?php

use Illuminate\Database\Capsule\Manager as Capsule;

// Create a new table.
try {
Capsule::schema()->create(
'my_table',
function ($table) {
/** @var \Illuminate\Database\Schema\Blueprint $table */
$table->increments('id');
$table->string('name');
$table->integer('serial_number');
$table->boolean('is_required');
$table->timestamps();
}
);
} catch (\Exception $e) {
echo "Unable to create my_table: {$e->getMessage()}";
}
</syntaxhighlight>

==The Connection Manager==

The '''Capsule::connection()''' method provides low-level access to the database connection itself. Use it to initiate transactions with automatic commit and rollback or to access the underlying PDO connection to perform manual database queries outside the DBAL. The connection manager also has methods to retrieve query and schema managers.

<syntaxhighlight lang="php">
<?php

use Illuminate\Database\Capsule\Manager as Capsule;

// Perform potentially risky queries in a transaction for easy rollback.
try {
Capsule::connection()->transaction(
function ($connectionManager)
{
/** @var \Illuminate\Database\Connection $connectionManager */
$connectionManager->table('my_table')->insert(
[
'name' => $_POST['name'],
'serial_number' => $_POST['serialNumber'],
'is_required' => (int)(bool) $_POST['isRequired'],
]
);
}
);
} catch (\Exception $e) {
echo "Uh oh! Inserting didn't work, but I was able to rollback. {$e->getMessage()}";
}
</syntaxhighlight>

===Getting to PDO===

Use the connection manager's '''getPdo()''' method to retrieve the underlying PDO connection instance. Use the PDO connection to perform manual queries and advanced database usage.

<syntaxhighlight lang="php">
<?php

use Illuminate\Database\Capsule\Manager as Capsule;

// Perform potentially risky queries in a transaction for easy rollback.
$pdo = Capsule::connection()->getPdo();
$pdo->beginTransaction();

try {
$statement = $pdo->prepare(
'insert into my_table (name, serial_number, is_required) values (:name, :serialNumber, :isRequired)'
);

$statement->execute(
[
':name' => $_POST['name'],
':serialNumber' => $_POST['serialNumber'],
':isRequired' => (bool) $_POST['isRequired'],
]
);

$pdo->commit();
} catch (\Exception $e) {
echo "Uh oh! {$e->getMessage()}";
$pdo->rollBack();
}
</syntaxhighlight>

=Troubleshooting=

==Exceptions==

All Capsule methods throw an exception on failure. Catch these exceptions and analyze their messages and stack traces to help determine the nature of the failure. WHMCS recommends placing all database interactivity in <tt>try</tt>/<tt>catch</tt> blocks for graceful error handling.

==The Capsule Query Log==

The connection manager's '''getQueryLog()''' method returns an array of all queries made during the life of the page request. Queries are stored in the log as an array containing the query run, the parameter bindings passed to the query, and the time it took for the query to execute, measured in milliseconds.

<syntaxhighlight lang="php">
<?php

use Illuminate\Database\Capsule\Manager as Capsule;

// Loop through each Capsule query made during the page request.
foreach (Capsule::connection()->getQueryLog() as $query) {
echo "Query: {$query['query']}" . PHP_EOL;
echo "Execution Time: {$query['time']}ms" . PHP_EOL;
echo "Parameters: " . PHP_EOL;

foreach ($query['bindings'] as $key => $value) {
echo "{$key} => {$value}" . PHP_EOL;
}
}
</syntaxhighlight>

==The WHMCS Activity Log==

All uncaught PDO-based query failures, including those made by Capsule and manual PDO queries, are written to to the WHMCS activity log. View the system activity log to view the details of these failed queries.

=See Also=
* [[SQL Helper Functions]] (functional, but deprecated in WHMCS 6.0)

=External Links=
* [http://laravel.com/docs/4.2/queries Query Builder - Laravel 4.2]
* [http://laravel.com/docs/4.2/schema Schema Builder - Laravel 4.2]
* [http://php.net/manual/en/book.pdo.php PHP: PDO]

=References=
<references />

Client Email Verification

2016-03-08T16:27:17Z

Nicolas:

'''Email Verification''' is an optional feature which allows admins to request that users confirm their email addresses on signup or change of email address. This adds a layer of security when manually accepting client orders, as well as ensuring that correct information is provided. To enable email verification, navigate to ''Setup >> General Settings >> Security tab''. Tick the '''Email Verification''' checkbox and save the changes.

[[File:Enable_email_verification.png|center|850x250px|Enable email verification in general settings]]

When viewing the '''Client Profile''' page, a warning banner displays notifying admins if that specific client has an unverified email address on file. By clicking the '''Resend Verification Email''' button, a new verification email is sent to the client, which contains a link that is valid for 24 hours and invalidates the previous link. No banner will display after the client has verified their email address. A similar banner displays on the Manage Orders page, with the same option to resend the verification email, advising the admin when the email address on file has not been verified.

[[File:Client_profile_verification_banner.png|400x150px|Client profile verification banner]]
[[File:Manage_orders_verification_banner.png|400x150px|Manage orders client verification status]]

A badge will also display alongside the client's email address throughout the admin backend denoting whether the client's email address is verified or not.
[[File:Unverified_badge.png|right|400x250px|Unverified email badge]]
[[File:Verified_badge.png|400x250px|Verified email badge]]

The client will be able to log into their account associated with the unverified email address, however, a banner reminding them to take action will display, as well as the '''Resend Verification Email''' button. No functionality is limited in the client area for clients with an unverified email address.

[[File:Client_verification_banner.png|center|850x250px|Email verification banner on client side]]

Clicking the '''Resend Verification Email''' button sends an email with a link that is valid for 24 hours. If the link is followed after the 24 hour window or if the button is clicked (which invalidates the previous link), then an error will display when the client tries to log in, but they will be allowed to generate and send a new email once they authenticate.

[[File:Expired_verification_warning.png|200x150px|Expired verification key warning]][[File:Expired_verification_banner.png|400x150px|Expired verification key banner]]

Upon the client following the link sent in the verification email, the client will be required to log into the client area. Even if the client is already logged in, they will be required to re-authenticate. Once logged in, the client will see a success message on the first page.

[[File:Verified_banner.png|850x250px|Verified email successfully]]

In the admin area, the email verification banner will no longer be present and a Verified badge will display alongside the client's email address.

[[File:Verified_client_profile.png|850x250px|Verified email in client profile view]]

Changing of the email address, whether via the admin interface or in the client area will cause the email verification banner and Unverified badge to re-appear.

'''Email Verification''' is a useful optional feature which assists admins in judging whether to manually accept an order and encourages correct information from clients. While no functionality is limited in the client area for clients with unverified email addresses, the verification email's link is masked when viewing email history in the client area. The link is not masked when viewing the email from the admin area.

Gateway Module Developer Docs

2016-01-06T20:50:50Z

Nicolas: /* App Store */

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)

{{Developer_Links}}

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 [[#Module Type|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.

<div class="docs-alert-info">
All functions within a gateway module must be prefixed with the filename. Open the file and replace all occurrences of '''template_''' with '''yougatewayname_'''
</div>

===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:
#Specify a system name (''all in lowercase for the setting to be referenced by in the module code itself'')
#A FriendlyName
#Type
#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:

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

<div class="docs-alert-warning">The '''_capture''' function must be deleted before activating the new gateway module in WHMCS.</div>

# Delete the '''_capture''' function from the module template.
# 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===
<source lang="php">
$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...)
</source>

===Client Variables===
<source lang="php">
$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']
</source>

===System Variables===
<source lang = "php">
$params['companyname'] # your Company Name setting in WHMCS
$params['systemurl'] # the url to the Client Area
</source>

# The processing of a payment is handled by a callback file separate from the module (see page 9 for more information).
# 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:

<div class="docs-alert-warning">
The '''_link''' function must be deleted before activating the new gateway module in WHMCS.
</div>

# Delete the '''_link''' function from the module template.
# 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===
<source lang="php">
$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...)
</source>

===Client Variables===
<source lang = "php">
$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']
</source>

===System Variables===
<source lang="php">
$params['companyname'] # your Company Name setting in WHMCS
$params['systemurl'] # the url to the Client Area
</source>

===Card Details===
<source lang = "php">
$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
</source>

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

<source lang="php">
return array(
"status" => "success",
"transid" => $results["transid"],
"rawdata" => $results,
);
</source>

# The status index ''must be'' '''success''' to tell WHMCS that the capture was successful.
# The transid index should be passed the value of the transaction ID that came back from the gateway.
# 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:

<source lang="php">
return array(
"status" => "declined",
"rawdata" => $results,
);
</source>

# 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.
# 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===

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

<source lang="php">
$params['transid'] # the transaction ID of the original transaction to be refunded
</source>

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

<div class="docs-alert-danger">
If the gateway provider does not support refunds, then the '''_refund''' function should be deleted from the module file.
</div>

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

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

These are some helper functions within the sample:

<source lang="php">
$GATEWAY = getGatewayVariables(‘yourgatewayname’);
</source>

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.

<source lang="php">
$invoiceid = checkCbInvoiceID($invoiceid, $GATEWAY[‘name’]);
</source>

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.

<source lang ="php">
checkCbTransID($transid);
</source>

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.

<source lang="php">
logTransaction($GATEWAY[‘name’], $_POST, "Successful");
</source>

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.

# Add a function to the module named '''yourgatewayname_3dsecure'''
# 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==
<source lang = "php">
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;
}
</source>

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

<source lang ="php">
$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)
</source>

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:

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

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

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.

<div class="docs-alert-warning">
'''Important:''' It is important that the gateway is not activated until step 1 has been completed for both the third party gateway or the merchant gateway modules, because the type of module created is stored in the database upon activation.
</div>

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

<source lang="php">
$display_errors = true;
</source>

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 [https://www.whmcs.com/members/submitticket.php?step=2&deptid=5 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.

{{Developer_Links}}

Gateway Module Developer Docs

2016-01-06T20:49:54Z

Nicolas: /* Blank Screen/Errors */

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)

{{Developer_Links}}

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 [[#Module Type|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.

<div class="docs-alert-info">
All functions within a gateway module must be prefixed with the filename. Open the file and replace all occurrences of '''template_''' with '''yougatewayname_'''
</div>

===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:
#Specify a system name (''all in lowercase for the setting to be referenced by in the module code itself'')
#A FriendlyName
#Type
#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:

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

<div class="docs-alert-warning">The '''_capture''' function must be deleted before activating the new gateway module in WHMCS.</div>

# Delete the '''_capture''' function from the module template.
# 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===
<source lang="php">
$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...)
</source>

===Client Variables===
<source lang="php">
$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']
</source>

===System Variables===
<source lang = "php">
$params['companyname'] # your Company Name setting in WHMCS
$params['systemurl'] # the url to the Client Area
</source>

# The processing of a payment is handled by a callback file separate from the module (see page 9 for more information).
# 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:

<div class="docs-alert-warning">
The '''_link''' function must be deleted before activating the new gateway module in WHMCS.
</div>

# Delete the '''_link''' function from the module template.
# 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===
<source lang="php">
$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...)
</source>

===Client Variables===
<source lang = "php">
$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']
</source>

===System Variables===
<source lang="php">
$params['companyname'] # your Company Name setting in WHMCS
$params['systemurl'] # the url to the Client Area
</source>

===Card Details===
<source lang = "php">
$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
</source>

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

<source lang="php">
return array(
"status" => "success",
"transid" => $results["transid"],
"rawdata" => $results,
);
</source>

# The status index ''must be'' '''success''' to tell WHMCS that the capture was successful.
# The transid index should be passed the value of the transaction ID that came back from the gateway.
# 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:

<source lang="php">
return array(
"status" => "declined",
"rawdata" => $results,
);
</source>

# 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.
# 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===

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

<source lang="php">
$params['transid'] # the transaction ID of the original transaction to be refunded
</source>

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

<div class="docs-alert-danger">
If the gateway provider does not support refunds, then the '''_refund''' function should be deleted from the module file.
</div>

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

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

These are some helper functions within the sample:

<source lang="php">
$GATEWAY = getGatewayVariables(‘yourgatewayname’);
</source>

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.

<source lang="php">
$invoiceid = checkCbInvoiceID($invoiceid, $GATEWAY[‘name’]);
</source>

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.

<source lang ="php">
checkCbTransID($transid);
</source>

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.

<source lang="php">
logTransaction($GATEWAY[‘name’], $_POST, "Successful");
</source>

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.

# Add a function to the module named '''yourgatewayname_3dsecure'''
# 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==
<source lang = "php">
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;
}
</source>

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

<source lang ="php">
$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)
</source>

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:

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

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

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.

<div class="docs-alert-warning">
'''Important:''' It is important that the gateway is not activated until step 1 has been completed for both the third party gateway or the merchant gateway modules, because the type of module created is stored in the database upon activation.
</div>

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

<source lang="php">
$display_errors = true;
</source>

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 [https://www.whmcs.com/members/submitticket.php?step=2&deptid=5 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.

{{Developer_Links}}

Gateway Module Developer Docs

2016-01-06T20:47:51Z

Nicolas: /* Installation & Activation */

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)

{{Developer_Links}}

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 [[#Module Type|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.

<div class="docs-alert-info">
All functions within a gateway module must be prefixed with the filename. Open the file and replace all occurrences of '''template_''' with '''yougatewayname_'''
</div>

===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:
#Specify a system name (''all in lowercase for the setting to be referenced by in the module code itself'')
#A FriendlyName
#Type
#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:

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

<div class="docs-alert-warning">The '''_capture''' function must be deleted before activating the new gateway module in WHMCS.</div>

# Delete the '''_capture''' function from the module template.
# 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===
<source lang="php">
$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...)
</source>

===Client Variables===
<source lang="php">
$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']
</source>

===System Variables===
<source lang = "php">
$params['companyname'] # your Company Name setting in WHMCS
$params['systemurl'] # the url to the Client Area
</source>

# The processing of a payment is handled by a callback file separate from the module (see page 9 for more information).
# 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:

<div class="docs-alert-warning">
The '''_link''' function must be deleted before activating the new gateway module in WHMCS.
</div>

# Delete the '''_link''' function from the module template.
# 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===
<source lang="php">
$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...)
</source>

===Client Variables===
<source lang = "php">
$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']
</source>

===System Variables===
<source lang="php">
$params['companyname'] # your Company Name setting in WHMCS
$params['systemurl'] # the url to the Client Area
</source>

===Card Details===
<source lang = "php">
$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
</source>

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

<source lang="php">
return array(
"status" => "success",
"transid" => $results["transid"],
"rawdata" => $results,
);
</source>

# The status index ''must be'' '''success''' to tell WHMCS that the capture was successful.
# The transid index should be passed the value of the transaction ID that came back from the gateway.
# 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:

<source lang="php">
return array(
"status" => "declined",
"rawdata" => $results,
);
</source>

# 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.
# 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===

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

<source lang="php">
$params['transid'] # the transaction ID of the original transaction to be refunded
</source>

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

<div class="docs-alert-danger">
If the gateway provider does not support refunds, then the '''_refund''' function should be deleted from the module file.
</div>

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

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

These are some helper functions within the sample:

<source lang="php">
$GATEWAY = getGatewayVariables(‘yourgatewayname’);
</source>

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.

<source lang="php">
$invoiceid = checkCbInvoiceID($invoiceid, $GATEWAY[‘name’]);
</source>

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.

<source lang ="php">
checkCbTransID($transid);
</source>

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.

<source lang="php">
logTransaction($GATEWAY[‘name’], $_POST, "Successful");
</source>

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.

# Add a function to the module named '''yourgatewayname_3dsecure'''
# 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==
<source lang = "php">
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;
}
</source>

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

<source lang ="php">
$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)
</source>

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:

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

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

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.

<div class="docs-alert-warning">
'''Important:''' It is important that the gateway is not activated until step 1 has been completed for both the third party gateway or the merchant gateway modules, because the type of module created is stored in the database upon activation.
</div>

==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:
<source lang="php">
$display_errors = true;
</source>

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 [https://www.whmcs.com/members/submitticket.php?step=2&deptid=5 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.

{{Developer_Links}}

Gateway Module Developer Docs

2016-01-06T20:44:04Z

Nicolas: /* Tokenised Remote Storage */

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)

{{Developer_Links}}

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 [[#Module Type|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.

<div class="docs-alert-info">
All functions within a gateway module must be prefixed with the filename. Open the file and replace all occurrences of '''template_''' with '''yougatewayname_'''
</div>

===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:
#Specify a system name (''all in lowercase for the setting to be referenced by in the module code itself'')
#A FriendlyName
#Type
#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:

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

<div class="docs-alert-warning">The '''_capture''' function must be deleted before activating the new gateway module in WHMCS.</div>

# Delete the '''_capture''' function from the module template.
# 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===
<source lang="php">
$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...)
</source>

===Client Variables===
<source lang="php">
$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']
</source>

===System Variables===
<source lang = "php">
$params['companyname'] # your Company Name setting in WHMCS
$params['systemurl'] # the url to the Client Area
</source>

# The processing of a payment is handled by a callback file separate from the module (see page 9 for more information).
# 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:

<div class="docs-alert-warning">
The '''_link''' function must be deleted before activating the new gateway module in WHMCS.
</div>

# Delete the '''_link''' function from the module template.
# 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===
<source lang="php">
$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...)
</source>

===Client Variables===
<source lang = "php">
$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']
</source>

===System Variables===
<source lang="php">
$params['companyname'] # your Company Name setting in WHMCS
$params['systemurl'] # the url to the Client Area
</source>

===Card Details===
<source lang = "php">
$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
</source>

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

<source lang="php">
return array(
"status" => "success",
"transid" => $results["transid"],
"rawdata" => $results,
);
</source>

# The status index ''must be'' '''success''' to tell WHMCS that the capture was successful.
# The transid index should be passed the value of the transaction ID that came back from the gateway.
# 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:

<source lang="php">
return array(
"status" => "declined",
"rawdata" => $results,
);
</source>

# 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.
# 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===

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

<source lang="php">
$params['transid'] # the transaction ID of the original transaction to be refunded
</source>

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

<div class="docs-alert-danger">
If the gateway provider does not support refunds, then the '''_refund''' function should be deleted from the module file.
</div>

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

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

These are some helper functions within the sample:

<source lang="php">
$GATEWAY = getGatewayVariables(‘yourgatewayname’);
</source>

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.

<source lang="php">
$invoiceid = checkCbInvoiceID($invoiceid, $GATEWAY[‘name’]);
</source>

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.

<source lang ="php">
checkCbTransID($transid);
</source>

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.

<source lang="php">
logTransaction($GATEWAY[‘name’], $_POST, "Successful");
</source>

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.

# Add a function to the module named '''yourgatewayname_3dsecure'''
# 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==
<source lang = "php">
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;
}
</source>

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

<source lang ="php">
$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)
</source>

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:

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

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

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 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:
<source lang="php">
$display_errors = true;
</source>

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 [https://www.whmcs.com/members/submitticket.php?step=2&deptid=5 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.

{{Developer_Links}}

Gateway Module Developer Docs

2016-01-06T20:39:17Z

Nicolas: /* 3D Secure Process */

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)

{{Developer_Links}}

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 [[#Module Type|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.

<div class="docs-alert-info">
All functions within a gateway module must be prefixed with the filename. Open the file and replace all occurrences of '''template_''' with '''yougatewayname_'''
</div>

===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:
#Specify a system name (''all in lowercase for the setting to be referenced by in the module code itself'')
#A FriendlyName
#Type
#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:

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

<div class="docs-alert-warning">The '''_capture''' function must be deleted before activating the new gateway module in WHMCS.</div>

# Delete the '''_capture''' function from the module template.
# 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===
<source lang="php">
$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...)
</source>

===Client Variables===
<source lang="php">
$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']
</source>

===System Variables===
<source lang = "php">
$params['companyname'] # your Company Name setting in WHMCS
$params['systemurl'] # the url to the Client Area
</source>

# The processing of a payment is handled by a callback file separate from the module (see page 9 for more information).
# 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:

<div class="docs-alert-warning">
The '''_link''' function must be deleted before activating the new gateway module in WHMCS.
</div>

# Delete the '''_link''' function from the module template.
# 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===
<source lang="php">
$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...)
</source>

===Client Variables===
<source lang = "php">
$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']
</source>

===System Variables===
<source lang="php">
$params['companyname'] # your Company Name setting in WHMCS
$params['systemurl'] # the url to the Client Area
</source>

===Card Details===
<source lang = "php">
$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
</source>

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

<source lang="php">
return array(
"status" => "success",
"transid" => $results["transid"],
"rawdata" => $results,
);
</source>

# The status index ''must be'' '''success''' to tell WHMCS that the capture was successful.
# The transid index should be passed the value of the transaction ID that came back from the gateway.
# 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:

<source lang="php">
return array(
"status" => "declined",
"rawdata" => $results,
);
</source>

# 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.
# 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===

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

<source lang="php">
$params['transid'] # the transaction ID of the original transaction to be refunded
</source>

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

<div class="docs-alert-danger">
If the gateway provider does not support refunds, then the '''_refund''' function should be deleted from the module file.
</div>

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

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

These are some helper functions within the sample:

<source lang="php">
$GATEWAY = getGatewayVariables(‘yourgatewayname’);
</source>

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.

<source lang="php">
$invoiceid = checkCbInvoiceID($invoiceid, $GATEWAY[‘name’]);
</source>

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.

<source lang ="php">
checkCbTransID($transid);
</source>

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.

<source lang="php">
logTransaction($GATEWAY[‘name’], $_POST, "Successful");
</source>

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.

# Add a function to the module named '''yourgatewayname_3dsecure'''
# 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==
<source lang = "php">
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;
}
</source>

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

<source lang ="php">
$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)
</source>

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:

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

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

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:
<source lang="php">
$display_errors = true;
</source>

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 [https://www.whmcs.com/members/submitticket.php?step=2&deptid=5 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.

{{Developer_Links}}

Gateway Module Developer Docs

2016-01-06T20:35:51Z

Nicolas: /* Callbacks */

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)

{{Developer_Links}}

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 [[#Module Type|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.

<div class="docs-alert-info">
All functions within a gateway module must be prefixed with the filename. Open the file and replace all occurrences of '''template_''' with '''yougatewayname_'''
</div>

===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:
#Specify a system name (''all in lowercase for the setting to be referenced by in the module code itself'')
#A FriendlyName
#Type
#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:

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

<div class="docs-alert-warning">The '''_capture''' function must be deleted before activating the new gateway module in WHMCS.</div>

# Delete the '''_capture''' function from the module template.
# 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===
<source lang="php">
$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...)
</source>

===Client Variables===
<source lang="php">
$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']
</source>

===System Variables===
<source lang = "php">
$params['companyname'] # your Company Name setting in WHMCS
$params['systemurl'] # the url to the Client Area
</source>

# The processing of a payment is handled by a callback file separate from the module (see page 9 for more information).
# 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:

<div class="docs-alert-warning">
The '''_link''' function must be deleted before activating the new gateway module in WHMCS.
</div>

# Delete the '''_link''' function from the module template.
# 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===
<source lang="php">
$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...)
</source>

===Client Variables===
<source lang = "php">
$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']
</source>

===System Variables===
<source lang="php">
$params['companyname'] # your Company Name setting in WHMCS
$params['systemurl'] # the url to the Client Area
</source>

===Card Details===
<source lang = "php">
$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
</source>

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

<source lang="php">
return array(
"status" => "success",
"transid" => $results["transid"],
"rawdata" => $results,
);
</source>

# The status index ''must be'' '''success''' to tell WHMCS that the capture was successful.
# The transid index should be passed the value of the transaction ID that came back from the gateway.
# 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:

<source lang="php">
return array(
"status" => "declined",
"rawdata" => $results,
);
</source>

# 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.
# 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===

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

<source lang="php">
$params['transid'] # the transaction ID of the original transaction to be refunded
</source>

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

<div class="docs-alert-danger">
If the gateway provider does not support refunds, then the '''_refund''' function should be deleted from the module file.
</div>

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

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

These are some helper functions within the sample:

<source lang="php">
$GATEWAY = getGatewayVariables(‘yourgatewayname’);
</source>

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.

<source lang="php">
$invoiceid = checkCbInvoiceID($invoiceid, $GATEWAY[‘name’]);
</source>

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.

<source lang ="php">
checkCbTransID($transid);
</source>

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.

<source lang="php">
logTransaction($GATEWAY[‘name’], $_POST, "Successful");
</source>

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 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==
<source lang = "php">
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;
}
</source>

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

<source lang ="php">
$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)
</source>

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:

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

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

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:
<source lang="php">
$display_errors = true;
</source>

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 [https://www.whmcs.com/members/submitticket.php?step=2&deptid=5 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.

{{Developer_Links}}

Gateway Module Developer Docs

2016-01-06T20:19:33Z

Nicolas: /* Card Details */

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)

{{Developer_Links}}

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 [[#Module Type|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.

<div class="docs-alert-info">
All functions within a gateway module must be prefixed with the filename. Open the file and replace all occurrences of '''template_''' with '''yougatewayname_'''
</div>

===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:
#Specify a system name (''all in lowercase for the setting to be referenced by in the module code itself'')
#A FriendlyName
#Type
#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:

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

<div class="docs-alert-warning">The '''_capture''' function must be deleted before activating the new gateway module in WHMCS.</div>

# Delete the '''_capture''' function from the module template.
# 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===
<source lang="php">
$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...)
</source>

===Client Variables===
<source lang="php">
$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']
</source>

===System Variables===
<source lang = "php">
$params['companyname'] # your Company Name setting in WHMCS
$params['systemurl'] # the url to the Client Area
</source>

# The processing of a payment is handled by a callback file separate from the module (see page 9 for more information).
# 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:

<div class="docs-alert-warning">
The '''_link''' function must be deleted before activating the new gateway module in WHMCS.
</div>

# Delete the '''_link''' function from the module template.
# 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===
<source lang="php">
$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...)
</source>

===Client Variables===
<source lang = "php">
$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']
</source>

===System Variables===
<source lang="php">
$params['companyname'] # your Company Name setting in WHMCS
$params['systemurl'] # the url to the Client Area
</source>

===Card Details===
<source lang = "php">
$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
</source>

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

<source lang="php">
return array(
"status" => "success",
"transid" => $results["transid"],
"rawdata" => $results,
);
</source>

# The status index ''must be'' '''success''' to tell WHMCS that the capture was successful.
# The transid index should be passed the value of the transaction ID that came back from the gateway.
# 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:

<source lang="php">
return array(
"status" => "declined",
"rawdata" => $results,
);
</source>

# 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.
# 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===

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

<source lang="php">
$params['transid'] # the transaction ID of the original transaction to be refunded
</source>

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

<div class="docs-alert-danger">
If the gateway provider does not support refunds, then the '''_refund''' function should be deleted from the module file.
</div>

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

<source lang="php">
$GATEWAY = getGatewayVariables(‘yourgatewayname’);
</source>

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.

<source lang="php">
$invoiceid = checkCbInvoiceID($invoiceid,$GATEWAY[‘name’]);
</source>

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.

<source lang ="php">
checkCbTransID($transid);
</source>

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.

<source lang="php">
logTransaction($GATEWAY[‘name’],$_POST,"Successful");
</source>

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==
<source lang = "php">
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;
}
</source>

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

<source lang ="php">
$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)
</source>

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:

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

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

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:
<source lang="php">
$display_errors = true;
</source>

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 [https://www.whmcs.com/members/submitticket.php?step=2&deptid=5 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.

{{Developer_Links}}

Gateway Module Developer Docs

2016-01-06T20:18:29Z

Nicolas: /* Merchant Gateway */

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)

{{Developer_Links}}

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 [[#Module Type|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.

<div class="docs-alert-info">
All functions within a gateway module must be prefixed with the filename. Open the file and replace all occurrences of '''template_''' with '''yougatewayname_'''
</div>

===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:
#Specify a system name (''all in lowercase for the setting to be referenced by in the module code itself'')
#A FriendlyName
#Type
#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:

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

<div class="docs-alert-warning">The '''_capture''' function must be deleted before activating the new gateway module in WHMCS.</div>

# Delete the '''_capture''' function from the module template.
# 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===
<source lang="php">
$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...)
</source>

===Client Variables===
<source lang="php">
$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']
</source>

===System Variables===
<source lang = "php">
$params['companyname'] # your Company Name setting in WHMCS
$params['systemurl'] # the url to the Client Area
</source>

# The processing of a payment is handled by a callback file separate from the module (see page 9 for more information).
# 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:

<div class="docs-alert-warning">
The '''_link''' function must be deleted before activating the new gateway module in WHMCS.
</div>

# Delete the '''_link''' function from the module template.
# 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===
<source lang="php">
$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...)
</source>

===Client Variables===
<source lang = "php">
$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']
</source>

===System Variables===
<source lang="php">
$params['companyname'] # your Company Name setting in WHMCS
$params['systemurl'] # the url to the Client Area
</source>

===Card Details===
<source lang = "php">
$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
</source>

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

<source lang="php">
return array(
"status" => "success",
"transid" => $results["transid"],
"rawdata" => $results,
);
</source>

# The status index ''must be'' '''success''' to tell WHMCS that the capture was successful.
# The transid index should be passed the value of the transaction ID that came back from the gateway.
# 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:

<source lang="php">
return array(
"status" => "declined",
"rawdata" => $results,
);
</source>

# 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.
# 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===

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

<source lang="php">
$params['transid'] # the transaction ID of the original transaction to be refunded
</source>

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

<div class="docs-alert-danger">
If the gateway provider does not support refunds, then the '''_refund''' function should be deleted from the module file.
</div>

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

<source lang="php">
$GATEWAY = getGatewayVariables(‘yourgatewayname’);
</source>

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.

<source lang="php">
$invoiceid = checkCbInvoiceID($invoiceid,$GATEWAY[‘name’]);
</source>

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.

<source lang ="php">
checkCbTransID($transid);
</source>

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.

<source lang="php">
logTransaction($GATEWAY[‘name’],$_POST,"Successful");
</source>

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==
<source lang = "php">
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;
}
</source>

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

<source lang ="php">
$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)
</source>

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:

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

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

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:
<source lang="php">
$display_errors = true;
</source>

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 [https://www.whmcs.com/members/submitticket.php?step=2&deptid=5 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.

{{Developer_Links}}

Gateway Module Developer Docs

2016-01-06T20:09:23Z

Nicolas: /* Third Party Gateway */

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)

{{Developer_Links}}

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 [[#Module Type|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.

<div class="docs-alert-info">
All functions within a gateway module must be prefixed with the filename. Open the file and replace all occurrences of '''template_''' with '''yougatewayname_'''
</div>

===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:
#Specify a system name (''all in lowercase for the setting to be referenced by in the module code itself'')
#A FriendlyName
#Type
#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:

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

<div class="docs-alert-warning">The '''_capture''' function must be deleted before activating the new gateway module in WHMCS.</div>

# Delete the '''_capture''' function from the module template.
# 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===
<source lang="php">
$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...)
</source>

===Client Variables===
<source lang="php">
$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']
</source>

===System Variables===
<source lang = "php">
$params['companyname'] # your Company Name setting in WHMCS
$params['systemurl'] # the url to the Client Area
</source>

# The processing of a payment is handled by a callback file separate from the module (see page 9 for more information).
# 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:

<div class="docs-alert-warning">
The '''_link''' function must be deleted before activating the new gateway module in WHMCS.
</div>

# Delete the '''_link''' function from the module template.
# 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===
<source lang="php">
$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...)
</source>

===Client Variables===
<source lang = "php">
$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']
</source>

===System Variables===
<source lang="php">
$params['companyname'] # your Company Name setting in WHMCS
$params['systemurl'] # the url to the Client Area
</source>

===Card Details===
<source lang = "php">
$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
</source>

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

<source lang="php">
return array("status"=>"success","transid"=>$results["transid"],"rawdata"=>$results);
</source>

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:

<source lang="php">
return array("status"=>"declined","rawdata"=>$results);
</source>

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.

# 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===

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

<source lang="php">
$params['transid'] # the transaction ID of the original transaction to be refunded
</source>

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:

<source lang="php">
$GATEWAY = getGatewayVariables(‘yourgatewayname’);
</source>

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.

<source lang="php">
$invoiceid = checkCbInvoiceID($invoiceid,$GATEWAY[‘name’]);
</source>

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.

<source lang ="php">
checkCbTransID($transid);
</source>

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.

<source lang="php">
logTransaction($GATEWAY[‘name’],$_POST,"Successful");
</source>

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==
<source lang = "php">
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;
}
</source>

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

<source lang ="php">
$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)
</source>

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:

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

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

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:
<source lang="php">
$display_errors = true;
</source>

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 [https://www.whmcs.com/members/submitticket.php?step=2&deptid=5 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.

{{Developer_Links}}

Gateway Module Developer Docs

2016-01-06T20:08:56Z

Nicolas: /* Merchant Gateway */

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)

{{Developer_Links}}

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 [[#Module Type|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.

<div class="docs-alert-info">
All functions within a gateway module must be prefixed with the filename. Open the file and replace all occurrences of '''template_''' with '''yougatewayname_'''
</div>

===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:
#Specify a system name (''all in lowercase for the setting to be referenced by in the module code itself'')
#A FriendlyName
#Type
#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:

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

<div class="docs-alert-warning">The '''_capture''' function must be deleted before activating the gateway module in WHMCS.</div>

# Delete the '''_capture''' function from the module template.
# 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===
<source lang="php">
$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...)
</source>

===Client Variables===
<source lang="php">
$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']
</source>

===System Variables===
<source lang = "php">
$params['companyname'] # your Company Name setting in WHMCS
$params['systemurl'] # the url to the Client Area
</source>

# The processing of a payment is handled by a callback file separate from the module (see page 9 for more information).
# 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:

<div class="docs-alert-warning">
The '''_link''' function must be deleted before activating the new gateway module in WHMCS.
</div>

# Delete the '''_link''' function from the module template.
# 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===
<source lang="php">
$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...)
</source>

===Client Variables===
<source lang = "php">
$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']
</source>

===System Variables===
<source lang="php">
$params['companyname'] # your Company Name setting in WHMCS
$params['systemurl'] # the url to the Client Area
</source>

===Card Details===
<source lang = "php">
$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
</source>

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

<source lang="php">
return array("status"=>"success","transid"=>$results["transid"],"rawdata"=>$results);
</source>

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:

<source lang="php">
return array("status"=>"declined","rawdata"=>$results);
</source>

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.

# 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===

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

<source lang="php">
$params['transid'] # the transaction ID of the original transaction to be refunded
</source>

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:

<source lang="php">
$GATEWAY = getGatewayVariables(‘yourgatewayname’);
</source>

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.

<source lang="php">
$invoiceid = checkCbInvoiceID($invoiceid,$GATEWAY[‘name’]);
</source>

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.

<source lang ="php">
checkCbTransID($transid);
</source>

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.

<source lang="php">
logTransaction($GATEWAY[‘name’],$_POST,"Successful");
</source>

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==
<source lang = "php">
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;
}
</source>

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

<source lang ="php">
$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)
</source>

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:

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

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

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:
<source lang="php">
$display_errors = true;
</source>

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 [https://www.whmcs.com/members/submitticket.php?step=2&deptid=5 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.

{{Developer_Links}}

Gateway Module Developer Docs

2016-01-06T20:01:40Z

Nicolas: /* App Store */

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)

{{Developer_Links}}

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 [[#Module Type|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.

<div class="docs-alert-info">
All functions within a gateway module must be prefixed with the filename. Open the file and replace all occurrences of '''template_''' with '''yougatewayname_'''
</div>

===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:
#Specify a system name (''all in lowercase for the setting to be referenced by in the module code itself'')
#A FriendlyName
#Type
#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:

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

<div class="docs-alert-warning">The '''_capture''' function must be deleted before activating the gateway module in WHMCS.</div>

# Delete the '''_capture''' function from the module template.
# 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===
<source lang="php">
$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...)
</source>

===Client Variables===
<source lang="php">
$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']
</source>

===System Variables===
<source lang = "php">
$params['companyname'] # your Company Name setting in WHMCS
$params['systemurl'] # the url to the Client Area
</source>

# The processing of a payment is handled by a callback file separate from the module (see page 9 for more information).
# 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==

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.

# Begin by deleting the _link function from the module template (important: you must do this before activating your new gateway module in WHMCS)
# 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===
<source lang="php">
$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...)
</source>

===Client Variables===
<source lang = "php">
$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']
</source>

===# System Variables===
<source lang="php">
$params['companyname'] # your Company Name setting in WHMCS
$params['systemurl'] – the url to the Client Area
</source>

===Card Details===
<source lang = "php">
$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
</source>

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

<source lang="php">
return array("status"=>"success","transid"=>$results["transid"],"rawdata"=>$results);
</source>

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:

<source lang="php">
return array("status"=>"declined","rawdata"=>$results);
</source>

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.

# 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===

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

<source lang="php">
$params['transid'] # the transaction ID of the original transaction to be refunded
</source>

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:

<source lang="php">
$GATEWAY = getGatewayVariables(‘yourgatewayname’);
</source>

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.

<source lang="php">
$invoiceid = checkCbInvoiceID($invoiceid,$GATEWAY[‘name’]);
</source>

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.

<source lang ="php">
checkCbTransID($transid);
</source>

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.

<source lang="php">
logTransaction($GATEWAY[‘name’],$_POST,"Successful");
</source>

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==
<source lang = "php">
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;
}
</source>

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

<source lang ="php">
$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)
</source>

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:

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

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

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:
<source lang="php">
$display_errors = true;
</source>

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 [https://www.whmcs.com/members/submitticket.php?step=2&deptid=5 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.

{{Developer_Links}}

Gateway Module Developer Docs

2016-01-06T19:59:20Z

Nicolas: /* Third Party Gateway */

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)

{{Developer_Links}}

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 [[#Module Type|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.

<div class="docs-alert-info">
All functions within a gateway module must be prefixed with the filename. Open the file and replace all occurrences of '''template_''' with '''yougatewayname_'''
</div>

===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:
#Specify a system name (''all in lowercase for the setting to be referenced by in the module code itself'')
#A FriendlyName
#Type
#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:

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

<div class="docs-alert-warning">The '''_capture''' function must be deleted before activating the gateway module in WHMCS.</div>

# Delete the '''_capture''' function from the module template.
# 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===
<source lang="php">
$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...)
</source>

===Client Variables===
<source lang="php">
$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']
</source>

===System Variables===
<source lang = "php">
$params['companyname'] # your Company Name setting in WHMCS
$params['systemurl'] # the url to the Client Area
</source>

# The processing of a payment is handled by a callback file separate from the module (see page 9 for more information).
# 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==

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.

# Begin by deleting the _link function from the module template (important: you must do this before activating your new gateway module in WHMCS)
# 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===
<source lang="php">
$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...)
</source>

===Client Variables===
<source lang = "php">
$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']
</source>

===# System Variables===
<source lang="php">
$params['companyname'] # your Company Name setting in WHMCS
$params['systemurl'] – the url to the Client Area
</source>

===Card Details===
<source lang = "php">
$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
</source>

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

<source lang="php">
return array("status"=>"success","transid"=>$results["transid"],"rawdata"=>$results);
</source>

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:

<source lang="php">
return array("status"=>"declined","rawdata"=>$results);
</source>

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.

# 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===

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

<source lang="php">
$params['transid'] # the transaction ID of the original transaction to be refunded
</source>

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:

<source lang="php">
$GATEWAY = getGatewayVariables(‘yourgatewayname’);
</source>

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.

<source lang="php">
$invoiceid = checkCbInvoiceID($invoiceid,$GATEWAY[‘name’]);
</source>

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.

<source lang ="php">
checkCbTransID($transid);
</source>

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.

<source lang="php">
logTransaction($GATEWAY[‘name’],$_POST,"Successful");
</source>

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==
<source lang = "php">
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;
}
</source>

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

<source lang ="php">
$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)
</source>

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:

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

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

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:
<source lang="php">
$display_errors = true;
</source>

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 to which your completed module 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 [https://www.whmcs.com/members/submitticket.php?step=2&deptid=5 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.

{{Developer_Links}}

Gateway Module Developer Docs

2016-01-06T19:58:07Z

Nicolas: /* Getting Started */

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)

{{Developer_Links}}

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 [[#Module Type|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.

<div class="docs-alert-info">
All functions within a gateway module must be prefixed with the filename. Open the file and replace all occurrences of '''template_''' with '''yougatewayname_'''
</div>

===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:
#Specify a system name (''all in lowercase for the setting to be referenced by in the module code itself'')
#A FriendlyName
#Type
#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:

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

<div class="docs-alert-warning">'''Important:''' The '''_capture''' method must be deleted before activating the gateway module in WHMCS.</div>

# Delete the '''_capture''' function from the module template.
# 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===
<source lang="php">
$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...)
</source>

===Client Variables===
<source lang="php">
$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']
</source>

===System Variables===
<source lang = "php">
$params['companyname'] # your Company Name setting in WHMCS
$params['systemurl'] # the url to the Client Area
</source>

# The processing of a payment is handled by a callback file separate from the module (see page 9 for more information).
# 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==

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.

# Begin by deleting the _link function from the module template (important: you must do this before activating your new gateway module in WHMCS)
# 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===
<source lang="php">
$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...)
</source>

===Client Variables===
<source lang = "php">
$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']
</source>

===# System Variables===
<source lang="php">
$params['companyname'] # your Company Name setting in WHMCS
$params['systemurl'] – the url to the Client Area
</source>

===Card Details===
<source lang = "php">
$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
</source>

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

<source lang="php">
return array("status"=>"success","transid"=>$results["transid"],"rawdata"=>$results);
</source>

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:

<source lang="php">
return array("status"=>"declined","rawdata"=>$results);
</source>

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.

# 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===

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

<source lang="php">
$params['transid'] # the transaction ID of the original transaction to be refunded
</source>

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:

<source lang="php">
$GATEWAY = getGatewayVariables(‘yourgatewayname’);
</source>

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.

<source lang="php">
$invoiceid = checkCbInvoiceID($invoiceid,$GATEWAY[‘name’]);
</source>

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.

<source lang ="php">
checkCbTransID($transid);
</source>

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.

<source lang="php">
logTransaction($GATEWAY[‘name’],$_POST,"Successful");
</source>

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==
<source lang = "php">
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;
}
</source>

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

<source lang ="php">
$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)
</source>

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:

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

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

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:
<source lang="php">
$display_errors = true;
</source>

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 to which your completed module 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 [https://www.whmcs.com/members/submitticket.php?step=2&deptid=5 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.

{{Developer_Links}}

Gateway Module Developer Docs

2016-01-06T19:57:35Z

Nicolas: /* Getting Started */

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)

{{Developer_Links}}

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 [[#Module Type|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.

<div class="docs-alert-warning">
All functions within a gateway module must be prefixed with the filename. Open the file and replace all occurrences of '''template_''' with '''yougatewayname_'''.
</div>

===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:
#Specify a system name (''all in lowercase for the setting to be referenced by in the module code itself'')
#A FriendlyName
#Type
#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:

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

<div class="docs-alert-warning">'''Important:''' The '''_capture''' method must be deleted before activating the gateway module in WHMCS.</div>

# Delete the '''_capture''' function from the module template.
# 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===
<source lang="php">
$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...)
</source>

===Client Variables===
<source lang="php">
$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']
</source>

===System Variables===
<source lang = "php">
$params['companyname'] # your Company Name setting in WHMCS
$params['systemurl'] # the url to the Client Area
</source>

# The processing of a payment is handled by a callback file separate from the module (see page 9 for more information).
# 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==

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.

# Begin by deleting the _link function from the module template (important: you must do this before activating your new gateway module in WHMCS)
# 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===
<source lang="php">
$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...)
</source>

===Client Variables===
<source lang = "php">
$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']
</source>

===# System Variables===
<source lang="php">
$params['companyname'] # your Company Name setting in WHMCS
$params['systemurl'] – the url to the Client Area
</source>

===Card Details===
<source lang = "php">
$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
</source>

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

<source lang="php">
return array("status"=>"success","transid"=>$results["transid"],"rawdata"=>$results);
</source>

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:

<source lang="php">
return array("status"=>"declined","rawdata"=>$results);
</source>

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.

# 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===

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

<source lang="php">
$params['transid'] # the transaction ID of the original transaction to be refunded
</source>

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:

<source lang="php">
$GATEWAY = getGatewayVariables(‘yourgatewayname’);
</source>

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.

<source lang="php">
$invoiceid = checkCbInvoiceID($invoiceid,$GATEWAY[‘name’]);
</source>

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.

<source lang ="php">
checkCbTransID($transid);
</source>

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.

<source lang="php">
logTransaction($GATEWAY[‘name’],$_POST,"Successful");
</source>

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==
<source lang = "php">
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;
}
</source>

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

<source lang ="php">
$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)
</source>

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:

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

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

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:
<source lang="php">
$display_errors = true;
</source>

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 to which your completed module 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 [https://www.whmcs.com/members/submitticket.php?step=2&deptid=5 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.

{{Developer_Links}}

Gateway Module Developer Docs

2016-01-06T19:56:08Z

Nicolas: /* Third Party Gateway */

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)

{{Developer_Links}}

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 [[#Module Type|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.

<div class="docs-alert-warning">
All functions within a gateway module must be prefixed with the filename. Open the file and replace all occurrences of "template_" with "yougatewayname_".
</div>

===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 is to:
#Specify a system name (''all in lowercase for the setting to be referenced by in the module code itself'')
#A FriendlyName
#Type
#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:

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

<div class="docs-alert-warning">'''Important:''' The '''_capture''' method must be deleted before activating the gateway module in WHMCS.</div>

# Delete the '''_capture''' function from the module template.
# 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===
<source lang="php">
$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...)
</source>

===Client Variables===
<source lang="php">
$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']
</source>

===System Variables===
<source lang = "php">
$params['companyname'] # your Company Name setting in WHMCS
$params['systemurl'] # the url to the Client Area
</source>

# The processing of a payment is handled by a callback file separate from the module (see page 9 for more information).
# 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==

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.

# Begin by deleting the _link function from the module template (important: you must do this before activating your new gateway module in WHMCS)
# 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===
<source lang="php">
$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...)
</source>

===Client Variables===
<source lang = "php">
$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']
</source>

===# System Variables===
<source lang="php">
$params['companyname'] # your Company Name setting in WHMCS
$params['systemurl'] – the url to the Client Area
</source>

===Card Details===
<source lang = "php">
$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
</source>

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

<source lang="php">
return array("status"=>"success","transid"=>$results["transid"],"rawdata"=>$results);
</source>

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:

<source lang="php">
return array("status"=>"declined","rawdata"=>$results);
</source>

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.

# 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===

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

<source lang="php">
$params['transid'] # the transaction ID of the original transaction to be refunded
</source>

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:

<source lang="php">
$GATEWAY = getGatewayVariables(‘yourgatewayname’);
</source>

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.

<source lang="php">
$invoiceid = checkCbInvoiceID($invoiceid,$GATEWAY[‘name’]);
</source>

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.

<source lang ="php">
checkCbTransID($transid);
</source>

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.

<source lang="php">
logTransaction($GATEWAY[‘name’],$_POST,"Successful");
</source>

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==
<source lang = "php">
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;
}
</source>

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

<source lang ="php">
$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)
</source>

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:

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

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

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:
<source lang="php">
$display_errors = true;
</source>

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 to which your completed module 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 [https://www.whmcs.com/members/submitticket.php?step=2&deptid=5 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.

{{Developer_Links}}

Gateway Module Developer Docs

2016-01-06T19:54:27Z

Nicolas: /* #System Variables */

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)

{{Developer_Links}}

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 [[#Module Type|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.

<div class="docs-alert-warning">
All functions within a gateway module must be prefixed with the filename. Open the file and replace all occurrences of "template_" with "yougatewayname_".
</div>

===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 is to:
#Specify a system name (''all in lowercase for the setting to be referenced by in the module code itself'')
#A FriendlyName
#Type
#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:

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

<div class="docs-alert-warning">'''Important:''' This must be done before activating the gateway module in WHMCS.</div>

#Begin by deleting the _capture function from the module template.
#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===
<source lang="php">
$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...)
</source>

===Client Variables===
<source lang="php">
$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']
</source>

===System Variables===
<source lang = "php">
$params['companyname'] # your Company Name setting in WHMCS
$params['systemurl'] # the url to the Client Area
</source>

# The processing of a payment is handled by a callback file separate from the module (see page 9 for more information).
# 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==

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.

# Begin by deleting the _link function from the module template (important: you must do this before activating your new gateway module in WHMCS)
# 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===
<source lang="php">
$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...)
</source>

===Client Variables===
<source lang = "php">
$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']
</source>

===# System Variables===
<source lang="php">
$params['companyname'] # your Company Name setting in WHMCS
$params['systemurl'] – the url to the Client Area
</source>

===Card Details===
<source lang = "php">
$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
</source>

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

<source lang="php">
return array("status"=>"success","transid"=>$results["transid"],"rawdata"=>$results);
</source>

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:

<source lang="php">
return array("status"=>"declined","rawdata"=>$results);
</source>

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.

# 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===

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

<source lang="php">
$params['transid'] # the transaction ID of the original transaction to be refunded
</source>

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:

<source lang="php">
$GATEWAY = getGatewayVariables(‘yourgatewayname’);
</source>

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.

<source lang="php">
$invoiceid = checkCbInvoiceID($invoiceid,$GATEWAY[‘name’]);
</source>

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.

<source lang ="php">
checkCbTransID($transid);
</source>

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.

<source lang="php">
logTransaction($GATEWAY[‘name’],$_POST,"Successful");
</source>

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==
<source lang = "php">
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;
}
</source>

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

<source lang ="php">
$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)
</source>

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:

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

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

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:
<source lang="php">
$display_errors = true;
</source>

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 to which your completed module 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 [https://www.whmcs.com/members/submitticket.php?step=2&deptid=5 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.

{{Developer_Links}}

Gateway Module Developer Docs

2016-01-06T19:51:59Z

Nicolas: /* Third Party Gateway */

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)

{{Developer_Links}}

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 [[#Module Type|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.

<div class="docs-alert-warning">
All functions within a gateway module must be prefixed with the filename. Open the file and replace all occurrences of "template_" with "yougatewayname_".
</div>

===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 is to:
#Specify a system name (''all in lowercase for the setting to be referenced by in the module code itself'')
#A FriendlyName
#Type
#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:

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

<div class="docs-alert-warning">'''Important:''' This must be done before activating the gateway module in WHMCS.</div>

#Begin by deleting the _capture function from the module template.
#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===
<source lang="php">
$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...)
</source>

===Client Variables===
<source lang="php">
$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']
</source>

===#System Variables===
<source lang = "php">
$params['companyname'] # your Company Name setting in WHMCS
$params['systemurl'] # the url to the Client Area
</source>

# 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 doesn'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.

# Begin by deleting the _link function from the module template (important: you must do this before activating your new gateway module in WHMCS)
# 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===
<source lang="php">
$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...)
</source>

===Client Variables===
<source lang = "php">
$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']
</source>

===# System Variables===
<source lang="php">
$params['companyname'] # your Company Name setting in WHMCS
$params['systemurl'] – the url to the Client Area
</source>

===Card Details===
<source lang = "php">
$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
</source>

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

<source lang="php">
return array("status"=>"success","transid"=>$results["transid"],"rawdata"=>$results);
</source>

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:

<source lang="php">
return array("status"=>"declined","rawdata"=>$results);
</source>

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.

# 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===

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

<source lang="php">
$params['transid'] # the transaction ID of the original transaction to be refunded
</source>

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:

<source lang="php">
$GATEWAY = getGatewayVariables(‘yourgatewayname’);
</source>

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.

<source lang="php">
$invoiceid = checkCbInvoiceID($invoiceid,$GATEWAY[‘name’]);
</source>

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.

<source lang ="php">
checkCbTransID($transid);
</source>

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.

<source lang="php">
logTransaction($GATEWAY[‘name’],$_POST,"Successful");
</source>

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==
<source lang = "php">
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;
}
</source>

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

<source lang ="php">
$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)
</source>

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:

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

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

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:
<source lang="php">
$display_errors = true;
</source>

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 to which your completed module 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 [https://www.whmcs.com/members/submitticket.php?step=2&deptid=5 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.

{{Developer_Links}}

Gateway Module Developer Docs

2016-01-06T19:22:42Z

Nicolas: /* Getting Started */

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)

{{Developer_Links}}

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 [[#Module Type|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.

<div class="docs-alert-warning">
All functions within a gateway module must be prefixed with the filename. Open the file and replace all occurrences of "template_" with "yougatewayname_".
</div>

===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 is to:
#Specify a system name (''all in lowercase for the setting to be referenced by in the module code itself'')
#A FriendlyName
#Type
#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:

#'''Third Party Gateways''' – the customer leaves your site to pay and is returned once the payment process is completed.
#'''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==

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.

# 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===
<source lang="php">
$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...)
</source>

===Client Variables===
<source lang="php">
$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']
</source>

===#System Variables===
<source lang = "php">
$params['companyname'] # your Company Name setting in WHMCS
$params['systemurl'] # the url to the Client Area
</source>

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

# Begin by deleting the _link function from the module template (important: you must do this before activating your new gateway module in WHMCS)
# 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===
<source lang="php">
$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...)
</source>

===Client Variables===
<source lang = "php">
$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']
</source>

===# System Variables===
<source lang="php">
$params['companyname'] # your Company Name setting in WHMCS
$params['systemurl'] – the url to the Client Area
</source>

===Card Details===
<source lang = "php">
$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
</source>

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

<source lang="php">
return array("status"=>"success","transid"=>$results["transid"],"rawdata"=>$results);
</source>

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:

<source lang="php">
return array("status"=>"declined","rawdata"=>$results);
</source>

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.

# 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===

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

<source lang="php">
$params['transid'] # the transaction ID of the original transaction to be refunded
</source>

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:

<source lang="php">
$GATEWAY = getGatewayVariables(‘yourgatewayname’);
</source>

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.

<source lang="php">
$invoiceid = checkCbInvoiceID($invoiceid,$GATEWAY[‘name’]);
</source>

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.

<source lang ="php">
checkCbTransID($transid);
</source>

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.

<source lang="php">
logTransaction($GATEWAY[‘name’],$_POST,"Successful");
</source>

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==
<source lang = "php">
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;
}
</source>

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

<source lang ="php">
$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)
</source>

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:

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

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

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:
<source lang="php">
$display_errors = true;
</source>

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 to which your completed module 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 [https://www.whmcs.com/members/submitticket.php?step=2&deptid=5 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.

{{Developer_Links}}

Gateway Module Developer Docs

2016-01-06T19:10:44Z

Nicolas: /* Getting Started */

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)

{{Developer_Links}}

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 [[#Module Type|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.

<div class="docs-alert-warning">
All functions within a gateway module must be prefixed with the filename. Open the file and replace all occurrences of "template_" with "yougatewayname_"
</div>

===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 [[#Third_Party_Gateway]], and for a merchant gateway go to [[#Merchant_Gateway]].

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

# 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===
<source lang="php">
$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...)
</source>

===Client Variables===
<source lang="php">
$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']
</source>

===#System Variables===
<source lang = "php">
$params['companyname'] # your Company Name setting in WHMCS
$params['systemurl'] # the url to the Client Area
</source>

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

# Begin by deleting the _link function from the module template (important: you must do this before activating your new gateway module in WHMCS)
# 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===
<source lang="php">
$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...)
</source>

===Client Variables===
<source lang = "php">
$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']
</source>

===# System Variables===
<source lang="php">
$params['companyname'] # your Company Name setting in WHMCS
$params['systemurl'] – the url to the Client Area
</source>

===Card Details===
<source lang = "php">
$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
</source>

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

<source lang="php">
return array("status"=>"success","transid"=>$results["transid"],"rawdata"=>$results);
</source>

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:

<source lang="php">
return array("status"=>"declined","rawdata"=>$results);
</source>

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.

# 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===

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

<source lang="php">
$params['transid'] # the transaction ID of the original transaction to be refunded
</source>

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:

<source lang="php">
$GATEWAY = getGatewayVariables(‘yourgatewayname’);
</source>

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.

<source lang="php">
$invoiceid = checkCbInvoiceID($invoiceid,$GATEWAY[‘name’]);
</source>

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.

<source lang ="php">
checkCbTransID($transid);
</source>

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.

<source lang="php">
logTransaction($GATEWAY[‘name’],$_POST,"Successful");
</source>

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==
<source lang = "php">
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;
}
</source>

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

<source lang ="php">
$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)
</source>

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:

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

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

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:
<source lang="php">
$display_errors = true;
</source>

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 to which your completed module 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 [https://www.whmcs.com/members/submitticket.php?step=2&deptid=5 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.

{{Developer_Links}}

Gateway Module Developer Docs

2016-01-06T19:08:04Z

Nicolas: /* Getting Started */

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)

{{Developer_Links}}

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 depending upon the [[#Module Type|type of gateway]] you are developing:
*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 to "yourgatewayname.php". it should be all lowercase and must start with a letter.

<div class="docs-alert-info">
<span class="title">xyz</span><br />
All functions within a gateway module must be prefixed with the filename. Open the file and replace all occurrences of "template_" with "yougatewayname_"
</div>

===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 [[#Third_Party_Gateway]], and for a merchant gateway go to [[#Merchant_Gateway]].

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

# 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===
<source lang="php">
$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...)
</source>

===Client Variables===
<source lang="php">
$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']
</source>

===#System Variables===
<source lang = "php">
$params['companyname'] # your Company Name setting in WHMCS
$params['systemurl'] # the url to the Client Area
</source>

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

# Begin by deleting the _link function from the module template (important: you must do this before activating your new gateway module in WHMCS)
# 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===
<source lang="php">
$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...)
</source>

===Client Variables===
<source lang = "php">
$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']
</source>

===# System Variables===
<source lang="php">
$params['companyname'] # your Company Name setting in WHMCS
$params['systemurl'] – the url to the Client Area
</source>

===Card Details===
<source lang = "php">
$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
</source>

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

<source lang="php">
return array("status"=>"success","transid"=>$results["transid"],"rawdata"=>$results);
</source>

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:

<source lang="php">
return array("status"=>"declined","rawdata"=>$results);
</source>

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.

# 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===

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

<source lang="php">
$params['transid'] # the transaction ID of the original transaction to be refunded
</source>

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:

<source lang="php">
$GATEWAY = getGatewayVariables(‘yourgatewayname’);
</source>

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.

<source lang="php">
$invoiceid = checkCbInvoiceID($invoiceid,$GATEWAY[‘name’]);
</source>

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.

<source lang ="php">
checkCbTransID($transid);
</source>

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.

<source lang="php">
logTransaction($GATEWAY[‘name’],$_POST,"Successful");
</source>

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==
<source lang = "php">
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;
}
</source>

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

<source lang ="php">
$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)
</source>

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:

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

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

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:
<source lang="php">
$display_errors = true;
</source>

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 to which your completed module 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 [https://www.whmcs.com/members/submitticket.php?step=2&deptid=5 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.

{{Developer_Links}}

Gateway Module Developer Docs

2016-01-06T18:56:15Z

Nicolas: /* Introduction */

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)

{{Developer_Links}}

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 depending upon the [[#Module Type|type of gateway]] you are developing:
*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 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 [[#Third_Party_Gateway]], and for a merchant gateway go to [[#Merchant_Gateway]].

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

# 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===
<source lang="php">
$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...)
</source>

===Client Variables===
<source lang="php">
$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']
</source>

===#System Variables===
<source lang = "php">
$params['companyname'] # your Company Name setting in WHMCS
$params['systemurl'] # the url to the Client Area
</source>

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

# Begin by deleting the _link function from the module template (important: you must do this before activating your new gateway module in WHMCS)
# 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===
<source lang="php">
$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...)
</source>

===Client Variables===
<source lang = "php">
$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']
</source>

===# System Variables===
<source lang="php">
$params['companyname'] # your Company Name setting in WHMCS
$params['systemurl'] – the url to the Client Area
</source>

===Card Details===
<source lang = "php">
$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
</source>

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

<source lang="php">
return array("status"=>"success","transid"=>$results["transid"],"rawdata"=>$results);
</source>

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:

<source lang="php">
return array("status"=>"declined","rawdata"=>$results);
</source>

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.

# 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===

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

<source lang="php">
$params['transid'] # the transaction ID of the original transaction to be refunded
</source>

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:

<source lang="php">
$GATEWAY = getGatewayVariables(‘yourgatewayname’);
</source>

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.

<source lang="php">
$invoiceid = checkCbInvoiceID($invoiceid,$GATEWAY[‘name’]);
</source>

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.

<source lang ="php">
checkCbTransID($transid);
</source>

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.

<source lang="php">
logTransaction($GATEWAY[‘name’],$_POST,"Successful");
</source>

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==
<source lang = "php">
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;
}
</source>

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

<source lang ="php">
$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)
</source>

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:

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

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

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:
<source lang="php">
$display_errors = true;
</source>

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 to which your completed module 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 [https://www.whmcs.com/members/submitticket.php?step=2&deptid=5 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.

{{Developer_Links}}

Gateway Module Developer Docs

2016-01-06T18:55:10Z

Nicolas: /* Introduction */

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)

{{Developer_Links}}

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 structure and contains everything needed in order to successfully create a gateway module.

==Getting Started==

To get started, begin by downloading the module development kit from our GitHub site. There are two sample modules depending upon the [[#Module Type|type of gateway]] you are developing:
*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 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 [[#Third_Party_Gateway]], and for a merchant gateway go to [[#Merchant_Gateway]].

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

# 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===
<source lang="php">
$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...)
</source>

===Client Variables===
<source lang="php">
$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']
</source>

===#System Variables===
<source lang = "php">
$params['companyname'] # your Company Name setting in WHMCS
$params['systemurl'] # the url to the Client Area
</source>

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

# Begin by deleting the _link function from the module template (important: you must do this before activating your new gateway module in WHMCS)
# 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===
<source lang="php">
$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...)
</source>

===Client Variables===
<source lang = "php">
$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']
</source>

===# System Variables===
<source lang="php">
$params['companyname'] # your Company Name setting in WHMCS
$params['systemurl'] – the url to the Client Area
</source>

===Card Details===
<source lang = "php">
$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
</source>

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

<source lang="php">
return array("status"=>"success","transid"=>$results["transid"],"rawdata"=>$results);
</source>

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:

<source lang="php">
return array("status"=>"declined","rawdata"=>$results);
</source>

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.

# 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===

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

<source lang="php">
$params['transid'] # the transaction ID of the original transaction to be refunded
</source>

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:

<source lang="php">
$GATEWAY = getGatewayVariables(‘yourgatewayname’);
</source>

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.

<source lang="php">
$invoiceid = checkCbInvoiceID($invoiceid,$GATEWAY[‘name’]);
</source>

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.

<source lang ="php">
checkCbTransID($transid);
</source>

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.

<source lang="php">
logTransaction($GATEWAY[‘name’],$_POST,"Successful");
</source>

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==
<source lang = "php">
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;
}
</source>

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

<source lang ="php">
$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)
</source>

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:

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

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

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:
<source lang="php">
$display_errors = true;
</source>

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 to which your completed module 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 [https://www.whmcs.com/members/submitticket.php?step=2&deptid=5 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.

{{Developer_Links}}