VibeFox GoPay for Adobe Commerce — Yardım

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 cURL and JSON extensions.

Currency: GoPay accepts CZK, EUR, PLN, USD, GBP, HUF, RON and BGN. When the customer's cart is in another currency, the payment method is hidden at checkout.

GoPay account: you need the GoID, Client ID and Client Secret of your GoPay merchant account. They are in the integration settings of the account. The sandbox (test) account has its own credentials. Nothing has to be set up in the GoPay account for notifications, but your store must be reachable from the internet.

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

2. Run bin/magento module:enable Vibefox_GopayPayment 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 GoPay. 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 sandbox GoID, Client ID and Client Secret, keep Test Mode = Yes, set Enable to Yes and click Save Config. Place a test order. When everything works, enter the production credentials and set Test Mode to No.

The module adds the GoPay 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 three tables for the GoPay payment attempts, their events and the refunds.

Configuration

All settings are in Stores > Configuration > Sales > Payment Methods > GoPay, 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. Saving also clears the cached GoPay access tokens, so new credentials are used at once. The fields are shown in one list; below they are grouped by topic.

Some wrong values are not saved, and the page shows an error while the other fields are saved: a GoID that is not 6 to 20 digits (GoID must contain 6 to 20 digits. The previous value was kept.) and an empty title or a title longer than 128 characters (GoPay title is required and must not exceed 128 characters. The previous value was kept.). For other wrong values Magento shows an error and nothing on the page is saved: a Sort Order that is not a whole number, and a Minimum Order Total or Maximum Order Total that is not a number of 0 or greater (use a dot as the decimal separator, for example 9.99).

When Enable is Yes, saving shows GoPay credentials are missing: GoID, Client ID and Client Secret are required for the selected environment. if the credentials of the current mode are not complete, and GoPay: sandbox mode, test payments only. while Test Mode is Yes.

General

Enable: shows or hides GoPay at checkout. It is shown only when the GoID, Client ID and Client Secret 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: GoPay. Required, at most 128 characters.

Description: shown in the payment method list at checkout, when the customer selects GoPay. Default: Pay securely via GoPay - cards, wallets, bank transfers.

API credentials

GoID, Client ID and Client Secret are shown in your GoPay merchant account (integration settings). The sandbox (test) account has its own credentials. The API documentation is at doc.gopay.com.

Test Mode: sends new payments to gw.sandbox.gopay.com with the sandbox credentials. No real money is charged. While it is on, customers see TEST MODE - no real payments will be processed. under the payment method. Set it to No to accept real payments at gate.gopay.cz with the production credentials. Default: Yes.

Sandbox GoID: the GoID of your GoPay sandbox (test) account.

Sandbox Client ID: the OAuth Client ID of the sandbox account.

Sandbox Client Secret: the OAuth Client Secret of the sandbox account.

Production GoID: your GoPay merchant ID (GoID).

Production Client ID: the OAuth Client ID from GoPay.

Production Client Secret: the OAuth Client Secret from GoPay.

A GoID contains 6 to 20 digits, for example 8123456789. Magento stores both client secrets encrypted and shows only a mask (******) after saving. Leave the mask as it is to keep the saved value, type a new value to change it. To delete a saved secret, clear the field and click Save Config.

Payment

Payment Page Language: the language of the GoPay payment page. Default: Automatic (site language, then billing country). Automatic uses the language of the store view; if GoPay does not have it, the billing country decides, and English is used otherwise. You can also fix one of 19 languages: Czech, English, Slovak, German, Polish, Hungarian, Romanian, Bulgarian, Croatian, Slovenian, Estonian, Latvian, Lithuanian, French, Italian, Spanish, Portuguese, Ukrainian or Russian.

Order Status After Payment: the order status set when the payment is confirmed.

Payments that do not match the order and pre-authorized payments always go to On Hold.

Conditions

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

Payment from Specific Countries: offer GoPay only for billing addresses in these countries.

Minimum Order Total: offer GoPay only from this order total, in the base currency of your store. 0 or empty means no minimum.

Maximum Order Total: offer GoPay only up to this order total, in the base currency. 0 or empty means no maximum.

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

Payment notifications

The notification tells your store that a payment has been made. The Notification URL is shown on the settings page, below Remove data on uninstall, and is sent to GoPay with every payment, so nothing has to be set up in the GoPay account. It is the storefront address of the store view of the order and looks like https://your-store/wcpgopaygateway/checkout/notify/. It must be reachable from the internet: no password protection or firewall in front of it.

GoPay notifications carry only the payment ID and no signature. Every notification is verified by asking the GoPay API for the payment state, with the credentials of the mode the payment was made in, and the payment must be one the module created for an order of your store. When the state cannot be read from GoPay, your store answers with an error and GoPay repeats the notification. In addition, the Magento cron checks open GoPay payments every 5 minutes, so a payment is confirmed even when the notification and the customer's return are both missing.

