VibeFox Autopay 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.

Autopay service: you need the Service ID and Shared key (hash key) of your Autopay service. They are shown in the Autopay merchant portal: portal.autopay.eu for production, testportal.autopay.eu for test. Test services have their own Service ID and Shared key; ask Autopay to open one. The hash function of the service must be SHA-256.

Currency: the order currency must be PLN, EUR, GBP, USD or CZK and accepted by your Autopay service.

Reachable store: Autopay must be able to send notifications to your store, so it must be reachable from the internet without basic authentication or a firewall that blocks POST requests.

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-autopay-payment. Without Composer: unpack the ZIP file into app/code/Vibefox/AutopayPayment/, so that registration.php is directly in that folder.

2. Run bin/magento module:enable Vibefox_AutopayPayment 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 Autopay Payment. 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 Service ID and Shared key (test and production) and choose the currencies of your service. In the Autopay portal set the ITN URL, the return URL and the SHA-256 hash function for your service (see Configuration). Set Enable to Yes, click Save Config and place a test order in test mode. When you are ready, set Test mode to No and click Save Config.

The module adds the Autopay 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 Autopay payment attempts and for the applied notifications.

Configuration

All settings are in Stores > Configuration > Sales > Payment Methods > VibeFox Autopay Payment, 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 for the default store view, so set it in the Default Config. Save Config saves the whole page. Amounts accept "9.99" and "9,99".

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 (Autopay: enter a title of 1 to 128 characters.), a Service ID with other characters than letters, digits, underscores or hyphens or longer than 64 characters (Autopay: Service ID must contain 1 to 64 letters, digits, underscores or hyphens.), a Sort order that is not a whole number (Autopay: sort order must be a whole number.), and a Minimum order total or Maximum order total that is not a number of 0 or greater (Autopay: order total must be a non-negative number.).

While Enable is Yes, the Payment notifications and return address row shows Autopay: the selected service credentials are incomplete. when the Service ID or Shared key of the selected environment is empty, and Autopay: the store currency is not selected. when the currency of the store is not selected in Currencies. In both cases the payment method is hidden at checkout (for the currency that is not selected).

General

Enable: shows or hides Autopay at checkout. Default: No.

Title: the payment method name customers see at checkout. It is also stored in the order. Default: Autopay. Required, at most 128 characters.

Description: shown in the payment method list at checkout, under the method when the customer selects it. Default: Pay online by bank transfer, BLIK or card. You will be redirected to the secure Autopay payment page.

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

Autopay service

The Service ID and Shared key are shown in the Autopay merchant portal. This section links to the Production portal (portal.autopay.eu) and the Test portal (testportal.autopay.eu).

Test mode: uses the Autopay test environment (testpay.autopay.eu) and the test credentials below. Default: Yes. Set it to No to accept real payments on pay.autopay.eu with the production credentials. While it is on, customers see Test mode: no real payment is taken. under the payment method.

Service ID (production): the service identifier from portal.autopay.eu.

Shared key (production): the hash key of the production service. Keep it secret.

Service ID (test): the service identifier from testportal.autopay.eu.

Shared key (test): the hash key of the test service.

Magento stores the Shared keys encrypted and shows only a mask (******) after saving. Leave the mask unchanged to keep the saved key, type a new value to change it. Spaces at the start and end are removed. To delete a saved key, clear the field and click Save Config. The keys are never sent to the browser.

Currencies: select the currencies accepted by your Autopay service: PLN, EUR, GBP, USD, CZK. Autopay usually opens a separate service per currency. The payment method is offered only when the currency of the cart is selected here. Default: PLN.

Payment notifications and return address

This row shows the reminder Set the Autopay service hash algorithm to SHA-256. and two addresses. Enter them in the Autopay portal for your service, for production and for test:

Copy the addresses exactly as the settings show them. Without the ITN URL no order is ever marked paid, because Magento invoices the order only when Autopay confirms the payment. Each ITN is checked with the SHA-256 hash made with the Shared key of the service named in the notification. Notifications without a valid hash or for an unknown Service ID are rejected. A notification is applied to an order only if its payment was started with the same Autopay service, so a test notification never confirms a production payment. Notifications and returns of payments started before you switched Test mode or set Enable to No are still verified with the key of the service and store view the payment was started with, as long as that Service ID and Shared key stay saved.

