Skip to content

Paystack for Shopware 6 — 0.9.0-beta.3 - #3

Merged
KommandHub merged 5 commits into
mainfrom
develop
Oct 13, 2026
Merged

KommandHub merged 5 commits into
mainfrom
develop

Conversation

@KommandHub

@KommandHub KommandHub commented Oct 13, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

Third pre-release (0.9.0-beta.3) for internal development, QA and sandbox/staging testing. Not yet submitted to the Shopware Store.

Upgrade note — the plugin was renamed. The technical name changed from KommandhubPaystackSW to KmhPaystackSW, so Shopware treats it as a different plugin and 0.9.0-beta.1 / 0.9.0-beta.2 installs are not updated in place. Install KmhPaystackSW, re-enter the API keys and settings (now under KmhPaystackSW.config.*), then remove the old plugin. The custom field set and bank fields were renamed too (kmh_paystack_*); previously saved bank details are not migrated.

Changes since 0.9.0-beta.2

  • Rename completed across the config domain, storefront templates, admin component and route, and the coverage config. The rename had left stale references that made every setting read empty and caused validly signed webhooks to be rejected with 403.
  • Fresh installs are ready to use: the payment method is assigned to all sales channels when first created, and Sandbox Mode is on by default so a new install never calls live Paystack until it is switched off. Updates never re-add the method to a channel it was removed from.
  • Declined cards are recorded as failed, not cancelled. When Paystack returns the customer without a reference, the plugin verifies the reference stored at checkout and lets Paystack's real status decide (failed → failed, abandoned → cancelled, success → paid, pending → open).
  • Late webhooks for an earlier retry attempt are matched to their order via the order transaction id now sent in the Paystack metadata. The payment is still verified with Paystack before the order is marked paid.
  • Stale built bundles rebuilt (administration and storefront) — they still embedded the old config domain and sat at the old path, so the plugin's storefront JS was never loaded.
  • Store compliance: replaced the deprecated EntitySearchResult::first() (removed in Shopware 6.8) with getEntities()->first(). shopware-cli extension validate --store-compliance reports no problems.
  • composer.json version fixed: the rename commit had lowered it to 0.9.0-beta, which sorts below beta.2.
  • Docs: first-install behaviour, supported-currency requirement, and troubleshooting for sandbox "Insufficient Funds", unsupported currencies and Shopware's default status-email wording. Release notes added in en, de and fr.

Test plan

  • 384 tests pass; PHPStan level 9, php-cs-fixer and the 100% coverage gate are green
  • shopware-cli extension validate --store-compliance: no problems found
  • Live (sandbox): successful payment, abandoned payment, forged charge.success for an unpaid order is ignored, lost-return recovery via webhook, webhook replay is idempotent, cancel-return stays cancelled, late webhook for an overwritten reference is matched via metadata
  • Declined card ends as failed against real Paystack (covered by unit tests; live check still pending)
  • CI green on this PR

…stackSW

Systematically rename the Paystack payment plugin to use the shorter
'Kmh' prefix instead of 'Kommandhub', improving consistency across the
plugin ecosystem while maintaining backward compatibility through the
existing PHP namespace.

Changes:
- Plugin directory: KommandhubPaystackSW/ → KmhPaystackSW/
- Plugin class: KommandhubPaystackSW → KmhPaystackSW
- Custom field set: kommandhub_paystack_fieldset → kmh_paystack_fieldset
- Custom fields: kommandhub_paystack_* → kmh_paystack_*
- Payment method: kommandhub_paystack_payment → kmh_paystack_payment
- Routes: kommandhub_paystack_* → kmh_paystack_*
- Admin components: kommandhub-paystack-detail → kmh-paystack-detail
- Translation keys: kommandhub-paystack-* → kmh-paystack-*
- Built assets: kommandhub-paystack-s-w-* → kmh-paystack-s-w-*
- Test files: KommandhubPaystackSWTest → KmhPaystackSWTest

Preserved:
- PHP namespace: Kommandhub\PaystackSW (unchanged)
- Composer package: kommandhub/paystack-sw (unchanged)

Breaking Changes:
- Database: Custom field names will change on plugin update
- Database: Payment method technical name will change on plugin update
- The plugin's update() method handles migration automatically

Updated 32 files including PHP classes, configuration, translations,
tests, and documentation. All tests passing.
…utes

The plugin rename left several references to the old KommandhubPaystackSW
name. QA against a live shop showed this broke the payment path:

- Config::KEY still read "KommandhubPaystackSW.config.", while Shopware stores
  the plugin's settings under "KmhPaystackSW.config.*". Every setting read
  returned empty: the secret key was blank, sandbox mode was off, and a
  correctly signed webhook was rejected with 403 because the signature
  validator saw no secret.
- The admin refund component and the sw-order-detail override read the same
  stale config domain, so refundEnabled and minimumRefundAmount were ignored.
- The storefront account templates used the stale config keys and the
  "@KommandhubPaystackSW/" Twig namespace, so bank/BVN options never applied
  and the account include could not resolve.
- The Paystack tab on the order detail page linked to the route
  "kommandhub.paystack.detail", but main.js registers "kmh.paystack.detail".
- phpunit.dist.xml still excluded src/KommandhubPaystackSW.php from coverage
  (the class is now KmhPaystackSW.php), pulling the kernel-only bootstrap class
  back into the CI coverage gate.

Replace the old name in all of these. Fix the stale container name in the
README.

Verified: a webhook signed with the sandbox key now returns 204 (was 403);
unsigned and badly signed webhooks still return 403; checkout initializes a
Paystack transaction and completes an NGN order to "paid" with the
paystack_* fields stored. 372 tests pass, PHPStan level 9 and php-cs-fixer
are clean, and the 100% coverage gate holds.

Note: the built administration and storefront bundles still contain the old
names and must be rebuilt before these admin and storefront fixes take effect
in a shop.
… declined payments

Fresh install
- Assign the Paystack payment method to all sales channels when it is first
  created, so it is selectable at checkout straight after install. An existing
  method is only refreshed, never re-assigned, so a merchant who removed it
  from a channel does not get it back on every update. The cart validator
  still blocks use until API keys are configured.
- Default enableSandbox to true so a fresh install never calls live Paystack
  until the merchant switches it off. Existing installs keep their value.

Late webhooks after a retry
- Each retry overwrites paystack_reference, so a late charge.success for an
  earlier attempt matched no order. Always send order_transaction_id in the
  Paystack metadata (Paystack echoes it back) and have ChargeSuccessSubscriber
  fall back to it when no transaction carries the reported reference. The id is
  only a lookup hint: the payment is still verified against Paystack (status,
  amount, currency) before the order is marked paid.
- Add OrderTransactionService::findOneById() for the nullable lookup.

Declined payments recorded as cancelled
- A redirect that carries no reference (cancel/back, some failures) was always
  treated as a customer cancellation, even when the card was declined. Verify
  the reference stored at pay time instead and let Paystack's real status
  decide: failed -> failed, abandoned -> cancelled, success -> paid, pending ->
  left open. The abandoned outcome applies only to a redirect without a
  reference, so webhook and normal return behaviour are unchanged.

Stale bundles
- Rebuild the administration and storefront bundles. They still embedded the
  pre-rename config domain, so admin refund settings were ignored, and the
  storefront bundle sat at the old path so the plugin's JS (bank verification)
  was never loaded.

Docs
- README: first-install behaviour and sandbox default, supported-currency
  requirement, and troubleshooting for "Insufficient Funds" in Paystack's
  sandbox (large amounts are rejected), unsupported currencies, and the stock
  Shopware status-email subject/typo (core templates, not shipped by this
  plugin).

Tests: 384 tests pass; PHPStan level 9, php-cs-fixer and the 100% coverage gate
are green. Verified against a live shop: late webhook for an overwritten
reference (found via metadata, verified, paid), cancel-return (still
cancelled), and sandbox default plus no re-assignment on reinstall.
- Bump composer.json to 0.9.0-beta.3. The rename commit had lowered it to
  0.9.0-beta, which sorts below 0.9.0-beta.2 and would read as a downgrade.
- Add 0.9.0-beta.3 release notes (en, de, fr), including an upgrade note for
  the KommandhubPaystackSW -> KmhPaystackSW rename: existing beta.1/beta.2
  installs are not updated in place and must be reinstalled and reconfigured.
  Mirror the note in the README.
- Replace the deprecated EntitySearchResult::first() (removed in Shopware 6.8)
  with getEntities()->first() in AbstractEntityReader, RefundInitializeService
  and WebhookSubscriber. shopware-cli store validation now reports no problems.
@KommandHub
KommandHub merged commit 4f60f85 into main Oct 13, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant