[Payment] Allow merchant to specify preferred ordering of payment

[prasad-stripe]

Summary

Today the merchant advertises payment.handlers (in the business profile and/or in the checkout response). The ordering of payment methods on the platform or agent side is unspecified: agents may treat array index as implicit ordering or use ordering in an unspecified way. This proposal adds a way for the merchant to specify a preferred ordering in the spec. The ordering is suggestive (not deterministic): the agent/platform may still override it, but the spec should allow the merchant to express preference at least.

Motivation

• Merchants have a preferred order for payment methods (e.g. “show our wallet first”, “prioritize BNPL in certain contexts”). They are best placed to suggest this ordering because they know what works for their fraud vs. conversion trade-off—which methods they trust, which convert best for their audience, and how they want to balance risk and revenue.
• Without a specified mechanism, every platform/agent invents its own interpretation (e.g. array order, alphabetical, or arbitrary), leading to inconsistent UX and no way for the merchant to communicate intent.
• Specifying a simple, suggestive ordering gives merchants a standard way to express preference while preserving platform/agent flexibility.

Goals

• Define in the spec how a merchant can indicate preferred order of payment handlers (e.g. in the handlers array or via an explicit field).
• Keep the semantics suggestive: platforms/agents MAY reorder or override; the spec does not require strict adherence.
• Avoid breaking existing implementations: ordering can be optional (e.g. “array order is the suggested order” by default or an optional display_order / priority field).

Non-Goals

• Mandating that platforms/agents always follow the merchant’s order.
• Defining UI/UX rules (e.g. how to display); only the data contract for expressing order.

Detailed Design

Option A — Explicit ordering field

• Add an optional field to each handler entry (e.g. display_order: number or priority: number) so that ordering is explicit even when serialization order differs. Again, semantics are suggestive; platform/agent may override.

Option B — Single ordered list

• Add an optional top-level field (e.g. handler_order: ["handler_id_1", "handler_id_2", ...]) that lists handler IDs in preferred order. Handlers not listed can be shown in any order after the listed ones.

Recommendation: Option A is the smallest change (clarify existing array order). Option B can be considered if the working group prefers explicit ordering specified outside of the core payment handlers.

Relevant spec surface:

• Checkout response: payment.handlers in the create-checkout (or equivalent) response

Risks and Mitigations

• Security: No new attack vectors or data exposure. Ordering is non-sensitive metadata. Mitigation: None required beyond normal spec hygiene.
• Performance: No impact. Ordering is a small optional field or list. No new network calls or heavy processing. Mitigation: N/A.
• Backward Compatibility: Optional fields only; clients that don’t understand them can ignore. Mitigation: Specify that ordering is OPTIONAL and suggestive so no client is required to change behavior.
• Complexity: Low. One optional field per handler (Option A) or one optional top-level list (Option B). Mitigation: None.

Test Plan

• Unit Tests: If the spec adds a formal field (e.g. display_order or handler_order), schema validation tests for the new field(s); valid/invalid payloads.
• Integration Tests: Business advertises ordered handlers; platform/agent parses and (optionally) respects order. Verify that responses with and without ordering are accepted and that ordering is preserved when present.
• End-to-End Tests: Merchant sets preferred order → checkout response includes handlers in that order (or with explicit order metadata) → agent/platform displays payment options; optional assertion that suggested order is used when no override is applied.

Graduation Criteria

Working Draft → Candidate:

• Schema/spec text merged and documented (with Working Draft disclaimer where applicable).
• Unit and integration tests are passing (e.g. conformance or schema tests for new/updated payment handler structures).
• Initial documentation is written (payment architecture or handler docs updated to describe ordering semantics).
• TC majority vote to advance.

Candidate → Stable:

• Adoption feedback has been collected and addressed.
• Full documentation and migration guides are published (if any migration is needed).
• TC majority vote to advance.

Implementation History

2026-02-11: Proposal submitted.

[raginpirate]

Thank you for the proposal and PR @prasad-stripe!
On the product side, I think this proposal targets how we order payment handlers, but it does conflate payment handlers being 1-1 with payment methods. Lets take a look at simple, but complex, example:

• Handler 1 is a wallet that has card and bank payment instruments
• Handler 2 is a tokenizer that has card (network tokens) and crypto payment instruments
• Handler 3 is a tokenizer that has card (PANs) and bank payment instruments

Its very interesting because... is the objective of the business to order funding sources, or order wallets, or both?
I.E.

• I want to always see funding sources ranked like [card, bank, crypto] because I know what I prefer as a business.
• I want to rank the wallet relatively; like [card, wallet, bank, crypto] because I know what converts for my buyers.

If the former product use case is what we're solving for, I think a display_order list on available_instruments (introduced here #187) could solve the problem; very similar solution to what you have, just one layer deeper!
If the later is what we want to solve for, then we may want display_order on both layers, with spec context to describe the algorithm for display ranking when ordering values live on both edges.