VibeFox Paystack for Adobe Commerce — Help

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.

Currency: the order 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, so an order total with decimals cannot be paid in these currencies.

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 store (see Configuration). Your store must be reachable from the internet to receive webhooks.

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

2. Run bin/magento module:enable Vibefox_PaystackPayment 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 Paystack 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. Paste your secret keys from the Paystack dashboard and set the webhook URL in the Paystack dashboard (see Configuration). Set Enable to Yes and click Save Config. Keep Test Mode at Yes until you have made a test payment, then set it to No to accept real payments.

The module adds the Paystack 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 Paystack payment attempts, refunds and processed events.

Configuration

All settings are in Stores > Configuration > Sales > Payment Methods > VibeFox Paystack 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 from the Default Config only. Save Config saves the whole page. Amounts are written with a dot, for example 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 (Payment method title is required and must not exceed 128 characters.); a Sort Order that is not a whole number (Sort order must be a whole number.); a Minimum Order Total or Maximum Order Total that is not a number of 0 or greater (Order total limit must be a non-negative number.).

The Paystack webhook row at the top of the group shows the webhook URL. While Enable is Yes, it also shows a warning when the secret key of the current mode has a problem, followed by The payment method is hidden until this is fixed.: Test mode is enabled but the test secret key is empty. (or the same for live mode), A public key was entered in a secret key field. Enter the secret key., The live secret key field contains a TEST key. or The test secret key field contains a LIVE key. While test mode is on, it shows TEST MODE ENABLED. No real charges will be made., and when Paystack does not accept the currency of the store, Paystack does not accept this store currency. The keys are saved even when they have a problem; the payment method stays hidden at checkout until the problem is fixed.

General

Enable: shows or hides Paystack at checkout. It is shown only when the secret key of the current mode is correct. Default: No.

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

Description: shown in the payment method list at checkout, under the payment method when the customer selects it. Default: Pay securely using your debit card, credit card, or bank account via Paystack.

Sort Order: the position among the payment methods at checkout. A whole number, including negative values.

API keys

Copy the secret keys from the Paystack dashboard, page Settings > API Keys & Webhooks.

Test Mode: test mode uses the test secret key, and no real money is charged. Live mode uses the live secret key. Default: Yes. Set it to No to accept real payments. Payments made in the other mode keep using the key of their own mode for verification and refunds. 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_.

Magento stores the keys encrypted and shows only a mask (******) after saving. Leave the mask as it is 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 around a pasted key are removed.

Webhook

The webhook tells your store that a payment has been made, even when the customer does not come back to the store. The Paystack webhook row shows Enter this URL as both the Test and Live Webhook URL in Paystack: and the URL. In the Paystack dashboard, page Settings > API Keys & Webhooks, set this URL as both the Test Webhook URL and the Live Webhook URL. It is the storefront address of the default store view (or, when the Scope switcher is set to a website, of the default store view of that website) and looks like https://your-store/wcppaystackpayment/webhook/index/?store=1, where the number is the store view. 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. One URL is enough for all store views: a webhook for an order of another store view is checked with the secret keys that apply to that order's store view and confirms the order in the same way. Without the webhook, an order is confirmed only when the customer comes back to the store after paying. Bank transfer and USSD payments that complete later are confirmed only by the webhook.

Orders

Autocomplete Order: virtual orders may complete after payment. When Yes, a paid order with nothing left to invoice or ship (for example an order of virtual products only) becomes Complete instead of Processing. Physical orders complete after native fulfilment, that is after you ship them in Magento. Default: No.

Conditions

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

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

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

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

Advanced

Debug log: writes Paystack events and API calls to var/log/paystack_p_debug.log.php in the Magento folder. The file cannot be opened from the web. Errors and warnings are always recorded. Other steps are recorded only when enabled. Keys, customer data and return tokens are never logged. Default: No.

Remove data on uninstall: when Yes, uninstalling the module with its data removes the module settings, cache and log (see Uninstall). Payment and refund history is always kept. Default: No.

Debug log viewer: shows the size and the latest entries of the log, or The log is empty. Click Clear log to empty it.

Checkout

At the payment step the customer chooses the payment method (by default Paystack) and sees the description and the note You will be redirected to Paystack to pay. 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 starts a Paystack transaction for the order total in the order 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 order number and the customer name.

After paying, the customer returns to your store. 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. Magento then creates the invoice, sets the order to Processing (or Complete, see Autocomplete Order) and sends the order e-mail. The customer sees the standard order success page.

If the payment is still being processed, for example a bank transfer, or Paystack cannot be reached when the customer comes back, a Payment confirmation page shows Your Paystack payment is being confirmed. Please do not pay again. with the buttons Check again and Back to checkout. The order stays in Pending Payment, and the webhook confirms it as soon as it arrives. While such a payment is being processed, a new Place Order for the same cart does not start a second payment: the new order is cancelled and the customer is shown the confirmation page of the first payment. For an order on hold the page shows Your Paystack payment is being reviewed. Please contact us.

If the customer cancels on the Paystack page, leaves it without paying or the payment is declined, the order is cancelled (the stock goes back), the cart is restored and the customer is back in the cart with 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. Before a new payment starts, recent unfinished attempts of the same cart are checked with Paystack: if one of them turns out to be paid, that payment is confirmed instead of a new one. If the cart was already paid with another order, the new order is cancelled and the customer sees Your earlier payment has already been received. Please check your order confirmation.

The order success page opens only in the customer's own browser. A customer who comes back in another browser lands on the home page with Your payment has been received. Please check your order confirmation., or Your payment is being processed. You will receive an email confirmation when it is confirmed. The payment is still checked.

