VibeFox HyperPay for WooCommerce — Help

Requirements

WordPress: 6.0 or later.

WooCommerce: 8.0 or later, installed and active. The plugin refuses to activate without it.

PHP: 8.0 or later.

HyperPay account: HyperPay issues the Access Token and Entity ID when your merchant account is set up. Test and live credentials are different. You also need a payment webhook in the HyperPay dashboard and its decryption key (webhook key), shown under Administration > Webhooks (see Configuration).

Card data: the card is entered only in the HyperPay widget, so card data never touches your server (PCI DSS SAQ A).

VibeFox license key: bought on vibefox.net. One key works on one domain.

Installation

1. In WordPress go to Plugins > Add New > Upload Plugin, choose the plugin ZIP file and click Install Now. You can also upload the wcp_hyperpay_payment_gateway folder to /wp-content/plugins/ by FTP.

2. Click Activate.

3. Open the settings: WooCommerce > Settings > Payments > HyperPay > Manage, or click Settings under the plugin name on the Plugins page.

4. Enter your VibeFox license key in the license block at the top of the page and click Activate.

5. Enter the test Access Token, Entity ID and webhook key issued by HyperPay and keep Test Mode on.

6. In the HyperPay dashboard (Administration > Webhooks) add a payment webhook with the URL shown in the settings and copy its decryption key into the webhook key field of the same mode.

7. Turn on Enable/Disable and make a test payment with a HyperPay test card. Then enter the live credentials and turn Test Mode off.

Configuration

All settings are on one page: WooCommerce > Settings > Payments > HyperPay. Above the fields the page shows Test mode is on: payments go to the HyperPay test system and no real money is charged. while test mode is on. It warns you when the Access Token or Entity ID of the current mode is missing (the payment method is then not shown at checkout), and when the current mode has no valid webhook key (payments are then confirmed only when the customer returns to the store). In the list of payment methods the gateway is marked as needing setup until the current mode has its Access Token and Entity ID. When you save, spaces are removed from the credentials, and the page shows an error if a webhook key is not a 64-character hexadecimal key.

Enable/Disable: Enable HyperPay Payment turns the payment method on or off. Default: off.

Title: the title the customer sees during checkout. Default: Credit/Debit Card (HyperPay).

Description: the description the customer sees during checkout. Default: Pay securely using your credit or debit card.

API credentials

The Access Token, Entity ID and webhook key are issued by HyperPay when your merchant account is set up. Test and live credentials are different. The webhook key is shown in the HyperPay dashboard under Administration > Webhooks.

Test Mode: Enable Test Mode uses the HyperPay test system (eu-test.oppwa.com) and the test credentials. No real money is charged. Turn it off to accept real payments with the live credentials (eu-prod.oppwa.com). Default: on.

Test Access Token: the bearer token of your HyperPay test account.

Test Entity ID: the Entity ID of the test payment channel.

Test Webhook Key: the 64-character hexadecimal key used to decrypt webhook notifications of the test system.

Live Access Token: the bearer token of your HyperPay live account.

Live Entity ID: the Entity ID of the live payment channel.

Live Webhook Key: the 64-character hexadecimal key used to decrypt webhook notifications of the live system.

Webhook

The webhook tells your store about payments even when the customer closes the browser before returning to the store. In the HyperPay dashboard (Administration > Webhooks) add a webhook for payments with the URL shown in this section of the settings. It looks like https://your-site/wp-json/hyperpay-p/v1/webhook. Then copy the webhook decryption key into Test Webhook Key or Live Webhook Key, for the same mode.

HyperPay webhooks are encrypted (AES-256-GCM). A webhook that cannot be decrypted with your keys is rejected. Only payment notifications are processed, and the payment must belong to a checkout of one of your orders, created in the same mode as the key that decrypted it. HyperPay test notifications are acknowledged. The webhook also reports captures, reversals, refunds and chargebacks made in the HyperPay dashboard (see Orders and refunds). Without the webhook, a payment is confirmed only when the customer returns to the store after paying.

