|
|
| (5 intermediate revisions by 3 users not shown) |
| Line 1: |
Line 1: |
| − | 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.
| + | This page has moved to https://developers.whmcs.com/payment-gateways/ |
| − | | |
| − | 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}}
| |