VibeFox Paystack for PrestaShop — Help

Requirements

PrestaShop: 8.0 to 9.x.

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

Currency: the cart must be in a currency Paystack accepts: NGN, USD, GHS, ZAR, KES, XOF, EGP or RWF, as enabled on your Paystack account. In other currencies the payment method is hidden. In XOF and RWF Paystack accepts whole amounts only.

Paystack account: you need the secret keys of your Paystack account: the test secret key (sk_test_...) and/or the live secret key (sk_live_...). The public keys (pk_...) are not needed, because the payment is made on the Paystack hosted page. In the Paystack dashboard you also set the webhook URL of your shop (see Configuration). Your shop must be reachable from the internet to receive webhooks.

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 Paystack Payment 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 your secret keys from the Paystack dashboard and set the webhook URL in the Paystack dashboard (see Configuration).

5. Turn on Enable/Disable and click Save. Keep Test Mode on until you have made a test payment, then turn it off to accept real payments.

On install the module creates two order statuses, Awaiting Paystack payment and Paystack payment on hold. PrestaShop offers a new payment module for all currencies, countries and customer groups. You can limit them in Payment > Preferences.

Configuration

All settings are on the module page: Modules > Module Manager > VibeFox Paystack Payment > Configure. Each section with fields has its own Save button, which saves the whole page. Above the fields a status box shows the mode: Test mode: no real money is charged. or Live mode: real payments are accepted. It also warns when the secret key of the current mode is empty, when a public key (pk_...) was entered in a secret key field, when live mode has a test key (sk_test_...) or test mode has a live key (sk_live_...), and when Paystack does not accept the default currency of your shop. While a key problem exists, the payment method is hidden at checkout.

Paystack

The first section is titled Paystack with a TEST or LIVE badge of the current mode.

Enable/Disable: Enable Paystack Payment 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: Paystack. Required.

Description: the text shown under the payment method at checkout. Default: Pay securely using your debit card, credit card, or bank account via Paystack.

API keys

Copy the secret keys from the Paystack dashboard, page Settings > API Keys & Webhooks. The section links to it.

Test Mode: uses the test secret key for new payments, and no real money is charged. Turn it off to accept real payments with the live secret key. Payments made in the other mode keep using the key of their own mode for verification and refunds. Default: on. While it is on, customers see TEST MODE ENABLED. No real charges will be made. under the payment method.

Test Secret Key: your Paystack test secret key. It starts with sk_test_.

Live Secret Key: your Paystack live secret key. It starts with sk_live_.

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 a key and click Save to remove it. An empty field keeps the saved value.

Webhook

The webhook tells your shop that a payment has been made, even when the customer does not return to the shop. In the Paystack dashboard, page Settings > API Keys & Webhooks, set the URL shown in Webhook URL in this section as both the Test Webhook URL and the Live Webhook URL. With friendly URLs it looks like https://your-shop/module/wcp_paystack_payment/webhook, possibly with a language code such as /en/. Copy the URL exactly as the settings show it.

Paystack signs every webhook with your secret key, so nothing else has to be configured. Webhooks without a valid signature are rejected. The module uses the event charge.success:

Other events are answered with OK and ignored. Without the webhook, an order is confirmed only when the customer comes back to the shop after paying. Bank transfer and USSD payments that complete later are confirmed only by the webhook.

Orders

Autocomplete Order: when on, paid orders get the status Delivered instead of Payment accepted, with one status change. Default: off.

Advanced

Debug log: logs Paystack events and API calls to logs/paystack_p_debug.log.php in the module folder. The file cannot be opened from the web. Errors and warnings are always logged. Keys and customer data are never logged. Default: off.

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

Delete data on uninstall: when on, uninstalling the module removes the module settings and the log. Payment data saved on orders is always kept. Default: off.

Checkout

At the payment step the customer chooses the payment method (by default Paystack) and confirms the order. The module starts a Paystack transaction for the cart total in the cart currency, with the customer's e-mail, and sends the customer to the Paystack hosted checkout page. There the customer pays with one of the channels enabled on your Paystack account. The payment shows the cart number and the customer name. No order exists yet at this point.

After paying, the customer returns to your shop. The order is marked paid only after Paystack confirms it: when the customer comes back and when the webhook arrives, the module reads the transaction from the Paystack API and checks the reference, status, amount and currency. The order is then created and the customer sees the standard order confirmation page.

If the payment is still being processed, for example a bank transfer, the order is created in Awaiting Paystack payment when the customer comes back, and the confirmation page shows Your payment is being confirmed by Paystack. You will receive an email as soon as it is confirmed. The webhook completes the order later. If Paystack cannot be reached when the customer comes back, a Payment confirmation page asks the customer not to pay again and offers Check again and Back to checkout; the webhook creates the order as soon as it arrives. For an order on hold the confirmation page shows Your payment was received and your order is being reviewed. We will contact you if anything is needed.

If the customer cancels on the Paystack page or leaves it without paying, no order is created and the cart is kept. The customer is back at checkout with a message, for example Payment was cancelled. You can try again or choose another payment method., The payment was not completed. You can try again or choose another payment method. or Your payment was declined. You can try again or choose another payment method. Each new attempt starts a new Paystack transaction. An older payment page of the cart stays valid: if it is paid later, the payment is still accepted.

The order confirmation page opens only in the customer's own browser. If the return link is opened elsewhere, the payment is still checked, but the order is not shown: the visitor sees a neutral message at checkout.