Payment

Transaction Type: how the card is charged.

Payment Brands: the brands shown in the payment widget: VISA, Mastercard, mada, American Express, STC Pay, Apple Pay. Default: VISA and Mastercard. Select only brands that HyperPay enabled for your Entity ID; mada, STC Pay and Apple Pay often use their own entity, which this plugin does not support.

Advanced

Enable Logging: Log API requests and responses. Debug information is written to WooCommerce > Status > Logs, source wcp_hyperpay_payment_gateway. Errors are always logged. Logs contain no card data, keys or customer data. Default: off.

Delete Data on Uninstall: Delete all plugin data when the plugin is uninstalled. Removes the settings and log files when the plugin is deleted. HyperPay data stored on orders is kept. Default: off.

Checkout

The customer chooses the payment method (by default Credit/Debit Card (HyperPay)) and clicks Continue to payment. The order is created and the customer goes to the Pay for order page. There the plugin prepares a HyperPay checkout for the order total in the order currency and shows the HyperPay widget with Please complete your payment below:. The widget uses the language of your site when HyperPay supports it. In test mode the page shows Test mode: use a HyperPay test card, no real payment will be made. The customer enters the card details in the widget.

After paying, the customer returns to your store. The plugin checks that the payment belongs to one of this order's checkouts and asks HyperPay for the result with a server-to-server request. The order is marked paid only after HyperPay confirms it: by that request or by the webhook. The amount and currency must match the order. A return and a webhook arriving at the same moment are handled one after the other, so the order is never processed twice. When the payment is confirmed, the customer lands on the order received page.

If the payment did not go through, the customer goes back to the Pay for order page with a message: Payment failed: and the reason from HyperPay, Payment was not completed. Please try again., or We could not confirm your payment yet. If you were charged, the order will be updated automatically; otherwise please try again. The customer can pay again on the same page. If the widget cannot be prepared, the customer sees a short message, for example that some billing details were not accepted by the payment provider, and a Try Again button. The details are added to the order notes.

Amounts are sent with two decimals, as the HyperPay API requires. In 3-decimal currencies (KWD, BHD, JOD, OMR) the order total is rounded to two decimals.

The payment method works on the classic checkout, on the Cart and Checkout blocks and on the Pay for order page. In test mode the Checkout block shows Test mode: no real payment will be made. It is compatible with WooCommerce High-Performance Order Storage (HPOS).

The plugin has no refunds or voids from WooCommerce, no saved cards or tokenization, no subscriptions, no Apple Pay domain verification, no separate entity per brand and no Tabby, Tamara or other buy-now-pay-later methods.

Orders and refunds

Order statuses

Pending payment: the customer has not paid yet, did not finish the widget, or HyperPay has not confirmed the payment yet.

Processing: a debit payment was confirmed, or a pre-authorization was captured. Orders with only virtual downloadable products become Completed, the WooCommerce default. The order note shows the HyperPay result code, description and payment ID. The transaction ID is the HyperPay payment ID. If HyperPay flagged the payment for manual review, the note says so; check it in the HyperPay dashboard before shipping.

On hold (pre-authorization): the amount was reserved. Capture it with the order action Capture HyperPay payment or in the HyperPay dashboard; the capture webhook then completes the order.

On hold after payment: HyperPay reported a different amount or currency than the order (for example the order was edited after the payment page was opened), the payment is still pending at HyperPay, or the payment arrived after the order had been cancelled. The order note explains it. Check the payment in the HyperPay dashboard and complete or refund it.

Failed: HyperPay declined the payment. The reason is in the order note and is shown to the customer. A declined attempt never changes an order that is already paid, reserved, on hold or cancelled.

Cancelled: a pre-authorization was reversed in the HyperPay dashboard, and the reversal webhook cancels the on-hold order.

If another successful payment arrives for an order that is already paid, the order is not changed. A note asks you to refund the duplicate in the HyperPay dashboard. A successful payment for a refunded order only adds a note.