If Paystack cannot start the payment, the order is cancelled, the cart is restored and the customer sees a short message in the cart, for example Paystack could not start the payment. Please try again or choose another payment method. or Paystack is temporarily unavailable. Please try again. The order total must be greater than zero, and the customer needs a valid e-mail address.

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 Paystack page cannot be closed, because Paystack has no API for that. If the customer still pays it, the order stays cancelled and a note asks you to review it (see Order statuses).

The module works with the standard Magento checkout. It has no inline or popup payment form, no saved cards, no subscriptions, no split payments or subaccounts and no choice of payment channels in Magento. Paystack 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 Paystack, but Paystack has not confirmed the payment yet, for example a bank transfer or USSD payment that is still processing. There is no invoice. If such a payment is never completed, the order stays in this status until you or the Magento cron cancel it.

Processing or Complete: the payment was confirmed. The invoice is created with the Paystack reference (mgorder_...) 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. The fees are not added to the Magento order totals.

On Hold after a mismatch: the paid amount or currency differs from the order (note Paystack amount or currency mismatch). No invoice is created. The note shows the amount charged, requested and expected. Check the payment in the Paystack dashboard, then fulfil the order or refund the payment (see Refunds).

Canceled: the customer cancelled or did not complete the payment, the payment was declined or could not be started, or the order was cancelled in Magento. If a payment arrives after the order was cancelled or closed, the order stays as it is and a note asks you to review fulfilment or refund the actual payment.

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

If a second payment arrives for an order that is already paid, the order is not changed. A note asks you to refund the duplicate payment in the Paystack dashboard. The notes are order comments that the customer does not see.

Paystack payment information

On the admin order page (Sales > Orders > View) the payment information shows the payment method title and, for a confirmed payment, Paystack reference, Payment mode, Paystack transaction ID, Payment channel, Card type, Card last four, Paid at, Charged amount in subunits and Charged currency. The customer sees only the payment method title.

Below the order information a VibeFox Paystack Payment block lists every payment attempt of the order (reference, mode, state, requested and charged amount, transaction ID, channel, card, payment date), the Refund history and the Paystack private notes of the order. The block is shown also when the payment method is disabled.

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 Paystack. 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 Paystack. The comment of the credit memo is sent to Paystack as the refund note.

The refund goes to the transaction that paid the order, in the order currency and up to the order total; Paystack fees paid by the customer are not refunded. It is sent with the secret key of the mode (test or live) the payment was made in, so that mode's key must be set. In XOF and RWF refunds must be whole amounts. Paystack queues refunds: the note on the order shows the status Paystack returned, for example pending, and the refund ID, and the refund ID is the transaction ID of the credit memo. A full refund closes the order.

If Paystack does not accept the refund, Magento shows the error, for example Paystack rejected the refund. No native credit memo was saved., and the credit memo is not created. If the answer of Paystack is unclear (no connection, a server error), Magento shows The refund result is uncertain. Check Paystack before retrying. Paystack has no protection against a refund sent twice, so further refunds of the order are blocked with An earlier refund has an uncertain result. Reconcile it in Paystack before sending another request. Check the refund in the Paystack dashboard first.

Held payments: an order on hold after a mismatch, or a payment that arrived after the order was cancelled, has no invoice. For such a payment the VibeFox Paystack Payment block shows Reconciliation refund for held funds with the remaining amount Paystack actually charged. Enter the amount and optionally a reason and click Request held payment refund. The refund is sent through Paystack and noted on the order; no invoice or credit memo is created. You need the permission to create credit memos.

Refunds made in the Paystack dashboard, and the final status of refunds queued by Paystack, are not synchronised back to Magento. If needed, create a credit memo with Refund Offline or update the order manually.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Paystack Payment is the first row of the VibeFox Paystack 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-paystack 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, Paystack 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 This payment method is not available. Please choose another one. 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

Paystack does not appear at checkout: check that the license is active and Enable is Yes for the website of the store, and that 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. The Paystack webhook row names the problem. Check that the order currency is one Paystack accepts, 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 webhook did not reach your store 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 the Paystack webhook row, and that no firewall or password protection blocks it. The Paystack dashboard shows the answer of your store for each webhook. Turn on Debug log and look at the Debug log viewer 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, for the website of the order's store view.

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 updated, retry later: the transaction could not be read from the Paystack API at that moment, the order was being processed by the customer return at the same time, or the order could not be updated. Paystack sends the webhook again. The log shows the reason.

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

The webhook URL shows Method not allowed in the browser: this is normal. The URL accepts only requests from Paystack.

Webhooks fail while the store is in maintenance mode: Magento maintenance mode closes the whole site, the webhook URL too. Paystack retries the webhook later, and the order is also confirmed 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 Debug log viewer in the Advanced section. The native order total must use the currency precision accepted by Paystack. XOF and RWF require whole amounts. means that an XOF or RWF order total has decimals. The order of that attempt is cancelled.

Order is On Hold after payment: read the order notes (see Order statuses), then fulfil the order or refund the payment with Request held payment refund.

Refund fails with a message about the mode: the message The secret key of the original test payment mode is not configured. (or live) means that the payment was made in that mode, and its secret key is not set. Enter it and try 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 (for example On Hold after a mismatch) cannot be refunded with a credit memo; use the reconciliation refund of the VibeFox Paystack Payment block.

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.

Developers can change the transaction request and the list of currencies with the Magento events paystack_p_payment_request, paystack_p_supported_currencies and paystack_p_currency_decimals. The reference, amount and currency of the request cannot be changed.

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

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

The license key and license status are always removed. If Remove data on uninstall is Yes, the module settings, cache and log are removed too. If it is No, the settings are kept for a re-install. The Paystack payment attempts 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.

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