feat: add payment instrument qualifiers #214
+277
−8
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -703,6 +703,230 @@ Follow-up calls after initial `fulfillment` data to update selection. | |
| } | ||
| ``` | ||
|
|
||
| #### Update Payment | ||
|
|
||
| Prior to completing checkout, the Platform may provide the Business with selected payment instrument hints. These hints allow the Business to apply to the checkout session the expected benefits the selected payment instrument qualifies the Buyer for. | ||
|
|
||
| === "Request" | ||
|
|
||
| ```json | ||
| PUT /checkout-sessions/{id} HTTP/1.1 | ||
| UCP-Agent: profile="https://platform.example/profile" | ||
ACSchil marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| Content-Type: application/json | ||
|
|
||
| { | ||
| "id": "chk_123456789", | ||
|
There was a problem hiding this comment. The Update Payment example uses PUT /checkout-sessions/{id} and includes "id": "chk_123456789" in the body, but the spec section doesn’t state what happens if the path {id} and body id differ. Add a normative rule: either (a) body id MUST match path {id} and mismatches MUST be rejected with a specific error, or (b) body id is ignored and the path is authoritative.
Author
There was a problem hiding this comment. Great call-out. Because this PR feat did not introduce that potential conflict (i.e. there are other Update docs with this issue), I propose we create a separate issue to address that. Thoughts? Thinking through the solution, it's probably to return a 400 or 422. And this would then be captured under https://ucp.dev/2026-01-23/specification/checkout-rest/#status-codes . There was a problem hiding this comment. Sounds good. Please create a separate issue. |
||
| "buyer": { | ||
| "email": "jane@example.com", | ||
| "first_name": "Jane", | ||
| "last_name": "Doe" | ||
| }, | ||
| "line_items": [ | ||
| { | ||
| "item": { | ||
| "id": "item_123", | ||
| "title": "Red T-Shirt", | ||
| "price": 2500 | ||
| }, | ||
| "id": "li_1", | ||
| "quantity": 2 | ||
| } | ||
| ], | ||
| "fulfillment": { | ||
| "methods": [ | ||
| { | ||
| "id": "shipping_1", | ||
| "type": "shipping", | ||
| "line_item_ids": ["item_123"], | ||
| "selected_destination_id": "dest_home", | ||
| "destinations": [ | ||
| { | ||
| "id": "dest_home", | ||
| "street_address": "123 Main St", | ||
| "address_locality": "Springfield", | ||
| "address_region": "IL", | ||
| "postal_code": "62701", | ||
| "address_country": "US" | ||
| } | ||
| ], | ||
| "groups": [ | ||
| { | ||
| "id": "package_1", | ||
| "selected_option_id": "express" | ||
| } | ||
| ] | ||
| } | ||
| ] | ||
| }, | ||
| "payment": { | ||
| "instruments": [ | ||
| { | ||
| "id": "pi_gpay_5678", | ||
| "handler_id": "gpay_1234", | ||
| "type": "card", | ||
| "selected": true, | ||
| "display": { | ||
| "brand": "mastercard", | ||
| "last_digits": "5678", | ||
| "rich_text_description": "Google Pay •••• 5678" | ||
| }, | ||
| "eligibility_hints": [ | ||
| "com.example.tender_a" | ||
| ] | ||
| } | ||
| ] | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| === "Response" | ||
|
|
||
| ```json | ||
| HTTP/1.1 200 OK | ||
| Content-Type: application/json | ||
|
|
||
| { | ||
| "ucp": { | ||
| "version": "2026-01-11", | ||
| "capabilities": { | ||
| "dev.ucp.shopping.checkout": [ | ||
| {"version": "2026-01-11"} | ||
| ] | ||
| }, | ||
| "payment_handlers": { | ||
| "com.google.pay": [ | ||
| { | ||
| "id": "gpay_1234", | ||
| "version": "2026-01-11", | ||
| "config": { | ||
| "allowed_payment_methods": [ | ||
| { | ||
| "type": "CARD", | ||
| "parameters": { | ||
| "allowed_card_networks": ["VISA", "MASTERCARD", "AMEX"] | ||
| } | ||
| } | ||
| ] | ||
| } | ||
| } | ||
| ] | ||
| } | ||
| }, | ||
| "id": "chk_123456789", | ||
| "status": "ready_for_complete", | ||
| "currency": "USD", | ||
| "line_items": [ | ||
| { | ||
| "id": "li_1", | ||
| "item": { | ||
| "id": "item_123", | ||
| "title": "Red T-Shirt", | ||
| "price": 2500 | ||
| }, | ||
| "quantity": 2, | ||
| "totals": [ | ||
| {"type": "subtotal", "amount": 5000}, | ||
| {"type": "total", "amount": 5000} | ||
| ] | ||
| } | ||
| ], | ||
| "buyer": { | ||
| "email": "jane@example.com", | ||
| "first_name": "Jane", | ||
| "last_name": "Doe" | ||
| }, | ||
| "totals": [ | ||
| { | ||
| "type": "subtotal", | ||
| "amount": 5000 | ||
| }, | ||
| { | ||
| "type": "tax", | ||
| "amount": 400 | ||
| }, | ||
| { | ||
| "type": "total", | ||
| "amount": 5400 | ||
| } | ||
| ], | ||
| "links": [ | ||
| { | ||
| "type": "terms_of_service", | ||
| "url": "https://merchant.com/terms" | ||
| } | ||
| ], | ||
| "fulfillment": { | ||
| "methods": [ | ||
| { | ||
| "id": "shipping_1", | ||
| "type": "shipping", | ||
| "line_item_ids": ["item_123"], | ||
| "selected_destination_id": "dest_home", | ||
| "destinations": [ | ||
| { | ||
| "id": "dest_home", | ||
| "street_address": "123 Main St", | ||
| "address_locality": "Springfield", | ||
| "address_region": "IL", | ||
| "postal_code": "62701", | ||
| "address_country": "US" | ||
| } | ||
| ], | ||
| "groups": [ | ||
| { | ||
| "id": "package_1", | ||
| "line_item_ids": ["item_123"], | ||
| "selected_option_id": "express", | ||
| "options": [ | ||
| { | ||
| "id": "standard", | ||
| "title": "Standard Shipping", | ||
| "description": "Arrives in 5-7 business days", | ||
| "totals": [ | ||
| { | ||
| "type": "total", | ||
| "amount": 500 | ||
| } | ||
| ] | ||
| }, | ||
| { | ||
| "id": "express", | ||
| "title": "Express Shipping", | ||
| "description": "Arrives in 2-3 business days", | ||
| "totals": [ | ||
| { | ||
| "type": "total", | ||
| "amount": 1000 | ||
| } | ||
| ] | ||
| } | ||
| ] | ||
| } | ||
| ] | ||
| } | ||
| ] | ||
| }, | ||
| "payment": { | ||
| "instruments": [ | ||
| { | ||
| "id": "pi_gpay_5678", | ||
| "handler_id": "gpay_1234", | ||
| "type": "card", | ||
| "selected": true, | ||
| "display": { | ||
| "brand": "mastercard", | ||
| "last_digits": "5678", | ||
| "rich_text_description": "Google Pay •••• 5678" | ||
| }, | ||
| "eligibility_hints": [ | ||
| "com.example.tender_a" | ||
| ] | ||
| } | ||
| ] | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ### Complete Checkout | ||
|
|
||
| If businesses have specific logic to enforce field existence in `buyer` and | ||
|
|
@@ -730,6 +954,9 @@ place to set these expectations via `messages`. | |
| "card_art": "https://cart-art-1.html", | ||
| "description": "Google Pay •••• 5678" | ||
| }, | ||
| "eligibility_hints": [ | ||
| "com.example.tender_a" | ||
| ], | ||
| "billing_address": { | ||
| "street_address": "123 Main St", | ||
| "address_locality": "Anytown", | ||
|
|
@@ -892,7 +1119,10 @@ place to set these expectations via `messages`. | |
| "brand": "mastercard", | ||
| "last_digits": "5678", | ||
| "rich_text_description": "Google Pay •••• 5678" | ||
| }, | ||
| "eligibility_hints": [ | ||
| "com.example.tender_a" | ||
| ] | ||
| } | ||
| ] | ||
| } | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -8,6 +8,7 @@ | |
| "out_of_stock", | ||
| "item_unavailable", | ||
| "address_undeliverable", | ||
| "payment_failed", | ||
| "invalid_eligibility_hint" | ||
| ] | ||
| } | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think we should come at this explanation as a feature of payment handlers, NOT from the perspective of a black hole platforms can leverage for out-of-band solutions.
As in, my payment handler lets me negotiate available qualifiers, and exposes that context to the agent to submit to the platform. It just so happens to give platforms and businesses an easy path to do out-of-band context sharing, but IMO we shouldn't be authoring this from that perspective.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I understand this POV. See #214 (comment) . Are you okay with us moving forward with this for now?