1. Documentation /
  2. WooCommerce First Data Payeezy

WooCommerce First Data Payeezy

Overview ↑ Back to top

Switching to Payment JS? Click here for instructions on how to make the switch now. Be sure to switch to Payment JS before March 15th, 2020 to ensure your site continues processing payments without issue.

Accept payment by all major credit cards directly on your site with First Data using the Payeezy Gateway, Payeezy, or legacy Global Gateway payment processing services. If you do not yet have a Payeezy (formerly GGe4) account, you can get a free demo account.

With TransArmor Tokenization enabled on your account, customers can choose to safely and securely save their credit card information to their accounts, allowing for quicker and easier future checkout. This would also let you accept recurring payments, as the plugin includes full support for WooCommerce Subscriptions and Pre-Orders.

This gateway requires an SSL certificate to protect your customers credit card data.

The three gateway modes may support different features, and merchants can switch between each gateway mode depending on what First Data account they’re connecting to WooCommerce. For example, if you use Payeezy API, you must have a Payeezy API account with First Data to connect to (you can request an upgrade to this account from First Data); you should select the gateway mode that corresponds to your First Data account.

Payeezy Gateway Payeezy (API) Global Gateway
Process payments on site
Supports enhanced checkout form
Supports client-side tokenization for enhanced security and reduced PCI compliance burden
Supports pre-authorization
Supports TransArmor tokenization ✔ *
Supports Subscriptions & Pre-Orders plugins
Supports soft descriptors
Supports TeleCheck (eCheck)
Supports capturing charges within WooCommerce
Supports WooCommerce refunds
Supports voiding pre-authorized transactions
* TransArmor is required in your First Data account to use the Payeezy (API) gateway mode.

Installation ↑ Back to top

  1. Download the extension from your WooCommerce dashboard
  2. Go to Plugins > Add New > Upload and select the ZIP file you just downloaded
  3. Click Install Now, and then Activate
  4. Go to WooCommerce > Settings > Payments and read the next section to learn how to setup and configure the plugin.

Setup and Configuration ↑ Back to top

To set up the plugin, you’ll need credentials from First Data for your payment gateway account. Please choose which payment gateway account you’ll be using to see how to obtain your payment gateway credentials for use in the plugin.

Be sure that the gateway is in the correct mode before you start. You can change the gateway mode under the Plugins list by clicking Use {Gateway name}.

WooCommerce First Data select gateway mode

Then, you can refer to the correct document to get credentials and configure the gateway:

eCheck Configuration ↑ Back to top

Supported by: Payeezy Gateway, Payeezy
Please note that TeleCheck does not support tokenization, and therefore cannot be used for Subscriptions or Pre-Orders.

Both the Payeezy Gateway and Payeezy plugin modes support TeleCheck checkout (eChecks). Each can be configured in the same way:

WooCommerce First Data Payeezy eCheck Settings
Payeezy eCheck Setting
WooCommerce First Data Payeezy Gateway eCheck Settings
Payeezy Gateway eCheck Settings

  • Enable / Disable – Enable to allow customers to use this gateway to checkout.
  • Title – The name of the payment method customers will see during checkout.
  • Description – The description of the payment method customers will see during checkout. Limited HTML is allowed.
  • Detailed Decline Messages – Enable to display detailed messages to customers to provide reasoning for declines when possible instead of a generic error message.
  • Debug Mode – Enable this if you are having issues correctly processing transactions. You can either log API requests / responses directly to the checkout / thank you page, save them to the WooCommerce Error Log (found under WooCommerce > System Status > Logs) or both. All debugging messages are cleaned of sensitive information before display, but as a best practice, please do not enable this unless you are having issues with the plugin and disable it once your issues are resolved.
  • Environment – You can set your site to process transactions in the production or demo environment depending on the type of account you have. If you are not sure, your account is most likely a production account. Make sure that your Gateway credentials match your configured environment.
  • Share connection settings – Enabling this will allow you to use connection / authentication settings between the credit card and eCheck gateways. If this is enabled, you’ll need to enter First Data gateway credentials under the Credit Card settings to process transactions.