Advanced

Debug Log: writes GoPay events to var/log/gopay_p_debug.log.php in the Magento folder. The file cannot be opened from the web. Errors and warnings are always logged. Credentials, tokens and customer data are masked. Default: No.

Log: the last row of the group 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 gateway settings and the log (see Uninstall). The license key and the cached GoPay access tokens are always removed. The GoPay payment attempts and refunds always stay, so old orders can still be refunded. Default: No.

Checkout

At the payment step the customer chooses the payment method (by default GoPay) and sees the description and the note You will be redirected to GoPay. 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 creates a GoPay payment for the order total in the order currency, with the products, shipping and taxes, and sends the customer to the GoPay payment page. There GoPay offers the payment methods enabled on your GoPay account, such as payment cards, bank transfers and wallets. The customer's billing name, e-mail, phone and address are passed to GoPay; empty fields are not sent. The payment shows at GoPay as Order MG- and the cart number.

After paying, the customer returns to your store. The order is marked paid only after GoPay confirms it: by the notification, by a request to the GoPay API when the customer returns, or by the cron check. A notification and a return arriving at the same moment are handled one after the other, so the order is invoiced only once. Magento then creates the invoice with the GoPay payment ID as the transaction ID, sets the status from Order Status After Payment and sends the order e-mail. The customer sees the standard order success page. A customer who comes back in another browser lands on the home page.

If GoPay has not confirmed the payment yet when the customer comes back (for example, a bank transfer is on its way, or GoPay cannot be reached), a GoPay payment confirmation page shows GoPay has not confirmed your payment yet. Please check again and do not pay again. with a Check again link. For a pre-authorized payment the page says Your GoPay payment is authorized but not captured. The store must capture it in GoPay., and for a payment that needs your review Your GoPay payment needs manual review. Contact the store.

If the customer comes back without paying, or GoPay reports the payment as cancelled or expired, the order is cancelled (the stock goes back), the cart is restored and the customer sees Your GoPay payment was not completed. You can try again or choose another payment method. A new attempt creates a new order and a new GoPay payment. Before that, the earlier GoPay payments of the same cart are checked, so the cart cannot be paid twice.

If GoPay cannot start the payment, the order is cancelled, the cart is restored and the customer sees The GoPay payment was not completed. Please try again or choose another method. When the result of the start is uncertain (for example, GoPay did not answer), the order is not cancelled and the customer sees GoPay could not start or an earlier payment is still pending. Contact the store before retrying. Check the payment in GoPay before you cancel such an order.

GoPay has no endpoint to cancel a payment link. When an order in Pending Payment is cancelled in Magento, by you or by the Magento cron after the Pending Payment Order Lifetime (Stores > Configuration > Sales > Sales > Orders Cron Settings), the module first checks the payment in GoPay. A payment attempt that has no GoPay payment ID (the start request failed or GoPay did not answer) never gave the customer a payment page: it is marked failed and does not hold up the cancellation. If GoPay has already captured or authorized money, or GoPay cannot be checked (GoPay cannot be reached, or the keys of the mode the payment was made in have been removed), the order is not cancelled. When you cancel it yourself in the Admin, you see GoPay has captured or authorized funds. Resolve them in GoPay before canceling this order. or GoPay payment could not be checked. Verify it before canceling. The Magento cron instead leaves the order in Pending Payment, adds a note that starts with GoPay could not confirm that this order is unpaid, so the automatic cancellation was skipped and goes on with the other expired orders; the next cron run tries again. Otherwise the order is cancelled and the link stays tracked: a late payment is recorded for your review, without an invoice.

The customer chooses the payment method on the GoPay page; it cannot be chosen in Magento. The module works with the standard Magento checkout. It has no subscriptions or recurring payments, no saved cards, no embedded payment form and no capture or void of pre-authorizations from Magento. GoPay 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 GoPay, but GoPay has not confirmed the payment yet. There is no invoice.

Processing or Complete: the payment was confirmed. The status follows Order Status After Payment. The invoice is created with the GoPay payment ID as the transaction ID, and a note shows the amount, the GoPay state and how it was verified (notification, return, cron or admin).

On Hold after a pre-authorization: GoPay reports the payment as authorized: the money is reserved, not captured. No invoice is created. Capture or void the payment in your GoPay account. When GoPay reports it as paid, the order is released and invoiced.

On Hold after a mismatch: GoPay confirmed a payment, but its amount, currency or order number differs from the order. No invoice is created. The note says Manual review; no native invoice. Check the payment in GoPay, then fulfil the order or refund the money.

Canceled: the customer did not complete the payment, GoPay cancelled it or it expired, the payment could not be started, or the order was cancelled in Magento.

Closed: the payment was fully refunded with a credit memo.

If another payment attempt of a cart that is already paid is paid as well, or a payment arrives for an order that is cancelled, the order is not changed and the payment is marked for review. The notes are order comments that the customer does not see.

