1. Documentation /
  2. WooCommerce Global Payments HPP

WooCommerce Global Payments HPP


↑ Back to top

Global Payments is one of Europe’s largest and fastest growing online payment gateways. The WooCommerce Global Payments HPP plugin (formerly “Realex HPP”) lets customers pay for their order with credit card, debit cards, or alternative payment methods without exposing your server to SSL requirements or costly PCI scans.

During checkout, customers can be either automatically redirected to Global Payment’s secure payment server or kept on your site with a hosted iFrame form. In both cases, their payment information never touches your server for maximum security. Global Payment HPP also supports 3D Secure v2 for added security and compliance.

Translation ready! This plugin uses two text domains:

  • woocommerce-gateway-realex-redirect
  • woocommerce-plugin-framework

Click here for translation help.

As of WooCommerce 8.3, Cart and Checkout blocks are available as the default experience. WooCommerce Global Payments HPP is now compatible with those blocks!


↑ Back to top


↑ Back to top
  1. Ensure your store meets the plugin requirements.
  2. Download the extension from your WooCommerce dashboard.
  3. Go to Plugins > Add New > Upload and select the ZIP file you just downloaded.
  4. Click Install Now, and then Activate.
  5. Click Configure and read the next section to learn how to setup the plugin.

Upgrading from Global Payments Direct

↑ Back to top

We are in the process of retiring the Global Payments direct payment gateway in favor of using Global Payments HPP, which provides a more secure checkout experience. If you are a current Global Payments direct user, you may have seen an email from the WooCommerce team and / or plugin notices about the upcoming migration of existing users from Global Payments direct to Global Payments HPP.

The migration from Global Payments direct to Global Payments HPP will take place in two steps:

Step 1. Request required credentials from Global Payments support.

In the 2.4.1 release, you’ll plugin notices encouraging you to contact Global Payments support to request the Rebate Password and Default Subaccount, which are required to use Global Payments HPP. Once you’ve received those credentials from Global Payments, you should enter them in the plugin settings. These credentials must be populated before you can migrate in step 2.

If you have already populated the Rebate Password and Default Subaccount in the plugin settings, you are all set for migration! You can sit back and relax until step 2 😀.

Step 2. Upgrade from Global Payments to Global Payments HPP.

In the 2.5 release, you can use our upgrade process to migrate from Global Payments to Global Payments HPP. Your existing subscription for Global Payments direct has automatically been converted to a subscription for Global Payments HPP! Once you have populated the Rebate Password and Default Subaccount in your plugin settings, you can migrate your site to Global Payments HPP seamlessly with a few clicks.

First, you should be connected to WooCommerce.com to complete this migration. If your site isn’t connected to WooCommerce.com, you’ll be prompted to connect. Click here for instructions on connecting to WooCommerce.com. If you can’t connect to WooCommerce.com, please see our upgrade FAQs.

After connecting to WooCommerce.com, you’ll see a notice prompting you to migrate. With a single click, this will automatically take care of the full migration:

  • Global Payments HPP will be downloaded from WooCommerce.com, installed, and activated on your site.
  • Your settings and credentials will be copied from Global Payments direct to Global Payments HPP.
  • Orders that were associated with Global Payments direct will be updated to Global Payments HPP, to support captures / refunds.
  • If you’re using Subscriptions, payment tokens and ongoing subscription renewals will be migrated to Global Payments HPP and will continue to process seamlessly.

Upgrade FAQs

↑ Back to top

Q: What if I can’t connect to WooCommerce.com? (For example, your site sells CBD products.)
A: You can still migrate, with a few extra steps:

  1. Download the Global Payments HPP extension from your WooCommerce account – you’ll already have a subscription for it!
  2. Install this plugin under Plugins > Add New > Upload.
  3. Activate the plugin.

Once Global Payments HPP is activated, the rest of the migration routine will begin automatically!

Note: If you haven’t populated the Rebate Password and Default Subaccount, the migration routine will not begin until those credentials are saved in the plugin settings.

