From 029195fb586bf00ddd439f49a90e55a17492e354 Mon Sep 17 00:00:00 2001 From: Jules Nsenda Date: Tue, 29 Sep 2026 14:32:42 +0200 Subject: [PATCH] docs: document the refund limitation and 3.1.0's remaining race residual Neither was documented anywhere public before this: a verified, registered payment has no Credit Memo path through Magento (canRefund() is false; refunds go through Paystack's dashboard directly) -- a pre-existing gap, not introduced by 3.1.0, but newly relevant now that orders show a real invoice/total_paid a merchant will expect to be able to refund. And 3.1.0's reference binding closes the sequential "one charge settles two orders" case but not a same-instant race between two verifications for a not-yet-bound reference -- recorded in CHANGELOG's Known Limitations at the same restrained, no-exploit-detail level as the existing D9 entry. Co-Authored-By: Claude Sonnet 5 --- CHANGELOG.md | 10 ++++++++++ marketplace/src/user-guide.md | 6 ++++++ 2 files changed, 16 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 2337f1d..61490b1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -133,6 +133,16 @@ what was requested. D9/R2.8) — not fixed by this settlement-gate work, which only changed the webhook's *retry* semantics (transient vs. permanent), not its order-lookup logic. +- The reference-to-order binding introduced above closes the *sequential* + version of "one charge settles two orders" but is a read-then-write check + with no lock: two verifications racing at the exact same instant, for a + reference not yet bound to anything, can still both pass the check before + either saves. Reference-keyed locking (tracked as a corrected R2.4) is not + implemented in this release. +- A verified, registered payment is not refundable through Magento's own + Credit Memo action — refunds must be issued directly from the Paystack + dashboard. This is a pre-existing gap, not introduced by this release; see + the User Guide's Refunds section. ### Upgrade note If a store's checkout was relying (unknowingly) on under- or mis-paid diff --git a/marketplace/src/user-guide.md b/marketplace/src/user-guide.md index 6555f1d..a72b0a3 100644 --- a/marketplace/src/user-guide.md +++ b/marketplace/src/user-guide.md @@ -76,6 +76,12 @@ Holding the confirmation email until payment is verified means customers are nev If verification does not complete — the customer closed the browser, or the network dropped — the webhook confirms the payment independently and moves the order forward. +## Refunds + +A verified order shows its payment on the order (paid amount, invoice, transaction reference), but Magento's own **Credit Memo** / refund action is not available for Paystack orders — the extension does not submit refunds back through Magento. + +To refund a customer, issue the refund directly from your Paystack dashboard (or via Paystack's API). The Magento order itself is not updated automatically when you do this; add an order comment noting the refund if you want it visible on the order in Magento. + ## Troubleshooting **Paystack does not appear at checkout.** Confirm **Enabled** is *Yes*, that both the public and secret key are filled in for the current mode, and that the order total falls between your configured minimum and maximum. Then run `php bin/magento cache:flush`.