VibeFox HyperPay for Adobe Commerce — सहायता

Requirements

Magento: Magento Open Source or Adobe Commerce 2.4.6 to 2.4.9, on your own server or hosting, on premises or on Adobe Commerce on cloud infrastructure. The module does not work with Adobe Commerce as a Cloud Service (the SaaS edition), which does not accept PHP modules.

PHP: 8.1 to 8.4, with the OpenSSL extension supporting AES-256-GCM (it decrypts the webhooks) and the cURL extension. Without AES-256-GCM, setup:upgrade stops with HyperPay requires OpenSSL with AES-256-GCM support.

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.

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

Installation

The module is one ZIP file. It is a Composer package and can also be copied into app/code. Run the commands in the Magento root folder as the user that owns the Magento files.

1. With Composer: put the ZIP file into a folder that your project uses as a Composer "artifact" repository and run composer require vibefox/module-hyperpay-payment. Without Composer: unpack the ZIP file into app/code/Vibefox/HyperpayPayment/, so that registration.php is directly in that folder.

2. Run bin/magento module:enable Vibefox_HyperpayPayment and bin/magento setup:upgrade. In production mode also run bin/magento setup:di:compile and bin/magento setup:static-content:deploy, then bin/magento cache:flush.

3. In the Admin go to Stores > Configuration > Sales > Payment Methods and open VibeFox HyperPay Payment Gateway. When the Magento PayPal module is enabled, the group is listed under Other Payment Methods. Paste your VibeFox license key into License key in the license block, the first row of the group, and click Activate (see License key).

4. Enter the test Access Token, Entity ID and webhook key issued by HyperPay and keep Test Mode = Yes. In the HyperPay dashboard (Administration > Webhooks) add a payment webhook with the URL shown in the Webhook field and copy its decryption key into the webhook key field of the same mode. Set Enable to Yes, click Save Config and make a test payment with a HyperPay test card. Then enter the live credentials and set Test Mode to No.

The module adds the Credit/Debit Card (HyperPay) payment method to the Magento checkout. It is off after installation (Enable = No). The module uses the standard Magento order states and creates no order statuses of its own. It creates two tables for the HyperPay payment attempts and the applied HyperPay events.

Configuration

All settings are in Stores > Configuration > Sales > Payment Methods > VibeFox HyperPay Payment Gateway, in the standard Magento configuration form. Like other Magento settings, they can be changed for a website with the Scope switcher at the top of the page; Title and Description also for a store view. Remove data on uninstall is read from the Default Config only. Save Config saves the whole page. Amounts accept "9.99" and "9,99". Spaces are removed from the credentials when you save.

If a value is wrong, Magento shows an error and nothing on the page is saved: an empty Title or a title longer than 128 characters (Enter a title for the payment method (1 to 128 characters).); a Sort Order that is not a whole number; a Minimum Order Total or Maximum Order Total that is not a number of 0 or greater; an unknown Transaction Type.

While Enable is Yes, the Webhook field shows the state of the current mode: HyperPay test mode is on., Enter the Access Token and Entity ID of the active environment. when the Access Token or Entity ID of the current mode is missing (the payment method is then not shown at checkout), and Webhook Key must contain 64 hexadecimal characters. Payments can still be checked on return. when the current mode has no valid webhook key.

The fields are in one list. They are described below in groups.

General

Enable: shows or hides the payment method at checkout. It is shown only when the Access Token and Entity ID of the current mode are set. Default: No.

Title: the payment method name customers see at checkout. It is also stored in the order. Default: Credit/Debit Card (HyperPay). Required, at most 128 characters.

Description: the text shown under the payment method when the customer selects it at 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: uses the HyperPay test system (eu-test.oppwa.com) and the test credentials. No real money is charged. Set it to No to accept real payments with the live credentials (eu-prod.oppwa.com). Default: Yes. While it is on, customers see Test mode: no real payment will be made. under the payment method and on the payment page.

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.

Magento stores the access tokens and webhook keys encrypted and shows only a mask after saving. As the fields say, Leave empty to keep the saved secret. Use the separate clear control to remove it. Type a new value only to change it. When a new webhook key is not 64 hexadecimal characters and Enable is Yes, it is saved and a warning is shown: HyperPay Webhook Key must be 64 hexadecimal characters. Such a key is not used to decrypt webhooks.

Clear saved Test Access Token, Clear saved Test Webhook Key, Clear saved Live Access Token, Clear saved Live Webhook Key: choose Yes and click Save Config to remove that saved secret. The control goes back to No after saving.

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 the Webhook field under Webhook URL:. It is the storefront address of the default store view and looks like https://your-store/wcphyperpaypaymentgateway/webhook/index/. Copy the URL exactly as the settings show it. Then copy the webhook decryption key into Test Webhook Key or Live Webhook Key, for the same mode. The webhook reads the keys of the default store view, so enter them in the Default Config or for the website of the default store view.

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 HyperPay checkout of one of your orders, created in the same mode as the key that decrypted it. Other notifications are acknowledged and ignored. 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. If no brand is selected, the widget shows 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 module does not support.

Conditions