Q: I sent an email to Global Payments support to request the Rebate Password and Default Subaccount, but I haven’t heard back yet. What should I do?
A: First, we should determine if the email was delivered as expected. Did you receive an auto-response from Global Payments support? Please check your Spam / Junk mail too (and if you see the response there, please add their support address to your contacts!).

If you received an auto-response, it’s likely that their support team hasn’t gotten to your request yet. The Global Payments team should respond to your request in 3-5 business days. If you’re still within that timeframe, please be patient!

If you did not receive an auto-response or it’s been more than 5 business days since you sent the email, please use the option to resend the email in the plugin notice. This will let you send another email directly from your email client (e.g., Outlook, Apple Mail, etc.), which should improve the deliverability if there was some problem sending from your WordPress site.

Please ensure that your Global Payments account owner is included in the email’s From / Reply-To field, so the Global Payments team knows you’re authorized to make this request!

Q: Are there any additional merchant fees associated with using Global Payments HPP instead of Global Payments direct?
A: No! The Global Payments team has confirmed that there are no additional charges associated with using Global Payments HPP.

Q: What will happen to my plugin subscription?
A: Your WooCommerce.com account was automatically gifted a new subscription for the Global Payments HPP plugin. Here’s how the WooCommerce team handled this:

  • You have been gifted a subscription for Global Payments HPP that ends on the same date as your original Global Payments direct subscription (so this upgrade is completely free!).
  • If your Global Payments direct subscription was set to auto-renew, we’ve turned that off, and enabled auto-renew on the Global Payments HPP subscription. If your Global Payments direct subscription did not auto-renew, we’ve left that disabled on both plugins.
  • Your Global Payments direct subscription is still in your account for now, but it will end on its end date as expected and cannot be renewed.

Q: Why is Global Payments direct being retired?
A: By using payment fields hosted by Global Payments instead of requiring you to accept payment information directly on your site, Global Payments HPP offers you and your customers a much more secure payment experience. Using Global Payments HPP can also help your site achieve SAQ-A PCI compliance!

Beyond that, the features in Global Payments HPP are largely similar to Global Payments direct – it supports tokenization (needed for Subscriptions / Pre-Orders compatibility), 3DS v2, and many other important features. You can read more about this plugin in this document!

Q: What if I don’t want to migrate to Global Payments HPP?
A: We strongly encourage that you start taking advantage of Global Payments HPP’s more secure checkout as soon as you can, but we will continue to support the Global Payments direct extension until your current subscription expires. Please plan to migrate to Global Payments HPP before that date to avoid interruption in payment processing!

Q: What if the migration doesn’t go smoothly?
A: We’ve handled this migration process before for other plugins, and it’s a pretty foolproof process! The worst-case scenario is that we’re not able to migrate the plugin’s settings, and you’d need to update them manually. If you’d like to double-check the migration process, we recommend completing it at an off-peak time for your store’s order activity, and then test a payment on the new gateway with your store. If anything seems off, our support team is happy to help!

Getting started

↑ Back to top

To use Global Payments HPP, you must have an active eCommerce merchant account with Global Payments and provide Global Payments support with your referring URL (i.e. the URL of your payment pages).

The referring URL will look like this, where ‘mysite.com’ is replaced with your site’s domain:


Send this URL to Global Payments support (ecomsupport@globalpay.com) as you prepare to accept payments with this plugin. Once you’ve completed that step, you can continue setup by following the steps below:

  1. Go to WooCommerce > Settings > Payments and select Global Payments HPP.
  2. Update the following fields with data provided by your Global Payment sales representative:
    • Merchant ID
    • Shared Secret
    • Rebate Password; this is required to process refunds from WooCommerce
    • Default Subaccount
  3. Click Save Changes.

That’s it! You’re ready to start accepting payments. Keep reading if you want to tweak settings and customize the checkout process.

Credit card settings

↑ Back to top

