Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,15 @@
# 0.9.0-beta.3

Third pre-release. Still for internal development, QA and sandbox/staging
testing; not yet submitted to the Shopware Store.

**Upgrade note: the plugin was renamed.** Its 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 your Paystack API keys and settings (they now live under the `KmhPaystackSW.config.*` domain), and then remove the old plugin. The custom field set and the bank fields were renamed as well (`kmh_paystack_*`); bank details saved by earlier versions are not migrated.

- Fresh installs are now ready to use: the Paystack payment method is assigned to all sales channels when it is first created, and Sandbox Mode is on by default, so a new install never calls live Paystack until it is switched off. Updating the plugin never re-adds the method to a channel it was removed from.
- A declined card is now recorded as a failed payment instead of a cancelled one. When Paystack sends the customer back without a reference (cancel/back, some failures), the plugin verifies the reference stored at checkout and lets Paystack's real status decide: failed payments fail, abandoned ones are cancelled, successful ones are marked paid, and pending ones stay open.
- A late `charge.success` webhook for an earlier payment attempt is now matched to its order. Every retry overwrites the stored reference, so the order transaction id is also sent in the Paystack metadata and used as a fallback lookup; the payment is still verified with Paystack before the order is marked paid.
- Documentation: first-install behaviour, the requirement that the checkout currency is enabled on your Paystack account, and troubleshooting for sandbox "Insufficient Funds" on large amounts and for Shopware's default status-email wording.

# 0.9.0-beta.2

Second pre-release. Still for internal development, QA and sandbox/staging
Expand Down
12 changes: 12 additions & 0 deletions CHANGELOG_de-DE.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,15 @@
# 0.9.0-beta.3

Dritte Vorabversion. Weiterhin für interne Entwicklung, QA und Sandbox-/
Staging-Tests; noch nicht im Shopware Store eingereicht.

**Hinweis zum Update: Das Plugin wurde umbenannt.** Der technische Name wurde von `KommandhubPaystackSW` in `KmhPaystackSW` geändert. Shopware behandelt es daher als anderes Plugin, und Installationen von `0.9.0-beta.1` / `0.9.0-beta.2` werden nicht direkt aktualisiert. Installieren Sie `KmhPaystackSW`, geben Sie Ihre Paystack-API-Schlüssel und Einstellungen erneut ein (sie liegen jetzt unter der Domain `KmhPaystackSW.config.*`) und entfernen Sie anschließend das alte Plugin. Auch das Zusatzfeld-Set und die Bankfelder wurden umbenannt (`kmh_paystack_*`); von früheren Versionen gespeicherte Bankdaten werden nicht migriert.

- Neue Installationen sind sofort einsatzbereit: Die Paystack-Zahlungsart wird bei der erstmaligen Anlage allen Verkaufskanälen zugewiesen, und der Sandbox-Modus ist standardmäßig aktiv, sodass eine neue Installation nie die Live-Umgebung von Paystack aufruft, bevor er deaktiviert wird. Ein Plugin-Update fügt die Zahlungsart nie wieder zu einem Verkaufskanal hinzu, aus dem sie entfernt wurde.
- Eine abgelehnte Karte wird jetzt als fehlgeschlagene statt als abgebrochene Zahlung erfasst. Schickt Paystack den Kunden ohne Referenz zurück (Abbruch/Zurück, einige Fehlerfälle), prüft das Plugin die beim Checkout gespeicherte Referenz und lässt den tatsächlichen Paystack-Status entscheiden: fehlgeschlagene Zahlungen schlagen fehl, abgebrochene werden storniert, erfolgreiche als bezahlt markiert und ausstehende bleiben offen.
- Ein verspäteter `charge.success`-Webhook für einen früheren Zahlungsversuch wird nun der Bestellung zugeordnet. Jeder erneute Versuch überschreibt die gespeicherte Referenz; deshalb wird die Bestelltransaktions-ID zusätzlich in den Paystack-Metadaten gesendet und als Ersatz-Suche genutzt. Die Zahlung wird weiterhin bei Paystack verifiziert, bevor die Bestellung als bezahlt markiert wird.
- Dokumentation: Verhalten bei der Erstinstallation, die Anforderung, dass die Checkout-Währung in Ihrem Paystack-Konto aktiviert ist, sowie Hinweise zu „Insufficient Funds" in der Sandbox bei hohen Beträgen und zum Standardtext der Shopware-Statusmails.