The module handles these payment statuses in the ITN:

Conditions

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

Payment from specific countries: offer Autopay only for billing addresses in these countries.

Minimum order total: offer Autopay only from this order total, in the base currency of your store. Empty or 0 means no minimum.

Maximum order total: offer Autopay only up to this order total, in the base currency. Empty or 0 means no maximum.

Advanced

Logging: writes payment events to var/log/wc_ap_debug.log.php in the Magento folder: started payments, notification results, rejected notifications and errors. The file cannot be opened from the web. Shared keys, web addresses and e-mail addresses are replaced with placeholders. Default: No. Nothing is written while it is off, errors included.

Remove data on uninstall: when Yes, uninstalling the module with its data deletes the gateway settings and the log (see Uninstall). The license key is always removed. The Autopay payment attempts and notifications, the orders and their history always stay. Default: No.

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

Checkout

At the payment step the customer chooses the payment method (by default Autopay) and sees the description and the note You will be redirected to Autopay to complete the payment securely. After Place Order, Magento places the order in Pending Payment. No invoice is created and no order e-mail is sent yet. The next page shows You are being redirected to Autopay. and sends the customer to the Autopay payment page. The automatic redirect happens once per order in the browser tab; if the customer comes back with the browser's back button, the page shows the Pay with Autopay button instead.

The module passes the order total in the order currency, the cart number as the Autopay OrderID, the description Magento order and the order number, and the customer's e-mail. On the Autopay page the customer chooses the payment method and pays.

The order is marked paid only after Autopay confirms it with a signed ITN and the amount and currency match the order. Magento then creates the invoice with the Autopay transaction ID as the transaction ID, the order moves to Processing and the order e-mail is sent. The notifications are handled even when Enable is No or the license is not active.

After paying, the customer returns to your store. The return address is signed, but it never marks an order as paid. If the order is already paid, the customer sees the standard order success page. If the ITN has not arrived yet, a page shows Your Autopay payment is awaiting confirmation. and The order is not marked as paid until the signed payment notification arrives. with the link Check again and the button Back to checkout. In the browser the order was placed in, Back to checkout cancels the unpaid order (the stock goes back), restores the cart and opens the cart; in another browser it only opens the cart. If Autopay reported a failed payment, the customer goes back to the cart with the cart restored and can pay again or choose another payment method. A customer who comes back in another browser, or with a return address that cannot be verified, lands on the home page.

If the payment cannot be started, for example because the Service ID or Shared key of the selected environment is empty or the currency is not selected, the order is cancelled, the cart is restored and the customer sees Autopay payment could not be started. Please contact the store or return to checkout. If the cart has already been paid by another order, the customer sees This cart has already been paid. Please contact the store if you need the receipt.

Magento cancels orders that stay in Pending Payment longer than the Pending Payment Order Lifetime (Stores > Configuration > Sales > Sales > Orders Cron Settings). The module does not stop such a cancellation. Autopay has no cancel operation, so a payment made later for a cancelled order is not invoiced: the order stays Canceled and a note asks you to reconcile the payment in the Autopay portal.

The module works with the standard Magento checkout. It has no online refunds from Magento, no subscriptions or recurring payments, no saved cards, no BLIK code or card form on the checkout page, no choice of bank or payment channel on the checkout page, and it uses one Service ID per environment. Autopay 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 Autopay, but no confirmation has arrived yet, or Autopay reported the payment as pending. There is no invoice. The order is invoiced when Autopay reports the payment.

Processing: Autopay confirmed the payment and the amount and currency match. The invoice is created with the Autopay transaction ID (remoteID) as the transaction ID, and notes show the transaction, the amount, the status and the Autopay OrderID.

On Hold: Autopay reported a different amount, currency or transaction ID than expected, for example the order total was changed after the payment started. No invoice is created. The note says Autopay: payment amount, currency or transaction ID mismatch. The order is not paid; verify manually. Check the transaction in the Autopay portal. A later correct notification for this order releases the hold and invoices the order.

Canceled: Autopay reported a failed payment, the customer clicked Back to checkout, the payment could not be started, or the order was cancelled in Magento.

