Custom Gateway Modules

You can develop your own custom payment gateway modules for use in WHMCS.

The Bank Transfer and Mail In Payment modules are open-source, allowing you to duplicate and customize them. For more information, see Copy a Gateway Module.

Dev:Gateway:Config Attributes

Use the Dev:Gateway:Config function to define your module’s attributes. This includes the required friendly display name for your module, required usage instructions, and, optionally, any settings that a user must configure for it.

The system passes the settings that you define here into all of the functions of your payment gateway module each time that the system calls it.

All modules require this function.

Fields and Attributes

Fields may support the following attributes:

  • FriendlyName — The display name for the field.
  • Size — The length of the field.
  • Default — The default value to assign or select. For yesno fields, this is true/false.
  • Description — A description for the field.

You can configure attributes for the following field types:

Field TypeFriendlyNameSizeOptionsDefaultColsRowsDescription
textRequiredRequired
passwordRequiredRequired
yesnoRequired
dropdownRequiredRequired
radioRequiredRequired
textareaRequired
  • Required indicates required attributes.
  • indicates optional attributes.

Attribute Example

    function demogateway_config() {
        return array(
            "FriendlyName" => array(
                "Type" => "System",
                "Value" => "My Custom Gateway Module",
            ),
            "UsageNotes" => array(
                "Type" => "System",
                "Value" => "Don't have an account yet? <a href=\"#\">Click here to Signup</a>",
            ),
            "accountnumber" => array(
                "FriendlyName" => "Account Number",
                "Type" => "text",
                "Size" => "10",
                "Description" => "This can be found in Profile > Account Information"
            ),
            "apiusername" => array(
                "FriendlyName" => "API Username",
                "Type" => "text",
                "Size" => "20",
            ),
            "apipassword" => array(
                "FriendlyName" => "API Password",
                "Type" => "password",
                "Size" => "20",
            ),
            "testmode" => array(
                "FriendlyName" => "Test Mode",
                "Type" => "yesno",
                "Default" => false,
                "Description" => "Check to enable",
            ),
        );
    }

Merchant Parameters

You can use the following Dev:Gateway:MerchantParamsRefund parameters:

Standard Parameters

KeySample DataDescription
companynameWHMCS LimitedThe company name for the WHMCS installation.
systemurlhttp://www.domain.com/whmcs/The URL to the WHMCS installation.
invoiceid123The invoice ID.
descriptionCompany Name - Invoice #123Invoice text representation.
amount19.95The amount due.
currencyUSDThe currency of the invoice.
clientdetailsArrayAn array of the client’s profile data (firstname, lastname, companyname, address1, address2, city, state, postcode, country, phonenumber, and email).

Refund-Specific Parameters

KeySample DataDescription
transidABC123The original transaction ID to issue the refund against.
cardtypeVisaThe card type.
cardnum4222222222222The card number.
cardexp0514The card’s expiry date (MMYY).
cardstart0508The card’s start date, if one exists (MMYY).
cardissuenum1234The card’s issue number, if one exists.
cccvv123The credit card verification value (for the first transaction only).
gatewayidxxxxxxThe gateway token value.

Module Parameters

You can use the following Dev:Gateway:Params parameters:

Standard Parameters

KeySample DataDescription
companynameWHMCS LimitedThe company name for the WHMCS installation.
systemurlhttp://www.domain.com/whmcs/The URL to the WHMCS installation.
invoiceid123The invoice ID.
descriptionCompany Name - Invoice #123An invoice text representation.
amount19.95The amount due.
currencyUSDThe currency of the invoice.
clientdetailsArrayAn array of the client’s profile data (firstname, lastname, companyname, address1, address2, city, state, postcode, country, phonenumber, and email).

Capture-Specific Parameters

KeySample DataDescription
cardtypeVisaThe card type.
cardnum4222222222222The card number.
cardexp0514The card’s expiry date (MMYY).
cardstart0508The card’s start date, if one exists (MMYY).
cardissuenum1234The card’s issue number, if one exists.
cccvv123The credit card verification value (for the first transaction only).
gatewayidxxxxxxThe gateway token value.

Last modified: June 5, 2024