Troubleshooting

For merchants

Logs

The plugin writes to var/log/paystack_<env>.log in your Shopware directory (rotating, 7 files). Errors are always written; turn on Enable Detailed Logging in the configuration for the full picture, then turn it off again.

tail -f var/log/paystack_prod.log

All plugin log lines start with [Paystack]. For Shopware's own logging setup, see Shopware: Logging.

Installation problems

The plugin is not listed in Extensions → My extensions. Run bin/console plugin:refresh. With Composer, check the package is in vendor/kommandhub/paystack-sw.

Composer: "could not find a version matching your minimum-stability". Require the beta explicitly: composer require "kommandhub/paystack-sw:^0.9@beta".

Checkout fails for Paystack after an update. Run bin/console plugin:update KommandhubPaystackSW and bin/console cache:clear — the update repairs the payment method's handler reference.

Pay with Paystack is not offered at checkout. Assign it to the sales channel (Sales Channels → (channel) → General → Payment methods) and check it is active under Settings → Shop → Payment methods. Any availability rule set on the payment method must match.

Configuration problems

Checkout says "Paystack is not configured correctly. Please contact the shop owner." The secret key for the active mode is empty for this sales channel. If Enable Sandbox Mode is on, fill Test Secret Key; otherwise Live Secret Key. Switch the configuration screen to the affected sales channel to check for an empty override. The log contains API secret key is not configured with the sales-channel ID.

Payment problems

Customer paid, but the order stays unpaid

The return redirect normally marks the order paid; if the customer did not come back, only the webhook can. Check:

1. In the Paystack dashboard, the webhook URL for the same mode (test/live) is https://<your-shop-domain>/paystack/webhook.
2. That domain is configured on a Shopware sales channel.
3. Nothing (basic auth, maintenance mode, firewall) blocks requests from Paystack.
4. Paystack's dashboard lists each webhook delivery with its response code (Paystack: Webhooks):

Response	Meaning	Fix
204	Accepted	Look for a follow-up warning in the log, e.g. an amount mismatch.
400 (from Shopware)	Domain not configured on a sales channel	Add the domain.
403	Signature invalid	See next section.
500	Processing failed	Read the error in the log; Paystack retries.

Webhooks return 403

The x-paystack-signature header does not match. The plugin checks it with the secret key of the active mode saved on All Sales Channels:

• test webhooks need sandbox mode on; live webhooks need it off;
• the key on All Sales Channels must belong to the Paystack account sending the webhook — per-channel overrides are not used here.

"Payment amount mismatch detected" or currency mismatch

Paystack reports a different amount or currency than the order, so the plugin refuses to mark it paid. This is a safety check. The log line Amount mismatch. shows expected and received amounts in minor units. Common causes: the order total changed after payment started, or a payment reference from another order was reused.

Refund problems

There is no Refund item in the Paystack tab's ⋯ menu. Check that:

• Enable Refunds is on for the order's sales channel;
• your role has Process Paystack refunds (Administrators always do);
• the order has not been refunded in full already;
• what is left to refund is at least the Minimum Refund Amount.

"The refund amount must be at least …" / "The refund amount cannot exceed …". The amount is below the Minimum Refund Amount or above what is left to refund. The message shows the limit.

The refund went through at Paystack, but the order still says Paid and no Captures card appears. Shopware records a refund only when Paystack's refund.pending and refund.processed webhooks arrive. The refund itself is done — don't refund again. Fix the webhook delivery as described in Customer paid, but the order stays unpaid. Paystack retries failed deliveries, so the refund appears once the webhook gets through.

Bank details problems

Bank list empty or verification fails. Enable Bank Data Collection must be on for the sales channel (otherwise the endpoints answer 404), the customer must be logged in, and the secret key must be valid. In sandbox mode only Paystack's test accounts resolve.

"This value should have exactly 10 characters." The form accepts only 10-digit account numbers — see Known issues.

Known issues

In version 0.9.0-beta.2:

Issue	Impact	Workaround
Webhook signatures are checked with the key on All Sales Channels only.	Webhooks from a second Paystack account are rejected.	One Paystack account per installation.
No setting to restrict payment channels (the code reads a paymentOptions key that has no field on the configuration screen).	Channels follow the Paystack dashboard.	Restrict channels in Paystack.
Bank-details form accepts only 10-digit account numbers.	Customers outside Nigeria may not be able to save their account.	—
Bank details and BVN stored unencrypted.	Readable by Administration users with customer access.	Enable only if needed; restrict roles.

Still stuck? Contact support with the plugin version, Shopware version and the log lines.