Capture

The order action Capture HyperPay payment appears on on-hold orders with a pre-authorization that is not captured yet. It captures the current order total, minus refunds already recorded in WooCommerce, in the mode the pre-authorization was made in. After a successful capture the order becomes Processing. If HyperPay refuses the capture, the result code and description are shown and added to the order notes. Reversing (voiding) a pre-authorization is done in the HyperPay dashboard.

Refunds

Refunds from WooCommerce are not supported. Refund the payment in the HyperPay dashboard and record it in WooCommerce with Refund manually. Refunds and chargebacks made in HyperPay are added to the order as a note by the webhook; the order status is not changed.

License key

The plugin works with a VibeFox license key from vibefox.net. The license block is at the top of WooCommerce > Settings > Payments > HyperPay. Paste the key into License key and click Activate. The block shows the status, for example the date the license is active until and your domain. Use Check now to check the status again, Change key to enter another key and Remove key to remove it from this site. The link Manage licenses and domains in your account opens your vibefox.net account.

One key works on one domain. Removing the key from a site does not free its domain slot. Free the slot in your vibefox.net account.

Without an active key, HyperPay is not shown to customers at checkout. If a payment is started anyway, the customer sees This payment method is not available. Please choose another one. Logged-in store managers still see the payment method, marked (unlicensed — visible to admins only), so you can set up and test the plugin before you buy a key. A reminder appears on the Plugins page and on WooCommerce pages. Existing orders are not affected: payments already started are still confirmed, and captures work.

When a license expires, the plugin keeps working, but updates and support need a renewal. The status is checked again automatically in the background.

Troubleshooting

HyperPay does not appear at checkout: check that the license is active, Enable/Disable is on and the current mode has its Access Token and Entity ID: the test ones in test mode, the live ones in live mode. The settings page shows a warning when they are missing.

The payment went through, but the order stays Pending payment: the webhook is not working and the customer did not return to the store. In the HyperPay dashboard check that the payment webhook exists for the mode you use, that its URL is exactly the one shown in the settings, and that its decryption key is in the webhook key field of the same mode. Look at WooCommerce > Status > Logs, source wcp_hyperpay_payment_gateway.

Webhook answers Decryption failed: the webhook key belongs to another webhook or another mode. Copy the key again from the HyperPay dashboard.

Webhook answers Webhook key not configured: no valid webhook key is set. Paste the 64-character key into the settings. HyperPay retries the webhook.

Log shows Webhook ignored: the payment does not belong to an order of this store, or it was made in the other mode. Test and live payments are kept apart.

The payment form does not load: read the order note. A configuration error usually means a wrong Access Token or Entity ID for the current mode. A message about billing details means HyperPay did not accept some customer data. Make sure the selected Payment Brands are enabled for your Entity ID.

Order is On hold with an amount/currency mismatch note: HyperPay reported a payment that does not match the order total or currency, for example because the order was edited after the payment page was opened. Check the payment in the HyperPay dashboard and complete or refund it.

Capture fails: read the result code and description in the order note. The capture is sent in the mode of the pre-authorization, so that mode's credentials must be set.

The license block shows an error: follow the message in the block. For example, if the key is already used on another domain, free a slot in your vibefox.net account and click Check now. If the site address changed, click Check now to activate the key for the new domain. If the license server cannot be reached, the plugin keeps working on the last known status.

For developers: the filter hyperpay_p_icon changes the payment method icon.

Uninstall

Deactivating the plugin keeps all data. To remove it, deactivate and delete it on the Plugins page. The license key and license status of this plugin are always removed. The gateway settings, the plugin's temporary data and the log files are removed only if Delete Data on Uninstall was on. Otherwise they stay for a later re-install. HyperPay data stored on orders is always kept. Existing orders keep their payment notes and transaction IDs.

HyperPay is a trademark of its respective owner. This plugin is not affiliated with or endorsed by HyperPay.