SL-386 Fix orders lost when paying with a different card brand than selected

[TLabutis]

Problem

Saferpay Fields let the shopper type any card into a form that was opened for one specific brand. When the brands differed, return.php resolved the checkout flow from the brand Saferpay reported back rather than from how the payment was started, so the flow fell through to the redirect branch and createAndValidateOrder() was never called. The money was authorized at Saferpay, saferpay_order.authorized stayed 0 and the shopper sat on the waiting screen forever.

Reloading that page made it worse: postProcess asserted again, and under a business licence the assert posts Payment/v1/Transaction/Authorize, which is state-changing. Saferpay answered TRANSACTION_IN_WRONG_STATE and the order was marked failed.

What changed

The flow is resolved from how the payment was initialized. PaymentTypeProvider::getForReturn() keys off the field token and the saved-card flag instead of the returned brand. The real brand is still recorded as the order's payment label, it just no longer decides the flow.

The return page cannot process the same payment twice. SaferPayTransactionProcessedGuard short-circuits postProcess when saferpay_order is already authorized or captured, and the page redirects straight to the success controller instead of asserting again. The lock is skipped when the request is the Saferpay notification, so the hosted payment page leg is not blocked by its own return page.

The Fields form only accepts brands the merchant enabled. EnabledCardBrandsProvider filters the card brands through the existing payment restrictions, PaymentFormAssetLoader maps them to the SDK's lowercase names per payment option, and inline-fields.js passes them to SaferpayFields.init as paymentMethods. InitializeRequest sends the same list. A mismatched card is now refused at entry rather than at the end.

Checkout shows a single "Cards" option. Enabled by default for existing shops through the 2.1.0 upgrade. Supporting it meant teaching the rest of the checkout that PAYMENT_CARDS stands for several brands: restrictions resolve to whether any enabled brand passes country and currency checks, saved cards are looked up across every enabled brand and labelled with the brand they were stored under, and alias registration is no longer suppressed under grouping.

One "Use Saferpay Fields" setting replaces the per-brand toggles. With cards grouped, the per-brand "Saferpay Fields" column did nothing (grouping was read before the toggles), and a shop without a Fields access token got an unpayable Cards option because only the frontend JS checked the token. Following the official Saferpay plugins on Magento, Shopware and WooCommerce, card form rendering is now a single switch in Payment Processing, and PaymentTypeProvider::get() falls back to the Payment Page whenever the business licence, the setting or the access token is missing, on both the checkout and return legs. The back office shows a warning when Fields is on but the token is empty. The 2.1.0 upgrade derives the setting from the old toggles (Payment Page only when toggles exist and all are off) and generates missing access tokens from the stored API credentials, logging failures without failing the upgrade.

American Express joins FIELD_SUPPORTED_PAYMENT_METHODS.

Known limits

• V PAY and myOne have no SDK brand name. A shop that enables either gets an unrestricted Fields form, because a partial list would decline a card Saferpay itself accepts.
• An order paid through the grouped option carries CARD as its payment label, not the brand actually used. Quoted separately.
• The saferpay_field table, entity and creator stay in place; the payment methods refresh service still writes brand snapshots there. Removing the schema is out of scope.

Tests

64/64 unit tests pass. New coverage for PaymentTypeProvider (full decision tree incl. token fallback and test-mode suffix), EnabledCardBrandsProvider, CardAliasRegistrationGuard and the grouped-cards restriction path.

Manual verification on PS 8.2.3 against a live Saferpay TEST account: Fields mode (inline form, order authorized), switch off (checkout option becomes saferpayPaymentType=basic, redirect to the hosted payment page, order authorized), token-empty fallback (no dead form, redirect works, back office warning shown), and the upgrade path (setting derived from toggles, real token generated and idempotent on rerun). Earlier full verification of the card brand fix is in the PR comment below.

Changelog

Release notes for the fix and the Use Saferpay Fields setting added under the 2.1.0 release section.

[TLabutis]

Verification

Run on PrestaShop 8.2.3 against a live Saferpay TEST account (JSON API 1.50, business licence on). Five real authorizations, orders 15 to 18. Every result below was confirmed in the database and in ps_saferpay_log, not only on the confirmation screen.

How it behaves now

Checkout shows one Cards option instead of a row per brand. Selecting it renders the Saferpay Fields form inline, restricted to the brands the merchant enabled - the SDK receives the brand map built by PaymentFormAssetLoader, for example {"AMEX":["amex"],"MASTERCARD":["mastercard"],"VISA":["visa"],"CARD":["amex","mastercard","visa"]}. Saved cards appear under the option prefixed with the brand they were stored under (VISA xxxx xxxx xxxx 0001), and choosing "use a new card" swaps the saved-card list for the Fields form without reloading the page.

A card outside the enabled brands is refused while it is being typed. A card inside them completes and creates the order, whichever brand it is.

Results

#	Scenario	Expected	Result
1	Grouped Cards, MASTERCARD Fields flag off, paid with Mastercard 9030003150000007 - the exact original defect condition	Order created	Assert returned PaymentMeans.Brand.PaymentMethod = MASTERCARD, log took the Not redirect payment selected, creating order branch, order 15 authorized, transaction l46rxvbxrChtSAt0x8Avbvb3l0tA
2	Reload the return URL for that cart	No second authorization	return - Payment already processed, skipping assert, no ApiRequest POST, order count and state unchanged
3	Grouping off, Mastercard PAN typed into the Visa form	Refused at entry	Card field gets has-error, submit blocked with "Please check the following: Card number", no order, no saferpay_order row, no API call
4	Same form, Visa PAN 9010003150000001	Pays through	Order 16, payment label VISA, authorized
5	Only VISA enabled, grouping on, paid with the saved card	Saved-card branch works	Brand map narrowed to {"VISA":["visa"],"CARD":["visa"]}, order 17 authorized through the usingSavedCard path
6	Fields off and grouping off - hosted Saferpay Payment Page	Unaffected	saferpayPaymentType=basic, redirect to test.saferpay.com/VT2/mpp/..., order 18 created in validation, return leg asserted, then the notify webhook hit Order already exists, returning without duplicating
7	Reload the return URL on the Payment Page flow (isWebhook=1)	No damage	Payment already processed, skipping assert, order still authorized

Unit suite: OK (57 tests, 68 assertions).

Not covered by this run

• PS 1.7.6.1 and PS 9.1 checkout, and the third-party one-page checkout themes under views/js/front/opc/.
• Multistore.
• V PAY and myOne, which have no SDK brand name and so leave the form unrestricted.
• SaferPayTransactionProcessedGuard has no unit test; it is covered only by the manual runs above.

One decision needed before merge

With SAFERPAY_GROUP_CARDS on, the grouped option reports hosted_iframe even when every brand's "Saferpay Fields" toggle is off, because PaymentTypeProvider::isHostedIframeRedirect() returns true for PAYMENT_CARDS before it reads isActiveByName(). Since upgrade/install-2.1.0.php turns grouping on for every shop, an upgrade can move a merchant from the Payment Page to inline Fields without them changing a setting. Either the grouped option is Fields by definition and we document that, or the per-brand toggle has to win.