VibeFox Paystack for WooCommerce — Help

Requirements

WordPress: 5.8 or later.

WooCommerce: 7.0 or later, installed and active. The plugin refuses to activate without it.

PHP: 8.0 or later.

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.

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 site 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 WordPress go to Plugins > Add New > Upload Plugin, choose the plugin ZIP file and click Install Now. You can also upload the wcp_paystack_payment folder to /wp-content/plugins/ by FTP.

2. Click Activate.

3. Open the settings: WooCommerce > Settings > Payments > Paystack > Manage, or click Settings under the plugin name on the Plugins page.

4. Enter your VibeFox license key in the license block at the top of the page and click Activate.

5. Paste your secret keys from the Paystack dashboard and set the webhook URL in the Paystack dashboard (see Configuration).

6. Turn on Enable/Disable and save. Keep Test Mode on until you have made a test payment, then untick it to accept real payments.

Configuration

All settings are on one page: WooCommerce > Settings > Payments > Paystack. 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 your store currency. While a key problem exists, the payment method is hidden at checkout. In the list of payment methods, Paystack is marked as needing setup until the current mode has a secret key.

Checkout

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

Title: the payment method name customers see at checkout. Default: Paystack.

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: Enable Test Mode uses the test secret key for new payments, and no real money is charged. Untick it 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.

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

Webhook

The webhook tells your store that a payment has been made, even when the customer does not return to the store. In the Paystack dashboard, page Settings > API Keys & Webhooks, set the URL shown in this section as both the Test Webhook URL and the Live Webhook URL. It looks like https://your-site/wc-api/paystack_p_webhook/. Copy the URL exactly as the settings show it.

Paystack signs every webhook with your secret key, so nothing else has to be configured. Test webhooks are checked with the test secret key and live webhooks with the live secret key. Webhooks without a valid signature are rejected. The plugin 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 store after paying. Bank transfer and USSD payments that complete later are confirmed only by the webhook.

Orders

Autocomplete Order: Automatically mark orders as completed after successful payment. When checked, paid orders become Completed instead of Processing, with one status change and one customer e-mail. Default: off.

Advanced

Debug log: Log Paystack events and API calls for debugging writes details to WooCommerce > Status > Logs, source wcp_paystack_payment. Errors are always logged. Keys and customer data are never logged. Default: off.

Delete data on uninstall: Remove the gateway settings and logs when the plugin is deleted. Deactivating the plugin never deletes anything. Payment data saved on orders is always kept. Default: off.

Checkout

The customer chooses the payment method (by default Paystack) and places the order. In test mode the checkout shows TEST MODE ENABLED. No real charges will be made. The plugin starts a Paystack transaction for the order total in the order currency, with the billing e-mail of the order, and sends the customer to the Paystack hosted checkout page. There the customer pays with one of the channels enabled on your Paystack account.

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 plugin reads the transaction from the Paystack API with the secret key of the mode the payment was started in, and checks the reference, status, amount and currency. If the payment is still being processed, for example a bank transfer, the order received 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 the customer cancels on the Paystack page or leaves it without paying, the order keeps waiting for payment. The customer comes back to the checkout or to the Pay for order page 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. The customer can pay the same order again. An older payment page of the order stays valid: if it is paid later, the payment is still accepted.

The order received page opens only for the customer of the order: the signed return link, the checkout session that created the order or the customer's account. Anyone else is sent to the checkout with a neutral message, and the order page is not shown.

If Paystack cannot start the payment, the customer sees 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 order total must be greater than zero, and the order needs a valid e-mail address.

The payment method works on the classic checkout, on the Checkout block and on the Pay for order page. It is compatible with WooCommerce High-Performance Order Storage (HPOS).

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

Orders and refunds

Order statuses

Pending payment: the customer was sent to Paystack and has not paid yet, left the Paystack page without paying, or the payment is still being processed by Paystack. When the customer returns without paying, a note says that the order is still waiting for payment.

Processing or Completed: the payment was confirmed. The status is Completed when Autocomplete Order is on. The order note shows the amount, the Paystack 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 transaction ID of the order is the Paystack reference (order_...).

On hold: the paid amount or currency differs from the order (note Paystack amount or currency mismatch), or the payment arrived after the order had been cancelled. The order note explains what to check. Fulfil the order or refund the payment.

Failed: Paystack reports the latest payment attempt of a pending order as failed or reversed. A failure of an older attempt does not change the order. The customer can pay again.

If a second payment attempt of an order that is already paid is paid as well, 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 Refunded, is only noted on the order.

Refunds

Open the order, click Refund, enter the amount and click Refund via Paystack. Full and partial refunds are supported. The refund button is offered only for orders paid through a verified Paystack transaction. 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. In XOF and RWF refunds must be whole amounts. Paystack queues refunds: the order note shows the status Paystack returned, for example pending, and the refund ID. If Paystack does not accept the refund, WooCommerce shows Paystack refund failed: with the reason, and no refund is recorded.

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

License key

The plugin works with a VibeFox license key from vibefox.net. The license block is at the top of WooCommerce > Settings > Payments > Paystack. Paste the key into License key and click Activate. The block shows the status, for example the date the license is active until and your domain. Use Check now to check the status again, Change key to enter another key and Remove key to remove it from this site. The link Manage licenses and domains in your account opens your vibefox.net account.

One key works on one domain. Removing the key from a site 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. Logged-in store managers still see the payment method, marked (unlicensed — visible to admins only), so you can set up and test the plugin before you buy a key. A reminder appears on the Plugins page and on WooCommerce pages. Existing orders are not affected: payments already started are still confirmed, and refunds work.

When a license expires, the plugin keeps working, but updates and support need a renewal. The status is checked again automatically in the background.

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 order currency is one Paystack accepts. The status box at the top of the settings names the problem.

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 settings, and that no maintenance mode, firewall or password protection blocks it. Look at WooCommerce > Status > Logs, source wcp_paystack_payment, 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 or Busy, retry later: the transaction could not be read from the Paystack API at that moment, or the order was being updated by the customer return at the same time. The order is not changed, and Paystack sends the webhook again.

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

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 On hold after payment: read the order note. The paid amount or currency differed from the order, or the payment arrived after the order had been cancelled. Process the order or refund the payment.

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. The message No verified Paystack payment was found for this order means the order was not paid through a verified Paystack transaction. Refund it in the Paystack dashboard.

The license block shows an error: follow the message in the block. For example, if the key is already used on another domain, free a slot in your vibefox.net account and click Check now. If the site address changed, click Check now to activate the key for the new domain. If the license server cannot be reached, the plugin keeps working on the last known status.

Uninstall

Deactivating the plugin keeps all data. To remove it, deactivate and delete it on the Plugins page. The license key and license status of this plugin are always removed. The gateway settings and the logs are removed only if Delete data on uninstall was on. Otherwise they stay for a later re-install. Existing orders keep their payment notes, transaction IDs and Paystack references.

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