@doswiftly/storefront-operations 16.1.0 → 17.0.0

package/AGENTS.md

@@ -27,10 +27,10 @@ consumer's `codegen.ts` references this package's `.graphql` files as
 live in the consumer's repo.
 
 <!-- AUTOGEN:STATS:BEGIN — auto-regenerated, do not edit by hand -->
-- **Schema version**: 16.1.0
+- **Schema version**: 17.0.0
 - **Queries**: 52
-- **Mutations**: 40
-- **Fragments**: 102
+- **Mutations**: 41
+- **Fragments**: 104
 <!-- AUTOGEN:STATS:END -->
 
 ## Loading order

package/CHANGELOG.md

@@ -1,5 +1,341 @@
 # Changelog
 
+## 17.0.0
+
+### Major Changes
+
+- d3f0f04: `cartSelectPaymentMethod` mutation is now method-centric.
+
+  The buyer picks a payment **category** (`BLIK`, `CARD`, `BANK_TRANSFER`, ...) and the backend resolves the preferred gateway from the merchant's `MerchantPaymentConfig` at `paymentCreate` time. Previously the storefront had to look up a per-provider tile UUID via `availablePaymentMethods` and pass it as `paymentMethodId`.
+
+  **Breaking** — `CartSelectPaymentMethodInput` shape changed:
+
+  ```graphql
+  # Before
+  input CartSelectPaymentMethodInput {
+    cartId: ID!
+    paymentMethodId: ID! # UUID of a per-provider tile
+  }
+
+  # After
+  input CartSelectPaymentMethodInput {
+    cartId: ID!
+    methodType: PaymentMethodType! # BLIK, CARD, BANK_TRANSFER, ...
+    preferredProviderId: String # optional override (provider code)
+  }
+  ```
+
+  Migration:
+
+  ```ts
+  // Before
+  await sdk.cartSelectPaymentMethod({ input: { cartId, paymentMethodId } });
+
+  // After
+  await sdk.cartSelectPaymentMethod({ input: { cartId, methodType: "BLIK" } });
+  // Or with explicit gateway override:
+  await sdk.cartSelectPaymentMethod({
+    input: { cartId, methodType: "BLIK", preferredProviderId: "payu" },
+  });
+  ```
+
+  The `availablePaymentMethods` query now returns deduplicated rows per `PaymentMethodType` (one row per BLIK, CARD, ...) with `providersAvailable` (gateway codes sorted by merchant priority) and `preferredProvider` (head of the list). The legacy `group: BY_PROVIDER` argument was removed — there is one canonical shape.
+
+  **Why** — A merchant configuring PayU + Przelewy24 would previously see "PayU BLIK" and "P24 BLIK" as two separate tiles on the storefront. After this change the storefront shows one BLIK tile; the merchant chooses which gateway handles BLIK via priority settings, and the buyer never sees the internal routing.
+
+  **Live capability sync (opt-in)** — gateway adapters may expose an optional `getAvailablePaymentMethods(credentials, { currency, amount, country })` capability returning the gateway-reported active methods (min/max amount, brand image, enabled flag). When supported, the platform caches the response per shop/currency and uses it to refine the storefront picker. Gateways without the capability fall back to a static capability matrix. Gateway HTTP failures are soft-failed — the buyer always sees the merchant's configured methods even when the upstream is temporarily unreachable.
+
+- 7931668: Payment instrument preselection — direct deep-link to a specific instrument screen on the hosted gateway page (BLIK code, branded bank, wallet, card brand) instead of the gateway default landing.
+
+  **Why**: shoppers picking BLIK from the storefront UI now skip the gateway method picker entirely — the redirect lands directly on the BLIK code entry. Same flow for picking mBank, ING, Apple Pay, etc. Industry shorthand calls this "deep-link checkout" — 5-15% conversion uplift on single-instrument funnels.
+
+  **Breaking schema changes**:
+  1. `CartSelectPaymentMethodInput.preferredProviderId` → `preferredProviderCode`. Rename only — same semantics (override the merchant's preferred provider). Aligns with the `*Code` naming convention (`*Id` reserved for UUIDs, `*Code` for lowercase string identifiers like `payu` / `przelewy24`).
+
+     ```graphql
+     # Before
+     input CartSelectPaymentMethodInput {
+       cartId: ID!
+       methodType: PaymentMethodType!
+       preferredProviderId: String # ← removed
+     }
+
+     # After
+     input CartSelectPaymentMethodInput {
+       cartId: ID!
+       methodType: PaymentMethodType!
+       preferredProviderCode: String # ← renamed
+       preferredInstrumentCode: String # ← new (additive)
+     }
+     ```
+
+  2. `PaymentMethod.provider` / `PaymentMethod.providersAvailable` / `PaymentMethod.preferredProvider` / `Order.paymentMethod` / `Payment.provider` are now the typed `ProviderCode` enum (UPPERCASE: `PAYU`, `PRZELEWY24`, `STRIPE`, `CASH_ON_DELIVERY`, `BANK_TRANSFER`, `MANUAL_PAYMENT`, `GIFT_CARD`, `TEST_GATEWAY`) instead of `String`. Replace any `if (provider === 'payu')` storefront branches with the imported enum.
+
+     ```ts
+     // Before
+     if (paymentMethod.provider === "payu") {
+       /* ... */
+     }
+
+     // After
+     import { ProviderCode } from "@doswiftly/storefront-sdk";
+     if (paymentMethod.provider === ProviderCode.PAYU) {
+       /* ... */
+     }
+     ```
+
+  3. `PaymentMethod.amountLimits` removed from the SDK fragment. The field still exists on the schema for backward-compat, but the SDK no longer selects it — most storefronts never used it and the data is provider-specific (PayU/P24 report limits per method, not per checkout). Re-add it to your local fragment if you need it.
+
+  **Additive (backward-compatible)**:
+  - `PaymentMethod.instruments: [PaymentMethodInstrument!]` — concrete instruments exposed by the gateway (BLIK code, branded banks, wallets, card brands). Each instrument carries `providerCode`, `instrumentCode`, `displayName`, `brandImageUrl`, `displayHint` (semantic UX hint: `PIN_ENTRY` / `WALLET_TAP` / `BANK_LIST` / `CARD_FORM`), `enabled`. `null` when the gateway doesn't expose granular data; empty array when all instruments are disabled.
+  - `cartSelectPaymentMethod(input: { preferredInstrumentCode })` — pass the chosen instrument's `instrumentCode` to persist it on the cart. Eager validation cross-checks against the gateway's live capabilities — invalid codes return `userErrors[].code = 'CART_INVALID_INSTRUMENT_CODE'`.
+  - `Cart.selectedPaymentInstrumentCode: String` — round-trips the persisted choice so the storefront can re-render the selected instrument on cart refresh.
+  - `Order.paymentInstrumentCode: String` — propagated from cart at `cartComplete`; the gateway adapter uses it to build the deep-link payload at `paymentCreate`.
+
+  **Usage example** — instrument-level deep-link checkout:
+
+  ```ts
+  import { useCartManager, ProviderCode } from "@doswiftly/storefront-sdk";
+
+  const { selectPaymentMethod, complete, createPayment } = useCartManager();
+
+  // 1. Render the instrument tiles from the gateway-reported list
+  const method = availablePaymentMethods.methods.find((m) => m.type === "BLIK");
+  const instrument = method?.instruments?.find(
+    (i) => i.instrumentCode === "blik",
+  );
+
+  // 2. Persist the buyer's choice on the cart
+  await selectPaymentMethod({
+    methodType: "BLIK",
+    preferredProviderCode: "payu",
+    preferredInstrumentCode: instrument.instrumentCode,
+  });
+
+  // 3. Complete the cart — instrument propagates to the Order
+  const { order } = await complete();
+
+  // 4. Initiate payment — gateway redirects directly to the BLIK code screen
+  const session = await createPayment(order.id);
+  window.location.href = session.redirectUrl;
+  ```
+
+  **Error handling**:
+  - `userErrors[].code === 'CART_INVALID_INSTRUMENT_CODE'` — instrument code is not available with the chosen provider (gateway disabled it, merchant config changed, typo). Refresh `availablePaymentMethods` and re-prompt the buyer.
+  - `paymentCreate` failed gateway initiation with the preselected instrument? The order's `paymentInstrumentCode` is automatically cleared (best-effort) — the next `paymentCreate` call falls back to the gateway default landing page. Storefront just retries.
+
+  **Rate limits**:
+  - `availablePaymentMethods` Query: 60 requests/min per IP+shop. Live capability lookups (OAuth + gateway list call) are expensive — hitting the limit returns `extensions.code: 'THROTTLED'` with `retryAfter`. Don't poll; cache the result for the duration of the checkout step.
+
+  **Gateway API version pinning**:
+  - PayU API pinned to `v2_1`, Przelewy24 API pinned to `v1`. When the upstream gateway ships a major version migration, the SDK / operations packages will bump major together with the constant update.
+
+  **Migration checklist for existing storefronts**:
+  - [ ] Rename `preferredProviderId` → `preferredProviderCode` everywhere in storefront mutations.
+  - [ ] Replace string comparisons (`provider === 'payu'`) with `ProviderCode` enum.
+  - [ ] Re-add `amountLimits` to your local PaymentMethod fragment if you used it.
+  - [ ] (Optional) Render the new `instruments` array as tiles to enable instrument-level deep-link checkout — 1-2 extra hours of UI work, measurable conversion impact on single-instrument flows.
+
+### Minor Changes
+
+- fd82b62: `PaymentMethod` type gains availability + amount limit fields.
+
+  The storefront `PaymentMethod` returned by `availablePaymentMethods` (and `Cart.availablePaymentMethods` / `Cart.selectedPaymentMethod`) now carries three additional fields:
+  - **`available: Boolean!`** — `false` when the resolving gateway is temporarily unavailable (incident, maintenance) or reported the method as disabled. Storefront should gray-out the tile instead of hiding it — gives merchants observability into routing failures.
+  - **`unavailableReason: PaymentMethodUnavailableReason`** — diagnostic enum (`GATEWAY_DOWN`, `GATEWAY_DISABLED`, `NO_INSTRUMENTS`, `CREDENTIALS_INVALID`). Null when `available` is true. Use for context-aware copy ("Provider is temporarily down" vs "Method not configured").
+  - **`amountLimits: PaymentMethodAmountLimits`** — gateway-reported min/max transaction amount in the resolving currency (e.g. BLIK 1-20000 PLN). Filter the picker against cart total. Null when the gateway does not report limits.
+
+  ```graphql
+  fragment PaymentMethod on PaymentMethod {
+    # existing fields (id, name, provider, type, icon, ...)
+    providersAvailable
+    preferredProvider
+    available
+    unavailableReason
+    amountLimits {
+      min
+      max
+      currency
+    }
+  }
+  ```
+
+  **Currency** is automatically resolved from the storefront context (cascade: `@inContext(currency:)` directive → `X-Preferred-Currency` header → cookie → `Accept-Language` → shop default). Override per query via the `@inContext(currency: "EUR")` directive — no new schema argument.
+
+  **Migration example** for storefront pickers:
+
+  ```ts
+  const { methods } = await sdk.cart.availablePaymentMethods();
+  return methods.map((method) => (
+    <PaymentTile
+      key={method.type}
+      type={method.type}
+      disabled={!method.available}
+      tooltip={method.unavailableReason && reasonCopy[method.unavailableReason]}
+      badge={method.amountLimits && cart.total > method.amountLimits.max ? 'Cart too large' : null}
+    />
+  ));
+  ```
+
+  Backend additionally sanitizes provider error messages (strips OAuth tokens, URLs, JSON secret keys, stack traces) before returning them in admin diagnostic responses — internal logs keep the full error for diagnostics.
+
+- c878d14: Payment instrument preselection — storefront UX completion (distinct error code + warnings array + explicit deselect mutation).
+
+  **Why**: storefront dispatching dla instrument failure stał się context-aware. Dziś generic `PAYMENT_FAILED` post-auto-clear nie pozwalał odróżnić "instrument cleared, retry default landing OK" od "real gateway outage, retry kolejnym attempt". Plus brak explicit deselect — accordion "wróć do wyboru metody" UI wymagał hack typu re-select method.
+
+  **Additive (backward-compatible)**:
+  1. `PaymentErrorCode.INSTRUMENT_PRESELECTION_FAILED` — new enum value. Wystawiany po auto-clear `Order.paymentInstrumentCode` post-`InvalidPaymentInstrumentError`. Distinct od `PAYMENT_FAILED` (generic gateway failure fallback dla credentials / network / 5xx / circuit breaker).
+  2. `PaymentCreatePayload.warnings: [PaymentWarning!]!` — new field, default empty array. Emitted post-auto-clear z entry `{ code: INSTRUMENT_CLEARED_FOR_RETRY, message, retryHint: null }`. Storefront dispatches retry hint differently (accordion reset / progress bar / itp.).
+  3. `cartClearPaymentSelection(input: { cartId: ID! })` — new mutation. Atomic NULL across all payment selection fields. Idempotent. The cart must be `ACTIVE` — `CONVERTED` carts reject with `userErrors[0].code = 'ALREADY_COMPLETED'`. Rate limit 30/min.
+
+  **Storefront usage** — handle instrument failure z context-aware retry:
+
+  ```ts
+  import {
+    useCartManager,
+    type CartMutationOutcome,
+  } from "@doswiftly/storefront-sdk";
+
+  const { selectPaymentMethod, clearPaymentSelection, createPayment } =
+    useCartManager();
+
+  // 1. Klient wybiera BLIK preselect
+  await selectPaymentMethod({
+    methodType: "BLIK",
+    preferredProviderCode: "payu",
+    preferredInstrumentCode: "blik",
+  });
+
+  // 2. Try paymentCreate — może rzucić instrument-specific error
+  try {
+    const session = await createPayment(orderId);
+    window.location.href = session.redirectUrl;
+  } catch (err) {
+    if (err.userErrors?.[0]?.code === "INSTRUMENT_PRESELECTION_FAILED") {
+      // Backend auto-cleared instrument — show retry button
+      // Warning message available via err.warnings[0].message
+      showRetryUI({
+        title: "Instrument płatności niedostępny",
+        message: err.warnings?.[0]?.message ?? err.message,
+        onRetry: () => createPayment(orderId), // next attempt = default landing
+      });
+    } else if (err.userErrors?.[0]?.code === "PAYMENT_FAILED") {
+      // Generic gateway outage — retry z tym samym instrumentem
+      showOutageUI({
+        message: err.message,
+        onRetry: () => createPayment(orderId),
+      });
+    }
+  }
+
+  // 3. Accordion "wróć do wyboru metody" — explicit deselect
+  await clearPaymentSelection({ cartId });
+  // Cart.selectedPaymentMethod === null, Cart.selectedPaymentInstrumentCode === null
+  ```
+
+  **Migration guide for existing storefronts**:
+  - [ ] Add `warnings[]` to your `paymentCreate` selection set (if you use a custom GraphQL document instead of the SDK helpers).
+  - [ ] Branch UI dispatch on `userErrors[0].code === 'INSTRUMENT_PRESELECTION_FAILED'` distinct from `PAYMENT_FAILED`.
+  - [ ] (Optional) Replace any accordion-reset hack with `cartClearPaymentSelection({ cartId })` — clearer API, idempotent, single round-trip.
+
+  **Standards note**: splitting `userErrors[]` (blocking) and `warnings[]` (non-blocking) is a common e-commerce convention. The `INSTRUMENT_PRESELECTION_FAILED` semantics match retry-hint patterns used by major payment gateway SDKs (Stripe `payment_method_unavailable`, etc.).
+
+- c553c80: Payment instrument preselection — cart re-validation stale signal + headless instrument components + browser data helper.
+
+  **Why**: previously the storefront kept showing an obsolete instrument selection until the buyer clicked "pay" — only then did the gateway reject it. The signal is now **proactive**: every cart query re-validates the selection against live gateway capabilities and emits a warning when the method or instrument disappeared. Plus a set of pre-built headless React components so the instrument picker no longer requires manual `displayHint` dispatch.
+
+  **Additive (backward-compatible)**:
+  1. `Cart.warnings: [CartWarning!]!` — new field, default empty array. Computed at query time. Currently emitted: `PAYMENT_SELECTION_STALE` (code) when `selectedPaymentMethod` or `selectedPaymentInstrumentCode` no longer matches live gateway capabilities. Read-only signal — backend persistence is preserved (clear via `cartClearPaymentSelection` or a fresh `cartSelectPaymentMethod`).
+  2. `Cart.selectedPaymentMethod` re-validation — when the method disappeared from live caps the field returns `null` plus a warning with `target: 'selectedPaymentMethod'`.
+  3. `Cart.selectedPaymentInstrumentCode` re-validation — when only the instrument disappeared (method preserved), the field returns `null` plus a warning with `target: 'selectedPaymentInstrumentCode'` (method-level signal stays intact). Backend persistence is preserved — a re-select gets a fresh state.
+  4. `CartWarningCode.PAYMENT_SELECTION_STALE` — new enum value in the existing `CartWarning` envelope.
+  5. Graceful degradation — when the live capability check fails (gateway timeout / network outage), `Cart` returns the existing selection without a warning (UX continuity over freshness; `cartComplete` time-of-payment validation is the final safety net).
+  6. `<PaymentInstrumentTile>` — new pre-built headless component. Single instrument button with full ARIA contract (`role="radio"`, `aria-checked`, `aria-label`, `data-instrument-code`, `data-display-hint`, `data-selected`). Zero opinionated styling — class props per part (button, icon, label). `displayHint` is emitted as a `data-display-hint` attribute so you can style via CSS attribute selectors.
+  7. `<PaymentInstrumentSection>` — new pre-built headless component. Radio-group container with keyboard navigation (ArrowUp/Down/Left/Right wrap, Home/End jump). Renders one `<PaymentInstrumentTile>` per instrument in the order received from `availablePaymentMethods` (no client-side resort — the backend ordering is the source of truth).
+  8. `getBrowserDataForPayment()` — new helper. Collects PSD2/3DS2 browser context (`userAgent`, `language`, screen dimensions, color depth, timezone offset, IANA timezone, `javaEnabled` fallback). Browser-only — throws `BrowserDataNotAvailableError` in SSR. Forward-looking utility for future 3DS challenge flows.
+
+  **Storefront usage** — listen to the stale signal in your cart query:
+
+  ```ts
+  const { cart } = useCart(cartId);
+
+  const staleWarning = cart?.warnings?.find(
+    (w) => w.code === "PAYMENT_SELECTION_STALE",
+  );
+
+  if (staleWarning) {
+    // The backend signals that the buyer picked a method which is no longer
+    // available at the gateway — show a "pick another method" dialog.
+    // `target` distinguishes method vs instrument level:
+    if (staleWarning.target === "selectedPaymentMethod") {
+      // cart.selectedPaymentMethod === null — full re-select required
+    } else if (staleWarning.target === "selectedPaymentInstrumentCode") {
+      // cart.selectedPaymentMethod is still set, only the instrument cleared
+    }
+    // Backend persistence is preserved — `cartClearPaymentSelection` or
+    // a fresh `cartSelectPaymentMethod` is the consumer's responsibility.
+  }
+  ```
+
+  **Storefront usage** — instrument picker with pre-built components:
+
+  ```tsx
+  import { PaymentInstrumentSection } from "@doswiftly/storefront-sdk/react";
+  import { useState } from "react";
+
+  function CheckoutPaymentStep({ method }: { method: PaymentMethod }) {
+    const [instrumentCode, setInstrumentCode] = useState<string | undefined>(
+      undefined,
+    );
+
+    return (
+      <PaymentInstrumentSection
+        method={method}
+        selectedInstrumentCode={instrumentCode}
+        onSelectInstrument={(code) => {
+          setInstrumentCode(code);
+          cart.selectPaymentMethod({
+            methodType: method.type,
+            preferredProviderCode: method.preferredProvider,
+            preferredInstrumentCode: code,
+          });
+        }}
+        sectionClassName="grid grid-cols-2 gap-2"
+        tileClassName="rounded border p-3 hover:bg-gray-50 data-[selected=true]:border-blue-500"
+        labelClassName="font-semibold"
+        ariaLabel="Pick a payment instrument"
+      />
+    );
+  }
+  ```
+
+  **Storefront usage** — browser data for future 3DS flows:
+
+  ```ts
+  import { getBrowserDataForPayment, BrowserDataNotAvailableError } from '@doswiftly/storefront-sdk/react';
+
+  function handleCheckoutSubmit() {
+    try {
+      const browserData = getBrowserDataForPayment();
+      // Pass to paymentCreate input when the gateway requires a 3DS challenge
+      await cart.createPayment({ ..., browserData });
+    } catch (err) {
+      if (err instanceof BrowserDataNotAvailableError) {
+        // SSR / no DOM — skip browser data; the gateway uses its default flow
+      }
+      throw err;
+    }
+  }
+  ```
+
+  **Migration checklist for existing storefronts**:
+  - [ ] Add `warnings { message code target }` to your cart query selection set (if you use a custom GraphQL document instead of the SDK fragments — SDK fragments are updated automatically).
+  - [ ] Branch UI on `cart.warnings[].code === 'PAYMENT_SELECTION_STALE'` to show a re-prompt dialog before checkout submit.
+  - [ ] (Optional) Replace a custom instrument picker with `<PaymentInstrumentSection>` — saves boilerplate, ships full ARIA + keyboard nav out of the box.
+  - [ ] (Forward-looking) Adopt `getBrowserDataForPayment()` in checkout submit handlers when 3DS flows become relevant (currently optional — the gateway accepts an undefined `browserData`).
+
+  **Standards reference**: `PaymentInstrumentSection` follows the WAI-ARIA radiogroup pattern (https://www.w3.org/WAI/ARIA/apg/patterns/radio/). The browser data helper shape matches the EMVCo 3DS2 BrowserData specification.
+
 ## 16.1.0
 
 ### Minor Changes

package/README.md

@@ -380,12 +380,13 @@ full executable body of each operation.
 | `CartSetShippingAddress` | Phase 3 unify-cart-graphql-surface: wszystkie fulfillment + payment + completion operations teraz na Cart aggregate (zamiast Checkout dual-aggregate). Klient robi typowy checkout flow: cart create/add items → setShipping/Billing/Method → selectPayment → (optional) applyGiftCard → cartComplete → Order created. Sets the shipping address on the cart (full replace, not patch). Triggers cart re-pricing (tax recalculation per address country/region). Address format validated against `CartAddressInput` constraints (firstName/lastName/streetLine1/city/country/postalCode required). Errors: `INVALID_ADDRESS`, `CART_NOT_FOUND`. |
 | `CartSetBillingAddress` | Sets the billing address on the cart (full replace). Independent of shipping address — pass it explicitly even when "billing same as shipping". Errors: `INVALID_ADDRESS`, `CART_NOT_FOUND`. |
 | `CartSelectShippingMethod` | Selects a shipping method by `shippingMethodId` (typed `ID!`, a stable shipping-method UUID — NOT a per-request token). The id comes from a list of methods available for the current address + cart subtotal (queryable separately). Errors: `SHIPPING_METHOD_REQUIRED`, `ZIP_CODE_NOT_SUPPORTED`, `CART_NOT_FOUND`. |
-| `CartSelectPaymentMethod` | Selects a payment method by `paymentMethodId` (UUID from `availablePaymentMethods` query). Validates existence + active status; no pre-authorization performed here. Errors: `PAYMENT_METHOD_REQUIRED`, `INVALID_PAYMENT`, `CART_NOT_FOUND`. |
+| `CartSelectPaymentMethod` | Selects a payment method on the cart by category (`methodType` — BLIK, CARD, BANK_TRANSFER, ...). Optional `preferredProviderId` overrides the merchant priority when the buyer explicitly picks a gateway from `PaymentMethod.providersAvailable`. The backend resolves the gateway routing from `MerchantPaymentConfig` at `cartComplete`; the selection persisted here is the category. Errors: `PAYMENT_METHOD_REQUIRED`, `CART_NOT_FOUND`, `CART_UNAUTHENTICATED`. |
 | `CartApplyGiftCard` | Applies a gift card to the cart, stackable with discount codes. Consumption is FIFO: each card consumes `min(remainingBalance, paymentDue)` against the current cart total in the order they were applied. The gift card balance is NOT debited yet — actual deduction happens atomically at `cartComplete`. Errors: `GIFT_CARD_NOT_FOUND`, `GIFT_CARD_DEPLETED`, `GIFT_CARD_UNUSABLE`. |
 | `CartRemoveGiftCard` | Removes a gift card from the applied list and recalculates FIFO `appliedAmount` for the remaining cards. Since gift card balances are only debited at `cartComplete`, removing before completion has no effect on the underlying gift card balance. |
 | `CartUpdateGiftCardRecipient` | Sets per-line-item recipient details (name, email, message) for digital gift card products in the cart (line items where the variant represents a gift-card SKU). Required before `cartComplete` for any line item with a gift-card variant. Recipient details propagated to the resulting order. |
 | `CartComplete` | Finalizes the cart — creates the `Order`, deducts gift cards, sends order-created confirmation — all atomically. **Idempotent on `idempotencyKey`** (auto-generated from cartId + minute timestamp if caller omits it). Returns `order` field after completion. Note: `paymentUrl` is intentionally NOT in payload — for hosted gateways (online providers) the storefront calls a separate `paymentCreate` mutation after this returns (check `order.canCreatePayment` first). Errors: `EMAIL_REQUIRED`, `SHIPPING_ADDRESS_REQUIRED`, `SHIPPING_METHOD_REQUIRED`, `PAYMENT_METHOD_REQUIRED`, `INSUFFICIENT_STOCK`, `ALREADY_COMPLETED`. |
-| `PaymentCreate` | Initiates a payment session for an order created by `cartComplete` — call this when `order.canCreatePayment` is `true` (orders with an offline payment method like cash-on-delivery skip this step). `orderId` is required; `returnUrl` / `cancelUrl` are optional and, when supplied, must point to a verified domain of the shop (open-redirect protected). Branch on the returned `payment.flow`: `ONLINE_REDIRECT` → redirect to `payment.redirectUrl`, `ONLINE_EMBEDDED` → render a widget with `payment.clientSecret`, `INSTANT_DIRECT` → already settled, read `payment.status`. Public, but ownership-checked — an authenticated customer cannot pay for another customer's order. **Idempotent** — calling it again for the same order returns the existing still-valid session instead of creating a duplicate (safe to retry). Rate limit: 5 requests/minute. `userErrors[].code`: `ORDER_NOT_FOUND`, `ORDER_ALREADY_PAID`, `ORDER_NOT_PAYABLE`, `PAYMENT_PROVIDER_NOT_CONFIGURED`, `RETURN_URL_INVALID`, `INVALID_ID_FORMAT`, `PAYMENT_FAILED`. |
+| `PaymentCreate` | Initiates a payment session for an order created by `cartComplete` — call this when `order.canCreatePayment` is `true` (orders with an offline payment method like cash-on-delivery skip this step). `orderId` is required; `returnUrl` / `cancelUrl` are optional and, when supplied, must point to a verified domain of the shop (open-redirect protected). Branch on the returned `payment.flow`: `ONLINE_REDIRECT` → redirect to `payment.redirectUrl`, `ONLINE_EMBEDDED` → render a widget with `payment.clientSecret`, `INSTANT_DIRECT` → already settled, read `payment.status`. Public, but ownership-checked — an authenticated customer cannot pay for another customer's order. **Idempotent** — calling it again for the same order returns the existing still-valid session instead of creating a duplicate (safe to retry). Rate limit: 5 requests/minute. `userErrors[].code`: `ORDER_NOT_FOUND`, `ORDER_ALREADY_PAID`, `ORDER_NOT_PAYABLE`, `PAYMENT_PROVIDER_NOT_CONFIGURED`, `RETURN_URL_INVALID`, `INVALID_ID_FORMAT`, `PAYMENT_FAILED`, `INSTRUMENT_PRESELECTION_FAILED`. `warnings[]` array zawiera `INSTRUMENT_CLEARED_FOR_RETRY` post-auto-clear instrument-specific failure (storefront retry hint: next attempt uses gateway default landing). |
+| `CartClearPaymentSelection` | Clears all payment selection state on the cart in a single atomic operation. Use for accordion "back to method picker" flows w storefront UI. Idempotent — calling twice yields the same end state. Cart MUSI być `ACTIVE` (CONVERTED carts reject z `ALREADY_COMPLETED`). Rate limit: 30 requests/minute per IP+shop. |
 
 #### Return Mutations
 
@@ -508,9 +509,11 @@ full executable body of each operation.
 
 | Fragment | On Type | Description |
 | --- | --- | --- |
-| `PaymentMethod` | `PaymentMethod` | Single payment method enabled for the shop — type (CARD / BANK_TRANSFER / BLIK / PAYPAL / APPLE_PAY / GOOGLE_PAY / CASH_ON_DELIVERY / OTHER), provider, icon, supported currencies, default flag, sort position. Spread on the checkout payment step. |
+| `PaymentMethodInstrument` | `PaymentMethodInstrument` | A single concrete instrument exposed by a gateway provider (BLIK code, branded bank, wallet, card brand). Pass `instrumentCode` as `preferredInstrumentCode` in `cartSelectPaymentMethod` for direct deep-link to that instrument screen on the gateway. `displayHint` is a semantic UX hint (`PIN_ENTRY`, `WALLET_TAP`, `BANK_LIST`, `CARD_FORM`) — storefront branches rendering accordingly. `enabled: false` means the gateway reported the instrument as temporarily disabled — gray out, don't hide. |
+| `PaymentMethod` | `PaymentMethod` | Single payment method enabled for the shop — method-centric. `type` is the category (CARD, BLIK, BANK_TRANSFER, CASH_ON_DELIVERY, OTHER) — drive iconography here. `provider`, `providersAvailable`, `preferredProvider` are `ProviderCode` enum (UPPERCASE: `PAYU`, `PRZELEWY24`, ...). `available` is `false` when the resolving gateway is temporarily unavailable or reported the method as disabled — gray-out the tile, don't hide it; `unavailableReason` carries the diagnostic. `instruments` lists concrete gateway-side instruments (BLIK code, branded banks, wallets) when the gateway exposes granular data — pass `instrumentCode` as `preferredInstrumentCode` in `cartSelectPaymentMethod` for direct deep-link to that instrument screen on the gateway. Spread on the checkout payment step. |
 | `AvailablePaymentMethods` | `AvailablePaymentMethods` | Active payment methods list with the merchant's `defaultMethod`. Returned by the `availablePaymentMethods` query. |
 | `PaymentSession` | `PaymentSession` | Initiated payment session for an order — returned by the `paymentCreate` mutation. Branch on `flow`: `ONLINE_REDIRECT` (redirect the browser to `redirectUrl`), `ONLINE_EMBEDDED` (render an in-page widget with `clientSecret`), `INSTANT_DIRECT` (settled with no UI — read `status`). `expiresAt` is ISO 8601, present when the gateway session has a TTL. |
+| `PaymentWarning` | `PaymentWarning` | Non-blocking signal emitted alongside `userErrors[]` in `paymentCreate` payload — backend state change context (e.g. an auto-clear of preselected instrument after gateway rejection). Pre-translated by backend per shop locale. `code === 'INSTRUMENT_CLEARED_FOR_RETRY'` signals storefront that the next `paymentCreate` will land on the gateway default landing page (server-side cleared `Order.paymentInstrumentCode` after `INSTRUMENT_PRESELECTION_FAILED`). `retryHint` is optional context for UI dispatch — currently unused for `INSTRUMENT_CLEARED_FOR_RETRY`, reserved for future warning codes. |
 
 #### Shipments / Tracking
 

package/fragments.graphql

@@ -510,6 +510,7 @@ fragment Cart on Cart {
   selectedPaymentMethod {
     ...CartSelectedPaymentMethod
   }
+  selectedPaymentInstrumentCode
   appliedGiftCards {
     ...CartAppliedGiftCard
   }
@@ -700,7 +701,23 @@ fragment ShopConfigFields on Shop {
 # Payment Methods
 # ============================================
 
-# Single payment method enabled for the shop — type (CARD / BANK_TRANSFER / BLIK / PAYPAL / APPLE_PAY / GOOGLE_PAY / CASH_ON_DELIVERY / OTHER), provider, icon, supported currencies, default flag, sort position. Spread on the checkout payment step.
+# A single concrete instrument exposed by a gateway provider (BLIK code, branded bank, wallet, card brand). Pass `instrumentCode` as `preferredInstrumentCode` in `cartSelectPaymentMethod` for direct deep-link to that instrument screen on the gateway. `displayHint` is a semantic UX hint (`PIN_ENTRY`, `WALLET_TAP`, `BANK_LIST`, `CARD_FORM`) — storefront branches rendering accordingly. `enabled: false` means the gateway reported the instrument as temporarily disabled — gray out, don't hide.
+fragment PaymentMethodInstrument on PaymentMethodInstrument {
+  providerCode
+  instrumentCode
+  type
+  displayName
+  displayHint
+  brandImageUrl
+  enabled
+}
+
+# Single payment method enabled for the shop — method-centric.
+# `type` is the category (CARD, BLIK, BANK_TRANSFER, CASH_ON_DELIVERY, OTHER) — drive iconography here.
+# `provider`, `providersAvailable`, `preferredProvider` are `ProviderCode` enum (UPPERCASE: `PAYU`, `PRZELEWY24`, ...).
+# `available` is `false` when the resolving gateway is temporarily unavailable or reported the method as disabled — gray-out the tile, don't hide it; `unavailableReason` carries the diagnostic.
+# `instruments` lists concrete gateway-side instruments (BLIK code, branded banks, wallets) when the gateway exposes granular data — pass `instrumentCode` as `preferredInstrumentCode` in `cartSelectPaymentMethod` for direct deep-link to that instrument screen on the gateway.
+# Spread on the checkout payment step.
 fragment PaymentMethod on PaymentMethod {
   id
   name
@@ -711,6 +728,13 @@ fragment PaymentMethod on PaymentMethod {
   isDefault
   supportedCurrencies
   position
+  providersAvailable
+  preferredProvider
+  available
+  unavailableReason
+  instruments {
+    ...PaymentMethodInstrument
+  }
 }
 
 # Active payment methods list with the merchant's `defaultMethod`. Returned by the `availablePaymentMethods` query.
@@ -735,6 +759,13 @@ fragment PaymentSession on PaymentSession {
   expiresAt
 }
 
+# Non-blocking signal emitted alongside `userErrors[]` in `paymentCreate` payload — backend state change context (e.g. an auto-clear of preselected instrument after gateway rejection). Pre-translated by backend per shop locale. `code === 'INSTRUMENT_CLEARED_FOR_RETRY'` signals storefront that the next `paymentCreate` will land on the gateway default landing page (server-side cleared `Order.paymentInstrumentCode` after `INSTRUMENT_PRESELECTION_FAILED`). `retryHint` is optional context for UI dispatch — currently unused for `INSTRUMENT_CLEARED_FOR_RETRY`, reserved for future warning codes.
+fragment PaymentWarning on PaymentWarning {
+  message
+  code
+  retryHint
+}
+
 # ============================================
 # Discount Code Validation
 # ============================================

package/llms-full.txt

@@ -1,7 +1,7 @@
 # DoSwiftly Storefront Operations — Full Reference
 
-> Schema version: **16.1.0**
-> 52 queries · 40 mutations · 102 fragments
+> Schema version: **17.0.0**
+> 52 queries · 41 mutations · 104 fragments
 
 Auto-generated from `.graphql` source files. Do not edit by hand — this file is
 regenerated on every release to match the published schema.
@@ -1975,7 +1975,7 @@ mutation CartSelectShippingMethod($input: CartSelectShippingMethodInput!) {
 
 **Section**: Cart Completion Mutations
 
-**Description**: Selects a payment method by `paymentMethodId` (UUID from `availablePaymentMethods` query). Validates existence + active status; no pre-authorization performed here. Errors: `PAYMENT_METHOD_REQUIRED`, `INVALID_PAYMENT`, `CART_NOT_FOUND`.
+**Description**: Selects a payment method on the cart by category (`methodType` — BLIK, CARD, BANK_TRANSFER, ...). Optional `preferredProviderId` overrides the merchant priority when the buyer explicitly picks a gateway from `PaymentMethod.providersAvailable`. The backend resolves the gateway routing from `MerchantPaymentConfig` at `cartComplete`; the selection persisted here is the category. Errors: `PAYMENT_METHOD_REQUIRED`, `CART_NOT_FOUND`, `CART_UNAUTHENTICATED`.
 
 **Variables**:
 - `$input`: `CartSelectPaymentMethodInput!`
@@ -2115,12 +2115,12 @@ mutation CartComplete($input: CartCompleteInput!) {
 
 **Section**: Cart Completion Mutations
 
-**Description**: Initiates a payment session for an order created by `cartComplete` — call this when `order.canCreatePayment` is `true` (orders with an offline payment method like cash-on-delivery skip this step). `orderId` is required; `returnUrl` / `cancelUrl` are optional and, when supplied, must point to a verified domain of the shop (open-redirect protected). Branch on the returned `payment.flow`: `ONLINE_REDIRECT` → redirect to `payment.redirectUrl`, `ONLINE_EMBEDDED` → render a widget with `payment.clientSecret`, `INSTANT_DIRECT` → already settled, read `payment.status`. Public, but ownership-checked — an authenticated customer cannot pay for another customer's order. **Idempotent** — calling it again for the same order returns the existing still-valid session instead of creating a duplicate (safe to retry). Rate limit: 5 requests/minute. `userErrors[].code`: `ORDER_NOT_FOUND`, `ORDER_ALREADY_PAID`, `ORDER_NOT_PAYABLE`, `PAYMENT_PROVIDER_NOT_CONFIGURED`, `RETURN_URL_INVALID`, `INVALID_ID_FORMAT`, `PAYMENT_FAILED`.
+**Description**: Initiates a payment session for an order created by `cartComplete` — call this when `order.canCreatePayment` is `true` (orders with an offline payment method like cash-on-delivery skip this step). `orderId` is required; `returnUrl` / `cancelUrl` are optional and, when supplied, must point to a verified domain of the shop (open-redirect protected). Branch on the returned `payment.flow`: `ONLINE_REDIRECT` → redirect to `payment.redirectUrl`, `ONLINE_EMBEDDED` → render a widget with `payment.clientSecret`, `INSTANT_DIRECT` → already settled, read `payment.status`. Public, but ownership-checked — an authenticated customer cannot pay for another customer's order. **Idempotent** — calling it again for the same order returns the existing still-valid session instead of creating a duplicate (safe to retry). Rate limit: 5 requests/minute. `userErrors[].code`: `ORDER_NOT_FOUND`, `ORDER_ALREADY_PAID`, `ORDER_NOT_PAYABLE`, `PAYMENT_PROVIDER_NOT_CONFIGURED`, `RETURN_URL_INVALID`, `INVALID_ID_FORMAT`, `PAYMENT_FAILED`, `INSTRUMENT_PRESELECTION_FAILED`. `warnings[]` array zawiera `INSTRUMENT_CLEARED_FOR_RETRY` post-auto-clear instrument-specific failure (storefront retry hint: next attempt uses gateway default landing).
 
 **Variables**:
 - `$input`: `PaymentCreateInput!`
 
-**Fragments used**: `PaymentSession`, `UserError`
+**Fragments used**: `PaymentSession`, `PaymentWarning`, `UserError`
 
 **GraphQL**:
 ```graphql
@@ -2132,6 +2132,37 @@ mutation PaymentCreate($input: PaymentCreateInput!) {
     userErrors {
       ...UserError
     }
+    warnings {
+      ...PaymentWarning
+    }
+  }
+}
+```
+
+### Mutation: `CartClearPaymentSelection`
+
+**Section**: Cart Completion Mutations
+
+**Description**: Clears all payment selection state on the cart in a single atomic operation. Use for accordion "back to method picker" flows w storefront UI. Idempotent — calling twice yields the same end state. Cart MUSI być `ACTIVE` (CONVERTED carts reject z `ALREADY_COMPLETED`). Rate limit: 30 requests/minute per IP+shop.
+
+**Variables**:
+- `$input`: `CartClearPaymentSelectionInput!`
+
+**Fragments used**: `Cart`, `CartWarning`, `UserError`
+
+**GraphQL**:
+```graphql
+mutation CartClearPaymentSelection($input: CartClearPaymentSelectionInput!) {
+  cartClearPaymentSelection(input: $input) {
+    cart {
+      ...Cart
+    }
+    userErrors {
+      ...UserError
+    }
+    warnings {
+      ...CartWarning
+    }
   }
 }
 ```
@@ -3171,6 +3202,7 @@ fragment Cart on Cart {
   selectedPaymentMethod {
     ...CartSelectedPaymentMethod
   }
+  selectedPaymentInstrumentCode
   appliedGiftCards {
     ...CartAppliedGiftCard
   }
@@ -3470,11 +3502,32 @@ fragment ShopConfigFields on Shop {
 }
 ```
 
+### Fragment: `PaymentMethodInstrument` on `PaymentMethodInstrument`
+
+**Section**: Payment Methods
+
+**Description**: A single concrete instrument exposed by a gateway provider (BLIK code, branded bank, wallet, card brand). Pass `instrumentCode` as `preferredInstrumentCode` in `cartSelectPaymentMethod` for direct deep-link to that instrument screen on the gateway. `displayHint` is a semantic UX hint (`PIN_ENTRY`, `WALLET_TAP`, `BANK_LIST`, `CARD_FORM`) — storefront branches rendering accordingly. `enabled: false` means the gateway reported the instrument as temporarily disabled — gray out, don't hide.
+
+**GraphQL**:
+```graphql
+fragment PaymentMethodInstrument on PaymentMethodInstrument {
+  providerCode
+  instrumentCode
+  type
+  displayName
+  displayHint
+  brandImageUrl
+  enabled
+}
+```
+
 ### Fragment: `PaymentMethod` on `PaymentMethod`
 
 **Section**: Payment Methods
 
-**Description**: Single payment method enabled for the shop — type (CARD / BANK_TRANSFER / BLIK / PAYPAL / APPLE_PAY / GOOGLE_PAY / CASH_ON_DELIVERY / OTHER), provider, icon, supported currencies, default flag, sort position. Spread on the checkout payment step.
+**Description**: Single payment method enabled for the shop — method-centric. `type` is the category (CARD, BLIK, BANK_TRANSFER, CASH_ON_DELIVERY, OTHER) — drive iconography here. `provider`, `providersAvailable`, `preferredProvider` are `ProviderCode` enum (UPPERCASE: `PAYU`, `PRZELEWY24`, ...). `available` is `false` when the resolving gateway is temporarily unavailable or reported the method as disabled — gray-out the tile, don't hide it; `unavailableReason` carries the diagnostic. `instruments` lists concrete gateway-side instruments (BLIK code, branded banks, wallets) when the gateway exposes granular data — pass `instrumentCode` as `preferredInstrumentCode` in `cartSelectPaymentMethod` for direct deep-link to that instrument screen on the gateway. Spread on the checkout payment step.
+
+**Uses fragments**: `PaymentMethodInstrument`
 
 **GraphQL**:
 ```graphql
@@ -3488,6 +3541,13 @@ fragment PaymentMethod on PaymentMethod {
   isDefault
   supportedCurrencies
   position
+  providersAvailable
+  preferredProvider
+  available
+  unavailableReason
+  instruments {
+    ...PaymentMethodInstrument
+  }
 }
 ```
 
@@ -3531,6 +3591,21 @@ fragment PaymentSession on PaymentSession {
 }
 ```
 
+### Fragment: `PaymentWarning` on `PaymentWarning`
+
+**Section**: Payment Methods
+
+**Description**: Non-blocking signal emitted alongside `userErrors[]` in `paymentCreate` payload — backend state change context (e.g. an auto-clear of preselected instrument after gateway rejection). Pre-translated by backend per shop locale. `code === 'INSTRUMENT_CLEARED_FOR_RETRY'` signals storefront that the next `paymentCreate` will land on the gateway default landing page (server-side cleared `Order.paymentInstrumentCode` after `INSTRUMENT_PRESELECTION_FAILED`). `retryHint` is optional context for UI dispatch — currently unused for `INSTRUMENT_CLEARED_FOR_RETRY`, reserved for future warning codes.
+
+**GraphQL**:
+```graphql
+fragment PaymentWarning on PaymentWarning {
+  message
+  code
+  retryHint
+}
+```
+
 ### Fragment: `ShipmentEvent` on `ShipmentEvent`
 
 **Section**: Shipments / Tracking

package/mutations.graphql

@@ -329,7 +329,11 @@ mutation CartSelectShippingMethod($input: CartSelectShippingMethodInput!) {
   }
 }
 
-# Selects a payment method by `paymentMethodId` (UUID from `availablePaymentMethods` query). Validates existence + active status; no pre-authorization performed here. Errors: `PAYMENT_METHOD_REQUIRED`, `INVALID_PAYMENT`, `CART_NOT_FOUND`.
+# Selects a payment method on the cart by category (`methodType` — BLIK, CARD, BANK_TRANSFER, ...).
+# Optional `preferredProviderId` overrides the merchant priority when the buyer explicitly picks
+# a gateway from `PaymentMethod.providersAvailable`. The backend resolves the gateway routing
+# from `MerchantPaymentConfig` at `cartComplete`; the selection persisted here is the category.
+# Errors: `PAYMENT_METHOD_REQUIRED`, `CART_NOT_FOUND`, `CART_UNAUTHENTICATED`.
 mutation CartSelectPaymentMethod($input: CartSelectPaymentMethodInput!) {
   cartSelectPaymentMethod(input: $input) {
     cart {
@@ -404,7 +408,7 @@ mutation CartComplete($input: CartCompleteInput!) {
   }
 }
 
-# Initiates a payment session for an order created by `cartComplete` — call this when `order.canCreatePayment` is `true` (orders with an offline payment method like cash-on-delivery skip this step). `orderId` is required; `returnUrl` / `cancelUrl` are optional and, when supplied, must point to a verified domain of the shop (open-redirect protected). Branch on the returned `payment.flow`: `ONLINE_REDIRECT` → redirect to `payment.redirectUrl`, `ONLINE_EMBEDDED` → render a widget with `payment.clientSecret`, `INSTANT_DIRECT` → already settled, read `payment.status`. Public, but ownership-checked — an authenticated customer cannot pay for another customer's order. **Idempotent** — calling it again for the same order returns the existing still-valid session instead of creating a duplicate (safe to retry). Rate limit: 5 requests/minute. `userErrors[].code`: `ORDER_NOT_FOUND`, `ORDER_ALREADY_PAID`, `ORDER_NOT_PAYABLE`, `PAYMENT_PROVIDER_NOT_CONFIGURED`, `RETURN_URL_INVALID`, `INVALID_ID_FORMAT`, `PAYMENT_FAILED`.
+# Initiates a payment session for an order created by `cartComplete` — call this when `order.canCreatePayment` is `true` (orders with an offline payment method like cash-on-delivery skip this step). `orderId` is required; `returnUrl` / `cancelUrl` are optional and, when supplied, must point to a verified domain of the shop (open-redirect protected). Branch on the returned `payment.flow`: `ONLINE_REDIRECT` → redirect to `payment.redirectUrl`, `ONLINE_EMBEDDED` → render a widget with `payment.clientSecret`, `INSTANT_DIRECT` → already settled, read `payment.status`. Public, but ownership-checked — an authenticated customer cannot pay for another customer's order. **Idempotent** — calling it again for the same order returns the existing still-valid session instead of creating a duplicate (safe to retry). Rate limit: 5 requests/minute. `userErrors[].code`: `ORDER_NOT_FOUND`, `ORDER_ALREADY_PAID`, `ORDER_NOT_PAYABLE`, `PAYMENT_PROVIDER_NOT_CONFIGURED`, `RETURN_URL_INVALID`, `INVALID_ID_FORMAT`, `PAYMENT_FAILED`, `INSTRUMENT_PRESELECTION_FAILED`. `warnings[]` array zawiera `INSTRUMENT_CLEARED_FOR_RETRY` post-auto-clear instrument-specific failure (storefront retry hint: next attempt uses gateway default landing).
 mutation PaymentCreate($input: PaymentCreateInput!) {
   paymentCreate(input: $input) {
     payment {
@@ -413,6 +417,24 @@ mutation PaymentCreate($input: PaymentCreateInput!) {
     userErrors {
       ...UserError
     }
+    warnings {
+      ...PaymentWarning
+    }
+  }
+}
+
+# Clears all payment selection state on the cart in a single atomic operation. Use for accordion "back to method picker" flows w storefront UI. Idempotent — calling twice yields the same end state. Cart MUSI być `ACTIVE` (CONVERTED carts reject z `ALREADY_COMPLETED`). Rate limit: 30 requests/minute per IP+shop.
+mutation CartClearPaymentSelection($input: CartClearPaymentSelectionInput!) {
+  cartClearPaymentSelection(input: $input) {
+    cart {
+      ...Cart
+    }
+    userErrors {
+      ...UserError
+    }
+    warnings {
+      ...CartWarning
+    }
   }
 }
 

package/operations.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": "16.1.0",
+  "schemaVersion": "17.0.0",
   "queries": [
     {
       "name": "Shop",
@@ -1518,7 +1518,7 @@
       "name": "CartSelectPaymentMethod",
       "kind": "mutation",
       "section": "Cart Completion Mutations",
-      "description": "Selects a payment method by `paymentMethodId` (UUID from `availablePaymentMethods` query). Validates existence + active status; no pre-authorization performed here. Errors: `PAYMENT_METHOD_REQUIRED`, `INVALID_PAYMENT`, `CART_NOT_FOUND`.",
+      "description": "Selects a payment method on the cart by category (`methodType` — BLIK, CARD, BANK_TRANSFER, ...). Optional `preferredProviderId` overrides the merchant priority when the buyer explicitly picks a gateway from `PaymentMethod.providersAvailable`. The backend resolves the gateway routing from `MerchantPaymentConfig` at `cartComplete`; the selection persisted here is the category. Errors: `PAYMENT_METHOD_REQUIRED`, `CART_NOT_FOUND`, `CART_UNAUTHENTICATED`.",
       "variables": [
         {
           "name": "input",
@@ -1613,7 +1613,7 @@
       "name": "PaymentCreate",
       "kind": "mutation",
       "section": "Cart Completion Mutations",
-      "description": "Initiates a payment session for an order created by `cartComplete` — call this when `order.canCreatePayment` is `true` (orders with an offline payment method like cash-on-delivery skip this step). `orderId` is required; `returnUrl` / `cancelUrl` are optional and, when supplied, must point to a verified domain of the shop (open-redirect protected). Branch on the returned `payment.flow`: `ONLINE_REDIRECT` → redirect to `payment.redirectUrl`, `ONLINE_EMBEDDED` → render a widget with `payment.clientSecret`, `INSTANT_DIRECT` → already settled, read `payment.status`. Public, but ownership-checked — an authenticated customer cannot pay for another customer's order. **Idempotent** — calling it again for the same order returns the existing still-valid session instead of creating a duplicate (safe to retry). Rate limit: 5 requests/minute. `userErrors[].code`: `ORDER_NOT_FOUND`, `ORDER_ALREADY_PAID`, `ORDER_NOT_PAYABLE`, `PAYMENT_PROVIDER_NOT_CONFIGURED`, `RETURN_URL_INVALID`, `INVALID_ID_FORMAT`, `PAYMENT_FAILED`.",
+      "description": "Initiates a payment session for an order created by `cartComplete` — call this when `order.canCreatePayment` is `true` (orders with an offline payment method like cash-on-delivery skip this step). `orderId` is required; `returnUrl` / `cancelUrl` are optional and, when supplied, must point to a verified domain of the shop (open-redirect protected). Branch on the returned `payment.flow`: `ONLINE_REDIRECT` → redirect to `payment.redirectUrl`, `ONLINE_EMBEDDED` → render a widget with `payment.clientSecret`, `INSTANT_DIRECT` → already settled, read `payment.status`. Public, but ownership-checked — an authenticated customer cannot pay for another customer's order. **Idempotent** — calling it again for the same order returns the existing still-valid session instead of creating a duplicate (safe to retry). Rate limit: 5 requests/minute. `userErrors[].code`: `ORDER_NOT_FOUND`, `ORDER_ALREADY_PAID`, `ORDER_NOT_PAYABLE`, `PAYMENT_PROVIDER_NOT_CONFIGURED`, `RETURN_URL_INVALID`, `INVALID_ID_FORMAT`, `PAYMENT_FAILED`, `INSTRUMENT_PRESELECTION_FAILED`. `warnings[]` array zawiera `INSTRUMENT_CLEARED_FOR_RETRY` post-auto-clear instrument-specific failure (storefront retry hint: next attempt uses gateway default landing).",
       "variables": [
         {
           "name": "input",
@@ -1623,9 +1623,29 @@
       ],
       "fragmentRefs": [
         "PaymentSession",
+        "PaymentWarning",
         "UserError"
       ],
-      "body": "mutation PaymentCreate($input: PaymentCreateInput!) {\n  paymentCreate(input: $input) {\n    payment {\n      ...PaymentSession\n    }\n    userErrors {\n      ...UserError\n    }\n  }\n}"
+      "body": "mutation PaymentCreate($input: PaymentCreateInput!) {\n  paymentCreate(input: $input) {\n    payment {\n      ...PaymentSession\n    }\n    userErrors {\n      ...UserError\n    }\n    warnings {\n      ...PaymentWarning\n    }\n  }\n}"
+    },
+    {
+      "name": "CartClearPaymentSelection",
+      "kind": "mutation",
+      "section": "Cart Completion Mutations",
+      "description": "Clears all payment selection state on the cart in a single atomic operation. Use for accordion \"back to method picker\" flows w storefront UI. Idempotent — calling twice yields the same end state. Cart MUSI być `ACTIVE` (CONVERTED carts reject z `ALREADY_COMPLETED`). Rate limit: 30 requests/minute per IP+shop.",
+      "variables": [
+        {
+          "name": "input",
+          "type": "CartClearPaymentSelectionInput!",
+          "defaultValue": null
+        }
+      ],
+      "fragmentRefs": [
+        "Cart",
+        "CartWarning",
+        "UserError"
+      ],
+      "body": "mutation CartClearPaymentSelection($input: CartClearPaymentSelectionInput!) {\n  cartClearPaymentSelection(input: $input) {\n    cart {\n      ...Cart\n    }\n    userErrors {\n      ...UserError\n    }\n    warnings {\n      ...CartWarning\n    }\n  }\n}"
     },
     {
       "name": "ReturnCreate",
@@ -2177,7 +2197,7 @@
         "MailingAddress",
         "PageInfo"
       ],
-      "body": "fragment Cart on Cart {\n  id\n  checkoutUrl\n  totalQuantity\n  cost {\n    ...CartCost\n  }\n  lines(first: 100) {\n    edges {\n      cursor\n      node {\n        ... on CartLine {\n          ...CartLine\n        }\n      }\n    }\n    nodes {\n      ... on CartLine {\n        ...CartLine\n      }\n    }\n    pageInfo {\n      ...PageInfo\n    }\n    totalCount\n  }\n  buyerIdentity {\n    ...CartBuyerIdentity\n  }\n  discountCodes {\n    ...CartDiscountCode\n  }\n  discountAllocations {\n    ...CartDiscountAllocation\n  }\n  note\n  attributes {\n    key\n    value\n  }\n  email\n  phone\n  shippingAddress {\n    ...MailingAddress\n  }\n  billingAddress {\n    ...MailingAddress\n  }\n  selectedShippingMethod {\n    ...CartShippingMethod\n  }\n  selectedPaymentMethod {\n    ...CartSelectedPaymentMethod\n  }\n  appliedGiftCards {\n    ...CartAppliedGiftCard\n  }\n  requiresShipping\n  createdAt\n  updatedAt\n  status\n  completedOrder {\n    id\n    orderNumber\n    accessToken\n    status\n    paymentStatus\n    fulfillmentStatus\n  }\n}",
+      "body": "fragment Cart on Cart {\n  id\n  checkoutUrl\n  totalQuantity\n  cost {\n    ...CartCost\n  }\n  lines(first: 100) {\n    edges {\n      cursor\n      node {\n        ... on CartLine {\n          ...CartLine\n        }\n      }\n    }\n    nodes {\n      ... on CartLine {\n        ...CartLine\n      }\n    }\n    pageInfo {\n      ...PageInfo\n    }\n    totalCount\n  }\n  buyerIdentity {\n    ...CartBuyerIdentity\n  }\n  discountCodes {\n    ...CartDiscountCode\n  }\n  discountAllocations {\n    ...CartDiscountAllocation\n  }\n  note\n  attributes {\n    key\n    value\n  }\n  email\n  phone\n  shippingAddress {\n    ...MailingAddress\n  }\n  billingAddress {\n    ...MailingAddress\n  }\n  selectedShippingMethod {\n    ...CartShippingMethod\n  }\n  selectedPaymentMethod {\n    ...CartSelectedPaymentMethod\n  }\n  selectedPaymentInstrumentCode\n  appliedGiftCards {\n    ...CartAppliedGiftCard\n  }\n  requiresShipping\n  createdAt\n  updatedAt\n  status\n  completedOrder {\n    id\n    orderNumber\n    accessToken\n    status\n    paymentStatus\n    fulfillmentStatus\n  }\n}",
       "onType": "Cart"
     },
     {
@@ -2330,13 +2350,25 @@
       "onType": "Shop"
     },
     {
-      "name": "PaymentMethod",
+      "name": "PaymentMethodInstrument",
       "kind": "fragment",
       "section": "Payment Methods",
-      "description": "Single payment method enabled for the shop — type (CARD / BANK_TRANSFER / BLIK / PAYPAL / APPLE_PAY / GOOGLE_PAY / CASH_ON_DELIVERY / OTHER), provider, icon, supported currencies, default flag, sort position. Spread on the checkout payment step.",
+      "description": "A single concrete instrument exposed by a gateway provider (BLIK code, branded bank, wallet, card brand). Pass `instrumentCode` as `preferredInstrumentCode` in `cartSelectPaymentMethod` for direct deep-link to that instrument screen on the gateway. `displayHint` is a semantic UX hint (`PIN_ENTRY`, `WALLET_TAP`, `BANK_LIST`, `CARD_FORM`) — storefront branches rendering accordingly. `enabled: false` means the gateway reported the instrument as temporarily disabled — gray out, don't hide.",
       "variables": [],
       "fragmentRefs": [],
-      "body": "fragment PaymentMethod on PaymentMethod {\n  id\n  name\n  provider\n  type\n  icon\n  description\n  isDefault\n  supportedCurrencies\n  position\n}",
+      "body": "fragment PaymentMethodInstrument on PaymentMethodInstrument {\n  providerCode\n  instrumentCode\n  type\n  displayName\n  displayHint\n  brandImageUrl\n  enabled\n}",
+      "onType": "PaymentMethodInstrument"
+    },
+    {
+      "name": "PaymentMethod",
+      "kind": "fragment",
+      "section": "Payment Methods",
+      "description": "Single payment method enabled for the shop — method-centric. `type` is the category (CARD, BLIK, BANK_TRANSFER, CASH_ON_DELIVERY, OTHER) — drive iconography here. `provider`, `providersAvailable`, `preferredProvider` are `ProviderCode` enum (UPPERCASE: `PAYU`, `PRZELEWY24`, ...). `available` is `false` when the resolving gateway is temporarily unavailable or reported the method as disabled — gray-out the tile, don't hide it; `unavailableReason` carries the diagnostic. `instruments` lists concrete gateway-side instruments (BLIK code, branded banks, wallets) when the gateway exposes granular data — pass `instrumentCode` as `preferredInstrumentCode` in `cartSelectPaymentMethod` for direct deep-link to that instrument screen on the gateway. Spread on the checkout payment step.",
+      "variables": [],
+      "fragmentRefs": [
+        "PaymentMethodInstrument"
+      ],
+      "body": "fragment PaymentMethod on PaymentMethod {\n  id\n  name\n  provider\n  type\n  icon\n  description\n  isDefault\n  supportedCurrencies\n  position\n  providersAvailable\n  preferredProvider\n  available\n  unavailableReason\n  instruments {\n    ...PaymentMethodInstrument\n  }\n}",
       "onType": "PaymentMethod"
     },
     {
@@ -2361,6 +2393,16 @@
       "body": "fragment PaymentSession on PaymentSession {\n  id\n  orderId\n  flow\n  provider\n  redirectUrl\n  clientSecret\n  status\n  expiresAt\n}",
       "onType": "PaymentSession"
     },
+    {
+      "name": "PaymentWarning",
+      "kind": "fragment",
+      "section": "Payment Methods",
+      "description": "Non-blocking signal emitted alongside `userErrors[]` in `paymentCreate` payload — backend state change context (e.g. an auto-clear of preselected instrument after gateway rejection). Pre-translated by backend per shop locale. `code === 'INSTRUMENT_CLEARED_FOR_RETRY'` signals storefront that the next `paymentCreate` will land on the gateway default landing page (server-side cleared `Order.paymentInstrumentCode` after `INSTRUMENT_PRESELECTION_FAILED`). `retryHint` is optional context for UI dispatch — currently unused for `INSTRUMENT_CLEARED_FOR_RETRY`, reserved for future warning codes.",
+      "variables": [],
+      "fragmentRefs": [],
+      "body": "fragment PaymentWarning on PaymentWarning {\n  message\n  code\n  retryHint\n}",
+      "onType": "PaymentWarning"
+    },
     {
       "name": "ShipmentEvent",
       "kind": "fragment",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doswiftly/storefront-operations",
-  "version": "16.1.0",
+  "version": "17.0.0",
   "description": "GraphQL operations for DoSwiftly Storefront - SSOT from backend",
   "homepage": "https://doswiftly.pl",
   "publishConfig": {

package/schema.graphql

@@ -880,7 +880,9 @@ type Cart implements Node {
   """
   attributes: [CartAttribute!]!
 
-  """Available payment methods dla tego cart (shop-configured providers)"""
+  """
+  Available payment methods dla tego carta — deduplikowane per type, sorted by merchant priority.
+  """
   availablePaymentMethods: [PaymentMethod!]!
 
   """
@@ -955,6 +957,11 @@ type Cart implements Node {
   """
   requiresShipping: Boolean!
 
+  """
+  Optional concrete instrument code selected within `selectedPaymentMethod` (e.g. `"blik"`, `"mb"`, `"154"`). Set gdy klient klika konkretny instrument tile na storefront (per `PaymentMethod.instruments`). Pre-payment intent: skopiowany do `Order.paymentInstrumentCode` przy `cartComplete`. Storefront może cross-reference z `availablePaymentMethods.methods[].instruments[]` żeby dostać `displayName` / `brandImageUrl`. Added by payment-instrument-preselection core sprint Req 3 AC7.
+  """
+  selectedPaymentInstrumentCode: String
+
   """
   The payment method currently selected on the cart. Null until the buyer picks a method via `cartSelectPaymentMethod`.
   """
@@ -982,6 +989,11 @@ type Cart implements Node {
 
   """When the cart was last modified (ISO 8601)."""
   updatedAt: DateTime!
+
+  """
+  Non-fatal advisories computed at query time. Currently emitted: `PAYMENT_SELECTION_STALE` when `selectedPaymentMethod` / `selectedPaymentInstrumentCode` are no longer in live gateway capabilities (storefront re-prompts the buyer). Read-only — backend state is not mutated. Added by payment-instrument-preselection-advanced sub-sprint Adv-2 Req 1.
+  """
+  warnings: [CartWarning!]!
 }
 
 """Result of `cartAddLines`."""
@@ -1171,6 +1183,30 @@ input CartBuyerIdentityInput {
   phone: String
 }
 
+"""
+Input for `cartClearPaymentSelection` — explicit deselect mutation. Use when the buyer goes back to the payment method picker w accordion UI bez hack typu re-selectując method. Atomic NULL na wszystkich payment selection fields (method type + provider code + instrument code + legacy method ID). Idempotent — wielokrotne wywołanie = same final state. Added by payment-instrument-preselection-advanced Adv-1 Req 3.1.
+"""
+input CartClearPaymentSelectionInput {
+  """ID of the cart to clear payment selection on."""
+  cartId: ID!
+}
+
+"""
+Result of `cartClearPaymentSelection`. `cart` populated on success z cleared selection fields (`selectedPaymentMethod === null`, `selectedPaymentInstrumentCode === null`). `userErrors` populated gdy cart locked (CONVERTED status → `ALREADY_COMPLETED` code).
+"""
+type CartClearPaymentSelectionPayload {
+  """The updated cart z cleared payment selection."""
+  cart: Cart
+
+  """
+  Business / validation errors carrying a stable `CartErrorCode` in `code` (e.g. `ALREADY_COMPLETED`).
+  """
+  userErrors: [UserError!]!
+
+  """Non-fatal advisories — the mutation itself succeeded."""
+  warnings: [CartWarning!]!
+}
+
 """Input for `cartComplete` — finalises the cart into an `Order`."""
 input CartCompleteInput {
   """ID of the cart to complete."""
@@ -1551,15 +1587,27 @@ type CartRemoveLinesPayload {
   warnings: [CartWarning!]!
 }
 
-"""Input for `cartSelectPaymentMethod`."""
+"""
+Input for `cartSelectPaymentMethod` (Intelligent Payment Methods). Method-centric: the buyer picks a category (BLIK, CARD, BANK_TRANSFER, ...) and the backend resolves the preferred provider from `MerchantPaymentConfig` (priority-sorted, merchant-configurable per shop). Optional `preferredProviderCode` + `preferredInstrumentCode` enable instrument-level deep-link na gateway hosted page (skipa default landing).
+"""
 input CartSelectPaymentMethodInput {
   """ID of the cart to update."""
   cartId: ID!
 
   """
-  ID of the chosen payment method (matches a `PaymentMethod.id` from `availablePaymentMethods`).
+  Category of the payment method the buyer picked (matches `PaymentMethod.type` from `availablePaymentMethods`).
+  """
+  methodType: PaymentMethodType!
+
   """
-  paymentMethodId: ID!
+  Optional gateway-specific instrument code (`blik`, `mb`, `c`, `154`, ...) z `PaymentMethod.instruments[].instrumentCode`. Wymaga ustawienia `preferredProviderCode` — instrument code jest provider-specific. Bez restrictive regex (różne bramki używają `.` / `:` / `/` w przyszłości). SQL injection chroniona przez Prisma parametrized queries. Added by payment-instrument-preselection core sprint Req 3.1.
+  """
+  preferredInstrumentCode: String
+
+  """
+  Optional override of `PaymentMethod.preferredProvider`. Pass a provider code (`payu`, `przelewy24`, ...) from `providersAvailable` when the buyer explicitly picks one (rare — usually the merchant priority is enough). Format: lowercase alphanumerics + underscore + hyphen, 2-50 characters. Renamed from `preferredProviderId` — `*Code` is reserved for lowercase string identifiers, `*Id` for UUIDs.
+  """
+  preferredProviderCode: String
 }
 
 """Result of `cartSelectPaymentMethod`."""
@@ -1807,6 +1855,7 @@ enum CartWarningCode {
   MERCHANDISE_NOT_AVAILABLE
   MERCHANDISE_NOT_ENOUGH_STOCK
   PAYMENTS_AMOUNT_REGION_MISMATCH
+  PAYMENT_SELECTION_STALE
   SHIPPING_METHOD_AUTO_CLEARED
 }
 
@@ -3843,6 +3892,11 @@ type Mutation {
   """
   cartApplyGiftCard(input: CartApplyGiftCardInput!): CartApplyGiftCardPayload!
 
+  """
+  Clear all payment selection state on the cart in a single atomic operation. Use for accordion "back to method picker" flows w storefront UI. Idempotent — calling twice yields the same end state. Cart MUSI być `ACTIVE` (CONVERTED carts reject z `ALREADY_COMPLETED`).
+  """
+  cartClearPaymentSelection(input: CartClearPaymentSelectionInput!): CartClearPaymentSelectionPayload!
+
   """
   Finalise the cart into an `Order`. The cart is locked and no longer accepts mutations. Payment is initiated separately via `paymentCreate` — check `order.canCreatePayment` to decide whether to render a "Pay now" button or send the buyer directly to the confirmation page (for offline methods such as cash on delivery). Rate-limited to 5 requests per minute per IP+shop; pass an `idempotencyKey` to guard against duplicate orders on retry.
   """
@@ -3869,7 +3923,7 @@ type Mutation {
   cartRemoveLines(id: ID!, lineIds: [ID!]!): CartRemoveLinesPayload!
 
   """
-  Select a payment method on the cart. Validates against the active shop payment methods and currency. The selection is finalised at `cartComplete`; payment itself is initiated via a separate `paymentCreate` mutation after the order is created.
+  Select a payment method on the cart by category (BLIK, CARD, BANK_TRANSFER, ...). Backend resolves the preferred provider from `MerchantPaymentConfig` at `paymentCreate` time. Optional `preferredProviderCode` overrides the merchant priority when the buyer explicitly picks a gateway from `PaymentMethod.providersAvailable`. Optional `preferredInstrumentCode` enables instrument-level deep-link na gateway hosted page (BLIK ekran, mBank flow, etc.) — wymaga `preferredProviderCode`.
   """
   cartSelectPaymentMethod(input: CartSelectPaymentMethodInput!): CartSelectPaymentMethodPayload!
 
@@ -4337,9 +4391,14 @@ type PaymentCreatePayload {
   payment: PaymentSession
 
   """
-  Business / validation errors carrying a stable `PaymentErrorCode` in `code` (e.g. `ORDER_NOT_FOUND`, `ORDER_ALREADY_PAID`, `ORDER_NOT_PAYABLE`, `PAYMENT_PROVIDER_NOT_CONFIGURED`, `RETURN_URL_INVALID`, `PAYMENT_FAILED`).
+  Business / validation errors carrying a stable `PaymentErrorCode` in `code` (e.g. `ORDER_NOT_FOUND`, `ORDER_ALREADY_PAID`, `ORDER_NOT_PAYABLE`, `PAYMENT_PROVIDER_NOT_CONFIGURED`, `RETURN_URL_INVALID`, `PAYMENT_FAILED`, `INSTRUMENT_PRESELECTION_FAILED`).
   """
   userErrors: [UserError!]!
+
+  """
+  Non-blocking signals — backend state change context (e.g. instrument auto-cleared, server-side adjustment). Default empty array. Storefront branches per `code` for UI retry hints / analytics events. Added by payment-instrument-preselection-advanced Adv-1 Req 2.3.
+  """
+  warnings: [PaymentWarning!]!
 }
 
 """
@@ -4356,6 +4415,11 @@ enum PaymentInitiationFlow {
 A payment method offered to the buyer at checkout — what to render in the payment picker and pass to `cartSelectPaymentMethod`.
 """
 type PaymentMethod {
+  """
+  True when the buyer can actually pick this method right now. False when the resolving gateway is temporarily unavailable (incident/maintenance) or reported the method as disabled. Storefront UI should gray-out the tile when false instead of hiding it — gives merchants observability into routing failures.
+  """
+  available: Boolean!
+
   """
   Optional buyer-facing description shown under the name (e.g. "Pay with your bank app").
   """
@@ -4371,6 +4435,11 @@ type PaymentMethod {
   """
   id: ID!
 
+  """
+  Concrete instruments exposed by gateway providers w obrębie tej method (BLIK code, branded banks, wallets, card brands). Null gdy żaden provider nie expose'uje granular data dla tej method. Empty array gdy gateway expose'uje ale wszystkie instruments są disabled lub po post-filter (cross-provider leak prevention). Storefront może wyrenderować listę i pass `instrumentCode` jako `preferredInstrumentCode` w `cartSelectPaymentMethod` → gateway deep-link na ten ekran. Added by payment-instrument-preselection core sprint Req 1.
+  """
+  instruments: [PaymentMethodInstrument!]
+
   """
   True when the merchant has marked this method as the default. Pre-select it in the picker.
   """
@@ -4387,9 +4456,19 @@ type PaymentMethod {
   position: Float!
 
   """
-  Provider code (e.g. "payu", "stripe", "p24", "cash_on_delivery"). Identifies the integration behind the method; do not branch UI on it — use `type` instead.
+  Preferred provider code (UPPERCASE enum) that the backend will route to when the buyer picks this method type and does not specify `preferredProviderCode`. Populated only when at least one provider supports the type. Typed enum since core sprint payment-instrument-preselection (was `String` pre-v9.0).
   """
-  provider: String!
+  preferredProvider: ProviderCode
+
+  """
+  Provider code (e.g. `PAYU`, `STRIPE`, `PRZELEWY24`, `CASH_ON_DELIVERY`). Identifies the integration behind the method; do not branch UI on it — use `type` instead. Typed enum since core sprint payment-instrument-preselection (was `String` pre-v9.0).
+  """
+  provider: ProviderCode!
+
+  """
+  Provider codes (UPPERCASE enum: `PAYU`, `PRZELEWY24`, ...) that can fulfil this method type for the current shop, ordered by merchant priority. Pre-select `preferredProvider`; expose the rest only when the buyer wants to choose explicitly. Single-element array when only one provider supports the type. Typed enum since core sprint payment-instrument-preselection (was `[String]` pre-v9.0).
+  """
+  providersAvailable: [ProviderCode!]
 
   """
   ISO 4217 currency codes the method accepts. Null when the method accepts the shop currency without restriction.
@@ -4400,6 +4479,72 @@ type PaymentMethod {
   Category of the method (CARD, BLIK, BANK_TRANSFER, CASH_ON_DELIVERY, OTHER). Drives iconography and copy.
   """
   type: PaymentMethodType!
+
+  """
+  When `available` is false, this enum carries the diagnostic reason (GATEWAY_DOWN, GATEWAY_DISABLED, NO_INSTRUMENTS, CREDENTIALS_INVALID). Null when `available` is true. UI can render context-aware copy ("PayU is temporarily down" vs "Method not configured").
+  """
+  unavailableReason: PaymentMethodUnavailableReason
+}
+
+"""
+A single concrete instrument exposed by a gateway provider (e.g. BLIK code, mBank Pay-By-Link, Apple Pay) within a broader PaymentMethod. Pass `instrumentCode` jako `preferredInstrumentCode` w `cartSelectPaymentMethod` żeby gateway deep-link prosto na ten ekran.
+"""
+type PaymentMethodInstrument {
+  """
+  Optional brand image URL (bank logo, wallet icon). Storefront może użyć jako tile artwork. Null gdy gateway nie expose'uje albo instrument nie ma brand visual (BLIK code).
+  """
+  brandImageUrl: String
+
+  """
+  UX rendering hint — jak storefront powinien wyrenderować ten instrument (prominent button vs branded tile vs dropdown vs radio). Backend-agnostic mapping na visual treatment.
+  """
+  displayHint: PaymentMethodInstrumentDisplayHint!
+
+  """
+  Buyer-facing display name (e.g. "BLIK", "mBank", "ING Bank Śląski", "Apple Pay"). Lokalizacja zazwyczaj PL/EN — multi-language defer post-v1.
+  """
+  displayName: String!
+
+  """
+  True gdy instrument jest currently enabled w gateway live capabilities. Storefront może gray-out tile gdy false zamiast hide (observability dla merchant).
+  """
+  enabled: Boolean!
+
+  """
+  Gateway-specific instrument identifier (PayU: `"blik"`/`"mb"`/`"c"`, P24: numeric ID string `"154"`). Pass jako `preferredInstrumentCode` w `cartSelectPaymentMethod`. Stabilne per provider — gateway nie renumeruje.
+  """
+  instrumentCode: String!
+
+  """
+  Provider obsługujący ten instrument (UPPERCASE enum). Wymagane dla cross-provider dedupe (np. BLIK code dostępny zarówno przez PayU jak P24 — różne instrumenty mimo tej samej method type).
+  """
+  providerCode: ProviderCode!
+
+  """
+  Semantic type klasyfikujący instrument w obrębie method (BLIK code vs bank vs wallet vs card brand). Storefront-facing dispatch dla per-instrument UI components.
+  """
+  type: PaymentMethodInstrumentType!
+}
+
+"""
+UX rendering hint dla payment instrument — storefront może przełączać między prominent button / branded tile / dropdown / radio per hint. Backend-agnostic mapping na visual treatment.
+"""
+enum PaymentMethodInstrumentDisplayHint {
+  BRANDED_TILE
+  DROPDOWN_OPTION
+  PROMINENT_BUTTON
+  RADIO_OPTION
+}
+
+"""
+Klasyfikacja konkretnego instrumentu w obrębie PaymentMethod (BLIK kod vs bank vs wallet vs card brand). Storefront-facing typing dla per-instrument UI dispatch.
+"""
+enum PaymentMethodInstrumentType {
+  BANK
+  BLIK_CODE
+  CARD_BRAND
+  OTHER
+  WALLET
 }
 
 """
@@ -4413,6 +4558,16 @@ enum PaymentMethodType {
   OTHER
 }
 
+"""
+Why a payment method is currently unavailable. GATEWAY_DOWN/DISABLED/NO_INSTRUMENTS are transient (gateway-side); CREDENTIALS_INVALID needs merchant action in the admin panel.
+"""
+enum PaymentMethodUnavailableReason {
+  CREDENTIALS_INVALID
+  GATEWAY_DISABLED
+  GATEWAY_DOWN
+  NO_INSTRUMENTS
+}
+
 """
 Payment session created for an order. Branch on `flow` to launch payment: ONLINE_REDIRECT → redirect to `redirectUrl`; ONLINE_EMBEDDED → render an in-page widget using `clientSecret`; INSTANT_DIRECT → the payment is already settled, check `status`.
 """
@@ -4471,6 +4626,33 @@ type PaymentSettings {
   paymentProviders: [String!]!
 }
 
+"""
+Non-blocking signal emitted alongside `userErrors` — backend state change context (e.g. an auto-clear, a server-side adjustment) that the storefront may surface as a retry hint or analytics event. Always pre-translated by backend per shop locale.
+"""
+type PaymentWarning {
+  """
+  Machine-readable code — branch on this to dispatch UI retry hints. Add a new code only when there is a distinct UX response.
+  """
+  code: PaymentWarningCode!
+
+  """
+  Pre-translated user-facing message describing what happened (Polish-first per shop locale).
+  """
+  message: String!
+
+  """
+  Optional additional hint string for UI dispatch — currently unused for `INSTRUMENT_CLEARED_FOR_RETRY` (semantic encoded in `message`). Reserved for future warning codes (e.g. `SLOW_GATEWAY_RESPONSE` → "Retry in 30s").
+  """
+  retryHint: String
+}
+
+"""
+Machine-readable code for `PaymentWarning.code`. Non-blocking signals from payment mutations — branch on this to dispatch UI retry hints. `INSTRUMENT_CLEARED_FOR_RETRY` indicates backend auto-cleared a preselected payment instrument after gateway rejection; next `paymentCreate` will land on the gateway default page.
+"""
+enum PaymentWarningCode {
+  INSTRUMENT_CLEARED_FOR_RETRY
+}
+
 """
 A pickup point (parcel locker or staffed collection point) attached to a delivery address. The buyer picks it in the carrier widget; it is persisted on the cart shipping address and carried through to the order.
 """
@@ -5161,6 +5343,20 @@ enum ProductVisibility {
   PUBLIC
 }
 
+"""
+Canonical payment provider identifier (UPPERCASE per GraphQL convention). Use for `Order.paymentMethod`, `Payment.provider`, `PaymentMethod.providersAvailable`, `PaymentMethod.preferredProvider`. Add new providers in `@doswiftly/commerce-policy/provider-codes.ts` SSOT registry.
+"""
+enum ProviderCode {
+  BANK_TRANSFER
+  CASH_ON_DELIVERY
+  GIFT_CARD
+  MANUAL_PAYMENT
+  PAYU
+  PRZELEWY24
+  STRIPE
+  TEST_GATEWAY
+}
+
 type Query {
   """List of all currencies supported by the system (ECB rates)"""
   allSupportedCurrencies: [Currency!]!
@@ -5171,7 +5367,7 @@ type Query {
   attributeOptionsSearch(input: AttributeOptionsSearchInput!): AttributeFilterValueConnection!
 
   """
-  Payment methods active for the current shop, plus the merchant default. Shop-level — independent of cart contents in this iteration. Fetch once for the checkout payment step.
+  Payment methods active for the current shop, plus the merchant default. Returns one row per `PaymentMethodType` (BLIK, CARD, BANK_TRANSFER, ...) with `providersAvailable` (provider codes sorted by merchant priority) and `preferredProvider` (the head of the list). Shop-level — independent of cart contents.
   """
   availablePaymentMethods: AvailablePaymentMethods!