fix(rest/python): apply update request payment instruments instead of failing construction

[vishkaty]

What

A checkout update that submits payment.instruments returns a bare HTTP 500
instead of applying the instruments. A checkout create with the same shape
has the identical defect, unexercised by any existing test.

Root cause

rest/python/server/services/checkout_service.py:532 in update_checkout:

if checkout_req.payment:
  existing.payment = PaymentResponse(
    instruments=checkout_req.payment.instruments,
  )

checkout_req.payment.instruments holds
payment_instrument_update_request.SelectedPaymentInstrument instances,
the request side model that ucp_sdk generates for PaymentUpdateRequest.
PaymentResponse (imported as ucp_sdk.models.schemas.shopping.payment.Payment)
declares that same field as
list[payment_instrument.SelectedPaymentInstrument], the sibling response
class. The two classes share every field name and shape (id, handler_id,
type, billing_address, credential, display, selected) but are not
the same class and not a subclass of one another, so pydantic refuses to
construct PaymentResponse from an instance of the wrong one:

pydantic_core._pydantic_core.ValidationError: 1 validation error for Payment
instruments.0
  Input should be a valid dictionary or instance of SelectedPaymentInstrument

That ValidationError is neither a RequestValidationError nor a UcpError,
the two exception types this server maps to the UCP error envelope, so
FastAPI answers with its default unhandled exception response: a bare 500
with no body a caller can act on.

create_checkout at line 395 builds PaymentResponse the same way from
checkout_req.payment.instruments, where the request side class is instead
payment_instrument_create_request.SelectedPaymentInstrument. Same
construction, same collision, same 500. Every test in this repository that
sends payment on create sends instruments: [], and an empty list never
reaches the per item type check, so the create path 500 has been present
and untested since payment.instruments was first threaded through this
file.

Spec grounding

checkout.json marks the payment member of the update request
ucp_request: {create: "optional", update: "optional"}, so a platform
submitting payment on update is a conformant request, not an edge case.
checkout.md is explicit about what the field is for: "When the buyer
submits payment, the platform populates the payment.instruments array with
the collected instrument data." An update carrying instruments must apply
them and answer 200 with the instruments reflected, which is what the
added tests assert (checked against the currently pinned 2026-04-08 schema
and spec).

The fix

Both sites now dump the request side payment object to a dict first and
let PaymentResponse parse that dict, rather than handing it a foreign
model instance:

existing.payment = PaymentResponse(
  **checkout_req.payment.model_dump(exclude_none=True)
)

This mirrors the pattern this file already uses at the same request to
response boundary for buyer, context, signals, and discounts a few
lines below and above it (source_context.model_dump(exclude_none=True),
and so on), so the fix follows the established convention already in this file
rather than introducing a new one.

Class sweep table

The defect class is: a response model constructed from a request typed
object fields, where the two sides are different generated classes.
Every ...Response(...) construction in checkout_service.py that reaches
into request data was checked:

Site	Data source	Verdict
create_checkout payment (line 395)	checkout_req.payment.instruments	Converted (this PR)
update_checkout payment (line 532)	checkout_req.payment.instruments	Converted (this PR)
create_checkout / update_checkout LineItemResponse, ItemResponse	scalar fields (li_req.id, li_req.item.id, li_req.quantity)	Out of scope, no model instance crosses the boundary
create_checkout ShippingDestinationResponse (line 342)	scalar fields (dest_req.address_country, and so on)	Out of scope, same reason
update_checkout ShippingDestinationResponse (line 625)	dest_req.model_dump(exclude_none=True)	Already safe, already dumps to a dict before constructing
update_checkout ShippingDestinationResponse from stored customer address (line 634)	ORM row fields, not request models	Out of scope
FulfillmentResponseClass, FulfillmentMethod, FulfillmentGroup	built from already constructed response objects and scalars	Out of scope
TotalResponse (totals rebuild)	scalars (amount, type) computed by the server	Out of scope
cart_service.py	no payment handling anywhere in the file	Not applicable, carts do not carry payment

payment is the only field in this file where the response type is built
directly from a same shaped sibling model instead of a dict or scalars, on
both the create and the update path.

Testing

• Added test_update_applies_payment_instruments and
  test_create_applies_payment_instruments to integration_test.py.
  signature_integration_test.py and cart_test.py both import and
  subclass IntegrationTest, so the two new tests also run signed and as
  part of the cart to checkout conversion path, for 8 passing test
  instances total from the 2 new test bodies.
• Full suite: 253 passed, 3 warnings, 12 subtests passed (was 245 before
  the 8 new instances; 0 regressions).
• Kill test: reverting only the checkout_service.py change and keeping
  the tests turns all 8 instances red with the same
  pydantic_core._pydantic_core.ValidationError: ... model_type this PR
  fixes. Restoring the fix turns them green again.
• Pinned pre-commit run on both changed files: all hooks pass, including
  ruff and ruff-format as separate hooks.
• Happy path client: simple_happy_path_client.py against a freshly
  seeded server completes discovery through order completion.
• Direct wire check against the running server (not the test client): a
  create followed by PUT /checkout-sessions/{id} carrying a non empty
  payment.instruments now answers 200 with the instrument reflected in
  the response body, where it previously answered 500.

Dependency note

This branch is built on top of the fixture correction proposed in #219
(cherry picked here as 0da1797), which fixes an unrelated collision in
the shared checkout test helper (ShippingDestinationCreateRequest versus
its response sibling) that otherwise makes the whole suite fail to import
once a fresh install resolves ucp-sdk 0.4.6. If that PR has already
merged by the time this one is reviewed, this branch should rebase onto
main and drop the cherry picked commit; if not, this PR depends on it
landing first, or the same fix should be folded in ahead of merge.

Fixes #218