First Data Payeezy

Gateway Module for WHMCS

[wpspoiler name=”License” open=”false”]

This is proprietary code property of R1 Software LLC. All rights reserved. Not Freeware. Not Shareware. Not Open Source. Do not copy or distribute in whole or in part without written permission from the author. The code is encrypted in an effort to protect it. Any attempt to decrypt or reverse engineer the product is strictly prohibited. Contact the author if you wish to purchase the source code.

If you obtained this module from R1 Software you should have received a license key to operate this module. If you got this module from another source, you can obtain a license key by clicking here.

Time limited trial license keys are available free of charge, but you must register to complete checkout and receive the key by email. You will also be able to download the latest version, or patches available.

Licenses work for a single install on a single domain (same as WHMCS). The gateway will contact our licensing server once every fifteen (15) days to validate. If unable to “call home” it will continue trying for an additional five (5) days, before suspending the license. If your domain name, or installation directory is changed, you will need to re-issue the license. Re-issuing the license is something you can do from within your account in the Client Area, and has no additional cost.

[/wpspoiler]

[wpspoiler name=”Changelog” open=”true”]

Jan 20, 2020 Version 1.5.2 – Tested with WHMCS up to v7.9.1 and PHP 7.3
Sep 18, 2018 Version 1.5.2 – Tested with WHMCS up to v7.8.2
Jun 5, 2018 Version 1.5.2 – Tested with WHMCS v7.5
Nov 20, 2018 Version 1.5.2 – Tested with WHMCS v7.4
Sep 10, 2018 Version 1.5.2 – Tested with WHMCS v7.3
May 25, 2018 Version 1.5.2 – Tested with WHMCS v7.2
March 31, 2017 Version 1.5.2 – Bug Fix Release
- Fixes various Fatal Errors in PHP during cron job execution
- Only calls home to the licensing server when localkeydata is expired or empty
October 10, 2016 Version 1.5.1 – Release for WHMCS v6.x and WHMCS 7
- Improved the README for modifications to viewinvoice.tpl to show Incentive/Fees
- Improved Hook for template variables
- Fixed the way language files were invoked
- Fixed instantiation of API Class
- Tested with PHP 5.6 and PHP 7.0
- Tested with WHMCS 6.3.1 and WHMCS 7
- Version for WHMCS 7 encoded for latest ionCube Loaders
- Version for WHMCS 6 encoded for older ionCube loaders
January 02, 2016 Version 1.5.0 – Release for WHMCS v6.x
- Fixed the modifications to viewinvoice.tpl to show Incentive and Charge Fees to customer.
- New hook for template variables added.
- New instructions on how to modify viewinvoice.tpl file.
- Removed “Incentive Name” and “Fees Name” from module settings. Now handled with language files.
- New language files added.
- Added client_ip to transaction data and gateway log, to help in fraud checks. Thanks to Austin Sasko from Dark Host for the suggestion.
- ‘Invoice balance’ now used instead of ‘Invoice amount’ on captures. Thanks to Ramón Núñez from YES! Computer Services for pointing this out.
- Removed restriction that prevented Refunds when invoice was not in Paid status.
December 29, 2015 Version 1.0.4 – Release for WHMCS 5.x
- Fixed Fatal Error redeclaring API class when cron ran. Thanks to Omar Castaneda from Servidores Seguros for his help with this bug.
- Fixed branding on error messages.
October 23, 2015 Version 1.0.3 -Bug Fix Release
- Fixed version no. on module settings. Added index.html file for security.
October 16, 2015 Version 1.0.2 – Branding Release
- Changed licensing server. Re-branded as First Data Payeezy
December 20, 2013 Version 1.0.1 – Minor Improvements
- Added logic to automatically remove “Get Trial” and “Buy Now” buttons from gateway configuration
- Added Version Number to gateway configuration
- Added real-time license status check with color-coded status to gateway configuration
December 10, 2013 Version 1.0.0
- Initial Release

[/wpspoiler]

Introduction

We at R1 Software use WHMCS to bill our clients, and First Data Payeezy (formerly Global Gateway e4 or GGe4) as our credit card payment processor. We love that we can provide our customers the option to pay their invoices online, so we created First Data Payeezy for WHMCS to achieve this goal. We were seriously considering increasing our prices in order to cover the operating expenses related to our merchant account and fees. However, not all clients make their payments online, and we didn’t want to complicate our pricing structure, so we decided to pass the actual fees to the client, only if they paid online. So we included this as an option. We like money. And we like getting paid on-time, so our cash flow doesn’t suffer. So we decided to give our clients an incentive to pay their invoices before the due date. So we decided to include this optional feature too!

Our module works with First Data Payeezy because it uses the low level API (v12). There is no need to register as a developer, or create a Sandbox Application on the new Payeezy Developer’s Portal for this module to work.
That is only necessary if you have some other product (Web App or Mobile App) that will use the new high-level API.

