VibeFox Quickpay for PrestaShop — Help

Requirements

PrestaShop: 8.0 to 9.x.

PHP: 8.0 or later. The module refuses to install on older PHP versions.

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 shop 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

1. In the back office go to Modules > Module Manager and click Upload a module. Choose the module ZIP file.

2. When the upload finishes, click Configure, or find VibeFox Quickpay Gateway in the module list later and click Configure.

3. Paste your VibeFox license key into License key in the license block at the top of the Configure page and click Activate (see License key).

4. Paste the API key and the private key from the Quickpay manager and click Test API key (see Configuration).

5. Choose the capture mode and the order status after payment, turn on Enable/Disable and click Save. While your Quickpay account is in test mode, turn on Test payments and make a payment with a Quickpay test card.

On install the module creates one order status, Quickpay payment on hold. PrestaShop offers a new payment module for all currencies, countries and customer groups. The module is linked to the countries that are active when it is installed. You can change all of them in Payment > Preferences.

Configuration

All settings are on the module page: Modules > Module Manager > VibeFox Quickpay Gateway > Configure. Each section has its own Save button, which saves the whole page. Until both the API key and the private key are saved, the page shows Quickpay needs setup: enter the API key and the private key. Until both are saved the payment method is hidden at checkout. While Test payments is on, the page reminds you to turn it off when your Quickpay account goes live.

Quickpay

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

Title: the payment method name customers see at checkout. It is also the payment method name stored in the order. Default: Quickpay. Required: an empty title is not saved.

Description: the text shown under the payment method at checkout. Default: Pay securely by card or MobilePay on the Quickpay payment page.

Quickpay API credentials

In the Quickpay manager (manage.quickpay.net) open Settings > Integration. Copy the API key of an API user (Settings > Users) and the private key of the account.

Callback URL: shows the callback URL of your shop. With friendly URLs it looks like https://your-shop/module/wcp_quickpay_gateway/callback. Quickpay calls it after every payment operation (authorize, capture, refund, cancel). It is sent with every payment automatically, so nothing has to be configured in Quickpay.

API key: the API key of a Quickpay API user. It is used to create payments, capture and refund.

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

Saved keys are never shown again. The field stays empty and shows Saved — leave empty to keep it. Type a new value only to change it.

Clear saved secrets: tick API key or Private key and click Save to remove it. An empty field keeps the saved value.

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. Turn this on only while testing. When it is off, a test payment never marks an order as paid. While it is on, the checkout shows Test mode: Quickpay test cards are accepted. under the payment method. Default: off.

Test API key: this button checks the key typed in the API key field (or the saved one, if the field is empty) with an authenticated request to Quickpay, without saving it. It answers Connection successful — the API key is valid., Quickpay rejected the API key., API key is not configured. or Connection failed: followed by the reason.

Payment

Capture: when the money is taken from the card.

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

Advanced

Debug log: writes to logs/qpg_debug.log.php in the module folder. The file cannot be opened from the web. Errors and warnings, such as rejected callbacks and Quickpay API errors, are always logged. Turn this on to log the details of every request and callback too. API keys, card data and customer details are never logged. Default: off.

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

Delete data: when on, uninstalling the module removes the gateway settings and the log. Order data (Quickpay payments, refunds, notes) and the order status Quickpay payment on hold are always kept. Default: off.

Checkout

At the payment step the customer chooses the payment method (by default Quickpay, with a card icon) and confirms. The module creates a Quickpay payment for the cart in the cart currency and a payment link for the cart total, and sends the customer to the Quickpay payment window. No order exists yet at this point. The customer pays there with one of the methods enabled on your Quickpay payment window. The customer's e-mail is passed to Quickpay. The payment window opens in the customer's language 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 shop. The return itself does not mark anything as paid. The order is marked paid only after Quickpay confirms it: the signed callback creates the order once the captured amount and currency match the cart. The customer then sees the standard order confirmation page. With Authorize only, the order is created in Quickpay payment on hold instead, and you capture the payment later. If the callback has not arrived yet when the customer comes back, a Payment confirmation page shows Your payment is being confirmed by Quickpay. You will receive an e-mail as soon as the order is confirmed. with the buttons Check again and Back to checkout.

If the customer cancels on the payment window, the payment link is deleted in Quickpay and the customer is back at checkout with The payment was cancelled. You can try again or choose another payment method. If the card was declined, the message is The payment was not completed. You can try again or choose another payment method. The cart is kept. A new attempt reuses the cart's Quickpay payment with a fresh link, so an old link can never be paid in parallel. While a payment of the cart is authorized and waits for its capture, no second payment is started; the customer sees the Payment confirmation page.

If the payment cannot be started, the customer stays at checkout with The Quickpay payment could not be started. Please try again or choose another payment method. The technical reason is written to the log. If the keys are missing, the message is Quickpay is not available at the moment. Please choose another payment method.

The callback works while the shop is in maintenance mode and is not blocked by the country restriction of your shop.

The module 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 payment window.

Orders and refunds

Order statuses

No order yet: the customer was sent to Quickpay and has not paid, the card was declined, or the payment is authorized and waits for the automatic capture. Only the cart exists.

Payment accepted or Delivered: Quickpay confirmed the captured payment with the right amount and currency. The status follows Order status after payment. The payment is recorded with the Quickpay payment ID as the transaction ID, and a note shows the payment (marked TEST for test payments).

Quickpay payment on hold: the payment is authorized only and waits for Capture Quickpay payment; or Quickpay reported a different amount or currency than the order total (for example, the cart was changed after the payment started, or a different amount was captured in the Quickpay manager); or the automatic capture failed and the amount is still only reserved. The note explains it. When money was captured with a different amount, the payment is recorded on the order in the amount Quickpay captured.

Canceled: you cancelled the order, or the payment of an order on hold was cancelled in the Quickpay manager.

Refunded: the payment was fully refunded through the module.

A payment that arrives for an order that is already paid, 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.

When you cancel an unpaid order, its payment link is deleted in Quickpay. Cancelling an authorized order does not release the reserved amount automatically: a note reminds you to cancel the payment in the Quickpay manager; otherwise the reservation ends when the authorization expires.

Quickpay block

The order page shows a Quickpay payment block with the payment ID, the payment status, the amount and the amount refunded, a Test payment badge for test payments, the list of all Quickpay payments of the cart (when there is more than one), the refund history and the Quickpay notes of the order. Capture and refunds need the right to edit orders; access to the Modules pages is not needed.

Capture

With Authorize only, click Capture Quickpay payment in the Quickpay block and confirm Capture the order total through Quickpay? The order total is captured; partial capture is not available. If Quickpay confirms at once, the order is set to the status of Order status after payment. Otherwise a note says the capture was requested, and the order is marked paid when the Quickpay callback confirms it. A rejected capture is shown in the block and noted on the order.

Refunds

In the Quickpay block enter the amount (the amount not refunded yet is filled in), optionally a reason, and click Refund via Quickpay. Confirm the question Refund this amount through Quickpay? This cannot be undone. Full and partial refunds are supported for captured payments. Refunds are made in the amount and currency Quickpay captured, so after an amount or currency mismatch you can refund up to what the customer actually paid, not the order total. Quickpay processes refunds asynchronously: the refund history shows requested, and the callback sets it to confirmed or failed and adds the result to the notes. If Quickpay rejects the refund at once, the block shows the error and no refund is recorded. A full refund sets the order to Refunded; a partial refund does not change the status. An authorized payment that was never captured cannot be refunded; cancel it in the Quickpay manager.

The module does not create credit slips. The standard PrestaShop refund buttons of the order page do not send money back through Quickpay.

Refunds made directly in the Quickpay manager are only added to the notes. The order status and credit slips are not changed automatically. Update them manually 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 block on Modules > Module Manager > VibeFox Quickpay Gateway > Configure, 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 shop. Below them are the line Product: presta-payment-quickpay and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only employees with the Configure permission for the module can change the key. The texts of the block follow the back office language (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 shop 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 main shop, also in a multistore setup. Removing the key from the shop 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 customer sees This payment method is not available. Please choose another one. The PrestaShop storefront does not know that you are logged in to the back office, 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 Modules > Module Manager on the Alerts tab. 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 while you work in the back office: once a day for the first 14 days after the key is entered, then once a week. No cron job is needed. Uninstalling or resetting the module always removes the license key and license status.

Troubleshooting

Quickpay does not appear at checkout: check that the license is active, Enable/Disable is on and both API key and Private key are saved. Without both keys the method is hidden. In Payment > Preferences check that the module is allowed for the cart currency, the customer's country and the customer's group.

The payment went through, but no order was created: the Quickpay callback did not reach your shop or was rejected. Check that your shop is reachable from the internet (no password protection) and that Private key is the private key of the same Quickpay account. Rejected callbacks are always written to the log on the module page. Turn on Debug log to see every callback.

Log shows Callback rejected: invalid checksum.: 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: the private key is not configured.: enter the private key. Callbacks are never accepted without it.

Log shows Callback: no cart found for payment …: the callback belongs to a Quickpay payment that this shop did not create, for example a payment made outside PrestaShop.

Log shows Could not lock the cart or Cannot create the order: another callback of the same cart was being applied at that moment, or the order could not be created (for example, the module is disabled). The callback is answered with an error, so Quickpay sends it again.

A test payment did not mark the order paid: Test payments is off. The log (and the note, if the order exists) says the test payment was not accepted. Turn the setting on while testing, and off when your account goes live.

Order is Quickpay payment on hold after payment: read the notes in the Quickpay block. 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, fulfil the order or refund the payment.

Test API key says Quickpay rejected the API key.: the key is wrong or belongs to a user without API access. 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 module page. It shows the Quickpay error, for example a currency your Quickpay account does not accept.

Refund fails: the order must have a captured Quickpay payment. The message The Quickpay payment of this order has not been captured — there is nothing to refund. means the payment is only authorized; capture it or cancel it in the Quickpay manager. Invalid refund amount: at most … means the amount is above what is left of the captured payment.

Developers can change the parameters of the Quickpay payment link with the hook actionQpgQuickpayLinkData.

Uninstall

Go to Modules > Module Manager, open the menu next to VibeFox Quickpay Gateway and choose Uninstall. The license key and license status of this module are always removed. If Delete data is on, the gateway settings and the log are removed. If it is off, all settings are kept for a later re-install. The Quickpay payments, refunds and the order status Quickpay payment on hold are always kept, so orders paid before can still be refunded after a re-install. Existing orders keep their payment notes and transaction IDs.

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