feat: add payment instruments to the order capability

[richmolj]

Description

Order confirmation pages typically want to show how the buyer paid — card vs gift card, last four, billing address — but the Order capability has no payment field today. This adds order.payment, mirroring the checkout payment object but reduced to the subset of fields relevant at order time (dropping collection-time details like handler reference, credential, and selection state).

order_payment_instrument follows the existing order-subset pattern (order_line_item, order_confirmation): a standalone read-only sibling of the checkout type carrying only id, type, amount, billing_address, and an open display block. type is an open string and display is left open so businesses snapshot whatever they present to the buyer.

Category (Required)

• Capability: New schemas (Discovery, Cart, etc.) or extensions. (Requires Maintainer approval)
• Documentation: Updates to README, or documentations regarding schema or capabilities. (Requires Maintainer approval)

Related Issues

Checklist

• I have followed the Contributing Guide (including Conventional Commits title requirements and ! for breaking changes).
• I have updated the documentation (if applicable).
• My changes pass all local linting and formatting checks.
• 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.
• (For Core/Capability) I have included/updated the relevant JSON schemas.
• I have regenerated Python Pydantic models by running generate_models.sh under python_sdk.

Screenshots / Logs (if applicable)

Rendered Order Payment Instrument schema table:

Name	Type	Required	Description
id	string	Yes	Identifier for this instrument instance.
type	string	Yes	The broad category of the instrument (e.g., 'card', 'gift_card').
amount	Amount	No	The amount charged to this instrument, in the order currency's minor units (ISO 4217).
billing_address	Postal Address	No	The billing address associated with this payment method.
display	object	No	Display information for this payment instrument (e.g., card brand and last four digits).

[vixdug]

cc @jingyli @amithanda Now that we will land split payments (https://ucp.dev/draft/specification/split-payments/#gift-card-credit-card) in 08 this follow up allows order confirmation screens to properly display the split. This came up during implementations as there is no clear way to show the buyer what portion of the payment is captured on each method. LGTM.

[raginpirate]

Hey @richmolj! Thanks for identifying and filling this gap. I agree with the core problem: Order needs a durable, buyer-facing record of how the order was paid, especially so split payments can show each instrument’s contribution.

I forked the PR to explore a different schema boundary rather than editing your branch directly: #638

The goal is to preserve your end-to-end behaviour while avoiding a second payment-instrument hierarchy that the current handler prose does not extend, which we should treat as a blocking issue with this proposal. LMK what you think!

[dkoch74]

Most of these fields would be reused any time we need to display a payment instrument summary. Instead of a having a detailed object for just this use case, it would be ideal to create something like payment_instrument_display.json and have order_payment_instrument.json inherit from that. Billing address might be overly specific for the former but could be included in the order_payment_instrument.json object.