Choose a payment method
Customer App can present payment choices after it reads the current business, cart, checkout context, customer state, and device capability. A choice shown on screen is a candidate for that state. It is not proof that the method can be authorized, charged, confirmed, or used to create an order.
:::warning Important boundary
Do not select, reopen, or switch a payment choice to test whether an earlier attempt settled. A selection, external return, provider message, closed dialog, or changed screen is not an authoritative payment or order receipt.
:::
What the method list means
The list can be assembled from current business and project settings, cart and fulfillment state, customer or guest state, device platform, provider capability, and the checkout variant. It can change after any of those inputs change.
| Visible state | Safe interpretation |
|---|---|
| Loading choices | Eligibility and supporting capability reads are unresolved |
| One or more choices | The app has candidate methods for the current state |
| No choices | No eligible choice was returned or retained for the current state |
| A choice disappears | A relevant cart, account, device, project, or provider condition changed |
| A choice is disabled | At least one current requirement is unresolved |
Do not infer that a hidden method is unavailable everywhere or that a visible method is available for every cart.
Selection and persistence are different
| Layer | What may happen | What it does not prove |
|---|---|---|
| List read | Customer App receives and filters method capability data | Payment authorization or provider readiness |
| Local selection | A choice becomes highlighted or its detail surface opens | That the cart stored the choice |
| Cart persistence | The selected method or supporting state is written to the cart | That a provider accepted it |
| Provider handoff | An embedded, external, redirect, SDK, or native surface receives control | Payment settlement or order creation |
| Confirmation | Ordering reconciles a pending cart or group | That every provider, wallet, or order effect completed |
| Order state | An authorized Ordering order is visible | That every external financial effect has settled |
Some method families persist selection automatically, while others wait for additional method data. Treat visible highlighting and stored cart state as separate unless the current checkout reconciles them.
Automatic selection and zero-balance behavior
When only one method remains, the current source can select it automatically. That automatic choice can also enter the normal persistence boundary. It is not customer authorization, payment confirmation, or consent to an external provider action.
When the current balance is zero, Customer App can clear the local payment selection and explain that no payment choice is needed. That presentation does not itself prove the final cart total, placement result, discount settlement, wallet state, or order creation.
External and native payment boundaries
Method families can use different handoff classes:
| Handoff class | Customer-safe boundary |
|---|---|
| Embedded provider view | Web content, messages, navigation, and Ordering state settle separately |
| External redirect | Leaving and returning to Customer App does not establish success or cancellation |
| Provider SDK | A local SDK result is provider input, not an Ordering receipt |
| Native wallet sheet | Device capability and local confirmation remain separate from cart and order settlement |
| Saved-instrument surface | Masked presentation and selection remain separate from ownership and authorization |
Closing, cancelling, returning, or seeing a provider result can leave the outcome unknown. Do not use Back, foregrounding, reopening, or another method as a diagnostic.
Saved cards, wallets, and checkout variants
- Saved cards can require separate capability, credential, account ownership, list, selection, and provider checks. A masked card does not prove it can be used.
- Wallet availability and wallet balance are separate from payment-method availability. In grouped checkout, selecting or removing a wallet can change shared group state rather than only local presentation.
- Gift-card and zero-balance carts can use different method sources or omit the ordinary method list.
- Grouped checkout can expose different method families and settlement rules from a single-business checkout. One member or one visible choice does not prove group-wide eligibility.
- Guest checkout can require account conversion for some method families. Conversion, session, guest-data transfer, payment, and order placement remain separate outcomes.
Credentials are not payment authorization
Customer App or a provider component can read capability or public integration credentials to decide whether a method can render. Those reads do not authorize a payment, identify the correct customer or cart, prove a saved instrument is owned by the current account, confirm the final financial context, or create an order.
A safe payment result must remain bound to the current authorized account, project, session, cart or group, business, method, financial revision, and operation generation. Customer-facing method details, provider responses, and navigation are not substitutes for that authoritative settlement.
Unknown and partial outcomes
| Observed state | Safe response |
|---|---|
| Choice highlighted but cart state is unclear | Treat selection persistence as unresolved |
| Provider surface did not open | Do not assume that no method or cart write occurred |
| Provider surface closed or returned | Do not infer success, cancellation, or no effect |
| Loading ended with an error | Treat provider, payment, wallet, cart, and order settlement as separate |
| Method changed after account or project change | Treat the prior result as stale |
| One grouped member advances | Keep every other member unresolved |
| An order appears | Use it only as the current authorized Ordering order state |
| No order appears | Absence in one view does not prove that no financial effect occurred |
While settlement is unknown, do not select another method or repeat payment, confirmation, wallet, or placement work. Use the ordinary Orders surface only as Ordering state; if uncertainty remains, use an approved support channel.
Troubleshoot safely
| What you observe | Safe next check |
|---|---|
| Method list is still loading | Wait without reopening Checkout or changing context as a test |
| No methods appear | Confirm the current cart and fulfillment state; do not infer global availability |
| The sole method becomes selected | Treat it as automatic selection, not payment authorization |
| Selection does not remain highlighted | Treat local and persisted selection as unresolved; do not repeat to diagnose |
| A method asks for account details | Use the separate account or guest-conversion boundary; do not infer payment support |
| A saved card or wallet is missing | Do not add, delete, or switch instruments as a diagnostic |
| A provider closes unexpectedly | Keep the outcome unknown and follow the no-repeat recovery guidance |
| Account, project, cart, or group changed | Disregard the stale view and rely only on the current authorized context |
Support reports should use only a value-free state class, such as “payment method selection unresolved.” Do not include payment information, card details, credentials, tokens, method or provider messages, account/cart/order identifiers, links, or private screenshots.
Privacy and accessibility
- Enter payment information only in the app's current authorized payment surface. Never send it through support or documentation evidence.
- Method labels, selection state, disabled and busy state, errors, dialogs, and external handoff consequences need clear accessible names and announcements.
- A horizontal method list must remain operable without relying only on logos, color, borders, motion, or haptics.
- At large text sizes, labels and errors should reflow without hiding the active choice or no-repeat warning. Provider return and dialog close should restore focus predictably.
- Screen-reader, keyboard, switch, safe-area, Back, and reduced-motion behavior require current-platform verification; this guide does not certify them.
Recertification triggers
Revalidate this reference after changes to method filtering, business or project configuration, cart persistence, sole-method selection, zero-balance behavior, guest conversion, saved cards, wallets, grouped or gift-card checkout, WebViews, redirects, provider SDKs, native wallets, credentials, return handling, confirmation, order settlement, session or project teardown, or accessibility primitives.
Also recertify after changes to API deployment authority, ownership and target binding, financial revisions, operation receipts, idempotency, provider callback deduplication, error mapping, or unknown-outcome recovery.