setono / sylius-quickpay-plugin
Quickpay payment plugin for Sylius
Package info
github.com/Setono/SyliusQuickpayPlugin
Type:sylius-plugin
pkg:composer/setono/sylius-quickpay-plugin
Fund package maintenance!
Requires
- php: >=8.1
- composer-runtime-api: ^2.0
- ext-json: *
- cuyz/valinor: ^2.2.2
- doctrine/orm: ^2.13
- doctrine/persistence: ^2.0 || ^3.0
- payum/payum: ^1.6
- payum/payum-bundle: ^2.5 !=2.7.0
- psr/cache: ^2.0 || ^3.0
- psr/log: ^1.1 || ^2.0 || ^3.0
- setono/doctrine-orm-trait: ^1.4
- setono/payum-quickpay: ^2.0.0-rc.4
- setono/quickpay-php-sdk: ^1.4
- sylius/core: ^1.0
- sylius/core-bundle: ^1.0
- sylius/locale: ^1.0
- sylius/mailer-bundle: ^1.8 || ^2.0
- sylius/order: ^1.0
- sylius/payment: ^1.0
- sylius/payum-bundle: ^1.0
- sylius/resource-bundle: ^1.10
- sylius/state-machine-abstraction: ^1.0
- symfony/config: ^6.4
- symfony/console: ^6.4
- symfony/dependency-injection: ^6.4
- symfony/event-dispatcher: ^6.4
- symfony/form: ^6.4
- symfony/http-client: ^6.4
- symfony/http-client-contracts: ^3.0
- symfony/http-foundation: ^6.4
- symfony/http-kernel: ^6.4
- symfony/intl: ^6.4
- symfony/lock: ^6.4
- symfony/routing: ^6.4
- symfony/security-csrf: ^6.4
- symfony/validator: ^6.4
- symfony/workflow: ^6.4
- twig/twig: ^2.15 || ^3.0
- webmozart/assert: ^1.11
- winzou/state-machine: ^0.3 || ^0.4
Requires (Dev)
- api-platform/core: ^2.7.16
- babdev/pagerfanta-bundle: ^3.8
- behat/behat: ^3.14
- dama/doctrine-test-bundle: ^8.0
- doctrine/doctrine-bundle: ^2.11
- jms/serializer-bundle: ^4.2
- lexik/jwt-authentication-bundle: ^2.17
- matthiasnoback/symfony-config-test: ^5.1
- nyholm/psr7: ^1.8
- setono/sylius-plugin-pack: ~1.14.1
- shipmonk/composer-dependency-analyser: ^1.6
- sylius-labs/polyfill-symfony-security: ^1.1.2
- symfony/debug-bundle: ^6.4
- symfony/dotenv: ^6.4
- symfony/property-info: ^6.4
- symfony/serializer: ^6.4
- symfony/translation: ^6.4.3
- symfony/web-profiler-bundle: ^6.4
- symfony/webpack-encore-bundle: ^1.17.2
- willdurand/negotiation: ^3.1
Suggests
None
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-19 07:48:31 UTC
README
Adds Quickpay as a payment gateway to your Sylius store. The plugin integrates the
setono/payum-quickpay Payum gateway into Sylius' checkout,
state machine, and admin.
Requirements
- PHP 8.1 or higher
- Sylius 1.x on Symfony ^6.4 (tested against Sylius 1.14)
- PSR-17 factories discoverable by
php-http/discovery(e.g.nyholm/psr7) — the plugin itself bringssymfony/http-clientas its PSR-18 client
Installation
1. Install the plugin
The plugin 2.x line and the setono/payum-quickpay gateway it builds on are still in pre-release,
so your project must allow the pre-release versions explicitly:
composer require setono/sylius-quickpay-plugin:^2.0@beta setono/payum-quickpay:^2.0@RC setono/quickpay-php-sdk:^1.4
If your project does not already provide PSR-17 factories:
composer require nyholm/psr7
2. Register the bundle
<?php # config/bundles.php return [ // ... Setono\SyliusQuickpayPlugin\SetonoSyliusQuickpayPlugin::class => ['all' => true], ];
3. Configure the plugin (optional)
The state machine callback that captures, refunds, and cancels Quickpay payments when the corresponding Sylius payment transitions are applied (see How it works) is registered automatically. Each operation can be turned off individually:
# config/packages/setono_sylius_quickpay.yaml setono_sylius_quickpay: operations: capture: true # forward the payment's complete transition to Quickpay as a capture refund: true # forward the refund transition to Quickpay cancel: true # forward the cancel transition to Quickpay fraud: block_capture: false # skip the automatic capture when Quickpay reports the payment as fraud suspected (see Fraud signals)
The plugin hooks into both state machine adapters supported by Sylius 1.14 — a winzou_state_machine
callback (the default adapter) and a Symfony workflow event subscriber — so the operations are forwarded to
Quickpay no matter which adapter your application runs the sylius_payment graph on.
4. Import the routes
# config/routes/setono_sylius_quickpay.yaml setono_sylius_quickpay: resource: "@SetonoSyliusQuickpayPlugin/Resources/config/routes.yaml"
This registers the callback endpoint (POST /payment/quickpay/notify) that receives the callbacks of operations
made outside your store — in the Quickpay manager, or by anything else talking to the API. Everything the store
itself does is confirmed without configuration; see Callbacks.
5. Install the assets
bin/console assets:install
The plugin ships the payment method logos shown on the checkout (see
Payment method logos on the checkout); like every bundle asset they are
published to public/bundles/setonosyliusquickpayplugin/ by assets:install.
6. Import fixtures (optional, development only)
# config/packages/setono_sylius_quickpay.yaml imports: - { resource: "@SetonoSyliusQuickpayPlugin/Resources/config/app/fixtures.yaml" }
The fixtures create a Quickpay credit card payment method and matching channels. They read the gateway credentials from these environment variables:
QUICKPAY_API_KEY= QUICKPAY_PRIVATE_KEY= QUICKPAY_AGREEMENT_ID= QUICKPAY_ORDER_PREFIX=qp_
Configuration
Create a new payment method of type Quickpay in the admin panel (Configuration → Payment methods) and fill out the gateway configuration:
| Field | Description |
|---|---|
| Api key | The API key of the API user in your Quickpay manager (Settings → Users) |
| Private key | The private key of your merchant account (Settings → Integration) |
| Agreement id | (optional) Which agreement the payment window runs on. Leave empty to use your account's default Payment Window agreement — set it only if your account has several agreements and the window should use a specific one |
| Order prefix | Prepended to order numbers sent to Quickpay as the order_id — must be unique per project and environment sharing the same Quickpay account (see Troubleshooting). Letters, digits, spaces, ., _ and - only, and the order_id — prefix and order number together — at most 20 characters: with Sylius' default 9-digit order numbers, a prefix of 11 characters or less. Saving checks it against your latest order's number |
| Payment methods | Which payment methods the Quickpay payment window offers, e.g. creditcard or mobilepay — see the Quickpay documentation |
| Capture mode | When the money is taken. On completion (default) only authorizes the payment at checkout and captures it when the payment is completed in Sylius (e.g. when the order is shipped) — what shops that may not capture before dispatch need. Immediately lets Quickpay capture the moment the card is authorized — useful for digital products |
| Synchronized operations | Run capture, refund and cancel synchronously instead of relying on the Quickpay callback |
| Branding id | (optional) The payment window branding to use |
When you save the payment method, in the admin or through the Admin API, the plugin refuses a gateway configuration
the gateway would reject (a missing api or private key, a branding name where the branding id belongs, an agreement
id of 0, ...), with an error on each field to fix. Once the configuration is valid, it verifies the API key against
Quickpay's API and refuses the key if Quickpay rejects it — a typo'd key is caught immediately instead of by the first
customer whose checkout fails. A valid key whose API user lacks the /ping permission is verified through a
/payments read instead, so a locked-down API user never blocks saving; neither does an unreachable
Quickpay — the check fails open on anything but an explicit rejection, and logs at info level why the key couldn't be
verified. With the API key accepted, an Agreement id is looked up on the account as well, and refused if Quickpay
doesn't find it. Quickpay accepts a payment link with an agreement id it doesn't know, so without this check the mistake
only shows when a customer's payment window fails to open. The lookup needs the API user's permission to read
agreements (GET /agreements/:id); grant it, or the check can't tell. It fails open the same way as the API key: an
API user without the /agreements permission, or an unreachable Quickpay, never blocks saving, and why the agreement
couldn't be checked is logged at info level (the doctor prints it as a warning). Fixtures, the console and writes straight to the database skip
this validation.
Encrypting gateway configurations is not supported. Don't switch on PayumBundle's encryption of stored gateway
configurations (payum.dynamic_gateways.encryption.defuse_secret_key) in a store that uses this plugin. Only Payum's
own storage and Sylius' admin form decrypt a configuration, so the plugin finds none where it reads one and treats
that as an error: the shared callback endpoint, for one, answers every callback with a 500 until encryption is
switched off. Sylius core itself also reads the capture mode (use_authorize) before Payum decrypts the
configuration, so its checkout would capture immediately whatever the payment method's capture mode says.
How it works
-
During checkout the customer is redirected to the Quickpay payment window through a payment link. What happens to the money is the payment method's capture mode: on completion (the default) only authorizes the payment and the plugin captures it when the payment is completed in Sylius; immediately has Quickpay capture the moment the card is authorized. Under the hood the mode is Sylius core's
use_authorizegateway option — the plugin runs Payum'sAuthorizeorCaptureaccordingly, which is how the gateway library expresses the two flows since 2.0. -
When checkout creates the Quickpay payment, the plugin describes the order to Quickpay: the invoice and shipping addresses, the basket with each line's VAT rate, shipping, and the plugin and its version as the shop system. The Quickpay manager shows them on the payment, and they never change what is charged, but some payment methods check them: Klarna rejects a payment whose basket and shipping don't add up to its amount, and Resurs requires a basket. So the basket and shipping add up to the order total:
- each basket line is priced per unit with its VAT, whether your channel includes the tax in its prices or adds it on top, and an item whose units cost different amounts after promotions (an order promotion's odd cents) gets a line per price;
- an adjustment outside the units and shipping, such as a payment fee or a gift card a plugin puts on the order, is
a line of its own, named by its label, with the VAT rate stored in its details (
taxRateAmount), else 0.
They can't add up when the payment is for another amount than the order total (a plugin's partial payments, or Quickpay's auto fee added in the payment window), or when Sylius clamps a total that adjustments made negative at 0. Whatever the order lacks, such as a shipping address, is left out. A customer paying the same order again after a declined attempt continues on the Quickpay payment created the first time, which keeps what it was told then. To change what Quickpay is told, decorate
Setono\SyliusQuickpayPlugin\OrderDescription\OrderDescriberInterface, orSetono\SyliusQuickpayPlugin\Taxation\VatRateResolverInterfacefor the VAT rates (forAdjustment()for an adjustment's line, e.g. a fee that carries VAT). -
Quickpay notifies your store of payment changes through callbacks on a per-payment url the gateway mints — for the payment window's outcome and for every capture, refund and cancel the store issues (the gateway names that url on each operation). Only operations made outside the store need the account-wide callback url (see Callbacks). Every callback's
Quickpay-Checksum-SHA256header is validated against your private key before anything about the payment changes. A genuine callback then reconciles the payment: Sylius applies the state change its own mapping gives for the Quickpay payment's status (authorized, completed, refunded, ...), at most once. -
When you complete, refund, or cancel a payment in the Sylius admin, the plugin performs the matching capture, refund, or cancel operation against Quickpay. A failed cancel at Quickpay (e.g. the customer never completed checkout, so there is nothing to cancel) is logged but does not block cancelling the order, and neither does Quickpay being unreachable. Cancelling aborts, with no cancel sent to Quickpay, where Quickpay holds money: when it holds the payment's captured money (captured at checkout, in the Quickpay manager, or by a capture whose callback never arrived) or an operation, such as a capture, is still in flight. A cancelled payment can't be refunded in Sylius, so cancelling it would leave the customer's money at Quickpay. Cancelling such an order in the admin or the Admin API fails with an error naming the Quickpay payment and saves nothing, and
sylius:cancel-unpaid-ordersstops at it on every run (see Troubleshooting for both and how to recover). Completing captures only a payment Quickpay holds an authorization for: completing one the customer never paid, or whose authorization was declined, fails with an error naming the payment and the state Quickpay's status maps to, and nothing is sent to Quickpay. An operation turned off in the plugin config leaves Quickpay alone: its transition is applied without contacting Quickpay. -
A payment is a Quickpay payment only while its payment method is a Quickpay one. A customer who opened the Quickpay window and then switched the order to another payment method, such as bank transfer, leaves a payment Sylius keeps, Quickpay details included; the plugin leaves it to that method: completing, refunding or cancelling it contacts no one, and the admin shows no Quickpay panel for it (see Troubleshooting).
-
A refund targets Quickpay's balance (what is still captured) rather than the original amount — so a payment that was partially refunded directly in the Quickpay manager refunds only the remainder instead of failing. The balance is also persisted into the payment details whenever a callback or the reconciliation command reconciles the payment, also when its state doesn't change. An explicit
refund_amount/capture_amountin the payment details is passed through to Quickpay untouched for programmatic partial operations; note that Sylius' payment state machine still treats the payment as a whole — therefundtransition can only be applied once.
Payment method logos on the checkout
On the checkout payment step, each Quickpay payment method shows the brands its payment window will offer — derived
from the gateway configuration's Payment methods field, so nothing is configured twice and no API is called.
creditcard, mobilepay renders the Visa and Mastercard marks (what creditcard stands for is configurable) and the
MobilePay mark; a token without a bundled logo (e.g. resurs) renders as a small text label. Quickpay's token
grammar is understood: exclusions (!diners) are skipped, forced 3-D Secure (3d-creditcard) is ignored, and
regional/debit variants (visa-dk, mastercard-debet-dk, mobilepay-subscriptions) collapse onto their brand.
The field is read the way the gateway reads it, so payment_methods stored as a list (by fixtures or the Admin API)
gets logos too. A payment method whose gateway configuration is unusable shows no logos and a warning is logged; the
checkout keeps working.
Bundled logos cover cards (Visa, Visa Electron, Mastercard, Maestro, American Express, Diners Club, Discover, JCB, UnionPay, Dankort, Forbrugsforeningen) and MobilePay, Apple Pay, Google Pay, Klarna, Anyday, Vipps, Swish, PayPal, ViaBill, Trustly, iDEAL, Sofort and paysafecard. They come from Shopify's MIT-licensed payment_icons; the marks remain their owners' trademarks and are shown only to indicate acceptance.
To use your own images, add or override a token, or hide one, configure the plugin — the value is an asset path (or
URL) as asset() understands it, or null to hide the token:
setono_sylius_quickpay: checkout: payment_method_logos: mobilepay: build/images/mobilepay.svg resurs: https://cdn.example.com/resurs.png apple-pay: ~ creditcard_brands: [dankort, visa, mastercard] # what the `creditcard` token shows; default [visa, mastercard]
The markup lives in @SetonoSyliusQuickpayPlugin/shop/checkout/select_payment/_payment_method_logos.html.twig (a
sylius_ui block on sylius.shop.checkout.select_payment.choice_item_content) and can be overridden like any bundle
template.
Payment link in the admin
Every Quickpay payment that is still awaiting payment shows a Payment link panel on the admin order view: a copy-able link, and a button that emails it to the customer. Use it to collect payment for a phone or invoice order, or after a customer abandoned the checkout — anyone opening the link is taken through the normal flow into the Quickpay payment window, and the payment resolves exactly as after checkout.
The link is Sylius' own "pay for this order" url (sylius_shop_order_pay), built for the order's channel hostname:
nothing happens at Quickpay until the customer clicks, so it can be shown, copied and sent as often as needed, and it
also works for a payment whose Quickpay payment was never created (the flow creates it on first use). It is offered for
the order's last payment in state new on a Quickpay method, as long as the order is not cancelled — the same payment
Sylius' own "Pay" button in the customer account pays.
The email (@SetonoSyliusQuickpayPlugin/email/payment_link.html.twig, code setono_sylius_quickpay_payment_link)
is sent in the order's locale through Sylius' mailer and can be overridden like any Sylius email template.
Operation history in the admin
Each Quickpay payment on the admin order view (one whose payment method is a Quickpay one and that got as far as the payment window) shows its live operation history — every authorize/capture/refund/cancel with amount, Quickpay status code and message, and timestamp, plus the captured balance and a test-mode badge. Each operation also shows its callback outcome, as Quickpay records it: not sent yet, the status code the store answered with (green when Quickpay counted it a success, red when not) or no answer at all, with the time, and the url the callback went to as a tooltip, so you can tell the payment's own callback url from the account-wide one. A hint under the table explains the codes the plugin answers with: 204 reconciled, or no payment of the store's to reconcile (an order prefix changed since, say, or a payment switched to another payment method; logged as a warning), 409 the payment was already being reconciled and 5xx an error (Quickpay retries both), 400 a wrong checksum. So "did the callback arrive, and what did the store do with it?" needs no log dive. The data is fetched from Quickpay after the page has rendered, so the order page is never delayed by a slow gateway; if Quickpay cannot be reached, or the payment method's gateway configuration is unusable, the panel shows an inline notice with a retry link, and the cause is logged as a warning with the payment id and the gateway name. Nothing is stored — the panel reflects what Quickpay reports right now.
Fraud signals
Quickpay flags payments it suspects of fraud, and the plugin surfaces that in three places:
- A Fraud suspected badge on the admin operation history panel, next to the test-mode badge.
- An opt-in capture guard: with
fraud.block_capture: true(see Configure the plugin), the automatic capture on the payment'scompletetransition is skipped when Quickpay reports the payment as fraud suspected — the completion itself is not blocked; the payment is logged and left for manual review, so you capture or cancel it in the Quickpay manager after looking at it. The check asks Quickpay at capture time and fails open: an unreachable Quickpay, or an unusable gateway configuration, never blocks the payment flow. It costs one extra API call per automatic capture, which is why it is off by default. - A report mode on the reconciliation command that asks Quickpay for every payment flagged in the period, whatever the state of its Sylius payment — report only, nothing is transitioned. A gateway it can't query, because Quickpay fails or its gateway configuration is unusable, is reported by name and makes the run exit non-zero:
bin/console setono:sylius-quickpay:reconcile-payments --fraud-suspected --since="7 days"
--since (default 7 days) is the period the payments were created in. Without --limit, every flagged payment is
reported; --limit caps the payments reported across all gateways. A report that reaches it says so and names the
gateways it didn't query; raise --limit to see the rest.
Callbacks
All callbacks for what your store does arrive on a per-payment url the gateway mints and registers itself —
the payment window's outcome on the payment link's callback url, and capture/refund/cancel confirmations via the
QuickPay-Callback-Url header the gateway sends on every operation it issues. Payum checks the url's token and
the plugin handles the callback; none of it needs configuration.
The account-wide callback url of your Quickpay account (Settings → Integration → Callback url, empty by default) is only consulted for operations made outside the store — a refund clicked in the Quickpay manager, a capture issued by another system talking to the API. If you make those, point the account-wide url at the plugin's endpoint:
https://your-shop.example/payment/quickpay/notify
That endpoint resolves the payment from the callback body (order_id → your order prefix → the Sylius payment)
precisely because one static url cannot carry a Payum token. It reads the order number under the order prefix of every
Quickpay payment method, and tries each until an order holds the callback's Quickpay payment. When none does, as for a
payment made under an order prefix you have since changed, it answers 204 (retrying can't help) and logs a warning
naming the order_id and the Quickpay payment id: that payment is left to you. A payment switched to another payment
method since (see Troubleshooting) is no Quickpay payment any more, so it never matches either;
its own callback url answers a callback about it the same way. While one of the payment methods has a
gateway configuration the gateway can't be built from (written by fixtures, the Admin API or the database directly),
it answers every callback with a 500 and Quickpay retries it once that is fixed.
A Quickpay account has exactly one such url, so when
several environments share an account, only the one it points at receives those callbacks. Quickpay retries
undelivered callbacks 24 times with backoff.
Without those callbacks, in a store that leaves the account-wide url empty or an environment it doesn't point at, the reconciliation command still reconciles a capture or cancel of an authorized payment made outside the store, but not a refund of a paid order: it reconciles only pending payments. A full refund made in the Quickpay manager on a paid order then never reaches that store, and the order stays paid in Sylius. Refund the payment in Sylius yourself to bring the order in line: the plugin first asks Quickpay for the Quickpay payment's status, sees it refunded already, and sends no second refund.
Deliveries can race: Quickpay retries a callback it considers undelivered, and a retry can arrive while the
original is still being handled. Two operations in quick succession, such as the authorization and the capture under
the capture mode "immediately", also send two callbacks moments apart. Both callback urls reconcile the payment under
a per-payment lock, held until the state change is applied and saved. A callback arriving while the lock is held runs
nothing, so nothing is applied twice, and is answered 409 Conflict: it may report an operation that happened after
the callback holding the lock read the payment, so Quickpay retries it, and the retry reconciles the payment from a
fresh read once the lock is released. A retried duplicate finds the payment in step and changes nothing. A 409 in
Quickpay's callback history is this race, not an error. The lock is taken before the callback's signature is
checked, so a forged callback arriving while the payment's lock is held is answered 409 as well; it runs nothing and
changes nothing. A callback whose handling fails (Quickpay unreachable, a
state-machine callback throwing) saves nothing, not even a state change that was halfway applied, and is answered
with an error, so Quickpay's retry finds the payment as it was. The
reconciliation command takes the same lock, so a callback and the command never
reconcile a payment at the same time. The lock is a regular Symfony lock:
the plugin registers a named framework.lock resource, setono_sylius_quickpay, defaulting to the flock store,
which locks per server. If your shop runs on several servers, redefine the resource with a shared store, or two
servers can each handle one of a pair of duplicate callbacks:
# config/packages/lock.yaml framework: lock: setono_sylius_quickpay: '%env(LOCK_DSN)%' # e.g. LOCK_DSN=redis://localhost
Reconciling missed callbacks
Callbacks are normally how your store learns about a payment state change. If one never arrives — the store was unreachable until Quickpay gave up retrying, or a capture or cancel was made outside the store and the account-wide callback url points elsewhere (see Callbacks) — the payment stays stuck and the order never completes. The plugin ships a reconciliation command that closes this gap for pending payments (below): each run asks Quickpay which payments changed since the previous run, and reconciles those still pending in your store with their Quickpay payments:
bin/console setono:sylius-quickpay:reconcile-payments # the payments Quickpay changed since the last run bin/console setono:sylius-quickpay:reconcile-payments --full # every payment Quickpay changed in the last 7 days bin/console setono:sylius-quickpay:reconcile-payments --dry-run # report only, change nothing
A pending payment is a payment of a Quickpay payment method in state new, processing or authorized that has a Quickpay payment, however old it is. A run lists the payments Quickpay changed once per Quickpay account (each distinct api key among your Quickpay payment methods, however many payment methods share it) and reconciles the pending ones among them: the stuck ones (new, processing) first, then the authorized ones, each oldest first. A payment Quickpay hasn't changed costs no request, so a run sends a list request per account (one per page of a long list) and one request per payment it reconciles. A capture or cancel made in the Quickpay manager is reconciled by the next run however old the payment is.
Only pending payments are reconciled, so a refund made in the Quickpay manager on a paid order (a completed payment) never is: only a callback on the account-wide callback url reconciles it, and Callbacks says what to do without one. Completed payments are left out on purpose: a run reads through the pending payments in your database to find the ones Quickpay changed, and reading through the completed ones too would mean every paid order your store ever took, on every run.
Each run first says, per account, which changes it lists:
Gateway(s) "quickpay": the payments Quickpay changed since 2026-11-16 10:25 (since the last run)
(since the last run): since the previous run started, less 5 minutes in case Quickpay's clock and yours differ.(no earlier run: the last 7 days): the account has no earlier run on record — the first run, a new api key, an emptied cache — so the run looks back--since(default7 days).(the last run was more than 7 days ago: the last 7 days): the account's last run was longer ago than--since, so the run looks back--sinceonly.(--full: the last 7 days):--fullignores the earlier run and looks back--since, e.g. after you restored a database backup. It only applies to reconciling: with--fraud-suspectedthe command stops with an error.
--since is only this fallback; it doesn't limit how old a payment may be. After the command hasn't run for longer
than --since, run it once with a --since covering the gap. --limit only applies to the
fraud report: a reconciling run reconciles every pending payment Quickpay changed, and given
--limit it stops with an error.
Each pending payment is reconciled: the command fetches its status from Quickpay and Sylius applies the state change its own mapping gives, exactly the change the callback would have made (a pending Quickpay payment, for example, moves a new payment to processing). Each payment is saved as soon as it is reconciled, and every payment that changed is listed with its state before and after and the state Sylius maps its Quickpay payment's status to:
Payment 42: "new" -> "authorized" (Quickpay → "authorized")
Payment 43: skipped, a callback is reconciling it
[OK] 3 checked, 1 transitioned, 1 unchanged, 1 skipped, 0 errored
The command takes the same per-payment lock as the callbacks: a payment whose callback is being handled at that moment is skipped and reported as such. A payment counted as unchanged kept its state; the payment details refreshed from Quickpay, such as its balance, are still saved. A payment that fails (Quickpay unreachable, a state-machine callback throwing, say Sylius failing to sell the order's inventory) is reported and counted, and nothing of it is saved, not even a state change that was halfway applied; the run goes on with the next payment. When the database fails to save a payment, Doctrine closes its entity manager and the rest of that run is reported as errored too; nothing of those payments is saved either.
A payment that failed or was skipped is retried by every later run until it reconciles or is no longer pending,
whether or not Quickpay changes it again. A run with payments to retry says how many (2 payment(s) to retry), and a
payment that fails again says since when it has been failing:
[WARNING] Payment 44: Quickpay is down (failing since 2026-11-16 10:25)
An account whose changes can't be listed, because Quickpay fails or a gateway configuration is unusable, is reported
(Gateway(s) "quickpay": could not list the payments Quickpay changed: …) and fails the run. Its changes are listed
again by the next run, while the other accounts carry on.
--dry-run only reads: it reports each payment's state, the transition that would be applied (or no transition)
and the state the Quickpay payment's status maps to, and changes nothing — no state, no state-machine callbacks, no
database writes, and no record of the run, so the next run lists the same changes. It is safe against a production
shop:
Payment 42: "new", would apply "authorize" (Quickpay → "authorized")
One run at a time. A run started while another is reconciling payments prints
Another run is reconciling payments; skipped. and exits 0, so overlapping cron runs neither send the same requests
twice nor alert your monitoring. The lock is in the plugin's lock resource setono_sylius_quickpay (see
Callbacks): if your shop runs the command on several servers, redefine the resource with a shared store
to keep their runs apart. A run that dies holding the lock doesn't block the next ones for long: a flock lock is
released with the process, and a lock in a shared store expires within 5 minutes. --dry-run and --fraud-suspected
take no lock, so they run alongside a run that reconciles.
Where a run keeps what the next one starts from
Each account's last run and the payments to retry are kept together, in one item of a cache pool,
setono_sylius_quickpay.reconcile, on your application cache (cache.app) by default. An account is stored under a
hash of its api key, never the key itself.
Symfony's default cache.app is a filesystem cache in the cache directory, which cache:clear and a deploy into a
fresh directory empty. The next run then lists the whole --since period again, as a first run does. Point the pool
at a persistent adapter, under the same name in your framework configuration, to avoid that:
# config/packages/cache.yaml framework: cache: pools: setono_sylius_quickpay.reconcile: adapter: cache.adapter.redis provider: '%env(REDIS_URL)%' # e.g. REDIS_URL=redis://localhost
Should the cache refuse to save it, full or unreachable, the run warns
Could not save the reconcile state; the next run lists the changes since the previous one again. and exits non-zero.
Nothing is lost: the next run starts from what the run before it saved, and lists those changes again.
Scheduling
Scheduling is your application's choice; a cron entry along these lines is plenty:
*/30 * * * * /usr/bin/php /path/to/shop/bin/console setono:sylius-quickpay:reconcile-payments >> /var/log/quickpay-reconcile.log 2>&1
A run reads only what changed, so running it more often costs little more than a list request per account, and a missed callback is fixed sooner. The command exits non-zero when a payment couldn't be reconciled, an account's changes couldn't be listed or what the next run starts from couldn't be saved, so cron mail or your monitoring will surface persistent problems; a run skipped because another one is going exits 0.
HTTP policy
Every request to Quickpay, the gateway's (checkout, capture, refund, cancel, callbacks, reconciling) and the plugin's
own (the fraud check, the operation history, listing the payments Quickpay changed, the fraud report, the doctor,
checking the api key and agreement on save), goes through one
scoped HTTP client that the plugin adds to your
framework configuration: setono_sylius_quickpay.http_client. Its defaults:
| Option | Default | |
|---|---|---|
base_uri |
https://api.quickpay.net |
|
timeout |
10 |
seconds a request may wait for Quickpay without receiving anything |
max_duration |
10 |
seconds a request may take in total |
retry_failed |
off | no request is retried |
So a slow Quickpay can't hang checkout, the admin or a callback for more than 10 seconds per request, and the requests show up in the Symfony profiler. Override any option under the same name in your own framework configuration; the others keep the plugin's defaults. A proxy or extra headers go here too:
# config/packages/framework.yaml framework: http_client: scoped_clients: setono_sylius_quickpay.http_client: timeout: 5 max_duration: 15 proxy: 'http://proxy.example.com:3128'
Mind the reconcile lock when you raise the timeouts: a callback makes up to four requests in a row while it holds its payment's lock, which expires after 60 seconds.
Retries are off on purpose. Symfony's retry_failed also retries POST requests on some statuses (423, 425,
429, 502 and 503), and a retried capture or refund can take or return the money twice. If you enable retries, limit
them to reads:
framework: http_client: scoped_clients: setono_sylius_quickpay.http_client: retry_failed: max_retries: 1 http_codes: 0: [GET] # no response at all, a timeout included 429: [GET] 500: [GET] 502: [GET] 503: [GET] 504: [GET]
Each retry waits up to the full timeouts again, so keep max_retries low with the lock in mind.
Mind app-wide retries. Your framework.http_client.default_options.retry_failed doesn't reach the plugin's client
by itself: Symfony copies it onto a scoped client only when the same framework: block configures that scoped client
too (the same file, and the same when@<env> section if it is in one), and only when it is given as settings rather
than just true. So configuring setono_sylius_quickpay.http_client in the file that sets your app-wide retries, as in
the examples above, turns them on for Quickpay, for POST requests too unless their http_codes say otherwise. Give
the plugin's client a retry_failed of its own there: false, or the reads-only settings above. Include http_codes
in it, because any setting it leaves out is taken from the app-wide one.
Testing
composer phpunit # unit and functional tests (the functional suite needs the test application's database) composer analyse # static analysis (PHPStan) composer check-style # coding standards
For manual testing, use the credit card numbers from the Quickpay test data.
Checking your configuration
The plugin ships a doctor that runs the checks otherwise surfacing as support cases — try it first when something misbehaves, and after every configuration change:
bin/console setono:sylius-quickpay:doctor # read-only bin/console setono:sylius-quickpay:doctor --live # also checks the payment link permission
For every configured Quickpay gateway it verifies the api key against Quickpay, self-tests the private
key's checksum computation, checks that a configured agreement id exists on the account, and checks that the
order_id the order prefix gives your latest order (Sylius' default first order number 000000001 while there are
no orders) is one Quickpay accepts, by payum-quickpay's own rule, so an order number format of your own counts too —
plus that the notify route is registered at all. With --live it also creates a money-less test payment and attempts the payment
link PUT the checkout depends on, catching a missing Create or update payment link permission before
a customer does (the test payment remains visible on the account, and the check's line names its id and order id; it
never carries money). The command
exits non-zero when any check fails, so it can run in CI or cron.
A check against Quickpay prints as passed (✔), failed (✖, failing the run) or, when Quickpay's answer proves neither (it didn't answer, answered with an error, or the API user may not ask), as a warning (!) saying why. The checks of an agreement id and of the payment link permission run only once Quickpay accepts the api key; without an agreement id there is nothing to ask, and Quickpay uses the account's default Payment Window agreement.
First, it reads each gateway configuration by the same rules the gateway is built from, so "All checks passed" means the gateway can be built:
- every gateway option the gateway would reject is a failed check of its own, e.g. a missing api key or private key,
an agreement or branding id that isn't a positive whole number, or a
synchronizedthat isn't a yes/no value. Only the checks against Quickpay are then skipped for that gateway, since their errors would only follow from these: theorder_idits order prefix gives your latest order is still checked; - an encrypted gateway configuration is a failed check saying encryption isn't supported (see Configuration);
- the agreement it looks up is the one the gateway sends: an empty agreement id means the account's default
agreement, and an agreement id stored under its 1.x name
agreementis used like the gateway uses it.
It also warns, without failing the run, about two things that work but surprise people:
- a gateway option still stored under its 1.x name (
apikey,privatekey,agreement), or the deprecatedauto_captureswitched on: re-save the payment method in the admin to replace them; - no capture mode stored (
use_authorize), as fixtures and the Admin API may leave it: checkout then captures immediately. Choose the capture mode on the payment method in the admin and save it.
Upgrading from 1.x
See UPGRADE-2.0.md for the full list of changes an upgrading store has to make — gateway configuration keys, removed imports, renamed routes and classes, the Klarna removal, and the behavioral changes around refunds and callbacks. Coming from an earlier 2.0 alpha, read its Upgrading from an earlier 2.0 alpha section.
Troubleshooting
Run the doctor first — it detects every configuration problem below.
-
Not authorized: Not authorized to PUT /payments/:id/linkat a/payment/authorize/...url:In the Quickpay manager, check under Settings → Users that the API user's User permissions have the
PUTcheckbox checked for Create or update payment link. Also make sure the Api key field of your payment method holds the API user's key (Settings → Users) — not the api key of a Payment Window agreement (Settings → Integration). -
This agreement doesn't exist on your Quickpay accountwhen saving a payment method, orAgreement 12345 does not exist on this Quickpay accountfrom the doctorThe payment method's Agreement id isn't an agreement of the Quickpay account its API key belongs to, so checkout can't create a payment link with it. Enter the id of one of the account's agreements (Settings → Integration in the Quickpay manager), or leave the field empty to use the account's default Payment Window agreement.
-
Validation error: order_id already exists on another paymentQuickpay requires the
order_idto be unique across everything sharing the account, and theorder_idis your order number with the payment method's Order prefix prepended. Change the prefix to a string unique per project and environment, short enough to leave room for your order numbers (11 characters with Sylius' default 9-digit numbers), e.g.<project initials><date>_such asab261116_, whenever:- you recreate a development database, so order numbers start over and collide with the ones already sent
to Quickpay — bump the
<date>part; - several projects or environments share the same Quickpay (developer) account credentials.
- you recreate a development database, so order numbers start over and collide with the ones already sent
to Quickpay — bump the
-
Validation error: order_id must have length between 4 and 20,The Quickpay order id "…" is not one Quickpay acceptsat checkout or from the doctor, or the payment method's Order prefix refused when savingThe
order_idis the Order prefix followed by the order number, and Quickpay accepts 4–20 letters, digits, spaces,.,_and-. Saving the payment method checks theorder_idyour latest order would get, and so does the doctor. Shorten the prefix (11 characters or less with Sylius' default 9-digit order numbers) or remove other characters from it. If your order numbers themselves hold other characters (a custom order number generator), no prefix helps: Quickpay refuses every suchorder_id. -
The callback of Quickpay payment … was not reconciled: its Sylius payment … is no longer paid with a Quickpay gatewayin the log, or a paid Quickpay payment for an order paid by bank transferThe customer opened the Quickpay payment window, then switched the order to another payment method (Sylius lets them on the order page while it awaits payment) and paid in the Quickpay window still open in another tab. The Sylius payment is the other method's now, so the plugin reconciles nothing for it, and the money the Quickpay payment holds is yours to handle in the Quickpay manager: cancel an authorization you don't want (unused, it expires by itself) or refund a capture. Completing, refunding or cancelling the Sylius payment in the admin leaves Quickpay alone.
-
The Sylius payment … can't be cancelled: Quickpay holds the captured money of its Quickpay payment …orA capture of Quickpay payment … is still pending(or a refund or cancel) when cancelling an order, orsylius:cancel-unpaid-ordersfailing with one of them on every runQuickpay holds the payment's captured money, or an operation on it, a capture say, hasn't settled yet, while Sylius still shows the payment unpaid: it was captured at checkout or in the Quickpay manager and its callback never arrived. A cancelled payment can't be refunded in Sylius, so cancelling the order aborts and saves nothing.
sylius:cancel-unpaid-ordersends the whole run at that order: nothing in its batch is saved, and every later run stops at the same order until its payment is reconciled. This takes a payment Quickpay captured that Sylius shows unpaid for the whole expiry period, which in practice happens only when the reconciliation command isn't scheduled.To recover, run the reconciliation command, with
--full --since <period>when the capture is older than its lookback. The payment becomes completed and the order paid, so the order is no longer an unpaid one. Then refund the payment in Sylius, and cancel the order if you still want to. For a capture still in flight, wait until it settles (its callback reconciles the payment) and cancel again, or recover as above once it is captured. -
The "branding_id" option must be a positive integer (or an integer string), got 'Our brand'from the doctor, or any otherThe "<option>" option ...failureThe gateway is built from that gateway configuration on every checkout, callback, capture, refund and reconcile, and it rejects the option, so each of them fails for that payment method. Open the payment method in the admin and correct the field named in the message: an agreement or branding id is the number from the Quickpay manager, not its name.
-
The gateway configuration of the Quickpay gateway "<gateway>" reads as empty, as an encrypted one doesfrom the doctorPayumBundle's encryption of gateway configurations is switched on, which this plugin doesn't support. Switch it off (see Configuration).
-
The gateway configuration uses a deprecated gateway option(a doctor warning)The payment method's gateway configuration still has a 1.x option name (
apikey,privatekey,agreement) orauto_captureswitched on. It works, but 3.0 stops reading them. Open the payment method in the admin and save it: that stores the current names, withauto_capturefolded into the capture mode. -
The capture mode is not set, so checkout captures immediately(a doctor warning)The gateway configuration has no
use_authorize, as fixtures and the Admin API can leave it, and Sylius' checkout then lets Quickpay capture the money at authorization. The admin form shows it as "Immediately". Open the payment method in the admin, choose the capture mode you want and save it: the mode is then stored, and the warning goes. -
Payment 42: skipped, a callback is reconciling itThe reconcile command found the payment's lock held: a callback for it was being handled at that moment (another run of the command can't hold it, since runs reconcile one at a time). Nothing was changed, and every later run retries the payment until it reconciles. A lock is never left behind for long: a
flocklock is released with the process holding it, and a lock in a shared store expires after 60 seconds.