VibeFox Quickpay 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 cURL extension.

Quickpay account: you need two values from the Quickpay manager: the API key of an API user (to create payments, capture and refund) and the private key of the account (to check the signature of Quickpay callbacks). Nothing else has to be set up in Quickpay. Your store must be reachable from the internet, not behind password protection, so that Quickpay callbacks can arrive.

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

2. Run bin/magento module:enable Vibefox_QuickpayPayment 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 Quickpay 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 API key and the private key from the Quickpay manager, choose the capture mode, set Enable to Yes and click Save Config. Click Test API key to check the key. While your Quickpay account is in test mode, set Test payments to Yes and place an order with a Quickpay test card.

The module adds the Quickpay 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 Quickpay payments and refunds. The callback URL is sent with every payment. Nothing has to be configured in Quickpay.

Configuration

All settings are in Stores > Configuration > Sales > Payment Methods > VibeFox Quickpay Gateway, in the standard Magento configuration form. The settings can be changed for a website or a store view with the Scope switcher at the top of the page. The license block, Gateway notices, Test API key and Log are shown in the Default Config only, and Delete data on uninstall is read from the Default Config only. 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: Enter a title for the payment method (1 to 128 characters)., "Sort order" must be a whole number. or Order total must be a number, 0 or greater.

Enable: shows or hides Quickpay at checkout. It is shown only when both API key and Private key are saved. Default: No.

Title: the payment method name customers see at checkout. Default: Quickpay. Required, at most 128 characters.

Description: shown in the payment method list at checkout, when the customer selects the method. Default: Pay securely by card or MobilePay on the Quickpay payment page.

API key: the API key of a Quickpay API user. It is used to create payments, capture and refund. In the Quickpay manager (manage.quickpay.net) open Settings > Integration and copy the API key of an API user (Settings > Users).

Private key: the private key of the account, from the same page. It is used to check the signature (HMAC-SHA256) of Quickpay callbacks. Without it no payment can be confirmed, and callbacks are rejected.

Magento stores both 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. To delete a saved key, clear the field and click Save Config. Spaces at the start and end of a key are ignored.

Test payments: accept payments made with Quickpay test cards. Quickpay has no separate sandbox: while your Quickpay account is in test mode, payments are made with test cards and flagged as test. Set this to Yes only while testing. When it is No, a test payment never marks an order as paid. While it is Yes, the checkout shows TEST PAYMENTS ACCEPTED — do not ship test orders. under the payment method. Default: No.

Capture: when the money is taken from the card.

Order status after payment: the order status once Quickpay has confirmed the captured payment.

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

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

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

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

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

Debug log: writes to var/log/qpg_debug.log.php in the Magento folder. The file cannot be opened from the web. Errors and warnings, such as rejected callbacks and Quickpay API errors, are always logged. Set this to Yes to log the details of every request too. API keys, request bodies, e-mail addresses and card data are never logged. Default: No.

Delete data on uninstall: Only settings and log are deleted. Payment history is retained. When Yes, uninstalling the module with its data deletes the gateway settings and the log (see Uninstall). The license key is always removed. Default: No.

Gateway notices: while Enable is Yes, shows Quickpay needs setup: enter API key and Private key. when a key is missing, and Quickpay: test payments are accepted. Do not ship test orders. while Test payments is Yes. It also shows, for reference, the Callback URL of the default store view, which looks like https://your-store/wcpquickpaygateway/checkout/callback/. Each payment, capture and refund sends this URL of the store view where the order was placed. Quickpay calls it after every payment operation (authorize, capture, refund, cancel). The URL is sent with every payment automatically, so nothing has to be configured in Quickpay.

Test API key: this button checks the key typed in the API key field (or the saved one, if the field is empty or shows the mask) with an authenticated request to Quickpay, without saving it. It answers Quickpay API key is valid. or Quickpay API key could not be verified.

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 Quickpay) and sees the description and the note You will be redirected to Quickpay to complete your payment. After Place Order, Magento places the order in Pending Payment. No invoice is created and no order e-mail is sent yet. The module creates a Quickpay payment and a payment link for the order total in the order currency and sends the customer to the Quickpay payment window. The customer pays there with one of the methods enabled on your Quickpay account. The customer's e-mail is passed to Quickpay. The payment window opens in the language of the store view when Quickpay offers it (Danish, German, English, Spanish, Finnish, French, Italian, Dutch, Norwegian, Polish, Swedish), otherwise in English.

After paying, the customer returns to your store. The return itself does not mark anything as paid. The order is marked paid only after Quickpay confirms it: a signed callback with the right payment, cart, amount and currency. Magento then creates the invoice with the Quickpay payment ID as the transaction ID, the order moves to Processing (see Order status after payment) and the order e-mail is sent. The customer sees the standard order success page. The callback is handled for the store view of the order, whichever store view address it arrives on, and also when Enable is No or the license is not active.

