├── .gitignore
├── LICENSE
├── README.md
├── composer.json
├── modules
    └── gateways
    │   ├── callback
    │       └── gatewaymodule.php
    │   └── gatewaymodule.php
└── whmcs.json


/.gitignore:
--------------------------------------------------------------------------------
1 | # PHPUnit
2 | phpunit.xml
3 | 
4 | # Composer
5 | composer.phar
6 | composer.lock
7 | vendor/*
8 | 


--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
 1 | The MIT License (MIT)
 2 | 
 3 | Copyright (c) 2015 WHMCS, Limited
 4 | 
 5 | Permission is hereby granted, free of charge, to any person obtaining a copy
 6 | of this software and associated documentation files (the "Software"), to deal
 7 | in the Software without restriction, including without limitation the rights
 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 9 | copies of the Software, and to permit persons to whom the Software is
10 | furnished to do so, subject to the following conditions:
11 | 
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 | 
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 | SOFTWARE.
22 | 
23 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
 1 | # WHMCS Sample Third Party Payment Gateway Module #
 2 | 
 3 | ## Summary ##
 4 | 
 5 | Payment Gateway modules allow you to integrate payment solutions with the WHMCS
 6 | platform.
 7 | 
 8 | There are two types of gateway module:
 9 | 
10 | * Third Party Gateways - these are payment solutions where checkout occurs
11 | on a remote website, usually hosted by the payment gateway themselves.
12 | 
13 | * Merchant Gateways - these are payment solutions where credit card details
14 | are collected - usually within the WHMCS application, though more and more
15 | often this will be done remotely, typically via an iframe, with a page hosted
16 | remotely by the payment gateway enabling tokenised storage.
17 | 
18 | The sample files here demonstrate how we suggest a Third Party Payment Gateway
19 | module for WHMCS be structured and implemented.
20 | 
21 | For more information, please refer to the documentation at:
22 | https://developers.whmcs.com/payment-gateways/
23 | 
24 | ## Recommended Module Content ##
25 | 
26 | The recommended structure of a third party gateway module is as follows.
27 | 
28 | ```
29 |  modules/gateways/
30 |   |- callback/gatewaymodule.php
31 |   |  gatewaymodule.php
32 | ```
33 | 
34 | ## Minimum Requirements ##
35 | 
36 | For the latest WHMCS minimum system requirements, please refer to
37 | https://docs.whmcs.com/System_Requirements
38 | 
39 | We recommend your module follows the same minimum requirements wherever
40 | possible.
41 | 
42 | ## Useful Resources
43 | * [Developer Resources](https://developers.whmcs.com/)
44 | * [Hook Documentation](https://developers.whmcs.com/hooks/)
45 | * [API Documentation](https://developers.whmcs.com/api/)
46 | 
47 | [WHMCS Limited](https://www.whmcs.com)
48 | 


--------------------------------------------------------------------------------
/composer.json:
--------------------------------------------------------------------------------
 1 | {
 2 |     "name": "whmcs/sample-gateway-module",
 3 |     "description": "Sample Third Party Payment Gateway Module for the WHMCS Billing Automation Platform",
 4 |     "keywords": [
 5 |         "whmcs",
 6 |         "web host automation platform",
 7 |         "third party gateway module",
 8 |         "gateway module",
 9 |         "third party gateway"
10 |     ],
11 |     "homepage": "http://www.whmcs.com/",
12 |     "license": "MIT",
13 |     "authors": [
14 |         {
15 |             "name": "WHMCS Development Team",
16 |             "email": "development@whmcs.com",
17 |             "homepage": "http://www.whmcs.com/",
18 |             "role": "Developer"
19 |         }
20 |     ],
21 |     "support": {
22 |         "email": "support@whmcs.com",
23 |         "forum": "http://forums.whmcs.com/",
24 |         "wiki": "http://docs.whmcs.com/"
25 |     }
26 | }
27 | 


--------------------------------------------------------------------------------
/modules/gateways/callback/gatewaymodule.php:
--------------------------------------------------------------------------------
  1 | <?php
  2 | /**
  3 |  * WHMCS Sample Payment Callback File
  4 |  *
  5 |  * This sample file demonstrates how a payment gateway callback should be
  6 |  * handled within WHMCS.
  7 |  *
  8 |  * It demonstrates verifying that the payment gateway module is active,
  9 |  * validating an Invoice ID, checking for the existence of a Transaction ID,
 10 |  * Logging the Transaction for debugging and Adding Payment to an Invoice.
 11 |  *
 12 |  * For more information, please refer to the online documentation.
 13 |  *
 14 |  * @see https://developers.whmcs.com/payment-gateways/callbacks/
 15 |  *
 16 |  * @copyright Copyright (c) WHMCS Limited 2017
 17 |  * @license http://www.whmcs.com/license/ WHMCS Eula
 18 |  */
 19 | 
 20 | // Require libraries needed for gateway module functions.
 21 | require_once __DIR__ . '/../../../init.php';
 22 | require_once __DIR__ . '/../../../includes/gatewayfunctions.php';
 23 | require_once __DIR__ . '/../../../includes/invoicefunctions.php';
 24 | 
 25 | // Detect module name from filename.
 26 | $gatewayModuleName = basename(__FILE__, '.php');
 27 | 
 28 | // Fetch gateway configuration parameters.
 29 | $gatewayParams = getGatewayVariables($gatewayModuleName);
 30 | 
 31 | // Die if module is not active.
 32 | if (!$gatewayParams['type']) {
 33 |     die("Module Not Activated");
 34 | }
 35 | 
 36 | // Retrieve data returned in payment gateway callback
 37 | // Varies per payment gateway
 38 | $success = $_POST["x_status"];
 39 | $invoiceId = $_POST["x_invoice_id"];
 40 | $transactionId = $_POST["x_trans_id"];
 41 | $paymentAmount = $_POST["x_amount"];
 42 | $paymentFee = $_POST["x_fee"];
 43 | $hash = $_POST["x_hash"];
 44 | 
 45 | $transactionStatus = $success ? 'Success' : 'Failure';
 46 | 
 47 | /**
 48 |  * Validate callback authenticity.
 49 |  *
 50 |  * Most payment gateways provide a method of verifying that a callback
 51 |  * originated from them. In the case of our example here, this is achieved by
 52 |  * way of a shared secret which is used to build and compare a hash.
 53 |  */
 54 | $secretKey = $gatewayParams['secretKey'];
 55 | if ($hash != md5($invoiceId . $transactionId . $paymentAmount . $secretKey)) {
 56 |     $transactionStatus = 'Hash Verification Failure';
 57 |     $success = false;
 58 | }
 59 | 
 60 | /**
 61 |  * Validate Callback Invoice ID.
 62 |  *
 63 |  * Checks invoice ID is a valid invoice number. Note it will count an
 64 |  * invoice in any status as valid.
 65 |  *
 66 |  * Performs a die upon encountering an invalid Invoice ID.
 67 |  *
 68 |  * Returns a normalised invoice ID.
 69 |  *
 70 |  * @param int $invoiceId Invoice ID
 71 |  * @param string $gatewayName Gateway Name
 72 |  */
 73 | $invoiceId = checkCbInvoiceID($invoiceId, $gatewayParams['name']);
 74 | 
 75 | /**
 76 |  * Check Callback Transaction ID.
 77 |  *
 78 |  * Performs a check for any existing transactions with the same given
 79 |  * transaction number.
 80 |  *
 81 |  * Performs a die upon encountering a duplicate.
 82 |  *
 83 |  * @param string $transactionId Unique Transaction ID
 84 |  */
 85 | checkCbTransID($transactionId);
 86 | 
 87 | /**
 88 |  * Log Transaction.
 89 |  *
 90 |  * Add an entry to the Gateway Log for debugging purposes.
 91 |  *
 92 |  * The debug data can be a string or an array. In the case of an
 93 |  * array it will be
 94 |  *
 95 |  * @param string $gatewayName        Display label
 96 |  * @param string|array $debugData    Data to log
 97 |  * @param string $transactionStatus  Status
 98 |  */
 99 | logTransaction($gatewayParams['name'], $_POST, $transactionStatus);
