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 Type	`FriendlyName`	`Size`	`Options`	`Default`	`Cols`	`Rows`	`Description`
`text`	Required	Required		✓			✓
`password`	Required	Required		✓			✓
`yesno`	Required		✓	✓			✓
`dropdown`	Required		Required	✓			✓
`radio`	Required		Required	✓			✓
`textarea`	Required			✓	✓	✓	✓

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

Key	Sample Data	Description
`companyname`	`WHMCS Limited`	The company name for the WHMCS installation.
`systemurl`	`http://www.domain.com/whmcs/`	The URL to the WHMCS installation.
`invoiceid`	`123`	The invoice ID.
`description`	`Company Name - Invoice #123`	Invoice text representation.
`amount`	`19.95`	The amount due.
`currency`	`USD`	The currency of the invoice.
`clientdetails`	`Array`	An array of the client’s profile data (`firstname`, `lastname`, `companyname`, `address1`, `address2`, `city`, `state`, `postcode`, `country`, `phonenumber`, and `email`).

Refund-Specific Parameters

Key	Sample Data	Description
`transid`	`ABC123`	The original transaction ID to issue the refund against.
`cardtype`	`Visa`	The card type.
`cardnum`	`4222222222222`	The card number.
`cardexp`	`0514`	The card’s expiry date (`MMYY`).
`cardstart`	`0508`	The card’s start date, if one exists (`MMYY`).
`cardissuenum`	`1234`	The card’s issue number, if one exists.
`cccvv`	`123`	The credit card verification value (for the first transaction only).
`gatewayid`	`xxxxxx`	The gateway token value.

Module Parameters

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

Standard Parameters

Key	Sample Data	Description
`companyname`	`WHMCS Limited`	The company name for the WHMCS installation.
`systemurl`	`http://www.domain.com/whmcs/`	The URL to the WHMCS installation.
`invoiceid`	`123`	The invoice ID.
`description`	`Company Name - Invoice #123`	An invoice text representation.
`amount`	`19.95`	The amount due.
`currency`	`USD`	The currency of the invoice.
`clientdetails`	`Array`	An array of the client’s profile data (`firstname`, `lastname`, `companyname`, `address1`, `address2`, `city`, `state`, `postcode`, `country`, `phonenumber`, and `email`).

Capture-Specific Parameters

Key	Sample Data	Description
`cardtype`	`Visa`	The card type.
`cardnum`	`4222222222222`	The card number.
`cardexp`	`0514`	The card’s expiry date (`MMYY`).
`cardstart`	`0508`	The card’s start date, if one exists (`MMYY`).
`cardissuenum`	`1234`	The card’s issue number, if one exists.
`cccvv`	`123`	The credit card verification value (for the first transaction only).
`gatewayid`	`xxxxxx`	The gateway token value.

payment-gateways

Last modified: June 14, 2024