If Paystack cannot start the payment, the customer stays at checkout with a short message, for example Paystack could not start the payment: followed by the reason from Paystack, or Paystack is temporarily unavailable. Please try again in a moment or choose another payment method. The cart total must be greater than zero, and the customer needs a valid e-mail address.

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

The module has no inline or popup payment form, no saved cards, no subscriptions, no split payments or subaccounts and no choice of payment channels in PrestaShop.

Orders and refunds

Order statuses

No order yet: the customer was sent to Paystack and has not paid, left the Paystack page, or Paystack has not confirmed the payment yet. Only the cart exists.

Awaiting Paystack payment: the customer came back while Paystack was still processing the payment, for example a bank transfer or USSD. The order moves to the paid status when Paystack confirms the payment. If such a payment is never completed, the order stays in this status until you change it.

Payment accepted or Delivered: the payment was confirmed. The status is Delivered when Autocomplete Order is on. The payment is recorded with the Paystack reference (pscart_...) as the transaction ID. A note shows the amount, the reference, the transaction number, the mode (test or live), the payment channel, the card type and last digits for card payments, and any Paystack fees paid by the customer.

Paystack payment on hold: the paid amount or currency differs from the order (note Paystack amount or currency mismatch), for example because the cart was changed after the payment started, or the payment arrived after the order had been cancelled. The note explains what to check. Fulfil the order or refund the payment.

Payment error: Paystack reports the latest payment attempt of an order in Awaiting Paystack payment as failed or reversed. A failure of an older attempt does not change the order.

If a second payment of a cart whose order is already paid arrives, the order is not changed. A note asks you to refund the duplicate payment in the Paystack dashboard. A payment that arrives for an order in another status, for example Shipped, is only noted on the order.

Paystack payment block

The order page shows a Paystack payment block with the reference, the transaction ID, the mode with a Test mode badge for test payments, the payment status, channel and card, the payment date, the amounts paid and refunded, the refund history and the Payment notes of the order.

Refunds

In the Paystack payment block enter the amount (the amount not refunded yet is filled in), optionally a reason, and click Refund via Paystack. Confirm the question Refund this amount through Paystack? This cannot be undone. Full and partial refunds are supported. You need the right to edit orders; access to the Modules pages is not needed. The refund goes to the transaction that paid the order, with the secret key of the mode (test or live) it was made in, so that mode's key must be set. Refunds are made in the amount and currency Paystack charged, so for an order on hold after an amount or currency mismatch you can refund up to what the customer actually paid, not the order total. In XOF and RWF refunds must be whole amounts. Paystack queues refunds: the note and the refund history show the status Paystack returned, for example pending, and the refund ID. If Paystack does not accept the refund, the block shows Paystack refund failed: with the reason, and no refund is recorded. A full refund sets the order to Refunded. A partial refund does not change the status. Refunds are available once Paystack has confirmed the payment.

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

Refunds made in the Paystack dashboard, and the final status of refunds queued by Paystack, are not synchronised back to PrestaShop. If needed, record them manually.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Paystack Payment is the first block on Modules > Module Manager > VibeFox Paystack Payment > 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-paystack 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, Paystack 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 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

Paystack does not appear at checkout: check that the license is active, Enable/Disable is on, the current mode has a correct secret key (Test Secret Key with sk_test_... in test mode, Live Secret Key with sk_live_... in live mode) and the cart currency is one Paystack accepts. The status box at the top of the settings names the problem. 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 webhook did not reach your shop and the customer did not come back. In the Paystack dashboard check that the Test Webhook URL and the Live Webhook URL are exactly the URL shown in Webhook URL, and that no firewall or password protection blocks it. Turn on Debug log and look at the Log field for rejected webhooks.

Webhook answers Invalid signature: the webhook was not signed with the test or live secret key entered in the settings, for example because the keys belong to another Paystack account. Enter the keys of the account that sends the webhook.

Webhook answers Secret key not configured: neither secret key is set. Enter the secret keys in the settings.

Webhook answers Verification failed, Busy, retry later or Order could not be created, retry later: the transaction could not be read from the Paystack API at that moment, the cart was being processed by the customer return at the same time, or the order could not be created (for example, the module is disabled). Paystack sends the webhook again. The log shows the reason.

Webhook answers OK - unknown reference: the payment was not made for a cart of this shop, for example a Paystack payment page or another integration on the same account. It is ignored.

The webhook URL shows Empty body in the browser: this is normal. The URL accepts only requests from Paystack.

The customer sees Payment gateway is not properly configured: the secret key of the current mode is missing or wrong. Fix it as the status box at the top of the settings says.

The order is Paystack payment on hold after payment: read the payment notes in the Paystack payment block (see Order statuses), then fulfil the order or refund the payment.

The order stays Awaiting Paystack payment: Paystack has not confirmed the payment yet. Check the transaction in the Paystack dashboard and the webhook settings. If the customer never completed the payment, change the status manually.

Refund fails with a message about the mode: the payment was made in test or live mode, and the secret key of that mode is not configured. Enter it and try again.

Developers can change the transaction request and the list of currencies with the module hooks actionWcpPaystackPaymentRequest, actionWcpPaystackSupportedCurrencies and actionWcpPaystackCurrencyDecimals.

Uninstall

Go to Modules > Module Manager, open the menu next to VibeFox Paystack Payment and choose Uninstall. The license key and license status of this module are always removed. If Delete data on uninstall is on, the module settings and the log are removed. If it is off, all settings are kept for a later re-install. The Paystack payment data of orders, the refunds and the order statuses Awaiting Paystack payment and Paystack 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.

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