feat: add optional display_order to payment handlers

[prasad-stripe]

Payment handler display order (merchant-suggested ordering)

Description

Please include a summary of the changes and the related issue. Please also
include relevant motivation and context.

Adds an optional display_order field to each payment handler in
payment_handlers. Businesses (merchants) can set an integer per handler
(lower = higher preference) to suggest how payment methods should be ordered
when presented to the user. The ordering is suggestive only: platforms and
agents MAY reorder (e.g. for user preference, localization, or A/B tests). Addresses #170

This gives merchants a standard way to express their preferred order—e.g. for
fraud vs. conversion trade-offs—without requiring agents to follow it strictly.
Aligns with the same capability in the Agentic Commerce Protocol (ACP).

Type of change

Please delete options that are not relevant.

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing
  functionality to not work as expected, including removal of schema files
  or fields)
• Documentation update

---

Is this a Breaking Change or Removal?

N/A — optional additive field only.

---

Motivation and context

Today the ordering of payment methods on the platform or agent side is
unspecified. Merchants know what works best for their fraud/conversion
trade-off and should be able to suggest an order at the spec level.

Fixes/Addresses: #[issue number] (fill in the UCP issue number you created)

---

Example

Handler with display_order:

{
  "id": "processor_tokenizer_1234",
  "version": "2026-01-11",
  "spec": "https://example.com/ucp/handler",
  "schema": "https://example.com/ucp/handler/schema.json",
  "config": { "environment": "production", "business_id": "business_xyz_789" },
  "display_order": 0
}

Lower display_order = higher preference (e.g. show first). Omission means no
suggestion.

---

Checklist

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• Any dependent changes have been merged and published in downstream modules

---

Pull Request Title

Use Conventional Commits, e.g.:

feat: add optional display_order to payment handlers

---

Files changed

• Schema: source/schemas/payment_handler.json — added optional
  display_order (integer) to base definition.
• Docs: docs/specification/payment-handler-guide.md — added
  display_order to Business Schema example and a short description of the
  field.

---

Additional notes

• Backward compatible: Optional field; existing implementations can ignore
  unknown properties. No breaking changes.
• If this project regenerates TypeScript types from the JSON schemas (e.g. via
  a script that reads source/schemas), re-run the generator so
  display_order appears in the generated types.
• Same capability is implemented in the Agentic Commerce Protocol (ACP); this
  keeps UCP and ACP aligned for merchant-suggested payment handler ordering.

[raginpirate]

Gave feedback in the issue description, as higher-level alignment on the solution will help drive this PR shape ❤️ 🚀
#170 (comment)

[prasad-stripe]

Gave feedback in the issue description, as higher-level alignment on the solution will help drive this PR shape ❤️ 🚀 #170 (comment)

Thanks @raginpirate — great point about handlers not being 1:1 with payment methods.

I've updated PR #176 to move display_order from the handler level to available_instruments. It's now an optional integer on available_payment_instrument.json, relative across all instruments across all handlers in the response. This handles both use cases: ordering funding sources (card before bank) and ordering distinct payment paths (card via Google Pay before card via direct entry).

Kept it to a single layer (instruments only) to keep semantics simple — we can add handler-level ordering later if needed. Would appreciate another look on the PR when you get a chance.

[kmcduffie]

@prasad-stripe Thanks for the PR! A few questions in line.

[kmcduffie]

An alternative might be that the spec does not support duplicate values in a given payload.

I'd like to better understand the use case you're thinking of that's driving this modeling where there could be collisions?

[kmcduffie]

This field shares the same name as the first field in this comment. Did you mean for this to be different than the display_order above?

[kmcduffie]

I don't believe a handler will know of any other handlers. Can the display_order be across all handlers, or is more signaling the priority within the instruments returned by this handler?

[raginpirate]

fwiw this PR is great @prasad-stripe, I got to catch @igrigorik async for a moment on this and I think there might be a higher level abstraction here for how we generally offer ordering hints across UCP for arrays... we're thinking about this and will circle back, if you don't also come up with something 😄

TLDR; seems like this isn't just a payments concern!

[archrao]

Adding some thoughts for discussion to provide ordering hints for arrays within UCP objects (like available_instruments, line_items, totals, etc.)

Option 1: Sibling _hints Object
This approach adds a new JSON object alongside the array, named by convention as [array_field_name]_hints.
"available_instruments": [
{ "id": "instr_card", "type": "card", "description": "Major credit/debit cards" },
{ "id": "instr_paypal", "type": "ewallet", "description": "Pay with PayPal" },
{ "id": "instr_bnpl_klarna", "type": "bnpl", "description": "Pay over time with Klarna" }
],
"available_instruments_hints": {
"item_ids": ["instr_card", "instr_paypal", "instr_bnpl_klarna"],
"order": [
"instr_card",
"instr_paypal",
"instr_bnpl_klarna"
]}
This option is clean but could increase payload.

Option 2: In-Item _display Hints
This approach adds a reserved _display object within each item of the array that needs hints.
"available_instruments": [
{
"id": "instr_card",
"type": "card",
"description": "Major credit/debit cards",
"_display": {
"order": 1
}
}]
This option is more payload efficient and hints are co-located with the item.