Paystack for WooCommerce: Setup and Troubleshooting

The Paystack WooCommerce plugin connects your WordPress store to Paystack's payment infrastructure. When a customer reaches your checkout page, the plugin presents the Paystack payment form (either as a popup on your site or as a redirect to a Paystack-hosted page), collects the payment, and updates the WooCommerce order status based on the result.

Under the hood, the plugin handles three things:

• Transaction initialization. When the customer clicks "Place Order," the plugin sends the order details (amount, currency, customer email, order reference) to Paystack's API to create a transaction.
• Payment collection. Paystack presents the payment form to the customer. The customer chooses their payment method (card, bank transfer, M-Pesa, USSD, mobile money) and completes the payment.
• Order confirmation. After payment, Paystack sends a webhook to your site and/or redirects the customer back. The plugin verifies the transaction with Paystack's API and updates the WooCommerce order status to "Processing" or "Completed."

The plugin supports all payment channels available in your Paystack account. If you are a Kenyan merchant, your customers can pay with M-Pesa, cards, and bank transfers. If you are a Nigerian merchant, they can pay with cards, bank transfers, USSD, and more. The available channels depend on your country and your Paystack account configuration, not on the plugin itself.

This guide is part of the Paystack plugins and no-code integrations cluster.

Installing the plugin takes about five minutes. Configuring it properly takes a bit longer, but the process is straightforward.

Step 1: Install the plugin.

In your WordPress admin, go to Plugins > Add New. Search for "Paystack WooCommerce." The official plugin is published by Paystack. Click "Install Now," then "Activate."

Alternatively, download the plugin from the WordPress plugin directory or from Paystack's GitHub repository and upload it manually via Plugins > Add New > Upload Plugin.

Step 2: Enter your API keys.

Go to WooCommerce > Settings > Payments. You should see "Paystack" listed. Click "Set up" or "Manage."

Enter your API keys from the Paystack Dashboard (Settings > API Keys & Webhooks). You will see fields for both test and live keys:

• Test Public Key (starts with pk_test_)
• Test Secret Key (starts with sk_test_)
• Live Public Key (starts with pk_live_)
• Live Secret Key (starts with sk_live_)

Start in test mode. The plugin has a toggle or checkbox to switch between test and live. Leave it on test until you have confirmed everything works.

Step 3: Configure the webhook URL.

In the Paystack Dashboard, go to Settings > API Keys & Webhooks. Set the webhook URL to:

https://yourdomain.com/?wc-api=tbz_wc_paystack_gateway

Replace yourdomain.com with your actual domain. This URL must be publicly accessible. It will not work with localhost or a staging site behind HTTP authentication.

Step 4: Choose your checkout mode.

The plugin offers two checkout modes:

• Inline (Popup): The Paystack payment form appears as a popup overlay on your checkout page. The customer stays on your site. This is the recommended mode for most stores.
• Redirect: The customer is sent to a Paystack-hosted payment page. After payment, they are redirected back to your site. This mode works better if your site has JavaScript conflicts or if your hosting has strict Content Security Policy headers.

Before accepting real money, run a test transaction to confirm the full flow works.

Make sure the plugin is in test mode. Add a product to your cart, go to checkout, fill in the billing details, and click "Place Order." The Paystack payment form should appear (inline or redirect, depending on your setting).

Use Paystack's test card numbers:

• Card number: 4084 0840 8408 4081
• Expiry: any future date
• CVV: 408
• OTP/PIN: 0000 (if prompted)

After the test payment completes, check three things:

1. Order status in WooCommerce: The order should move from "Pending" to "Processing" or "Completed." If it stays on "Pending," the webhook did not arrive or the verification failed.
2. Transaction in Paystack Dashboard: Go to Transactions in your Paystack Dashboard (test mode). You should see the transaction with the correct amount and reference.
3. Webhook delivery: In the Paystack Dashboard, check the webhook logs (Settings > Webhooks > Recent Deliveries). You should see a successful delivery to your webhook URL with a 200 response.

If all three check out, your integration is working. If not, see the troubleshooting section below.

Once testing is complete, switch the plugin to live mode, enter your live API keys, and update the webhook URL in the Paystack Dashboard if needed (though most setups use the same URL for both test and live).

Webhooks are the backbone of reliable payment processing. When a customer pays, Paystack sends a POST request to your webhook URL with the transaction details. The plugin uses this webhook to verify the payment and update the order.

Why can you not just rely on the redirect callback? Because redirects are unreliable. The customer might close their browser after paying. Their internet might drop. The redirect URL might fail to load. If your only confirmation mechanism is the redirect, you will miss payments. Webhooks are server-to-server, so they work regardless of what the customer's browser does.

Common webhook problems and fixes:

Webhook URL returns 404. The WooCommerce webhook endpoint uses the ?wc-api= parameter. If your site uses pretty permalinks, make sure they are working correctly. Go to Settings > Permalinks in WordPress and click "Save Changes" (even without changing anything) to flush the rewrite rules.

Webhook URL returns 500. Check your PHP error logs. Common causes: a plugin conflict, a PHP version mismatch, or a database connection issue. Temporarily deactivate other plugins to isolate the problem.

Webhook never arrives. Confirm the URL is correct in the Paystack Dashboard. Confirm your site is publicly accessible (not behind HTTP auth, not on localhost). Check if your hosting provider or a security plugin (like Wordfence) is blocking POST requests from external servers.

Webhook arrives but order status does not update. The plugin verifies the webhook by checking the x-paystack-signature header against your secret key. If the secret key in your plugin settings does not match the one used by Paystack, verification fails silently. Double-check that your keys match and that you are not mixing test and live keys.

If you sell subscription products (monthly boxes, memberships, recurring services), you can use the Paystack plugin with WooCommerce Subscriptions, a premium WooCommerce extension.

The Paystack plugin supports WooCommerce Subscriptions by creating a Paystack Plan that matches your subscription product's billing cycle. When a customer subscribes, the plugin charges them immediately for the first period and sets up automatic recurring charges through Paystack.

Setup steps for subscriptions:

1. Install and activate WooCommerce Subscriptions (paid plugin from WooCommerce.com).
2. Create a subscription product in WooCommerce with the desired billing cycle (weekly, monthly, yearly).
3. The Paystack plugin will automatically detect subscription products at checkout and handle the recurring billing setup.

Things to watch for with subscriptions:

• Plan mismatch. If you change the price or billing cycle of a subscription product after customers have already subscribed, existing subscriptions continue at the old rate on Paystack's side. You need to handle migrations manually.
• Failed renewals. When a recurring charge fails (card expired, insufficient funds), Paystack retries according to its retry schedule. The plugin updates the subscription status in WooCommerce based on the outcome. Make sure your webhook is always active so these status updates come through.
• Cancellations. When a customer cancels through WooCommerce, the plugin should cancel the subscription on Paystack's side. Test this flow to confirm it works in your setup.

These are the problems that come up most often with the Paystack WooCommerce plugin:

"Transaction was not verified" or order stays on Pending.

This means the plugin could not confirm the payment with Paystack's API. Check your secret key. Check that your webhook URL is reachable. Check that your server can make outbound HTTPS requests to api.paystack.co (some hosting providers block outbound requests).

Checkout page shows a blank screen or JavaScript error.

Usually caused by a JavaScript conflict with another plugin. Common culprits: minification plugins, caching plugins that combine JavaScript files, or security plugins that add Content Security Policy headers blocking Paystack's domain. Temporarily deactivate plugins one by one to find the conflict. Add js.paystack.co to your Content Security Policy whitelist if needed.

Payment succeeds on Paystack but WooCommerce shows nothing.

The webhook is not getting through. Check the Paystack Dashboard webhook logs. If the delivery shows a non-200 response, your server is rejecting the webhook. Common causes: security plugins blocking POST requests, .htaccess rules blocking requests without a user agent, or the WordPress REST API being disabled.

"Currency not supported" error.

WooCommerce currency must match what your Paystack account supports. If your Paystack account is in Nigeria, it accepts NGN. If your WooCommerce store is set to USD, the plugin cannot process the payment. Set your WooCommerce currency to match your Paystack account's currency.

Double charges or duplicate orders.

This usually happens when both the redirect callback and the webhook create separate orders or update the same order twice. The plugin handles this with transaction reference checks, but caching plugins can interfere. Exclude the WooCommerce checkout and order-received pages from your caching plugin.

WordPress sites love caching plugins. Payment pages hate them. The checkout page, the order-received page (thank you page), and the WooCommerce API endpoint must never be cached.

Most caching plugins (WP Super Cache, W3 Total Cache, WP Rocket, LiteSpeed Cache) have an option to exclude specific URLs from caching. Add these paths to your exclusion list:

• /checkout/
• /cart/
• /my-account/
• /?wc-api=

If you use a CDN like Cloudflare, set a page rule to bypass cache for your checkout and cart pages. Also make sure Cloudflare is not blocking Paystack's webhook requests. Under Security > WAF, check if any rules are blocking POST requests from Paystack's IP addresses.

JavaScript minification and file combining can also break the Paystack inline checkout. If your optimization plugin combines all JavaScript files into one, the Paystack inline script may fail to load or execute in the correct order. Exclude js.paystack.co from any JavaScript optimization.

These issues are not unique to Paystack. Any payment gateway plugin on WooCommerce has the same caching sensitivities. The fix is always the same: exclude payment-related pages and endpoints from caching and optimization.

Your WooCommerce store handles customer data and processes financial transactions. Security is not optional.

SSL certificate. Your site must use HTTPS. Paystack will not work on an HTTP site. Most hosting providers offer free SSL through Let's Encrypt. If your checkout page is not on HTTPS, fix that before anything else.

Keep everything updated. Update WordPress, WooCommerce, the Paystack plugin, and all other plugins regularly. Payment-related security vulnerabilities are patched quickly, but only if you apply the updates.

Protect your API keys. Never share your secret key publicly. Do not paste it in a support forum, a GitHub issue, or a WhatsApp group asking for help. If you suspect your secret key has been compromised, regenerate it immediately in the Paystack Dashboard and update it in your WooCommerce settings.

Limit admin access. Only give WordPress admin access to people who need it. Every admin user can see and modify the Paystack plugin settings, including the API keys. Use WooCommerce's built-in role system to restrict access to payment settings.

Monitor transactions. Check your Paystack Dashboard regularly for unusual activity. Set up webhook-based alerts (through Zapier or n8n) to notify you of large transactions, failed payments, or disputes.

If you want to dig deeper into how the Paystack checkout works at the engineering level, see the complete Paystack engineering guide.