Paystack with Magento

Magento (now Adobe Commerce for the enterprise version, and Magento Open Source for the community edition) is an enterprise-grade e-commerce platform. It is not the right choice for a small business selling ten products. It is the right choice when your requirements include:

• Large product catalogs. Hundreds or thousands of SKUs with complex attributes (size, color, material, weight). Magento's catalog system handles this scale better than WooCommerce.
• Complex pricing rules. Tiered pricing, customer group pricing, catalog price rules, cart price rules, and promotions that interact with each other.
• Multi-store or multi-brand. A single Magento installation can power multiple storefronts with different domains, themes, catalogs, and currencies. A company selling in Nigeria, Kenya, and Ghana might run three store views from one Magento backend.
• B2B e-commerce. Magento has built-in B2B features: quote requests, purchase orders, company accounts, and shared catalogs.
• Performance at scale. With proper hosting and caching, Magento handles high traffic and transaction volumes that would slow down a typical WordPress/WooCommerce setup.

The tradeoff is complexity. Magento requires more technical skill to install, configure, and maintain than WooCommerce or Shopify. You need a developer (or agency) who knows Magento, or you need to invest time learning the platform.

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

The Paystack Magento 2 extension is installed via Composer, the PHP dependency manager that Magento uses for extension management. You need SSH access to your server.

Step 1: Require the extension via Composer.

composer require paystack/magento2-paystack

If the package is not available on Packagist, you may need to add the GitHub repository as a Composer source first. Check the extension's GitHub README for the current installation instructions.

Step 2: Run the Magento setup commands.

php bin/magento module:enable Paystack_Paystack
php bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento setup:static-content:deploy
php bin/magento cache:flush

These commands enable the module, update the database schema, compile dependency injection, deploy static assets, and clear the cache. They take a few minutes on most servers.

Step 3: Verify the module is active.

php bin/magento module:status Paystack_Paystack

The output should show the module as enabled.

After installation, configure the extension in the Magento admin panel.

Step 1: Go to Stores > Configuration > Sales > Payment Methods. You should see "Paystack" in the list of payment methods.

Step 2: Enter your API keys:

• Test Secret Key and Test Public Key (for development)
• Live Secret Key and Live Public Key (for production)

Step 3: Set the payment mode to "Test" while you are setting up. Switch to "Live" after testing.

Step 4: Configure the payment title that appears at checkout (for example, "Pay with Paystack" or "Pay with Card/Bank Transfer").

Step 5: Set the order status mapping. Configure which Magento order status corresponds to a successful payment (typically "Processing"), a failed payment ("Canceled"), and a pending payment ("Pending Payment").

Step 6: Save the configuration and flush the cache.

Step 7: Set the webhook URL. In the Paystack Dashboard (Settings > API Keys & Webhooks), enter the webhook URL provided by the extension. The format is typically your store URL followed by the module's webhook endpoint. Check the extension's documentation for the exact URL pattern.

Before accepting real payments, test the complete flow:

1. Make sure the extension is in test mode.
2. Add a product to your cart on the storefront.
3. Proceed to checkout. Fill in the shipping address and select a shipping method.
4. On the payment step, select Paystack.
5. Complete the payment using Paystack's test card (4084 0840 8408 4081, any future expiry, CVV 408).
6. After payment, you should be redirected back to the Magento order success page.

Verify these three things:

• Magento order status: The order should be in "Processing" status if the payment succeeded.
• Paystack Dashboard: The test transaction should appear in your Paystack test transactions.
• Webhook delivery: Check the Paystack Dashboard webhook logs to confirm the webhook was delivered with a 200 response.

Once testing passes, switch the extension to live mode, enter your live API keys, and update the webhook URL if needed. Process a small real transaction to confirm everything works in production.

One of Magento's strengths is multi-store support. A single Magento installation can serve multiple websites, stores, and store views. Each can have its own domain, theme, catalog, and payment configuration.

For merchants operating across multiple African countries, this means you can run a Nigerian store (NGN, Paystack Nigeria account), a Kenyan store (KES, Paystack Kenya account), and a Ghanaian store (GHS, Paystack Ghana account) from one Magento backend.

To configure different Paystack accounts per store view:

1. In the admin, go to Stores > Configuration.
2. Use the "Store View" dropdown at the top of the page to select the specific store view.
3. Navigate to Sales > Payment Methods > Paystack.
4. Uncheck "Use Website" for the fields you want to override.
5. Enter the API keys for the Paystack account that corresponds to this store view's country and currency.
6. Save and flush cache.

Each store view now uses its own Paystack account. Customers on the Nigerian store pay in NGN through the Nigerian Paystack account. Customers on the Kenyan store pay in KES through the Kenyan account. Orders from both stores appear in the same Magento admin, but payments are processed through separate Paystack accounts.

Remember to configure separate webhook URLs in each Paystack Dashboard account, pointing to the correct store view's webhook endpoint.

Magento is performance-sensitive, and most production Magento stores use aggressive caching. Full page cache (FPC), Varnish, Redis, and CDN layers are common. But caching and payment pages do not mix well.

Exclude checkout pages from full page cache. Magento's built-in FPC should already exclude the checkout by default, but verify this if you use a custom FPC extension or Varnish configuration. The checkout page must not serve cached content because each customer's cart, address, and payment state is unique.

Varnish configuration. If you use Varnish as a reverse proxy, ensure that URLs matching the checkout path and the Paystack webhook endpoint bypass the Varnish cache entirely. A cached webhook response means Paystack gets the same response for different transactions, which breaks payment verification.

Redis for sessions. Magento can use Redis for session storage, which is faster than file-based sessions. This matters for checkout performance because the payment flow involves multiple session reads and writes as the customer progresses through checkout steps.

Static content deployment. After installing or updating the Paystack extension, always run setup:static-content:deploy. If you skip this step, the extension's JavaScript and CSS files may not load on the frontend, causing the payment step to break.

Extension does not appear in admin. Run php bin/magento module:status to check if the module is enabled. If it shows as disabled, run php bin/magento module:enable Paystack_Paystack followed by setup:upgrade and cache:flush.

Checkout shows "Unable to process payment." Check the Magento exception log at var/log/exception.log and the system log at var/log/system.log. Common causes: incorrect API keys, currency mismatch, or the server cannot make outbound HTTPS requests to Paystack's API.

Order stays in "Pending Payment" after customer pays. The webhook did not arrive or failed verification. Check the Paystack Dashboard webhook logs. Common causes: incorrect webhook URL, firewall blocking POST requests from Paystack, or the extension's webhook handler throwing a PHP error.

Compilation errors after installation. If setup:di:compile fails, check for PHP version compatibility issues. The Paystack extension requires a PHP version compatible with your Magento installation. Check both the extension's requirements and your Magento version's PHP requirements.

Static content not deploying. If the payment step does not render correctly, run setup:static-content:deploy with the correct locale flags. For a store serving multiple languages, deploy for each locale.