Merchant Usage ↑ Back to top

There are several features available in different gateway modes to assist merchants in managing transactions.

Capture Charges in WooCommerce ↑ Back to top

Supported by: Payeezy Gateway, Payeezy

Both of these gateways support capturing pre-authorized credit card transactions from directly within the WooCommerce admin — no logging into your First Data account to capture transactions needed.

You can read about how to capture charges in WooCommerce here.

Refund Transactions in WooCommerce ↑ Back to top

Supported by: Payeezy Gateway, Payeezy

You can refund credit card transactions (not eCheck / TeleCheck transactions) from directly within the WooCommerce admin using version 3.5.0 or newer of First Data. This means that refunds can be processed directly in WooCommerce without the logging into your First Data account to save time on store management. Both partial and full refunds are supported.

You can read more about managing refunds here.

Void Transactions in WooCommerce ↑ Back to top

Supported by: Payeezy Gateway, Payeezy

You can void pre-authorized credit card transactions (not eCheck / TeleCheck transactions) from directly within the WooCommerce admin using version 4.0 or newer of First Data. This will cancel the order as funds have not been captured yet, and will void the charge within First Data within the need to log into the First Data admin.

Voided transactions must be voided in full; partial voids are not accepted by First Data. You can read more about voiding transactions here.

Managing Credit Card Tokens ↑ Back to top

Supported by: Payeezy Gateway, Payeezy

Saved card tokens for a customer can be managed by an admin. While using TransArmor Tokenization, card tokens are saved in the customer’s account (though no sensitive information is saved in your database). Shop admins can create or delete credit card tokens from the “edit WP User” page when tokenization is enabled.

You can read more about managing saved card tokens here.

Manually Adding Tokens

To manually add a card token, you’ll need information from First Data. Log into your First Data account, click on the “Transactions” tab, then search for the transactions you want to view:

WooCommerce First Data Transactions List
First Data Transactions List

Note that the first transaction in this image has Card Number ############1111. This means that the card token is not available because TransArmor Tokenization was not configured / enabled when that transaction was processed. The second transaction shows what a credit card token looks like when this is properly configured.

To manually add the payment token, use the “Card Number” in the transaction list for the tokenized transaction, then enter the rest of the needed information and save the user profile.

Customer Experience ↑ Back to top

Enhanced Checkout Form ↑ Back to top

Supported by: Payeezy Gateway, Payeezy, Global Gateway

All First Data gateway modes support the enhanced checkout form. This improves both mobile and desktop checkout. You can read more about this feature here.

Payeezy Gateway credit card form
Payeezy Gateway credit card form
Global Gateway credit card form
Global Gateway credit card form


With the switch to Payment.JS, the Checkout experience for the Payeezy JS mode differs slightly. The customer won’t see a credit card form on the Checkout page and must continue to the “Pay for order” page to fill out the credit card details.

Payeezy JS on the Checkout page
Payeezy JS on the Checkout page
Payeezy JS credit card form on the Pay for order page
Payeezy JS credit card form on the Pay for order page


The TeleCheck checkout is supported by Payeezy Gateway and Payeezy, and will show the required payment disclaimers from First Data. First Data also requires a piece of personal information, such as Driver’s License, so the customer can select an ID type.

WooCommerce First Data Telecheck Checkout
Telecheck Checkout

Detailed Decline Messages ↑ Back to top

Supported by: Payeezy Gateway, Payeezy

When detailed decline messages are enabled, they will provide informative error messages to the customer at checkout when First Data returns a useful response.

You can read more about detailed decline messages here.

My Payment Methods ↑ Back to top

Supported by: Payeezy Gateway, Payeezy

When TransArmor Tokenization is configured, logged-in customers can save cards to their accounts during the checkout process, and view or manage these cards in the account section.

WooCommerce First Data Saved Payment Methods
My Payment Methods

Customers can then select one of these saved methods while checking out in the future.

WooCommerce First Data Use Saved Card

First Data also supports adding new methods from the account. You can read more about adding methods from the account here.

WooCommerce First Data Add Payment Method
Add Payment Method

Other Info & Features ↑ Back to top

Storing Credit Cards ↑ Back to top

Supported by: Payeezy Gateway, Payeezy

Credit card information is not stored on your server, rather it is tokenized and stored on First Data’s secure servers, which reduces your PCI compliance burden. Learn more about TransArmor Tokenization.

Configuring TransArmor Multi-Pay Tokenization ↑ Back to top

Supported by: Payeezy Gateway, Payeezy

To configure tokenization support for your live First Data account, first contact your merchant services provider and request a TransArmor token if you have not already done so.

Next sign in to your First Data account: globalgatewaye4.firstdata.com

Select your ecommerce terminal by clicking: Administration > Terminals > Your ecommerce terminal:

Select a Terminal
Select a Terminal

Finally enter your token value in the Transarmor Token field for the selected terminal:

Configure Transarmor Token
Configure Transarmor Token

A note on testing: When testing using your demo account follow the steps as outlined above, but rather than requesting a token from your merchant services provider simply use any four digit value, such as ‘1234’ to enable tokenization.

WooCommerce Subscriptions / Pre-Orders Support ↑ Back to top

Supported by: Payeezy Gateway, Payeezy

First Data fully supports all features of WooCommerce Subscriptions and WooCommerce Pre-Orders, though you must first configure TransArmor Multi-Pay Tokenization for your First Data account and then enable Tokenization for this gateway.

When Subscriptions is used, the enhanced “My Payment Methods” table is also active to prevent deleting cards associated with a subscription. You can read about subscription saved methods here.

Soft Descriptors ↑ Back to top

Supported by: Payeezy Gateway, Payeezy

First Data allows a single merchant account to be used across 150 different websites. This is achieved through the use of “Soft Descriptors”. The soft descriptor allows for a secondary business name, address and phone to be recorded into the customers credit card transactions.

Here are some instructions meant to help as a guide in enabling soft descriptors for your merchant account; this is in no way a definitive guide, and we are unable to further help with this process. The First Data account manager for the merchant must go through this process with you.

  • All of the soft descriptors are optional. If you would like to use Soft Descriptors, please contact your First Data Relationship Manager or Sales Rep and have them set your “Foreign Indicator” in your “North Merchant Manager File” to “5”.
  • Then the “Allow Soft Descriptors” box must be checked in the merchants online Payeezy account: globalgatewaye4.firstdata.com. The checkbox for “Allow Soft Descriptors” can be checked by the merchant at any time, but it will not work unless the “Foreign Indicator” has been set to “5” first.
  • Some users have expressed that some account managers will not know how to go through the process for enabling soft descriptors. If you have issues getting this set up, we recommend that customers call the technical support line for Payeezy, then let them call an account manager on behalf of the customer, and get everyone on a 3-way call to ensure that the soft descriptors are enabled successfully.

CVV2 Filtering ↑ Back to top

To configure First Data to decline transactions based on CVV2 response, perform the following configuration to your First Data account:

  1. Log into your demo or production First Data account
  2. Select your eCommerce terminal by clicking: Administration > Terminals > Your ecommerce terminal:

    Select a Terminal
    Select a Terminal
  3. On the “Details” tab scroll down to the “Type” field and ensure “E-Commerce Transaction (CVV2)” is selected. Click “Update”.
    Note: this step is the easiest to overlook or not perform correctly but it’s the most important!

    Enable "E-Commerce Transaction (CVV2)" Type
    Enable “E-Commerce Transaction (CVV2)” Type
  4. Click the “CVV2 Filters” tab and select the CVV2 responses that you wish to result in a declined transaction. Click “Update” once you’re happy:

    Select CVV2 Filters
    Select CVV2 Filters
  5. Optional: you can test the CVV2 handling by enabling demo mode and using one of the special test CVV2 values as shown in the documentation. For instance, use ‘234’ to simulate “CVV2 does not match”.

Upgrading to 4.0 ↑ Back to top

When upgrading First Data to version 4.0 from a previous installation, there are a few changes you should be aware of:

  1. The Key ID and HMAC key values are now required to process payments. This yields both improved transaction security and eCheck support (if enabled in your First Data account).
  2. As of version 4.0.0, both demo and live tokens are now supported, whereas previously only a single “token” type was supported. During the upgrade, demo tokens can’t be separated from live tokens, so all tokens will be treated as production tokens. If you had demo tokens for a user (such as your testing account), these should be deleted or manually updated. For developers: you can also change the meta_key for the token to append _demo to the end if you’d like to just update this in the db.

Troubleshooting ↑ Back to top

First, if you use the Payeezy (API) mode and experience errors while processing, please ensure that Transarmor is enabled for your First Data account, as it is required to use Payeezy (API).

Debug Mode ↑ Back to top

If you see errors when testing your gateway integration, the first step to diagnosing the issue will often likely be to enable the Debug Mode setting in the gateway plugin configuration. Enabling debug mode will give you access to the transaction request/response messages and can be extremely helpful to provide to WooCommerce and First Data support staff for resolving payment issues.

Setting Debug Mode to “Show on Checkout Page” will display the additional debug information and requests/responses (stripped of any sensitive information) directly on the checkout page. This is most useful when you are initially configuring and testing your plugin in demo mode.

Setting Debug Mode to “Save to log” will save the debug information and requests/responses (stripped of any sensitive information) to the WooCommerce Error Log (found under WooCommerce > System Status > Logs). This can be useful when diagnosing an intermittent issue with your production account that is difficult to replicate, to provide a record of the transactions for review by support staff.

Setting Debug Mode to “Both” will cause logging both to the checkout page as well as WooCommerce logs.

As a best practice, be sure to enable Debug Mode only when necessary, and set to “Off” once your issue has been resolved.

Transaction Response – HTTP 401: Unauthorized – Unauthorized Request. Bad or missing credentials. ↑ Back to top

If you are verifying your integration with a test order (always a good idea) and encounter the above error, it means that the Gateway ID and/or Password is configured incorrectly in the plugin for your selected environment (Production/Demo).

If you have the correct Gateway ID/Password (not the same as your account password used to sign into your First Data online account) for your selected environment (Production or Demo) the easiest solution is to update the plugin with the corrected information.

If that fails, or you do not have the password written down, a new one can be generated by following these steps:

  1. Log into your demo or production First Data account
  2. Select your eCommerce terminal by clicking: Administration > Terminals > Your ecommerce terminal:

    Select a Terminal
    Select a Terminal
  3. Ensure that the First Data plugin is configured with the correct Gateway ID for the ecommerce terminal you selected.
  4. After clicking on your ecommerce terminal, scroll down the next page to the Password field, click “Generate” to create a new password, write that password down in a secure location as you won’t be able to view it again. Click “Update” to set the password:

    Updating the Gateway Password
    Updating the Gateway Password
  5. Configure the WooCommerce First Data plugin gateway password setting with your updated password.
  6. Perform a new (hopefully successful) test transaction!

Global Gateway ↑ Back to top

We’re unable to provide extensive support for the Global Gateway integration, as this is deprecated and should be upgraded to Payeezy Gateway or Payeezy (API). However, depending on your host, you may need to request that they open port 1129 bi-directionally.

Questions & Support ↑ Back to top

Have a question before you buy? Please fill out this pre-sales form.

Already purchased and need some assistance? Get in touch via the help desk.


The most customizable eCommerce platform for building your online business.

  • 30 day money back guarantee
  • Support teams across the world
  • Safe & Secure online payment