First Data Payeezy

License

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, on a single IP, and a single installation folder (same as WHMCS). The module 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.

Change Log

• Aug. 18, 2024 Version 1.6.0
  • Tested with PHP 8.1,8.2 with Ioncube Loaders 12,13 and WHMCS 8.10.1
  • Fixed _config not found error

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 during subscription period¹.

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 v8.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.6.0] Support for PHP 7.4, 8.1, 8.2
• [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] 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 8.x and PHP 7.4, 8.1, 8.2
  
• Supports First Data V12 API
• No Telecheck Support
• No Transarmor Tokenization Support

Top of Page

Archive Contents (v1.6.0)

• 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.

1. Login to the Client Area using your credentials.
2. Go to Services >> My Services
3. Locate the product, and click View Details
4. 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:

1. Make sure localkeydata.txt is readable/writeable by the server ( 600 permissions, should be fine).
2. Module should be available on the WHMCS Admin Portal, under System Settings >Payment Gateways
3. Go to All Payment Gateways
4. Select First Data Payeezy from the menu, and activate.
   
5. If activation is successful you should see a message.
   
6. 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).
7. Configure your First Data Payeezy Module with the appropriate settings. You will need to access your First Data online portal to locate the values and API parameters needed, if you don’t have them already.
8. (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 Payeezy Portal to find it. Copy it to a safe place.
• Gateway Password – Your Gateway Password. Login to your Payeezy 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 Payeezy 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 System Settings > Tax Configuration
• 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 or check template documentation.
• Other errors / white screen – Refer to your Billing > Gateway Log for information that may help you figure out what is wrong.  You may also benefit from enabling Display Errors, Log Errors or Hooks Debug Mode under System Settings > 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 our friend Ramón Núñez from YES! Computer Services, Inc. for his help, unconditional support, and valuable ideas.

Top of Page

Foot Notes

¹ Subscription Period means “as long your subscription is current”. 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