100 | 
101 | if ($success) {
102 | 
103 |     /**
104 |      * Add Invoice Payment.
105 |      *
106 |      * Applies a payment transaction entry to the given invoice ID.
107 |      *
108 |      * @param int $invoiceId         Invoice ID
109 |      * @param string $transactionId  Transaction ID
110 |      * @param float $paymentAmount   Amount paid (defaults to full balance)
111 |      * @param float $paymentFee      Payment fee (optional)
112 |      * @param string $gatewayModule  Gateway module name
113 |      */
114 |     addInvoicePayment(
115 |         $invoiceId,
116 |         $transactionId,
117 |         $paymentAmount,
118 |         $paymentFee,
119 |         $gatewayModuleName
120 |     );
121 | 
122 | }
123 | 


--------------------------------------------------------------------------------
/modules/gateways/gatewaymodule.php:
--------------------------------------------------------------------------------
  1 | <?php
  2 | /**
  3 |  * WHMCS Sample Payment Gateway Module
  4 |  *
  5 |  * Payment Gateway modules allow you to integrate payment solutions with the
  6 |  * WHMCS platform.
  7 |  *
  8 |  * This sample file demonstrates how a payment gateway module for WHMCS should
  9 |  * be structured and all supported functionality it can contain.
 10 |  *
 11 |  * Within the module itself, all functions must be prefixed with the module
 12 |  * filename, followed by an underscore, and then the function name. For this
 13 |  * example file, the filename is "gatewaymodule" and therefore all functions
 14 |  * begin "gatewaymodule_".
 15 |  *
 16 |  * If your module or third party API does not support a given function, you
 17 |  * should not define that function within your module. Only the _config
 18 |  * function is required.
 19 |  *
 20 |  * For more information, please refer to the online documentation.
 21 |  *
 22 |  * @see https://developers.whmcs.com/payment-gateways/
 23 |  *
 24 |  * @copyright Copyright (c) WHMCS Limited 2017
 25 |  * @license http://www.whmcs.com/license/ WHMCS Eula
 26 |  */
 27 | 
 28 | if (!defined("WHMCS")) {
 29 |     die("This file cannot be accessed directly");
 30 | }
 31 | 
 32 | /**
 33 |  * Define module related meta data.
 34 |  *
 35 |  * Values returned here are used to determine module related capabilities and
 36 |  * settings.
 37 |  *
 38 |  * @see https://developers.whmcs.com/payment-gateways/meta-data-params/
 39 |  *
 40 |  * @return array
 41 |  */
 42 | function gatewaymodule_MetaData()
 43 | {
 44 |     return array(
 45 |         'DisplayName' => 'Sample Payment Gateway Module',
 46 |         'APIVersion' => '1.1', // Use API Version 1.1
 47 |         'DisableLocalCreditCardInput' => true,
 48 |         'TokenisedStorage' => false,
 49 |     );
 50 | }
 51 | 
 52 | /**
 53 |  * Define gateway configuration options.
 54 |  *
 55 |  * The fields you define here determine the configuration options that are
 56 |  * presented to administrator users when activating and configuring your
 57 |  * payment gateway module for use.
 58 |  *
 59 |  * Supported field types include:
 60 |  * * text
 61 |  * * password
 62 |  * * yesno
 63 |  * * dropdown
 64 |  * * radio
 65 |  * * textarea
 66 |  *
 67 |  * Examples of each field type and their possible configuration parameters are
 68 |  * provided in the sample function below.
 69 |  *
 70 |  * @return array
 71 |  */
 72 | function gatewaymodule_config()
 73 | {
 74 |     return array(
 75 |         // the friendly display name for a payment gateway should be
 76 |         // defined here for backwards compatibility
 77 |         'FriendlyName' => array(
 78 |             'Type' => 'System',
 79 |             'Value' => 'Sample Third Party Payment Gateway Module',
 80 |         ),
 81 |         // a text field type allows for single line text input
 82 |         'accountID' => array(
 83 |             'FriendlyName' => 'Account ID',
 84 |             'Type' => 'text',
 85 |             'Size' => '25',
 86 |             'Default' => '',
 87 |             'Description' => 'Enter your account ID here',
 88 |         ),
 89 |         // a password field type allows for masked text input
 90 |         'secretKey' => array(
 91 |             'FriendlyName' => 'Secret Key',
 92 |             'Type' => 'password',
 93 |             'Size' => '25',
 94 |             'Default' => '',
 95 |             'Description' => 'Enter secret key here',
 96 |         ),
 97 |         // the yesno field type displays a single checkbox option
 98 |         'testMode' => array(
 99 |             'FriendlyName' => 'Test Mode',
100 |             'Type' => 'yesno',
101 |             'Description' => 'Tick to enable test mode',
102 |         ),
103 |         // the dropdown field type renders a select menu of options
104 |         'dropdownField' => array(
105 |             'FriendlyName' => 'Dropdown Field',
106 |             'Type' => 'dropdown',
107 |             'Options' => array(
108 |                 'option1' => 'Display Value 1',
109 |                 'option2' => 'Second Option',
110 |                 'option3' => 'Another Option',
111 |             ),
112 |             'Description' => 'Choose one',
113 |         ),
114 |         // the radio field type displays a series of radio button options
115 |         'radioField' => array(
116 |             'FriendlyName' => 'Radio Field',
117 |             'Type' => 'radio',
118 |             'Options' => 'First Option,Second Option,Third Option',
119 |             'Description' => 'Choose your option!',
120 |         ),
121 |         // the textarea field type allows for multi-line text input
122 |         'textareaField' => array(
123 |             'FriendlyName' => 'Textarea Field',
124 |             'Type' => 'textarea',
125 |             'Rows' => '3',
126 |             'Cols' => '60',
127 |             'Description' => 'Freeform multi-line text input field',
128 |         ),
129 |     );
130 | }
131 | 
132 | /**
133 |  * Payment link.
134 |  *
135 |  * Required by third party payment gateway modules only.
136 |  *
137 |  * Defines the HTML output displayed on an invoice. Typically consists of an
138 |  * HTML form that will take the user to the payment gateway endpoint.
139 |  *
140 |  * @param array $params Payment Gateway Module Parameters
141 |  *
142 |  * @see https://developers.whmcs.com/payment-gateways/third-party-gateway/
143 |  *
144 |  * @return string
145 |  */
146 | function gatewaymodule_link($params)
147 | {
148 |     // Gateway Configuration Parameters
149 |     $accountId = $params['accountID'];
150 |     $secretKey = $params['secretKey'];
151 |     $testMode = $params['testMode'];
152 |     $dropdownField = $params['dropdownField'];
153 |     $radioField = $params['radioField'];
154 |     $textareaField = $params['textareaField'];
155 | 
156 |     // Invoice Parameters
157 |     $invoiceId = $params['invoiceid'];
158 |     $description = $params["description"];
159 |     $amount = $params['amount'];
160 |     $currencyCode = $params['currency'];
161 | 
162 |     // Client Parameters
163 |     $firstname = $params['clientdetails']['firstname'];
164 |     $lastname = $params['clientdetails']['lastname'];
165 |     $email = $params['clientdetails']['email'];
166 |     $address1 = $params['clientdetails']['address1'];
167 |     $address2 = $params['clientdetails']['address2'];
168 |     $city = $params['clientdetails']['city'];
169 |     $state = $params['clientdetails']['state'];
170 |     $postcode = $params['clientdetails']['postcode'];
171 |     $country = $params['clientdetails']['country'];
172 |     $phone = $params['clientdetails']['phonenumber'];
173 | 
174 |     // System Parameters
175 |     $companyName = $params['companyname'];
176 |     $systemUrl = $params['systemurl'];
177 |     $returnUrl = $params['returnurl'];
178 |     $langPayNow = $params['langpaynow'];
179 |     $moduleDisplayName = $params['name'];
180 |     $moduleName = $params['paymentmethod'];
181 |     $whmcsVersion = $params['whmcsVersion'];
182 | 
183 |     $url = 'https://www.demopaymentgateway.com/do.payment';
184 | 
185 |     $postfields = array();
186 |     $postfields['username'] = $username;
187 |     $postfields['invoice_id'] = $invoiceId;
188 |     $postfields['description'] = $description;
189 |     $postfields['amount'] = $amount;
190 |     $postfields['currency'] = $currencyCode;
191 |     $postfields['first_name'] = $firstname;
192 |     $postfields['last_name'] = $lastname;
193 |     $postfields['email'] = $email;
194 |     $postfields['address1'] = $address1;
195 |     $postfields['address2'] = $address2;
196 |     $postfields['city'] = $city;
197 |     $postfields['state'] = $state;
198 |     $postfields['postcode'] = $postcode;
199 |     $postfields['country'] = $country;
200 |     $postfields['phone'] = $phone;
201 |     $postfields['callback_url'] = $systemUrl . '/modules/gateways/callback/' . $moduleName . '.php';
202 |     $postfields['return_url'] = $returnUrl;
203 | 
204 |     $htmlOutput = '<form method="post" action="' . $url . '">';
205 |     foreach ($postfields as $k => $v) {
206 |         $htmlOutput .= '<input type="hidden" name="' . $k . '" value="' . urlencode($v) . '" />';
207 |     }
208 |     $htmlOutput .= '<input type="submit" value="' . $langPayNow . '" />';
209 |     $htmlOutput .= '</form>';
210 | 
211 |     return $htmlOutput;
212 | }
213 | 
214 | /**
215 |  * Refund transaction.
216 |  *
217 |  * Called when a refund is requested for a previously successful transaction.
218 |  *
219 |  * @param array $params Payment Gateway Module Parameters
220 |  *
221 |  * @see https://developers.whmcs.com/payment-gateways/refunds/
222 |  *
223 |  * @return array Transaction response status
224 |  */
225 | function gatewaymodule_refund($params)
226 | {
227 |     // Gateway Configuration Parameters
228 |     $accountId = $params['accountID'];
229 |     $secretKey = $params['secretKey'];
230 |     $testMode = $params['testMode'];
231 |     $dropdownField = $params['dropdownField'];
232 |     $radioField = $params['radioField'];
233 |     $textareaField = $params['textareaField'];
234 | 
235 |     // Transaction Parameters
236 |     $transactionIdToRefund = $params['transid'];
237 |     $refundAmount = $params['amount'];
238 |     $currencyCode = $params['currency'];
239 | 
240 |     // Client Parameters
241 |     $firstname = $params['clientdetails']['firstname'];
242 |     $lastname = $params['clientdetails']['lastname'];
243 |     $email = $params['clientdetails']['email'];
244 |     $address1 = $params['clientdetails']['address1'];
245 |     $address2 = $params['clientdetails']['address2'];
246 |     $city = $params['clientdetails']['city'];
247 |     $state = $params['clientdetails']['state'];
248 |     $postcode = $params['clientdetails']['postcode'];
249 |     $country = $params['clientdetails']['country'];
250 |     $phone = $params['clientdetails']['phonenumber'];
251 | 
252 |     // System Parameters
253 |     $companyName = $params['companyname'];
254 |     $systemUrl = $params['systemurl'];
255 |     $langPayNow = $params['langpaynow'];
256 |     $moduleDisplayName = $params['name'];
257 |     $moduleName = $params['paymentmethod'];
258 |     $whmcsVersion = $params['whmcsVersion'];
259 | 
260 |     // perform API call to initiate refund and interpret result
261 | 
262 |     return array(
263 |         // 'success' if successful, otherwise 'declined', 'error' for failure
264 |         'status' => 'success',
265 |         // Data to be recorded in the gateway log - can be a string or array
266 |         'rawdata' => $responseData,
267 |         // Unique Transaction ID for the refund transaction
268 |         'transid' => $refundTransactionId,
269 |         // Optional fee amount for the fee value refunded
270 |         'fees' => $feeAmount,
271 |     );
272 | }
273 | 
274 | /**
275 |  * Cancel subscription.
276 |  *
277 |  * If the payment gateway creates subscriptions and stores the subscription
278 |  * ID in tblhosting.subscriptionid, this function is called upon cancellation
279 |  * or request by an admin user.
280 |  *
281 |  * @param array $params Payment Gateway Module Parameters
282 |  *
283 |  * @see https://developers.whmcs.com/payment-gateways/subscription-management/
284 |  *
285 |  * @return array Transaction response status
286 |  */
287 | function gatewaymodule_cancelSubscription($params)
288 | {
289 |     // Gateway Configuration Parameters
290 |     $accountId = $params['accountID'];
291 |     $secretKey = $params['secretKey'];
292 |     $testMode = $params['testMode'];
293 |     $dropdownField = $params['dropdownField'];
294 |     $radioField = $params['radioField'];
295 |     $textareaField = $params['textareaField'];
296 | 
297 |     // Subscription Parameters
298 |     $subscriptionIdToCancel = $params['subscriptionID'];
299 | 
300 |     // System Parameters
301 |     $companyName = $params['companyname'];
302 |     $systemUrl = $params['systemurl'];
303 |     $langPayNow = $params['langpaynow'];
304 |     $moduleDisplayName = $params['name'];
305 |     $moduleName = $params['paymentmethod'];
306 |     $whmcsVersion = $params['whmcsVersion'];
307 | 
308 |     // perform API call to cancel subscription and interpret result
309 | 
310 |     return array(
311 |         // 'success' if successful, any other value for failure
312 |         'status' => 'success',
313 |         // Data to be recorded in the gateway log - can be a string or array
314 |         'rawdata' => $responseData,
315 |     );
316 | }
317 | 