This has caused some confusion, and I have talked to First Data asking them to explain this better to their customers.
If you were boarded into the new Payeezy Developer portal, they re-generate your Gateway Password and HMAC Key.

Top of Page

Description

This gateway module allows one WHMCS installation to process payments, refunds, calculate transaction fees, and track the fees, using First Data Payeezy (formerly Global Gateway e4). It supports the V12 End-point only. It calculates the fees and you have the option to pass the fees to your client on the fly, and/or give an incentive discount to customers that pay their invoices before the due date. Product includes email support, and free updates for the life cycle of the product¹.

Customers directly pay from WHMCS checkout page without leaving your site.
Your WHMCS can store the credit card details so you can capture payments from the Admin Panel, and automate recurring payments.

No need to setup Hosted Payment Pages, this is the real deal.

Top of Page

Requirements

WHMCS v7.x
See WHMCS System Requirements for more details
SSL certificate installed on your site (for obvious security reasons)
Active account with First Data Payeezy

Top of Page

Features

[v1.5.2] Support for PHP 7.1, 7.2, 7.3 was added
[v1.5.1] Support for PHP 7.0 and WHMCS 7.x was added
[v1.5.1] Can display custom Incentive/Fees notifications in viewinvoice.tpl
[v1.5.1] Improved Multi-Language support
[v1.5] Module attempts to detect visitor IP on transaction data
[v1.5] Language File support
[v1.5] Support for WHMCS 6.x
[v1.5] Refund individual transactions even if invoice is not marked as PAID
[v1.0] Test Mode for testing with First Data Demo API, and Production Mode for real transactions
[v1.0] Ability to specify fixed transaction fee and/or a percentage variable fee
[v1.0] Fees for the transaction are tracked in WHMCS whether you pass them to the client or not
[v1.0] Fees can be charged but not added to the invoice (optional)
[v1.0] Pass the calculated fees to the client (optional)
[v1.0] Add invoice line for fee to avoid net income inaccuracy
[v1.0] Choose the name of the line item for the fee
[v1.0] Give an incentive to clients that pay before due date (optional) Incentive can be a fixed amount or a percentage of invoice total
[v1.0] Message is displayed on on invoice for fees and/or incentive before payment is made (requires viewinvoice.tpl modification)
[v1.0] Updates WHMCS Gateway Transactions Log

Top of Page

Notes

Tested on WHMCS versions 7.x and PHP 5.6, 7.0, 7.1, 7.2, 7.3
Tested on WHMCS versions 6.x
Supports First Data V12 API
No Telecheck Support
No Transarmor Tokenization Support

Top of Page

Archive Contents (v1.5.2)

zipfile
- /whmcs/(directory)
  - /modules/(directory)
    - /gateways/ (directory)
      - /firstdatae4/ (directory)
        
        api.php (api file)
        
        english.php (language file)
        
        index.html (HTML file)
        
        localkeydata.txt (license key data, the web server must be able to read/write to it)
        
        spanish.php (language file)
      - firstdatae4.php (gateway file)
- /includes/(directory)
  - /hooks/ (directory)
    - hooks_firstdatae4.php (hooks file)
- /README.md (text file)
- /viewinvoice_tpl_modification_README.md (text file)

Top of Page

Installation

STEP 1: You must first get a Trial Key or purchase the full version, then you can download the product files.

Login to the Client Area using your credentials.
Go to Services >> My Services
Locate the product, and click View Details
Look for the Downloads tab. Files are usually available in ZIP format.

STEP 2: Upload files. You have two options: With a File Manager: If you have a file manager that allows you to upload and extract files directly on your web server. Upload the provided zip file to your base directory (the directory where your WHMCS folder resides), and extract the contents.

You can copy the entire /whmcs/ on top of your existing /whmcs/ folder. If your WHMCS is installed on a different directory, you will need to move the /modules/ folder inside your WHMCS folder on top of your existing /modules/ folder.
No files should be replaced if you are installing the gateway for the first time.

By FTP: Extract the contents of the zip file in your computer, then upload the /modules/ directory to your WHMCS base directory, on top of your existing /modules/ folder.

No files should be replaced if you are installing the gateway for the first time.

STEP 3:

Make sure localkeydata.txt is readable/writeable by the server ( 600 permissions, should be fine).
Module should be available on the WHMCS Admin Portal, under Setup>Payment>Payment Gateways
Go to All Payment Gateways
Select First Data Payeezy from the menu, and activate.
If activation is successful you should see a message.
Important: Update the command you use for your WHMCS cron job, to use wget -O /dev/null -q http://yourdomain.com/path-to-whmcs/cron.php (wget method with full URL) instead of the php -q /path-to-whmcs/cron.php (php CLI method will give License Invalid Error).
Configure your First Data Payeezy Module with the appropriate settings. You will need to access your First Data online portal (https://globalgatewaye4.firstdata.com) to locate some values and API parameters needed, if you don’t have them already.
(optional) Put the hooks_firstdatae4.php file in /includes/hooks/
Modify your viewinvoice.tpl file as explained in the viewinvoice_tpl_modification_README.md file found in zip.

Top of Page

Configuration

Show on Order Form – Tick this box to show the gateway on your checkout.
Display Name – You should probably change this to Credit Cards. It is the name customers see for the payment method on invoices and during checkout.
R1 License Key – You must get a trial or purchase a license from R1 Software to unlock.
Gateway ID – Your Gateway ID. Login to your First Data Portal to find it. Copy it to a safe place.
Gateway Password – Your Gateway Password. Login to your First Data Portal go to Administration >> Terminals and select the correct terminal. From here you can generate a new password, if you haven’t done so already, or if you don’t know the current password. Copy it to a safe place before you click the UPDATE button. It will be hidden after you update the record.
Key ID & HMAC Key – Your Gateway Password. Login to your First Data Portal go to Administration >> Terminals and select the correct terminal. Go to the API tab. From here you can generate a new HMAC Key, if you haven’t done so already, or if you don’t know the current HMAC Key. Copy it to a safe place before you click the UPDATE button. It will be hidden after you update the record. After generation also copy the Key ID to a safe place.
Environment – select Test or Production
WHMCS Admin Username – Admin username used for WHMCS Internal API calls. Default: admin. Must be a valid administrator username with api access.
Charge Fees to Customer – Tick this box if you want charge the transaction fees to the customer. Default: Checked
Transaction Fee – Format: #.## Default is 0.25 Don’t use any currency symbol.
Variable Fee – Format #.## Must be between 1.00 and 100. Don’t use percent ‘%’ symbol. Example: use 2.5 for 2.5%
Fees Taxable? – check this box if the fees must be taxed. You must setup, and enable your tax settings in WHMCS for this to work.
Don’t Add line to invoice – Tick this box to NOT add the fee to invoice (May affect net income calculations).
Incentive – Give discount to customers for paying before invoice due date. Select one of the options: None – Incentive disabled Fixed – Used Fixed Amount for incentive. (Only applied if invoice total is greater than the incentive) Percentage – Uses the percentage amount for the incentive.
Fixed incentive amount – Enter the incentive you wish to give. Format: X.XX
Incentive as a percentage – Enter the incentive you wish to give as a percentage. Use only numbers from 1.0 to 99.0. Don’t use the ‘%’ symbol.

Top of Page

Troubleshooting

Please review the documentation completely first. Most issues are due to configuration. For more troubleshooting help, visit our Knowledgebase.

Please Read These Useful Tips:

Internal API Errors – One common mistake is not entering the correct Admin User with API Access privileges on the field provided.
First Data API Errors – Double check your First Data fields (Gateway ID, Gateway Password, Key ID, and HMAC Key). Check for typos or extra white spaces before of after the strings, as these are common when copying and pasting.
Taxes not showing – please verify your Tax Rules, under SETUP >> PAYMENTS >> TAX RULES
Automatic CC processing not working – make sure you are using the “GET” or “curl” for your WHMCS cron job command. The CLI method will not work and you will see a License Invalid ** Trial Mode ** error on your Gateway Log.
License key errors – Make sure you have a valid License Key. If you change your installation directory or domain, you must re-issue the license form your Client Area. Make sure localkeydata.txt is readable/writeable by the server.
Messages for fees/incentive not showing on invoice – make sure you modified or replaced the viewinvoice.tpl for your current template as instructed.
Other errors / white screen – Refer to your WHMCS Gateway Log for information that may help you figure out what is wrong. We also recommend you enable the Module Log under UTILITIES >> LOGS >> MODULE LOG, you may also benefit from enabling Display Errors under SETUP >> GENERAL SETTINGS >> Others (tab). Include any useful information when contacting support.

For more troubleshooting help, visit our Knowledgebase.

Top of Page

Support

For support, please log-in to your Client Area, and Open a Ticket. Select the Support Department and select your product (identified by the product name and license key). Provide as much information as you can about the issue, error messages, logs, and your configuration details.

Top of Page

Credits

We would like to thank WHMCS, and First Data for their APIs, documentation, and developer resources.

Special thanks to Ryan Bealey from UncommonTrend for his patience and help during the troubleshooting to fix various fatal errors in version 1.5.1
Special thanks to Austin Sasko from Host Dark for his suggestion to add client_ip to aid in fraud investigations.
Special thanks to Omar Castaneda from Servidores Seguros for his help on the cron Fatal Error bug.
Special thanks our friend Ramón Núñez from YES! Computer Services, Inc. for his help, unconditional support, and valuable ideas.
Special thanks to Frederico Dalmas *Baggio* from Grupo Baggio Ltda for his suggestions for v1.0.1 Build 12202013

Top of Page

Foot Notes

¹ Life cycle of the product means “as long as we offer it for sale”. If the product is discontinued, we will give thirty days (30) advance notice, and a prorated refund if product was purchased less than 1 year prior to the End-Of-Life Notification (EOLN).

Top of Page