Skip to content

feat: add payment instrument qualifiers #214

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
ACSchil wants to merge 12 commits into from
+277 −8
Closed

feat: add payment instrument qualifiers #214

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
17163ab
feat: add payment instrument qualifiers
alexAtTarget Feb 24, 2026
9882035
docs: fixes typos and uses 'instrument' consistently
alexAtTarget Feb 24, 2026
607c229
docs: fixes mismatches in example json
alexAtTarget Feb 24, 2026
516841f
docs: tightens constraints on payment instrument qualifiers
alexAtTarget Feb 24, 2026
7a26d71
docs: adds explicit privacy / data minimization guidance to payment i…
alexAtTarget Feb 24, 2026
37beca0
docs: clarifies qualifier semantics
alexAtTarget Feb 25, 2026
00f586f
docs: adds invalid_qualifier error code
alexAtTarget Feb 25, 2026
76ff335
Merge branch 'main' into alex/137
ACSchil Feb 25, 2026
3e371ef
docs: adds benefit examples
alexAtTarget Feb 27, 2026
6c3f7de
docs: renames qualifiers to eligibility_hints
alexAtTarget Feb 27, 2026
3ba3107
Merge branch 'main' into alex/137
ACSchil Mar 2, 2026
c657203
docs: removed maxItems for eligibility_hints
alexAtTarget Mar 3, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
225 changes: 224 additions & 1 deletion docs/specification/checkout-rest.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -694,6 +694,223 @@ 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 instruction qualifies the Buyer for.

=== "Request"

```json
PUT /checkout-sessions/{id} HTTP/1.1
UCP-Agent: profile="https://platform.example/profile"
Content-Type: application/json

{
"id": "chk_123456789",
Copy link

@maximenajim maximenajim Feb 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

@ACSchil ACSchil Feb 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 .

Copy link

@maximenajim maximenajim Feb 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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"
},
"qualifiers": [
"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.shopify.shop_pay": [
{
"id": "shop_pay_1234",
"version": "2026-01-11",
"config": {
"merchant_id": "shop_merchant_123"
}
}
]
}
},
"id": "chk_1234567890",
"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"
},
"qualifiers": [
"com.example.tender_a"
]
}
]
}
}
```

### Complete Checkout

If businesses have specific logic to enforce field existence in `buyer` and
Expand Down Expand Up @@ -721,6 +938,9 @@ place to set these expectations via `messages`.
"card_art": "https://cart-art-1.html",
"description": "Google Pay •••• 5678"
},
"qualifiers": [
"com.example.tender_a"
],
"billing_address": {
"street_address": "123 Main St",
"address_locality": "Anytown",
Expand Down Expand Up @@ -883,7 +1103,10 @@ place to set these expectations via `messages`.
"brand": "mastercard",
"last_digits": "5678",
"rich_text_description": "Google Pay •••• 5678"
}
},
"qualifiers": [
"com.example.tender_a"
]
}
]
}
Expand Down
14 changes: 14 additions & 0 deletions docs/specification/overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1036,6 +1036,20 @@ within UCP: **Negotiation**, **Acquisition**, and **Completion**.
2. **Acquisition (Platform ↔ Payment Credential Provider):** The platform executes the handler's logic. This happens client-side or agent-side, directly with the payment credential provider (e.g., exchanging credentials for a network token). The business is not involved, ensuring raw data never touches the business's frontend API.
3. **Completion (Platform → Business):** The platform submits the opaque credential (token) to the business. The business uses it to capture funds via their backend integration with the payment credential provider.

### Payment Qualifiers
Copy link

@gsmith85 gsmith85 Feb 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Consideration: Is qualifiers descriptive enough? "Qualifiers" often implies a binding state or a restrictive limitation. Since the semantics explicitly define these as non-binding "hints" that require independent verification, benefit_hints or eligibility_hints might be a better fit. It signals that the field is a suggestion for the presentation and pre-checkout logic rather than a final, validated qualification for financial settlement.


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.

Payment instruments **MAY** include a `qualifiers` array: opaque, namespaced strings that indicate benefit eligibility associated with the selected instrument. The meaning of qualifier values (and how they are derived) is communicated between the Business and Platform out of band (for example, via offline agreement on BIN ranges or program identifiers).

Qualifiers are hints, not proofs:

- Businesses **SHOULD** treat unknown qualifiers as no-ops.
- When the Platform provides qualifiers and the Business applies benefits based on them, the Business **SHOULD** fail checkout if the selected payment instrument presented during checkout completion does not meet the hinted qualifications.
- Businesses **SHOULD NOT** fail checkout solely because a qualifier is unrecognized.

Qualifier strings **SHOULD** use reverse-domain naming to avoid collisions and make authority explicit.

### Payment Handlers

Payment Handlers are **specifications** (not entities) that define how payment
Expand Down
7 changes: 7 additions & 0 deletions source/schemas/shopping/types/payment_instrument.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,13 @@
"display": {
"type": "object",
"description": "Display information for this payment instrument. Each payment instrument schema defines its specific display properties, as outlined by the payment handler."
},
"qualifiers": {
Copy link

@maximenajim maximenajim Feb 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Qualifiers is currently an unbounded array of unbounded strings. For a protocol-level schema used by autonomous agents, this is a straightforward DoS / log-injection / storage-amplification risk.

Add schema constraints, for example:

  • maxItems (e.g., 10–50 depending on expected use)
  • uniqueItems: true (if semantics are set-like)
  • string constraints like maxLength (e.g., 128/256) and a conservative pattern (e.g., reverse-domain-ish allowed chars)

Even if implementations don’t enforce strictly, having constraints in the canonical schema sets a safe baseline.

Copy link
Contributor Author

@ACSchil ACSchil Feb 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How should we communicate the reverse-domain-ish characters?

Shall we say items match the pattern of ^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)+\.[a-z][a-z0-9_-]*$ ? i.e. {reverse-domain}.{service}.{qualifier}, e.g. "com.target.red_card" or "co.uk.example.qualifier-abc123"

Copy link
Contributor

@raginpirate raginpirate Feb 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

re: max items and string constraints; I feel like those needs to be applied across the board to UCP and are not today. We should discuss this in the TC; do we need a sweeping application of that to the spec, and should that be done in isolation of this PR?

I also disagree with enforcing reverse-dns here; from my POV the primary use case of this should be in-band by payment handlers to express how you negotiate qualfiier context that you want exposed by a payment handler for a specific instrument. Out-of-band use cases should not be dictated and require reverse-dns; they have their own solutions for identifying the relying party they negotiated with and interpreting those fields independently for those parties.

Copy link
Contributor Author

@ACSchil ACSchil Feb 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree we have an opportunity to apply these across the board. I am okay adding the constraint here (as I have done), or removing it an referencing this feedback in a new issue that takes a broader look.

Out-of-band use cases should not be dictated and require reverse-dns

Without reverse domain naming, there's a significant chance of collision. Imagine two entities with member_program; it would be helpful for the program named be tied to that program owner, e.g. com.target.member_program so that another merchant can also have com.merchant_b.member_program.

"type": "array",
"items": {
"type": "string"
},
"description": "Opaque, namespaced qualifier strings from the Platform that hint to the Business the benefits to apply at checkout time, based on the selected payment instruments."
}
},
"additionalProperties": true,
Expand Down