HTTP endpoints & webhooks

For developers

The plugin adds four storefront routes and one Admin API route. None of them is a general-purpose integration API; they exist for Paystack's webhooks, the storefront account page and the Administration refund tab.

POST /paystack/webhook

Receives Paystack webhooks. Register this URL in the Paystack dashboard.

Scope	Storefront (no Shopware authentication)
Authentication	x-paystack-signature header: hex(HMAC-SHA512(raw body, secret key))
Handled events	charge.success, refund.pending, refund.processed

Status	When
204 No Content	Signature valid and event handled — or an unhandled event type, which is logged and ignored
400 Bad Request	Body is not JSON with event and data
403 Forbidden	Missing or invalid signature, or no secret key configured
500 Internal Server Error	Processing threw; Paystack retries

Example (test delivery):

BODY='{"event":"charge.success","data":{"reference":"T123456789"}}'
SIG=$(printf '%s' "$BODY" | openssl dgst -sha512 -hmac "$PAYSTACK_TEST_SECRET" | sed 's/^.* //')
curl -i https://shop.example.com/paystack/webhook \
  -H "Content-Type: application/json" -H "x-paystack-signature: $SIG" -d "$BODY"

The plugin always re-verifies charge.success against the Paystack API before marking anything paid, so a forged-but-signed body cannot pay an order for a different amount.

POST /api/_action/paystack/refund

Creates a refund at Paystack. Used by the order's Paystack tab.

Scope	Admin API — Bearer token of an Administration user or integration
Permission	paystack.refund

Request body:

Field	Required	Description
transaction	yes	The Paystack reference (paystack_reference) of the order transaction
amount	no	Amount in the order currency's major unit (e.g. 2500.50). Omit for a full refund — the plugin's minimum and maximum checks then don't run and Paystack applies its own default (the full transaction amount).
reason	no	Defaults to Refund initiated from shop administration
customer_note	no	Passed to Paystack
merchant_note	no	Passed to Paystack

curl -X POST https://shop.example.com/api/_action/paystack/refund \
  -H "Authorization: Bearer $ADMIN_TOKEN" -H "Content-Type: application/json" \
  -d '{"transaction":"T123456789","amount":"1500.00","customer_note":"Returned item"}'

Responses:

• 200 — Paystack's JSON response for the created refund.
• 400 — {"error": "<message>"}. Messages include: Transaction reference is required, Refundable transaction not found for the provided reference, Transaction is not in a refundable state (only paid, partially paid and partially refunded transactions can be refunded), Refund feature is currently disabled, Refund amount must be a positive number, Unable to resolve the order currency for this transaction, Refund amount must be at least …, Refund amount exceeds the refundable balance of …, or Paystack's own error.
• 403 — missing permission.

Storefront bank-details routes

Available only when Enable Bank Data Collection is on for the sales channel (404 otherwise) and only to logged-in customers.

Method & path	Purpose	Notes
GET /paystack/bank/list	Bank list from Paystack's GET /bank	XHR only; returns Paystack's response
POST /paystack/bank/verify	Resolve an account via Paystack's GET /bank/resolve	XHR only; body account_number, bank_code; 400 on failed resolution
POST /paystack/bank/save	Validate and save the bank details to the customer	Form post; redirects to the profile page with a flash message