PaymentMethod

A payment method offered to the buyer at checkout — what to render in the payment picker and pass to cartSelectPaymentMethod.

type PaymentMethod {
  acknowledgements: [PaymentAcknowledgement!]!
  available: Boolean!
  description: String
  fee: PaymentMethodFee
  icon: Image
  id: ID!
  instruments: [PaymentInstrument!]
  isDefault: Boolean!
  name: String!
  position: Float!
  preferredProvider: PaymentProvider
  provider: PaymentProvider!
  providersAvailable: [PaymentProvider!]
  supportedCurrencies: [String!]
  type: PaymentMethodType!
  unavailableReason: PaymentMethodUnavailableReason
}

Fields

PaymentMethod.acknowledgements ● [PaymentAcknowledgement!]! non-null object

Consents the buyer can affirm before paying with this method (e.g. the Przelewy24 regulation declaration). Render each as a checkbox using statement + documents, then echo accepted codes back in PaymentCreateInput.acknowledgements. Empty when the method carries no acknowledgements.

PaymentMethod.available ● Boolean! non-null scalar

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.

PaymentMethod.description ● String scalar

Optional buyer-facing description shown under the name (e.g. "Pay with your bank app").

PaymentMethod.fee ● PaymentMethodFee object

Surcharge for picking this method, ready to render on its tile (e.g. "Cash on delivery +5 zł"). Present only when the whole method maps to one fee identity: cash on delivery, or a method whose every instrument shares it. The amount follows the provider that handles the payment by default (the preferred one) — when several providers back the method with different fee setups, per-provider amounts live on instruments[].fee. Null when identities differ, when no fee applies, or on the shop-level query — only Cart.availablePaymentMethods carries amounts.

PaymentMethod.icon ● Image object

Icon image for the method tile in the payment picker. When the merchant uploaded custom artwork, url is absolute and ready to render. When they did not, the platform emits a RELATIVE fallback path following the /icons/payment/{provider}.svg convention (provider = lowercase provider code, e.g. payu, przelewy24, bank_transfer) — such a path is NOT served by the API: either ship matching files with the storefront or ignore relative URLs and derive artwork from type. Never feed a relative url straight into an img tag.

PaymentMethod.id ● ID! non-null scalar

Stable ID of the payment method. Pass to cartSelectPaymentMethod to select it.

PaymentMethod.instruments ● [PaymentInstrument!] list object

Concrete instruments exposed by gateway providers within this method (BLIK code, branded banks, wallets, card brands). Null when no provider exposes granular data for this method. Empty array when a gateway exposes them but all instruments are disabled or removed by post-filtering (cross-provider leak prevention). Render the list and pass code as preferredInstrument (together with preferredProvider) in cartSelectPaymentMethod to deep-link the gateway to this screen. Key list items and selection state by the (provider, code) PAIR — code alone is not unique in this list (two providers can expose the same code for one method). An instrument with no brandImage whose displayName merely repeats the method category or its own code adds nothing over the method tile — consider hiding such entries and rendering the picker only when two or more presentable instruments remain.

PaymentMethod.isDefault ● Boolean! non-null scalar

True when the merchant has marked this method as the default. Pre-select it in the picker.

PaymentMethod.name ● String! non-null scalar

Display name configured by the merchant (e.g. "BLIK", "Credit card", "Cash on delivery").

PaymentMethod.position ● Float! non-null scalar

Merchant-configured display position — lower values come first in the picker.

PaymentMethod.preferredProvider ● PaymentProvider enum

Preferred provider (UPPERCASE enum) that the backend will route to when the buyer picks this method type and does not specify preferredProvider. Populated only when at least one provider supports the type.

PaymentMethod.provider ● PaymentProvider! non-null enum

Provider (e.g. PAYU, STRIPE, PRZELEWY24, CASH_ON_DELIVERY). Identifies the integration behind the method; do not branch UI on it — use type instead.

PaymentMethod.providersAvailable ● [PaymentProvider!] list enum

Providers (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.

PaymentMethod.supportedCurrencies ● [String!] list scalar

ISO 4217 currency codes the method accepts. Null when the method accepts the shop currency without restriction.

PaymentMethod.type ● PaymentMethodType! non-null enum

Category of the method (CARD, BLIK, BANK_TRANSFER, INSTALLMENT, WALLET, CASH_ON_DELIVERY, OTHER). Drives iconography and copy.

PaymentMethod.unavailableReason ● PaymentMethodUnavailableReason enum

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").

Member Of

AvailablePaymentMethods object ● Cart object