You can configure the following settings for the Global Payments HPP gateway:

  • Enable / Disable: Allow customers to use this gateway to checkout.
  • Title: The text shown for the payment during checkout and on the Order Received page.
  • Description: The text shown under the gateway’s title during checkout. Limited HTML is allowed.
  • Card Verification (CSC): Require customers to enter their card security code when checking out.
  • Transaction Type: Controls how transactions are submitted to Global Payments. Defaults to “Charge” to automatically capture payments. Click here to learn more about capturing payments.
    • Charge Virtual-Only Orders: If Transaction Type is set to “Authorization”, enable to automatically capture charges for orders with only virtual products. For downloadable products, this will grant download access right away.
    • Enable Partial Capture: If Transaction Type is set to “Authorization”, enable to allow multiple, partial captures. Click here to read more about partial captures.
    • Capture Paid Orders: If Transaction Type is set to “Authorization”, enable to automatically capture charges when orders move to a paid status (i.e. Processing or Completed).
  • Accepted Card Logos: Determines which card logos are displayed during checkout. This has no impact on which cards are accepted by your merchant account.
  • Tokenization: Let customers save their payment methods for future use at checkout. You must have card storage tokenization enabled on your Global Payments account to save payment methods. This is required for Subscriptions or Pre-Orders.
    • Require Tokenization: If Tokenization is enabled, require merchants to save payment methods during checkout. This will disable guest purchasing.
  • Detailed Decline Messages: Display detailed messages to customers to provide reasoning for declines instead of a generic error message when possible. Click here to read more about detailed decline messages.
  • Debug Mode: Enable when you’re having issues processing transactions. You can choose to log API requests directly on the checkout page, save them to the WooCommerce > Status > Logs page, or both. As a best practice, please do not enable this setting unless you’re having issues with the plugin.
  • Environment: Switch between “Production” and “Sandbox” credentials. Set to “Production” to process payments and “Sandbox” to send transactions to your Global Payments sandbox account.
  • Merchant ID: Your Global Payments merchant ID, provided by your Global Payments sales representative.
  • Shared Secret: The shared secret for your account, provided by your Global Payments sales representative.
  • Rebate Password: The rebate password for your account, provided by your Global Payments sales representative. This is required to process refunds in WooCommerce.
  • Default Subaccount: The Global Payments subaccount to use for your transactions.
  • Form URL: Use the default checkout form, or enter the URL for your custom form. Click here to learn more about form customization.
  • Form Type: Choose the form type for your payment form. Select “iFrame” to show the Global Payments hosted credit card form, which keeps customers on your site during payment. Select “Redirect” to redirect customers directly to the hosted credit card page for payment.