Payment from Applicable Countries: All Allowed Countries offers the payment method for every country your store allows, Specific Countries only for the countries below.

Payment from Specific Countries: offer the payment method only for billing addresses in these countries.

Minimum Order Total: offer the payment method only from this order total, in the base currency of your store. Empty means no minimum.

Maximum Order Total: offer the payment method only up to this order total, in the base currency. Empty means no maximum.

Sort Order: the position among the payment methods at checkout. A whole number.

Advanced

Debug log: writes API requests and responses to var/log/hyperpay_p_debug.log.php in the Magento folder. The file cannot be opened from the web. Errors and warnings are always logged. Logs contain no card data, keys or customer data. Default: No.

Log: shows the size and the latest entries of the log. Click Clear log to empty it.

Remove data on uninstall: when Yes, uninstalling the module with its data deletes the settings and the log (see Uninstall). The license key is always removed. The tables of HyperPay payment attempts and events always stay. Default: No.

Checkout

At the payment step the customer chooses the payment method (by default Credit/Debit Card (HyperPay)) and sees the description and the note You will complete your payment in the secure HyperPay widget. After Place Order, Magento places the order in Pending Payment. No invoice is created and no order e-mail is sent yet. The module then prepares a HyperPay checkout for the order total in the order currency and opens the Complete your HyperPay payment page of your store with the HyperPay widget. The widget uses the store language when HyperPay supports it. In test mode the page shows Test mode: no real payment will be made. The customer enters the card details in the widget. The payment page link works for 25 minutes. If the customer opens the payment again for the same order within that time, the same HyperPay checkout is reused.

After paying, the customer returns to your store. The module checks that the payment belongs to one of this order's HyperPay checkouts and asks HyperPay for the result with a server-to-server request, in the mode the checkout was created in. 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 invoiced twice. When the payment is confirmed, Magento creates the invoice with the HyperPay payment ID and sends the order e-mail, and the customer sees the standard order success page. For a pre-authorization or a mismatch the success page shows Your HyperPay payment is being reviewed by the store. A customer who comes back in another browser lands on the home page.

If the payment was declined, the order is cancelled (the stock goes back), the cart is restored and the customer is back in the cart with Payment failed. Please try again or choose another payment method. If HyperPay has not given a final result yet, or cannot be reached, the customer sees the text We could not confirm your payment yet. Please wait; do not pay again. The order stays in Pending Payment and is updated by the webhook.

If the payment cannot be started, the order is cancelled, the cart is restored and the customer sees a short message in the cart, for example HyperPay could not start the payment. Please try again. or HyperPay payments are unavailable. The technical reason is written to the log. If the cart was already paid with another order, the new order is cancelled and the customer sees Your cart has already been paid with order # and the order number.

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 module works with the standard Magento checkout. It has no refunds or voids from Magento, no partial capture, 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. The payment method is not offered for orders created in the Admin.

Orders and refunds

Order statuses

Pending Payment: the order was placed and the customer was sent to the payment page, but HyperPay has not confirmed the payment yet. There is no invoice. If HyperPay reports the payment as pending, a note says HyperPay payment is pending confirmation.

Processing: a debit payment was confirmed, or a pre-authorization was captured. The invoice is created with the HyperPay payment ID (or the capture ID) as the transaction ID, and a note shows HyperPay payment confirmed: with the payment ID and the HyperPay result code. If HyperPay flagged the payment for manual review, the invoiced order is put On Hold; check it in the HyperPay dashboard before shipping.

On Hold after a pre-authorization: the amount was reserved. The note says HyperPay pre-authorization successful. Capture payment to create a paid invoice. Capture it on the order page or in the HyperPay dashboard; the capture webhook then creates the paid invoice.

On Hold after a mismatch: HyperPay reported a different amount or currency than the order. No invoice is created, and the note says so. Check the payment in the HyperPay dashboard, then fulfil the order or refund the payment there.

Canceled: the payment was declined, it could not be started, or a pre-authorization was reversed in the HyperPay dashboard (the note says HyperPay pre-authorization reversed.).

A declined result never changes a paid order. If another successful payment arrives for an order that is already paid, or a payment arrives after the order was cancelled, the order is not reopened. A note asks you to review and refund the payment in HyperPay. A second pre-authorization for an authorized order is noted the same way. The notes are order comments that the customer does not see.

HyperPay payment information

On the admin order page (Sales > Orders > View) the payment information shows the payment method title and HyperPay environment (test or live), HyperPay reference (the merchant transaction ID), HyperPay payment (the payment ID) and, after a capture, HyperPay capture. The customer sees only the payment method title. On the Information tab the HyperPay payment history table lists every payment attempt of the order with Date, Reference, Checkout ID, Amount, Currency, Environment, Payment ID, Capture ID and Status.

Capture

For an authorized order that is not paid yet, the HyperPay payment history shows the button Capture HyperPay payment. You need the Admin permission to create invoices. Click it to capture the full order total through HyperPay, in the mode the pre-authorization was made in, so that mode's Access Token and Entity ID must be set. After a successful capture Magento creates the paid invoice with the capture ID, the order leaves On Hold and the order e-mail is sent; the message is HyperPay authorization captured. If HyperPay refuses the capture, Magento shows HyperPay capture failed. Code: with the result code, and the order stays On Hold. A repeated click does not capture twice. Partial capture is not supported. Reversing (voiding) a pre-authorization is done in the HyperPay dashboard.

Refunds

Refunds from Magento are not supported: a credit memo offers only Refund Offline, which does not send money back through HyperPay. Refund the payment in the HyperPay dashboard, then create a credit memo with Refund Offline if needed. Refunds and chargebacks made in HyperPay are added to the order as a note by the webhook (HyperPay reports RF for payment … or CB for a chargeback); the order is not changed.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox HyperPay Payment Gateway is the first row of the VibeFox HyperPay Payment Gateway group in Stores > Configuration > Sales > Payment Methods, above the settings. Paste the key into License key and click Activate. After that the block shows the key masked, the status (for example the date the license is active until and your domain) and the buttons Check now to check the status again, Change key to enter another key and Remove key to remove the key from this store. Below them are the line Product: magento-payment-hyperpay and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only Admin users whose role allows the Payment Methods configuration section can change the key. The texts of the block follow the Admin interface locale (English and Russian are included).

If the key is not accepted, the block says why, for example Key not found, This key belongs to another product, Domain limit reached or License expired on a date. After the store address changes, or after you free a domain slot in your account, click Check now. If the license server cannot be reached, the module keeps working on the last known status.

One key works on one domain: the domain of the default store view, also when the installation has several websites or stores. Removing the key from the store does not free its domain slot. Free the slot in your vibefox.net account.

Without an active key, the payment method is not shown to customers at checkout. If a payment is started anyway, the order is cancelled, the cart is restored and the customer sees This payment method is not available. Please choose another one. The Magento storefront does not know that you are logged in to the Admin, so the payment method is hidden for you too: you can set up the module before you buy a key, but not test it at checkout. A reminder appears in the System Messages of the Admin, with the links Enter the license key and Dismiss, which hides it for 7 days. Existing orders are not affected: payments already started are still confirmed, and captures work.

When a license expires, the module keeps working, but updates and support need a renewal. The status is checked again automatically: once a day for the first 14 days after the key is entered, then once a week, by the Magento cron and while you work in the Admin. Uninstalling the module with its data always removes the license key and license status.

Troubleshooting

HyperPay does not appear at checkout: check that the license is active and Enable is Yes for the website of the store, and that the current mode has its Access Token and Entity ID: the test ones in test mode, the live ones in live mode. The Webhook field shows a warning when they are missing. Check Payment from Applicable Countries and Payment from Specific Countries against the customer's billing address, and Minimum Order Total and Maximum Order Total.

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 under Webhook URL:, and that its decryption key is in the webhook key field of the same mode, in the Default Config or for the website of the default store view. Turn on Debug log and look at the Log field.

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.

Webhook answers Busy, retry later: the order was being processed by another request at the same moment, or an error occurred while the order was being updated. HyperPay retries the webhook. The reason is in the log.

Webhook answers 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 webhook URL shows Method not allowed in the browser: this is normal. The URL accepts only POST requests from HyperPay.

Webhooks fail while the store is in maintenance mode: Magento maintenance mode closes the whole site, the webhook URL too. HyperPay retries the webhook later, and the order is also confirmed when the customer returns.

The customer is back in the cart with an error after Place Order: look at the log. A wrong Access Token or Entity ID for the current mode, or customer data that HyperPay did not accept, prevents the payment form from being prepared. Make sure the selected Payment Brands are enabled for your Entity ID. The order of that attempt is cancelled.

The payment page says Invalid or expired HyperPay checkout: the payment page link is older than 25 minutes or the attempt is already finished. The customer places the order again from the cart.

Order is On Hold: read the order notes (see Order statuses), check the payment in the HyperPay dashboard, then capture, fulfil or cancel the order, or refund the payment in HyperPay.

Capture fails: read the result code in the message and the HyperPay log. The capture is sent in the mode of the pre-authorization, so that mode's credentials must be set. This order has no full uncaptured HyperPay authorization. means that the order is already paid or has no open pre-authorization.

The settings page or the checkout looks unchanged after installing or updating: run bin/magento setup:upgrade and bin/magento cache:flush; in production mode also setup:di:compile and setup:static-content:deploy.

Uninstall

Deleting the module code alone removes nothing from the database: the license key and the settings stay. To remove the data, uninstall the module with the Magento command:

Installed with Composer: run bin/magento module:uninstall --remove-data Vibefox_HyperpayPayment. It removes the data and the code.

Installed in app/code: run bin/magento module:uninstall --non-composer Vibefox_HyperpayPayment to remove the data, then bin/magento module:disable Vibefox_HyperpayPayment, delete the folder app/code/Vibefox/HyperpayPayment and run bin/magento setup:upgrade.

The license key and license status are always removed. If Remove data on uninstall is Yes, the settings and the log are removed too. If it is No, the settings are kept for a re-install. The tables of HyperPay payment attempts and events are always kept. Existing orders keep their invoices, payment notes and transaction IDs.

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