A paid order is never changed by a later failure notification. If Autopay reports another successful payment for a paid order, a note warns about a possible duplicate payment. A payment for a cancelled order, or for a cart that was paid by another order, is not invoiced; a note asks you to reconcile it in the Autopay portal. The notes are order comments that the customer does not see.

Autopay payment information

On the admin order page (Sales > Orders > View) the payment information shows the payment method title and, when known, Autopay transaction ID, Autopay OrderID, Autopay last transaction ID, Autopay last notification (status, transaction, amount, currency and date), Autopay attempt status, Autopay service ID, Autopay environment and Autopay expected amount, with the reminder that refunds are managed in the Autopay merchant portal. It is shown also when the module is disabled. The customer sees only the payment method title.

Refunds

Refunds from Magento are not sent to Autopay. Refund the payment in the Autopay merchant portal, then create a credit memo for the invoice with Refund Offline to record the refund in Magento. A full refund closes the order (Closed).

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Autopay Payment is the first row of the VibeFox Autopay Payment 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-autopay 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, Autopay 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 Autopay payment could not be started. Please contact the store or return to checkout. 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.

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

Autopay does not appear at checkout: check that the license is active and Enable is Yes for the website of the store, and that the selected environment has a Service ID and Shared key: the test fields in test mode, the production fields when Test mode is No. Check that the currency of the cart is selected in Currencies. The Payment notifications and return address row shows a warning when one of these is 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: Autopay did not deliver the ITN, or the store rejected it. Check that the ITN URL shown in the settings is set for the service in the Autopay portal (production or test), that the hash function is SHA-256 and that the Shared key in the module matches the service. Check that the store is reachable from the internet. Turn on Logging and look for Autopay ITN rejected in the Log field. If Autopay reported the payment as pending, the order waits until Autopay reports the result.

The log shows Autopay ITN rejected: HASH_INVALID: the Shared key does not match the service, or the hash function of the service is not SHA-256. The store answers 403.

The log shows Autopay ITN rejected: UNKNOWN_SERVICE: the notification came from a service whose Service ID is not entered in the module, or whose Shared key is empty. The store answers 403. INVALID or NO_TRANSACTIONS (answer 400) means the notification could not be read or contained no transaction.

The log shows Autopay ITN rejected: RETRY: the order was being processed by another notification or by the customer at the same moment, or it could not be saved. The store answers 503 so that Autopay sends the notification again.

The ITN URL shows METHOD_NOT_ALLOWED in the browser: this is normal. The URL accepts only POST requests from Autopay.

Notifications fail while the store is in maintenance mode: Magento maintenance mode closes the whole site, the ITN and return URLs too. The order is confirmed by the next notification that reaches the store.

The order is On Hold with a mismatch note: Autopay reported a different amount or currency than the order total. Check the transaction in the Autopay portal and complete or refund the order manually.

A payment was made but the order is Canceled: the payment arrived after the order had been cancelled, for example by the customer with Back to checkout or by the Pending Payment Order Lifetime cron. Read the order notes and reconcile the payment in the Autopay portal.

After paying, the customer lands on the home page: the customer came back in another browser, or the return address could not be verified, for example because the Service ID or Shared key of that payment is no longer saved. The order is not affected; it follows the ITN.

The customer is back in the cart with Autopay payment could not be started: the Service ID or Shared key of the selected environment is empty, the currency of the order is not selected, the order total is zero, the module was disabled, another payment for this cart awaits confirmation or the license is not active. The order of that attempt is cancelled.

There is no Refund button on the credit memo: this is normal. The module has no online refunds. Refund the payment in the Autopay merchant portal, then use Refund Offline.

For developers: optional payment fields can be changed before they are signed with the Magento event wc_ap_payment_params (transport params and the order). ServiceID, OrderID, Amount and Currency are always set by the module.

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_AutopayPayment. It removes the data and the code.

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

The license key and license status are always removed. If Remove data on uninstall is Yes, the gateway settings, including the Shared keys, and the log are removed too. If it is No, the settings are kept for a re-install. The Autopay payment attempts and applied notifications are always kept, so a late notification of an old payment is still handled after a re-install. Existing orders keep their invoices, payment notes and transaction IDs.

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