[Feat]: Allow tender-based discounts via payment instrument qualifiers in Checkout Session Update

[ACSchil]

Is your feature request related to a problem? Please describe.

I’m working on the REST binding + Checkout Update flow and I don’t see a place for a Platform to indicate “what tender subtype was selected” in a way that a Business can use for tender-based discounts.

Concretely: as the Business, I want to offer discounts based on a card subtype / BIN group (e.g., certain debit/commercial/store-card programs). In many tokenized flows, the Business may not have access to PAN/BIN, so the Platform (or handler) is the party that can detect the subtype early.

Today, Checkout Update Request includes payment as a Payment Update Request, but that object is basically just selected_instrument_id + instruments[]. The base card instrument fields (brand/last4/etc.) don’t include a “subtype” or “qualifier” concept. As a result, there isn’t a standard way for the Platform to signal “selected tender qualifies for discount bucket X”.

Refs: https://ucp.dev/specification/reference/ (Checkout Update Request, Payment Update Request, Card Payment Instrument)

Describe the solution you'd like

Add a small, generic mechanism for the Platform to pass a coarse, business-defined indicator alongside the selected payment instrument during PUT /checkout-sessions/{id}.

One possible shape (example only):

• Add an optional field on Payment Instrument (or Payment Instrument Base) like:
  • qualifiers: string[] (namespaced values, coarse buckets only), or
  • qualifiers: Array<{ issuer: string, value: string }> for explicit namespacing.

Example usage (JSON payload):

{
  "payment": {
    "selected_instrument_id": "pi_123",
    "instruments": [
      {
        "id": "pi_123",
        "handler_id": "com.example.pay",
        "type": "card",
        "brand": "visa",
        "last_digits": "4242",
        "qualifiers": [
          "com.target.tender.bin_group:debit_promo_a"
        ]
      }
    ]
  }
}

Important constraints I think we should document if we do this:

• This is a coarse eligibility indicator (no raw BINs, no PAN fragments).
• Values should be namespaced to avoid collisions.
• Business remains authoritative: qualifier is an input signal, not a guarantee. At the time of the /complete call, a business may reject the call if the tender does not qualify.

Also: we should plan/spec the out-of-band coordination story: how the Business shares BIN ranges and the expected qualifier values to the Platform (and how often this changes, versioning, etc.). It can be “out of scope” for UCP to standardize the sharing protocol, but the spec should at least acknowledge it and set expectations.

Describe alternatives you've considered

1. Use the Discounts extension discounts.codes as the indicator (Platform submits a pre-arranged code like com.target.tender.debit_promo_a).
   Pros: no schema change.
   Cons: “codes” reads like coupon/user-input semantics; tender eligibility feels like a different axis.

2. Put subtype in handler-specific instrument schemas.
   Pros: doesn’t require changing core schemas.
   Cons: not interoperable; Business has to implement per-handler logic and it’s hard to make this a consistent capability across the ecosystem.

3. Don’t send anything; Business figures it out.
   In practice this breaks down in tokenized flows where Business doesn’t have BIN visibility.

Additional context

Why I think this belongs in Checkout Update:

• The Business often needs to reflect the discount in totals before “Complete Checkout”.
• The Platform is already calling Update Checkout as the buyer selects fulfillment/payment.

If maintainers think this should be an extension instead of core, I’m happy to move the proposal in that direction — but I’d still like a standard place + pattern so multiple businesses/platforms don’t invent incompatible one-offs.

Code of Conduct

• I agree to follow this project's Code of Conduct

[igrigorik]

Hmm, on first read this feels like perfect fit for capability negotiation; this should be modelled as an extension.

If qualifiers (or whatever name we settle on) is an optional field on core schema, business can't distinguish:

• Platform doesn't support tender qualifiers
• Platform supports it but doesn't have this merchant's BIN mapping
• Card doesn't qualify

All three = field absent. Capability negotiation solves this, via platform advertising in its profile:

{
  "name": "org.foo.bar.TBD_NAME_OF_CAPABILITY",
  "issuers": ["com.target", "..."]
}

The merchant now knows and can distinguish agents that will properly signal tender signals vs. ones that can't. When the capability is negotiated, the extension can augment instrument with something like you've outlined above...

{
  "id": "pi_123",
  "handler_id": "com.example.pay",
  "type": "card",
  "brand": "visa",
  "last_digits": "4242",
  "qualifiers": [
    {"issuer": "com.target", "value": "debit_promo_a"}
  ]
}

One question / assumption: how does platform know the BIN ranges? This relies on some out of band process to establish and associate with the instrument for the platform/agent — correct? That's not a thing we can standardize in UCP.

Does this framing align with what you had in mind?

[ACSchil]

Thank you @igrigorik . It does align!

This relies on some out of band process to establish and associate with the instrument for the platform/agent — correct?

That is one option. However, the business could conceivable advertise this in their profile; the information is public. This actually would solve the challenges around coordinating the mappings.

[igrigorik]

Ah, even better, that makes everyone's life easier!

With that, I think we have a good path forward. Let's prototype this as a capability. I suspect this will be a common need, and we can consider it for inclusion into 'core' if there is broader support - i.e. dev.ucp.shopping.tender_signals, or some such.

@ACSchil would you be up for drafting a PR for this? I'll also nominate and tag @raginpirate for extra eyes and support on this.

[raginpirate]

@ACSchil Thanks for the detailed writeup! Could you help me understand the use case a bit closer?

In many tokenized flows, the Business may not have access to PAN/BIN, so the Platform (or handler) is the party that can detect the subtype early.

My thinking here is that if this is context the business needs and the handler owns, the payment handler should expose this context to the merchant on the backend. Example: Platform tokenizes card X with handler Y. Business receives token via UCP, and then requests handler Y to forward it metadata about the token; the business can now respond back to the platform with discounts in the UCP response, because it's source of truth (the handler) told them the BIN range. Without the business being able to validate the credential context on the BE, a malicious actor could just submit you bin range data to get a discount without it being true.

It seems very strange to me that a business needs to rely on the platform to learn context about the payment instrument they are going to charge; maybe you could help me understand a flow where you can't do this!

[amithanda]

It might be a good idea to clarify the problem statement more clearly and map out top user journeys we expect to support using this feature.

Is the problem statement:

1. allowing businesses & agents to support branded cards e.g Co-branded (Open-Loop) Cards, Store-Branded (Closed-Loop) Cards, Loyalty rewards cards for payments?
2. as a result of business/agents aligning on branded cards, users may get different types of benefits e.g discounts, loyalty points or free shipping etc.

Should these be mixed in a single PR or should we keep these separate?

[sbeashwar]

Stepping back, the goal I presume is to help platform help user to choose the best payment method for this transaction. Whether it's a store-branded card discount (merchant-fulfilled) or Visa cashback/rewards (issuer-fulfilled), the Platform should surface benefits alongside each instrument so users can make an informed choice.

Current gap: Instruments in the checkout session have basic fields (brand, last_digits) plus optional rich_card_art and rich_text_description. However, there's no field for benefits/qualifiers, and no defined UCP touchpoint for Payment Handlers to provide this enriched data before payment selection.

Two fulfillment models:

1. Merchant-fulfilled (e.g., "10% off with Store Card")

• How Handler knows: Merchant advertises BIN ranges/rules in profile or passes via request; Handler matches
• Merchant validates at /complete: Yes

2. Issuer-fulfilled (e.g., "5x points on this purchase")

• How Handler knows: Handler/issuer attaches directly
• Merchant validates at /complete: No
  For merchant-fulfilled benefits, the business advertises eligibility rules (e.g., BIN ranges to qualifier mappings). The Handler matches instruments against these rules and attaches the benefit. At checkout confirm/complete, the business validates with the Handler to ensure the claim is legitimate - this prevents bad actors from faking qualifiers to get discounts.

For issuer-fulfilled benefits, the Handler is authoritative - no merchant validation needed since the issuer fulfills the reward post-transaction.

Capability negotiation as proposed by @igrigorik fits well here. The Handler advertises that it supports this capability, and when invoked, checks merchant-provided eligibility rules against the instrument and returns benefits in the response.

On entity model: In practice, this enrichment could come from a Wallet, a Payment Handler, or both working together (Wallet holds instruments, Handler knows issuer benefits). For simplicity, UCP could treat whichever entity surfaces the instrument as the one responsible for attaching presentation/benefits - whether that's a standalone Handler or a Wallet acting in the Handler role.

Possible approaches for Handler integration:

A. Out-of-band - Platform negotiates with Handler outside UCP. Tradeoff: Not standardized.

B. On-demand enrichment - Platform calls Handler when showing payment options, passing merchant eligibility rules. Tradeoff: New endpoint to spec, but standardized.

C. Prepopulate at tokenization - Handler provides presentation data when instrument is saved. Tradeoff: Data may go stale; doesn't support merchant-specific benefits.

Option B seems like the viable path - it's standardized and ensures fresh data.

Suggested endpoint
POST /payment-handlers/{handler_id}/instruments/{instrument_id}/enrichment

Request:
{
"merchant_id": "com.acme.store",
"eligibility_rules": [
{
"qualifier": "store_card_10pct",
"display": "10% off with Store Card",
"bin_ranges": ["411111-411199", "422222-422299"]
}
]
}

Response:
{
"presentation": {
"display_name": "Chase Sapphire Reserve",
"card_art_uri": "https://assets.bank.com/cards/sapphire.png"
},
"benefits": [
{ "code": "store_card_10pct", "display": "10% off with Store Card", "fulfillment": "merchant" },
{ "code": "visa_5x_travel", "display": "5x points on this purchase", "fulfillment": "issuer" }
]
}

Disclaimer: The views expressed here are my own and do not represent those of my employer. This is provided as-is without warranty of any kind.