# 0.9.0-beta.2

Zweite Vorabversion. Weiterhin für interne Entwicklung, QA und Sandbox-/
Expand Down
13 changes: 13 additions & 0 deletions CHANGELOG_fr-FR.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,16 @@
# 0.9.0-beta.3

Troisième version préliminaire. Toujours destinée au développement interne, à
l'assurance qualité et aux tests sandbox/staging ; pas encore soumise au
Shopware Store.

**Note de mise à jour : le plugin a été renommé.** Son nom technique est passé de `KommandhubPaystackSW` à `KmhPaystackSW` ; Shopware le considère donc comme un autre plugin et les installations de `0.9.0-beta.1` / `0.9.0-beta.2` ne sont pas mises à jour sur place. Installez `KmhPaystackSW`, saisissez à nouveau vos clés API et réglages Paystack (ils se trouvent désormais sous le domaine `KmhPaystackSW.config.*`), puis supprimez l'ancien plugin. L'ensemble de champs personnalisés et les champs bancaires ont aussi été renommés (`kmh_paystack_*`) ; les coordonnées bancaires enregistrées par les versions précédentes ne sont pas migrées.

- Les nouvelles installations sont immédiatement utilisables : le moyen de paiement Paystack est affecté à tous les canaux de vente lors de sa première création, et le mode sandbox est activé par défaut, de sorte qu'une nouvelle installation n'appelle jamais Paystack en production tant qu'il n'est pas désactivé. Une mise à jour du plugin ne réaffecte jamais le moyen de paiement à un canal dont il a été retiré.
- Une carte refusée est désormais enregistrée comme un paiement échoué et non comme un paiement annulé. Lorsque Paystack renvoie le client sans référence (annulation/retour, certains échecs), le plugin vérifie la référence enregistrée lors de la commande et laisse le statut réel de Paystack décider : les paiements échoués échouent, les paiements abandonnés sont annulés, les paiements réussis sont marqués comme payés et les paiements en attente restent ouverts.
- Un webhook `charge.success` tardif pour une tentative de paiement antérieure est désormais rattaché à sa commande. Chaque nouvelle tentative écrase la référence enregistrée ; l'identifiant de la transaction de commande est donc aussi envoyé dans les métadonnées Paystack et utilisé comme recherche de secours. Le paiement est toujours vérifié auprès de Paystack avant que la commande soit marquée comme payée.
- Documentation : comportement à la première installation, obligation que la devise du paiement soit activée sur votre compte Paystack, et dépannage pour « Insufficient Funds » en sandbox sur les montants élevés et pour le libellé par défaut des e-mails de statut de Shopware.

# 0.9.0-beta.2

Deuxième version préliminaire. Toujours destinée au développement interne, à
Expand Down
4 changes: 2 additions & 2 deletions CLAUDE.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# KommandhubPaystackSW
# KmhPaystackSW

Shopware 6 payment plugin integrating Paystack (cards, bank transfer, USSD) with
refunds, webhooks, bank-account verification, and African currency/language
Expand All @@ -7,7 +7,7 @@ support. PHP namespace root: `Kommandhub\PaystackSW\` → `src/`.
## Commands

All commands run inside the Docker dev stack (see `Makefile`). The plugin lives
at `custom/static-plugins/KommandhubPaystackSW` inside a Shopware install.
at `custom/static-plugins/KmhPaystackSW` inside a Shopware install.

- `make up` / `make down` — start / tear down the stack
- `make test` — PHPUnit (`phpunit.dist.xml`). Filter: `make test FILTER=SomeTest`
Expand Down
6 changes: 2 additions & 4 deletions Makefile
Original file line number Diff line number Diff line change
@@ -1,16 +1,14 @@
.PHONY: help up down build restart shell plugin-list test test-coverage cs cs-fix analyse fixture-load resync prepare validate-plugin cli changelog zip

CONTAINER := shopware
PLUGIN_DIR := custom/static-plugins/KommandhubPaystackSW
PLUGIN_DIR := custom/static-plugins/KmhPaystackSW

# Plugins installed via composer
STATIC_PLUGINS := \
kommandhub/foundation-sw:KommandhubFoundationSW \
kommandhub/paystack-sw:KommandhubPaystackSW
kommandhub/paystack-sw:KmhPaystackSW

# Only plugins that should be copied into custom/static-plugins
STATIC_COPY_PLUGINS := \
kommandhub/foundation-sw:KommandhubFoundationSW

# This plugin may ship at any stability (see "version" in composer.json), while
# the Shopware install it is tested against pins minimum-stability to "stable".
Expand Down
48 changes: 36 additions & 12 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -163,9 +163,9 @@ Paystack refund created ──► refund.pending / refund.processed webhooks upd
## Directory Structure

```text
KommandhubPaystackSW/
KmhPaystackSW/
├── src/
│ ├── KommandhubPaystackSW.php # Plugin base class (lifecycle hooks)
│ ├── KmhPaystackSW.php # Plugin base class (lifecycle hooks)
│ ├── Administration/
│ │ └── Controller/RefundController.php # Admin refund API endpoint
│ ├── BankVerification/
Expand Down Expand Up @@ -239,7 +239,7 @@ KommandhubPaystackSW/
```bash
composer require kommandhub/paystack-sw
bin/console plugin:refresh
bin/console plugin:install --activate KommandhubPaystackSW
bin/console plugin:install --activate KmhPaystackSW
bin/console cache:clear
```

Expand All @@ -249,7 +249,9 @@ bin/console cache:clear
2. In the Administration, go to **Extensions → My Extensions → Upload Extension**.
3. Install and activate **Paystack Payment**.

After installation, assign the **Paystack Payment** method to your sales channel under **Settings → Shop → Payment Methods**.
On first installation the **Paystack Payment** method is assigned to all of your sales channels and **Sandbox Mode is on by default**, so a fresh install never talks to live Paystack until you switch it off. The method cannot be used for an order until a secret key is configured. If you only want it on some channels, adjust the assignment in the sales channel settings. Updating the plugin never re-adds the method to a channel you removed it from.

Paystack only accepts currencies enabled on your Paystack account (for example NGN, GHS, ZAR, KES), and the plugin does not create currencies. Make sure the currency a customer checks out in is both enabled on your Paystack account and added to the sales channel.

---

Expand All @@ -259,21 +261,21 @@ The repository ships a Docker Compose stack based on [`dockware`](https://dockwa

```bash
# 1. Clone the repository
git clone <repository-url> KommandhubPaystackSW
cd KommandhubPaystackSW
git clone <repository-url> KmhPaystackSW
cd KmhPaystackSW

# 2. Start the stack (builds the container and prepares the shop)
make up

# 3. Install and activate the plugin inside the container
make shell
bin/console plugin:refresh
bin/console plugin:install --activate KommandhubPaystackSW
bin/console plugin:install --activate KmhPaystackSW
bin/console cache:clear
exit
```

The plugin directory is mounted at `/var/www/html/custom/static-plugins/KommandhubPaystackSW`; `.git/`, `node_modules/`, and `vendor/` are excluded from the mount. Changes to source files on the host are reflected immediately in the container.
The plugin directory is mounted at `/var/www/html/custom/static-plugins/KmhPaystackSW`; `.git/`, `node_modules/`, and `vendor/` are excluded from the mount. Changes to source files on the host are reflected immediately in the container.

Default dockware credentials:

Expand All @@ -294,7 +296,7 @@ a small [`Dockerfile`](Dockerfile):
runs `shopware-cli --version` so a broken install fails the image build rather
than the first `make validate-plugin`. Pin it for a reproducible build by
passing `--build-arg SHOPWARE_CLI_IMAGE=shopware/shopware-cli:bin@sha256:<digest>`.
- **Container**: `kommandhub-paystack-plugin`
- **Container**: `kmh-paystack-plugin`
- **PHP**: 8.3 (`XDEBUG_ENABLED` toggle available)
- **Persistent volume**: `database` (MySQL data)

Expand Down Expand Up @@ -345,12 +347,12 @@ make cs-fix && make analyse && make test

## Configuration Options

Configure the plugin under **Extensions → My Extensions → Paystack → Configuration**. Options are stored in Shopware's system configuration under the `KommandhubPaystackSW.config.*` domain and read through `Setting\Service\Config`.
Configure the plugin under **Extensions → My Extensions → Paystack → Configuration**. Options are stored in Shopware's system configuration under the `KmhPaystackSW.config.*` domain and read through `Setting\Service\Config`.

| Key | Type | Purpose |
| --- | --- | --- |
| `apiSecretKey` | password | Live secret key (`sk_live_...`) |
| `enableSandbox` | bool | Use the sandbox/test key instead of live |
| `enableSandbox` | bool | Use the sandbox/test key instead of live (**on by default** for new installs) |
| `apiSecretKeySandbox` | password | Test secret key (`sk_test_...`) |
| `enableSplitPayment` | bool | Enable Paystack split payments |
| `subaccountCode` | text | Split payment subaccount code |
Expand Down Expand Up @@ -470,7 +472,7 @@ Logging goes through `Logging\ConfigurableLogger`, wired to the `paystack_channe
2. Run:
```bash
bin/console plugin:refresh
bin/console plugin:update KommandhubPaystackSW # migrates handler identifier + custom fields
bin/console plugin:update KmhPaystackSW # migrates handler identifier + custom fields
bin/console cache:clear
```
3. Ensure compiled Administration and Storefront assets are built and committed as part of the release.
Expand Down Expand Up @@ -517,6 +519,16 @@ A single plugin release supports both Shopware 6.6 and 6.7 (`shopware/core: ~6.6

> **Pre-1.0 status:** the plugin is on a `0.x` version while it completes sandbox/staging validation (see [Roadmap](#roadmap)). Namespaces and the public API may still change before `1.0.0`. Once testing is complete and all critical issues are resolved, this will be promoted to `1.0.0` and submitted to the Shopware Store.

### Upgrading from `0.9.0-beta.1` / `0.9.0-beta.2`

In `0.9.0-beta.3` the plugin's technical name changed from `KommandhubPaystackSW` to `KmhPaystackSW`. Shopware treats a renamed plugin as a different plugin, so existing installs are **not updated in place**:

1. Install and activate `KmhPaystackSW`.
2. Re-enter your Paystack API keys and settings — they now live under the `KmhPaystackSW.config.*` configuration domain.
3. Remove the old `KommandhubPaystackSW` plugin.

The custom field set and the bank fields were renamed too (`kmh_paystack_*`); bank details saved by earlier versions are not migrated. Orders and their `paystack_*` transaction fields are unaffected.

---

## Troubleshooting
Expand All @@ -525,6 +537,18 @@ A single plugin release supports both Shopware 6.6 and 6.7 (`shopware/core: ~6.6
- Confirm the webhook endpoint is reachable from Paystack and the secret key matches the mode (test vs live).
- Check `var/log/` for verification or signature errors.

**Test payments fail with "Insufficient Funds"**
- Paystack's sandbox test cards reject large amounts. Test with small orders (a few hundred in the currency, not hundreds of thousands) — an order of NGN 150 succeeds where NGN 790,000 is declined.

**Payment fails with "No active channel to process transaction" or "Currency not supported by merchant"**
- The order currency is not enabled on your Paystack account. Enable it in the Paystack dashboard, or have customers check out in a currency your account supports.

**Status emails say "New document for your order" or contain "he status…"**
- These are Shopware's own default mail templates (they are not shipped by this plugin). Edit them under **Settings → Shop → Email templates** — for example the templates for "Payment status paid / cancelled / open".

**A payment was made but the order stayed open**
- Paystack's webhook delivers `charge.success` even when the customer never returned to the shop, and the order is then finalized. Orders are matched by the stored reference or, for an earlier retry attempt, by the order transaction id the plugin sends in the Paystack metadata. Check the webhook URL and secret key.

**Plugin not visible in the Administration**
```bash
bin/console plugin:refresh
Expand Down
12 changes: 6 additions & 6 deletions composer.json
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
"name": "kommandhub/paystack-sw",
"description": "Independent, third-party Shopware 6 integration for the Paystack payment gateway: accept secure payments via cards, bank transfers, USSD, and mobile money across Africa. Not affiliated with, endorsed by, or officially connected to Paystack.",
"type": "shopware-platform-plugin",
"version": "0.9.0-beta.2",
"version": "0.9.0-beta.3",
"license": "Apache-2.0",
"keywords": [
"shopware",
Expand All @@ -22,7 +22,7 @@
"nigeria",
"ecommerce"
],
"homepage": "https://github.com/KommandHub/KommandhubPaystackSW",
"homepage": "https://github.com/KommandHub/KmhPaystackSW",
"authors": [
{
"name": "Kommandhub Limited",
Expand All @@ -33,9 +33,9 @@
],
"support": {
"email": "info@kommandhub.com",
"issues": "https://github.com/KommandHub/KommandhubPaystackSW/issues",
"source": "https://github.com/KommandHub/KommandhubPaystackSW",
"docs": "https://github.com/KommandHub/KommandhubPaystackSW/blob/main/README.md"
"issues": "https://github.com/KommandHub/KmhPaystackSW/issues",
"source": "https://github.com/KommandHub/KmhPaystackSW",
"docs": "https://github.com/KommandHub/KmhPaystackSW/blob/main/README.md"
},
"require": {
"shopware/core": "~6.6.0 || ~6.7.0",
Expand All @@ -59,7 +59,7 @@
}
},
"extra": {
"shopware-plugin-class": "Kommandhub\\PaystackSW\\KommandhubPaystackSW",
"shopware-plugin-class": "Kommandhub\\PaystackSW\\KmhPaystackSW",
"label": {
"de-DE": "Paystack-Zahlung von Kommandhub",
"en-GB": "Paystack Payment by Kommandhub",
Expand Down
12 changes: 6 additions & 6 deletions docker-compose.yml
Original file line number Diff line number Diff line change
Expand Up @@ -5,23 +5,23 @@ services:
build:
context: .
dockerfile: Dockerfile
image: 'kommandhub-paystack-plugin:6.7.8.0'
container_name: kommandhub-paystack-plugin
image: 'kmh-paystack-plugin:6.7.8.0'
container_name: kmh-paystack-plugin
environment:
- 'XDEBUG_ENABLED=0'
- 'PHP_VERSION=8.3'
volumes:
# ----------------------------------------------------------------------------------------------------------------------------------
# PLUGINS
- "./:/var/www/html/custom/static-plugins/KommandhubPaystackSW"
- "./:/var/www/html/custom/static-plugins/KmhPaystackSW"
- "database:/var/lib/mysql"
- "./Makefile:/var/www/html/Makefile"
# - ".env.test:/var/www/html/.env.test"
# ----------------------------------------------------------------------------------------------------------------------------------
# EXCLUDE
- "/var/www/html/custom/static-plugins/KommandhubPaystackSW/.git/"
- "/var/www/html/custom/static-plugins/KommandhubPaystackSW/node_modules/"
- "/var/www/html/custom/static-plugins/KommandhubPaystackSW/vendor/"
- "/var/www/html/custom/static-plugins/KmhPaystackSW/.git/"
- "/var/www/html/custom/static-plugins/KmhPaystackSW/node_modules/"
- "/var/www/html/custom/static-plugins/KmhPaystackSW/vendor/"
# ----------------------------------------------------------------------------------------------------------------------------------

volumes:
Expand Down
2 changes: 1 addition & 1 deletion phpunit.dist.xml
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,7 @@
Shopware kernel. Covered by the @group kernel integration tests
in the full suite; excluded here so the no-kernel CI coverage
gate reflects code it can actually run. -->
<file>src/KommandhubPaystackSW.php</file>
<file>src/KmhPaystackSW.php</file>
</exclude>
</source>

Expand Down
Loading
Loading