If the callback has not arrived yet when the customer comes back, a Quickpay payment status page shows Your payment is being confirmed by Quickpay., the order number and status, and the buttons Check again and Back to checkout. With Authorize only, the customer also sees this page after the authorization, and the order e-mail is sent when the payment is captured. A customer who comes back in another browser lands on the home page with Return to the checkout that placed this order to see its payment status.

If the customer cancels on the payment window or clicks Back to checkout before an authorization, the payment link is deleted in Quickpay and the order is cancelled (the stock goes back). If the card was declined, the order is cancelled too. In both cases the cart is restored and the customer is back in the cart with The payment was not completed. Please try again or choose another payment method. A new attempt is a new Magento order that reuses the cart's Quickpay payment with a fresh link. If that link cannot be updated, a new Quickpay payment is created and the old link is deleted, so an old link can never be paid in parallel. A late decline of a replaced attempt does not cancel the current order. While a payment of the cart is authorized, no second payment is started.

If the payment cannot be started, the order is cancelled, the cart is restored and the customer sees The Quickpay payment could not be started. Please try again or choose another payment method. If the method is off, a key is missing or the license is not active, the message is Quickpay is currently unavailable.

Magento cancels orders that stay in Pending Payment longer than the Pending Payment Order Lifetime (Stores > Configuration > Sales > Sales > Orders Cron Settings). Before an unpaid order is cancelled, the module reads its payment from Quickpay. If the customer has already paid and only the callback was lost, the payment is recorded instead and the order is not cancelled. Otherwise the payment link is deleted in Quickpay, so it can no longer be paid, and the order is cancelled. If Quickpay cannot be reached (or the API key does not work), the cron does not cancel the order and adds the note Quickpay could not confirm that the payment can no longer be completed, so the order was not cancelled automatically. …; it tries again on its next run, and the other orders are processed as usual. Authorized orders are in Processing or On Hold, so the cron never cancels them. If a payment still arrives for a cancelled order, the order is not reopened and a note asks you to review or refund the payment in the Quickpay manager.

The module works with the standard Magento checkout. It takes one-time payments only. It has no subscriptions or recurring payments, no saved cards, no partial capture, sends no basket or invoice lines to Quickpay and has no separate MobilePay, Apple Pay or Klarna methods: the customer chooses among the methods of your Quickpay account. Quickpay is not offered for orders created in the Admin.

Orders and refunds

Order statuses

Pending Payment: the customer was sent to Quickpay and has not paid yet. There is no invoice.

Processing without an invoice: with automatic capture, the payment is authorized and waits for the capture callback; the note says Waiting for automatic capture; the invoice is created when Quickpay confirms the capture. Do not ship the order before the invoice is created. If no capture arrives, check the payment in the Quickpay manager. With Authorize only, an order taken off hold is also Processing without an invoice until you capture it.

Processing or Complete: Quickpay confirmed the captured payment with the right amount and currency. The invoice is created with the Quickpay payment ID as the transaction ID, and a note shows the payment and the amount (marked TEST for test payments). Complete applies only to virtual orders with Order status after payment set to Complete (virtual orders only).

On Hold: the payment is authorized only and waits for Capture Quickpay payment (Unhold returns it to Processing); or Quickpay reported a different amount or currency than the order total; or the capture failed and the amount is still only reserved. No invoice is created, and the note explains it. After an amount or currency mismatch the note shows the amount received and the amount expected. Review the payment and refund it in the Quickpay manager.

Canceled: the payment was declined or cancelled, the payment could not be started, the order was cancelled in Magento, or the payment was cancelled in the Quickpay manager before it was captured.

Closed: the order was fully refunded with credit memos.

A payment that arrives for an order or a cart that is already paid, or for an order that is cancelled or refunded, does not change the order. A note asks you to check the payment in the Quickpay manager, for example to refund a double payment. A test payment while Test payments is No does not change the order either; the note says Quickpay: TEST payment ignored because test payments are not accepted. The notes are order comments that the customer does not see.

When you cancel an authorized order that is not captured yet, the authorization is cancelled in Quickpay too and the reserved amount is released; the note says the authorization was cancelled with the order. An order that is On Hold must be taken off hold first. If Quickpay does not cancel the authorization (for example, it was already captured), the order is not cancelled and the Admin shows Quickpay did not cancel the authorization (it may already be captured). Check the payment in Quickpay manager; the order was not cancelled. While a capture is requested and not confirmed, cancelling shows A Quickpay capture is requested or unconfirmed. Reconcile it in Quickpay manager before cancelling the order.

Quickpay payment information

On the admin order page (Sales > Orders > View) the payment information shows the payment method title and, when known, Quickpay payment, Test payment, Authorized/captured amount, Actual captured amount and Refund status, then one line Quickpay attempt # for each payment attempt of the order and one line Quickpay refund # for each refund, with the Quickpay ID, amount and status. It is shown also when the module is disabled. On the storefront the customer sees only the payment method title.

Capture

With Authorize only, open the order and click Capture Quickpay payment in the block of that name on the Information tab. The Admin user's role must allow capturing orders. The order total is captured; partial capture is not available. If Quickpay confirms at once, the invoice is created and the order moves to Processing. Otherwise the page says Quickpay capture submitted. The invoice is created only when capture is confirmed. and a note says the capture was requested; the invoice is created when the signed Quickpay callback confirms it. The capture is never sent twice while its result is open. Use this button, not the Invoice page: a capture from an invoice is refused with Use Capture Quickpay payment on the order. The invoice is created when capture is confirmed.

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 Quickpay. 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 Quickpay.

The refund is made in the order currency, up to the amount Quickpay captured minus the amounts already refunded. Magento keeps two decimals also for currencies without them, such as ISK or JPY, and the payment went to Quickpay rounded. The refund is rounded in the same way, and the credit memo that closes the order refunds exactly what is left of the payment. Quickpay processes refunds asynchronously: the Refund status shows Requested — waiting for callback until the callback sets it to Confirmed or to FAILED — reconcile the native credit memo manually, and adds the result to the notes. A refund that fails later does not undo the credit memo and does not free its amount for a new online refund: check it in the Quickpay manager and correct the order manually. If Quickpay rejects the refund at once, Magento shows the error and the credit memo is not created. A full refund closes the order. Refunds are available once the capture is confirmed and the order has an invoice.

If the result of a refund request is unclear, for example after a timeout, Magento shows Quickpay did not confirm the refund. Check Quickpay manager before trying again. and the credit memo is not created. The module never sends such a refund again by itself. Further online refunds of that payment are refused with A previous Quickpay refund is unconfirmed. Reconcile it before retrying. Check the refund in the Quickpay manager, make it there if needed, and record it with Refund Offline.

A payment with a mismatch and a late payment have no valid invoice and cannot be refunded from Magento: refund them in the Quickpay manager. An authorized payment that was never captured cannot be refunded; cancel the order (see Order statuses) or cancel the payment in the Quickpay manager.

Refunds made directly in the Quickpay manager are only added to the notes. The order and credit memos are not changed automatically. 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 — VibeFox Quickpay Gateway is the first row of the VibeFox Quickpay 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-quickpay 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, Quickpay 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 Quickpay is currently unavailable. 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 capture 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

Quickpay does not appear at checkout: check that the license is active and Enable is Yes for the website of the store, and that both API key and Private key are saved. Without both keys the method is hidden. 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 Quickpay callback did not reach your store or was rejected. Check that your store is reachable from the internet (no password protection) and that Private key is the private key of the same Quickpay account, for the website or store view of the order. Rejected callbacks are always written to the Log. Set Debug log to Yes to see the API requests too.

Log shows Callback rejected: mismatch: the private key in the settings does not belong to the account that sent the callback. Copy it again from Settings > Integration in the Quickpay manager.

Log shows Callback rejected: no_key: enter the private key. Callbacks are never accepted without it.

The callback URL answers with an error code: 405 in the browser is normal, because the URL accepts only POST requests. 400 means an empty body, a missing signature or a payment of another cart, 403 a wrong signature or no private key, and 404 a Quickpay payment that this store did not create. 503 means another request of the same cart was being handled, or the order could not be updated; the callback is answered with an error, so Quickpay sends it again.

Callbacks fail while the store is in maintenance mode: Magento maintenance mode closes the whole site, the callback URL too. Check the payment in the Quickpay manager and the order after the store is open again.

A test payment did not mark the order paid: Test payments is No. The note on the order says the test payment was ignored. Set it to Yes while testing, and to No when your account goes live.

The order is On Hold after payment: read the order notes. The payment may be authorized only and waiting for Capture Quickpay payment, the paid amount or currency may differ from the order, or the capture failed.

Capture says Quickpay did not confirm the capture. Reconcile it before retrying. or A capture is already requested or unconfirmed. The module does not send the capture again. Check the payment in the Quickpay manager and capture it there if needed; the callback then creates the invoice.

Test API key says Quickpay API key could not be verified.: the key is wrong, belongs to a user without API access, or Quickpay could not be reached. Copy the API key of an API user from the Quickpay manager.

The customer sees The Quickpay payment could not be started.: look at the Log field on the settings page. It shows the Quickpay error, for example a currency your Quickpay account does not accept. The order of that attempt is cancelled.

A refund fails: No captured Quickpay payment found. means the payment is only authorized, or it is a mismatched or late payment that is refunded in the Quickpay manager. Invalid refund amount or currency; refund exceeds the remaining captured payment. means the amount is above what is left of the captured payment, or it rounds to zero in the order currency. An accepted Quickpay refund has no credit memo. means Quickpay accepted an earlier refund but Magento did not save its credit memo: check it in the Quickpay manager and record it with Refund Offline. Quickpay credentials are missing. means a key is not saved for the store view of the order.

There is no Refund button on the credit memo: start the credit memo from the invoice, not from the order page. An order without an invoice has no online refund.

For developers: the parameters of the Quickpay payment link can be changed with the Magento event qpg_quickpay_link_data (transport with the link data, and the order).

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

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

The license key and license status are always removed. If Delete 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 tables of Quickpay payments 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.

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