GoPay payment information

On the admin order page (Sales > Orders > View) the payment information shows the payment method title, GoPay payment ID, Environment (sandbox or live) and Payment state. The Information tab also has a GoPay payment history block: every payment attempt with its payment ID, environment, the requested and verified amount, the status and the payment instrument, and the GoPay refund history. The button Check payment / reconcile receipts asks GoPay for the current state of the payment. The buttons need the Admin permission for credit memos.

Refunds

Open the order, go to the Invoices tab, open the invoice and click Credit Memo. Choose the items and amounts to refund and click Refund. The money is sent back through GoPay. Full and partial refunds are supported. A credit memo started from the order page instead of the invoice offers only Refund Offline, which does not send money back through GoPay.

The refund is made in the order currency, in whole cents, up to the amount GoPay actually charged minus the refunds already made. Before sending it, the module checks the payment in GoPay. The refund is sent in the mode the payment was made in (sandbox or production), so that mode's credentials must be set. When GoPay finishes the refund, Magento creates the credit memo and a full refund closes the order. If GoPay refuses the refund, Magento shows the error and the credit memo is not created.

When GoPay only accepts the refund for later processing, or its result is uncertain, Magento shows GoPay refund is accepted, pending or uncertain. No Credit Memo was committed. Verify the exact refund in GoPay before reconciliation. The refund stays reserved in the GoPay refund history, and no further online refund is possible until it is settled. Check the exact amount, currency and completion of the refund in your GoPay account, tick I verified this exact amount, currency and completed refund in the original GoPay account. and click Reconcile verified refund without another debit. The credit memo is then created without sending money again. Never repeat an uncertain refund in GoPay.

For a payment marked for review (a mismatch or a duplicate payment), the history row has a field Refund actual review money with the button Request refund. It sends the money back through GoPay without a credit memo.

Refunds made in the GoPay account are recorded with a note when the module next checks the payment. No credit memo is created for them. Create a credit memo with Refund Offline if needed.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — GoPay is the first row of the GoPay 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-gopay 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, GoPay 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 The GoPay payment was not completed. Please try again or choose another method. 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 refunds 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

GoPay does not appear at checkout: check that the license is active and Enable is Yes for the website of the store, that the current mode has its GoID, Client ID and Client Secret (sandbox fields in test mode, production fields otherwise), and that the cart currency is one of CZK, EUR, PLN, USD, GBP, HUF, RON or BGN. 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: GoPay could not reach the notification URL, the customer did not return to the store and the Magento cron is not running. Remove password protection or firewall rules that block the URL, and check that the Magento cron runs. Check that the credentials of the mode the payment was made in are set, because each payment is verified with them. Click Check payment / reconcile receipts on the order page. Turn on Debug Log and look at the log in the settings.

Notification answers Order not found: the payment was not created by this store.

Notification answers Payment state could not be verified: the GoPay API could not be reached or the credentials of that mode are missing or wrong. GoPay repeats the notification.

Notification 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. GoPay repeats the notification.

Notifications fail while the store is in maintenance mode: Magento maintenance mode closes the whole site, the notification URL too. The payment is confirmed by the cron check or when the customer returns.

The customer is back in the cart with an error after Place Order: turn on Debug Log and look at the log. Wrong credentials, or credentials of the other mode, are the usual reason. The order of that attempt is cancelled.

Test payments do not confirm a live order: sandbox and production are kept apart. Each payment is checked and refunded in the mode it was created in. Switch Test Mode to the mode you want and use that mode's credentials.

Order is On Hold after payment: read the order notes and the GoPay payment history block. The paid amount, currency or order number differed from the order, or the payment is only pre-authorized and must be captured in GoPay.

Refund fails: GoPay accepts partial refunds only some time after the payment (24 hours), so try a partial refund later. A GoPay refund is pending or uncertain. Check its exact amount in GoPay before retrying. means an earlier refund is not settled yet (see Refunds). The original GoPay environment credentials are missing. means the payment was made in sandbox or production mode and that mode's credentials are not set. The GoPay order changed. Reload the Credit Memo before requesting a refund. means another refund was made meanwhile: open the credit memo again.

The Refund button is missing on the credit memo: start the credit memo from the invoice (Invoices tab), not from the order page. An order without an invoice (On Hold after a mismatch or a pre-authorization) cannot be refunded with a credit memo.

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.

For developers: the event gopay_p_payment_payload changes the payment request before it is sent to GoPay. The amount, currency and order number must stay the same.

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

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

The license key, the license status and the cached GoPay access tokens are always removed. If Remove data on uninstall is Yes, the gateway settings and the log are removed too. If it is No, the settings are kept for a re-install. The GoPay payment attempts, events and refunds are always kept, so orders paid before can still be refunded after a re-install. Existing orders keep their invoices, payment notes and transaction IDs.

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