In either case, you must first provide Global Payments with the correct referring URL for approval (e.g. https://mysite.com/checkout/*), otherwise Global Payments may reject transactions and prevent customer payment.
  • Form Language: Choose the language for the Hosted Pay Page form; defaults to your site language.
  • Address Verification Service (AVS): Prompt Global Payments to perform an AVS check on the submitted transaction.
  • Enable Alternative Payment Methods: Allow customers to choose an alternative payment method (APM) at checkout. APMs must first be enabled on your Global Payments account before they will appear at checkout.
    • Available APMs: Select the alternative payment methods to display at checkout, or leave blank to display all available APMs. APMs must first be enabled on your Global Payments account before they will appear at checkout.
    • Refund Password: The refund password for your account, provided by your Global Payments sales representative. This is required to process refunds in WooCommerce for alternative payment methods.

Managing orders

↑ Back to top

As a site administrator, you can use the Global Payments HPP gateway to manually capture charges and automatically refund / void transactions as needed.

Capture Charges from WooCommerce Order Admin

↑ Back to top

If the gateway’s Transaction Type is configured to “Authorization”, you can manually capture these payments from the WooCommerce Orders page. Click here to read more about capturing charges.

Partial captures

Global Payments HPP can support partial payment captures when enabled in the plugin settings. This lets you perform multiple captures on an existing authorization. Global Payments allows merchants to capture up to 115% of the order total if using multiple captures.

To perform a partial capture:

  1. Go to WooCommerce > Orders and select the authorized order in question.
  2. Click Capture Charge.
  3. Enter the desired Capture amount and click Capture. You can repeat this action until the total possible capture amount has been met.
WooCommerce Global Payments HPP process capture

Automatic refunds

↑ Back to top

You can process refunds directly in WooCommerce without needing to log into your Global Payments control panel. Click here to read more about issuing automatic refunds from WooCommerce.

Note: You must enter your Rebate password (and Refund password, for APM payments) in the credit card settings to support automatic refunds.

Void transactions

↑ Back to top

You can void transactions directly in WooCommerce in the following circumstances:

  • If the Transaction Type is set to “Authorization”, you can void when the transaction has been authorized but not yet captured.
  • If the Transaction Type is set to “Charge”, you can void when the transaction has not yet been settled (i.e. funds haven’t been transferred from the customer’s account to your Global Payments account).

Global Payments doesn’t accept partial voids. If a transaction is no longer eligible to be voided, you must refund the order. Click here to read more about voiding transactions in WooCommerce.

Gateway features

↑ Back to top

Your customers can take advantage of the following features when your site uses Global Payments HPP.

Saved payment methods

↑ Back to top

When Tokenization is enabled, customers can save payment methods during the checkout process or from their My Account area. This lets them quickly save payment details or link their PayPal account for faster future purchases and also lets your site support Subscriptions and Pre-Orders. Click here to read more about managing saved payment methods.

Change payment methods for subscriptions

↑ Back to top

If you’re using WooCommerce subscriptions, your customers can manage the payment methods for their subscriptions from the My Account dashboard.

  1. In My Account, click Subscriptions.
  2. On the Subscriptions page, click Change payment.
  3. On the Change payment method page, all enabled payment methods that support subscriptions will appear.
  4. Select a different payment method.
  5. Add or select a credit card.
  6. Click Change payment method. A success messsage will appear, “Payment method updated.”
  7. The new payment method now appears next to Payment in the subscription details.

Frequently Asked Questions

↑ Back to top

Q: Does Global Payments HPP work with WooCommerce Subscriptions or WooCommerce Pre-Orders?

A: Yes! This gateway fully supports all features of Subscriptions and Pre-Orders. Please note that in order to use these plugins with Global Payments HPP, you must:

Please also note that for subscriptions and pre-orders that require no initial payment, a €0.02 authorization may be processed when using an existing card. Click here for more information.

Q: Why do some order numbers not match between Global Payments and WooCommerce?

A: In some cases, the order number in Global Payments may not match WooCommerce (e.g. WC order #500 might display as #500-3 in Global Payments). This is due to a limitation with Global Payments where each payment attempt must use a unique order number, combined with a limitation in WooCommerce where failed orders from redirect gateways must use the same order number for each payment attempt.

To account for this, Global Payments APP appends an incrementing counter to the WooCommerce order to represent the transaction attempts. In our above example, #500-3 indicates that this is order #500 in WooCommerce, which was attempted 3 times before succeeding.

Q: Is this plugin compatible with the Global Iris payment gateways?
A: Yes, simply use your Global Iris Merchant ID and Shared Secret in the plugin settings to connect with a Global Iris gateway.

Q: How do I enable 3D Secure V2?
A: As long as you have 3D Secure V2 enabled on your Global Payments account, there’s not anything you need to enable via the plugin as we use a hosted payment form. If you don’t have 3D Secure V2 enabled, please contact your Global Payments sales representative or Global Payments support to enable this for your account.

This means that the processor takes care of 3D Secure V2 on their end as our plugin captures the data needed, and during checkout, customers can be either automatically redirected to Global Payment’s secure payment server or kept on your site with a hosted iFrame form.


↑ Back to top

Orders remain pending

↑ Back to top

Global Payments HPP uses an asynchronous payment notification system (similar to PayPal’s IPN), which means that Global Payments must be aware of your shop’s server and able to communicate with it to complete the checkout process. If Global Payments fails to communicate with your server, it can result in successful checkouts and payments that aren’t registered in WooCommerce as a paid order (i.e. stuck in a “pending” state).

Follow the steps below to troubleshoot (and hopefully resolve) this issue:

  1. Confirm your referring URL. Verify that you have provided your referring URL to Global Payments.
  2. Contact your host.Ensure that your hosting company isn’t blocking the Global Payments servers from notifying your site of payments. This is particularly likely if you are seeing the following error:Unable to connect to the merchant, response URL: http://www.YOUR-SHOP.com/wp/?wc-api=WC_Gateway_Global Payments_RedirectIf you see that error, ask your hosting company to allow the following Global Payments server IP addresses:
  3. Check plugin logs. Enable Debug Mode in the plugin settings, submit a transaction, and check the logs under WooCommerce > Status > Logs. You’ll want to look for a line starting with “Redirect Response”, which may contain some information about the error. If the error message does not guide you to a solution, please contact our support team. If you do not see a “Redirect Response” line, continue to the next step.
  4. Verify server accessibility. If you’ve gotten this far, it’s likely that there’s a communication issue between Global Payments and your server. Please verify that your server isn’t inaccessible (e.g., behind a firewall, using a “coming soon” plugin, or some other security measure).
  5. Check server access logs. Finally, try submitting a transaction while watching your web server (generally apache) access logs. This may require assistance from your server host, depending on your host and your own technical ability. If you see something like the following after you perform a test transaction… - - [02/May/2013:16:47:13 -0400] "POST /?wc-api=WC_Gateway_Global Payments_Redirect HTTP/1.1" 206 168 "-" "epage.cgi, getMerchantContent libwww-perl/5.805"…that means Global Payments can communicate with your server. In that case, you should contact support and provide information about the above test results. If you do not see a request like that, that means Global Payments isn’t performing the payment response request to your site. In that case, please contact Global Payments Support (ecomsupport@globalpay.com) and ask them to investigate further.

€0.02 Authorizations

↑ Back to top

In some cases, when a customer uses a saved card at checkout, this plugin will process a €0.02 authorization rather than a €0 order. This occurs when:

  • The customer is using an existing saved card token that has been saved from a previous order.
  • The current total for the order is “0” — this happens when a free trial subscription is purchased, or a pre-order that is charged at release.

This is due to a bug on the Global Payments side with the hosted payment form that will fail these transactions erroneously, and our plugin has no way to recognize these errors vs a “real” decline. As such, the small authorization is done as a workaround to ensure that these transactions don’t fail without any known error code in your store, so they will process successfully.

We are keeping tabs on this bug, and will remove the authorization workaround when it’s fixed by Global Payments to avoid your store being charged for an extra transaction. You can contact Global Payments with further questions and to let them know this fix is important to your store.

Success message not displayed

↑ Back to top

If your success message isn’t being displayed to customers after successful transactions, please first ensure that you’ve provided the referring URL to Global Payments support.

If you sent your referring URL to Global Payments very recently, please note that there’s an expected delay of 24 hours for email responses. Once a change has been implemented on the account, a confirmation email should be sent to whoever contacted Global Payments. Until you receive this email, you won’t be able to correctly accept credit card payments.

Mandatory field missing. HPP_(FIELD_NAME) not present in request.

↑ Back to top

If you are selliing digital products that do not require shipping and remove the related address fields from the Checkout page, you may receive “Mandatory field missing.” errors. These fields are required by GlobalPay in order to meet European SCA requirements and are set to Mandatory on the GlobalPay API. As such, you must ensure that your Checkout page displays and requires the address fields. You can review the fields and their Type in order to determine which fields are mandatory in the developers portal here.

Other issues

↑ Back to top

Having a different problem? Follow these steps below to make sure everything is setup correctly:

  • Please ensure that your site meets the plugin requirements.
  • Check the FAQs to see if they address your question.
  • Confirm that you have sent your referring URL to Global Payments and received confirmation.
  • Confirm that your Merchant ID, Shared Secret, Rebate Password, and Refund Password are all correct.
  • Confirm that you’re not using production credentials when the gateway’s Environment is set to “Sandbox” (or vice versa).
  • Enable Debug Mode and review the errors codes/messages provided by Global Payments under WooCommerce > Status > Logs. In some cases, such as a transaction being held for review or declined, the plugin cannot change the issue and it must be resolved in your Global Payment account. If the error code indicates an issue with the plugin, please submit a support ticket and include the logs to help us troubleshoot.

Questions & support

↑ Back to top

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

Already purchased and need some assistance? Please check out our troubleshooting tips and frequently asked questions for common issues or contact support via the help desk if you need more help.