--------------------------------------------------------------------------------
/whmcs.json:
--------------------------------------------------------------------------------
 1 | {
 2 |     "schema": "1.0",
 3 |     "type": "whmcs-gateways",
 4 |     "name": "sample-gateway-module",
 5 |     "license": "MIT",
 6 |     "category": "gateway",
 7 |     "description": {
 8 |         "name": "Sample Third Party Payment Gateway Module",
 9 |         "tagline": "Payment Gateway modules allow you to integrate payment solutions with the WHMCS platform.",
10 |         "long": "The sample files here demonstrate how we suggest a Third Party Payment Gateway module for WHMCS be structured and implemented.",
11 |         "features": [
12 |             "Provide both client and admin facing user interfaces",
13 |             "Utilize hook functionality within WHMCS"
14 |         ]
15 |     },
16 |     "logo": {
17 |         "filename": "logo.png"
18 |     },
19 |     "support": {
20 |         "homepage": "https:\/\/www.whmcs.com\/", 
21 |         "learn_more": "https:\/\/www.whmcs.com\/tour", 
22 |         "email": "support@whmcs.com", 
23 |         "support_url": "https:\/\/support.whmcs.com\/",
24 |         "docs_url": "https:\/\/developers.whmcs.com\/payment-gateways\/"
25 |     },
26 |     "authors": [
27 |         {
28 |             "name": "WHMCS",
29 |             "homepage": "https:\/\/www.whmcs.com\/"
30 |         }
31 |     ]
32 | }
33 | 


--------------------------------------------------------------------------------