Skip to content

feat: add payment instruments to the order capability#584

Open
richmolj wants to merge 2 commits into
mainfrom
order-payment-instruments
Open

feat: add payment instruments to the order capability#584
richmolj wants to merge 2 commits into
mainfrom
order-payment-instruments

Conversation

@richmolj

Copy link
Copy Markdown
Contributor

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

@richmolj
richmolj requested review from a team as code owners July 13, 2026 16:12
@richmolj
richmolj requested review from jingyli and mmohades July 13, 2026 16:13
@vixdug

vixdug commented Jul 13, 2026

Copy link
Copy Markdown

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.

@damaz91
damaz91 removed request for a team, jingyli and mmohades July 14, 2026 07:45
@damaz91 damaz91 added gov:needs-gc-review status:needs-triage Signal that the PR is ready for human triage area:payments and removed status:needs-triage Signal that the PR is ready for human triage payments labels Jul 14, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants