feat: add card verification and billing address constraints

[jamesandersen]

Enhancement Proposal: Card Payment Constraints

Summary

Adds named constraints to card_payment_instrument.json that enable merchants to communicate per-checkout instrument requirements to platforms. This gives platforms a clear signal of what the merchant requires — no guesswork, no trial-and-error tokenization.

Motivation

Many instrument and credential properties are optional at the protocol level but required by individual merchants and their PSPs. For example, CVC is optional in card_credential.json but most merchants require it for card-not-present transactions. A handler like dev.shopify.card serves thousands of merchants — some require CVC, some don't (it's a per-merchant fraud setting). Without a way to communicate these requirements, the platform must guess which optional fields the merchant actually needs.

Design

Uses the existing constraints mechanism on available_instruments, consistent with how brands constraints already work. Constraints participate in the existing resolution flow and can vary per merchant without changing the handler schema.

New Constraints

Constraint	Type	Description
requires_card_verification	boolean	When true, the handler requires card verification data. For FPAN: CVC. For network tokens: cryptogram and ECI.
requires_billing_address	boolean	When true, the handler requires a billing address on the instrument.
requires_billing_postal_code	boolean	When true, the handler requires a billing postal code for AVS verification. Ignored when requires_billing_address is true.

Example

{
  "available_instruments": [
    {
      "type": "card",
      "constraints": {
        "brands": ["visa", "mastercard"],
        "requires_card_verification": true,
        "requires_billing_postal_code": true
      }
    }
  ]
}

Per-card_number_type Semantics

The requires_card_verification constraint adapts to the credential mode:

card_number_type	Verification fields required
fpan	cvc
network_token	cryptogram, eci_value

The spec documents these mappings. A future PR could make the schema fully self-documenting via a verification object with conditionals per card_number_type (as discussed in PR review), but named constraints provide a pragmatic step forward today.

Code Changes

Modified Files:

• source/schemas/shopping/types/card_payment_instrument.json — Added requires_card_verification, requires_billing_address, and requires_billing_postal_code to the available_card_payment_instrument constraints
• docs/specification/payment-handler-guide.md — Added Card Constraints section with constraint table, example, and resolution flow documentation

Test Plan

• JSON Schema validation: new constraints accepted on card_payment_instrument.json
• Spell check (cspell): 0 issues
• Markdown lint (markdownlint): 0 issues
• Round-trip test: verify constraints flow through resolution in available_instruments

References

• PR #187 — Original constraints mechanism
• PR #49 — Prior instrument schema discussion

---

Type of change

• New feature (non-breaking change which adds functionality)
• Documentation update

Checklist

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have made corresponding changes to the documentation
• My changes generate no new warnings

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

[alexpark20]

I understand the motivation here, but I am concern that this solution is not scalable, especially for any new schema type to be introduced. I think the right solution is to leverage the .schema field in entity (ucp.json#/$defs/entity).

Before PR #49 , payment handlers had separate config_schema (URI) and instrument_schemas (array of URIs). PR #49 consolidated these into a single schema URI — but this was a simplification of the reference structure, not a reduction in capability. A single JSON Schema document can contain $defs covering all instrument types and their requirements. That said, I think the protocol's existing schema field is already capable of expressing everything required_fields is trying to express, and more.

Although, one can argue that the current schema in the entity (ucp.json#/$defs/entity) cannot really express its intention. I imagine people often assume that schema is only for the payment handler config. As an alternative to introducing required_fields, I think re introducing instrument_schema (just URI, not array though) could solve the problem. What do you think?

[jamesandersen]

@alexpark20 thanks for taking time to do the review! The context on #49 is useful.

I agree that schema is likely where one would expect new defs specific for the payment handler to live and it might be non-obvious if that same schema URL also was trying to refine other payment instrument and credential types e.g. card_payment_instrument.json and card_credential.json e.g. . Using instrument_schema would help with the clarity there. As you noted, this does offer the full expression of JSON schema syntax to essentially say "for this handler, the card credential you can supply to the card payment instrument looks a bit different from the standard definition in that cvc is a required field"

While I think I could get behind this idea here's a couple additional thoughts for why the required_fields still feels a bit more appealing to me:

• Requirements can vary per business, not per handler. A handler like dev.shopify.card serves thousands of merchants — some require CVC, some don't (it's a per-merchant fraud setting). required_fields lives on available_instruments, which already participates in the resolution flow, so it resolves per checkout naturally. A static instrument_schema URI can't vary per merchant without dynamically generating schema documents.
  • FWIW this is the exact problem we've encountered which motivated this PR ;-)
• Low overhead for a narrow problem. The platform needs to answer "does this merchant require CVC?". required_fields keeps that answer inline in the discovery response with no additional fetch, no $ref resolution across a schema inheritance to refine types, no JSON Schema evaluation engine. We could indicate that the dot-notation syntax follows RFC 9535 (JSONPath).
• Complementary, not competing. If the community wants instrument_schema for richer constraints down the road, required_fields wouldn't conflict.

To make it concrete — here's the Shopify card handler under each approach:

required_fields:

{
  "id": "shopify.card",
  "version": "2026-01-15",
  "schema": "https://shopify.dev/ucp/card-payment-handler/2026-01-15/config.json",
  "available_instruments": [{
    "type": "card",
    "constraints": { "brands": ["visa", "master", "american_express"] },
    // business can vary the required fields without serving a different handler schema
    "required_fields": ["credential.cvc"] 
  }]
}

instrument_schema — same declaration plus a new URI, and Shopify hosts a separate schema document:

// https://shopify.dev/ucp/card-payment-handler/2026-01-15/instrument-requirements.json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "allOf": [
    // need to pull this schema...
    { "$ref": "https://ucp.dev/schemas/shopping/types/card_payment_instrument.json" },
    {
      "properties": {
        "credential": {
          "allOf": [
            // ... and this one to get the complete picture of the type refinement
            { "$ref": "https://ucp.dev/schemas/shopping/types/card_credential.json" },
            // probably requires a different schema when using this handler definition 
            // where CVC isn't required or zip code IS required
            { "required": ["cvc"] }
          ]
        }
      }
    }
  ]
}

Again - I think either way could work and I'm still getting calibrated on what best serves the broader community but hopefully this helps flesh out a bit more of the motivation for the required_fields approach. LMK what you think.

[alexpark20]

@jamesandersen , thanks for the detailed response and the examples! It really helps me see the full motivation. The per-merchant variance point makes sense, and I think it actually clarifies why we need both required_fields and the static schema rather than one or the other.

I agree that required_fields inline in available_instruments is the right place for per-merchant variance to provide that information at run time.

The one gap I see in required_fields alone is that the dot-notation strings are unvalidated (i.e typo such as credential.cvv). Nothing ties "credential.cvc" back to an actual property in the composed instrument and credential schema. I think having the static instrument schema (either via existing schema or new instrument_schema, but I lean into the latter) that platform can fetch / resolve during the discovery closes that gap. In addition, the spec doc can address it explicitly by stating something like

the business MUST only include paths in required_fields that correspond to valid properties defined in ucp schema and instrument_schema, and the platform SHOULD validate accordingly

Note that the platform already fetches and evaluates the handler during the discovery, so there's no additional operational overhead. This gives the platform a static, structural definition of what the handler's instrument looks like.

---

Here is how I picture both plays its role:

Similar to how buyer.json (or any other type in the schema) work today, fields are declared as optional unless they are strongly required by the handler itself (e.g. a handler that fundamentally cannot process without a billing address would mark it required). Everything else stays optional in the schema, and per-merchant requirements are communicated at checkout time via required_fields. The schema defines the shape and the outer bounds. required_fields fills in the runtime specifics.

---

As suggestion for this PR, would you open to add more language in the doc? I am okay either deferring the decision of introducing a separate schema field in another PR or combining it as part of this PR.

[jamesandersen]

@alexpark20 thanks for the thoughtful review and the context on PR #49! I've updated this PR to incorporate your suggestion — the schema now includes both required_fields and instrument_schema:

• instrument_schema (new) — a URI to a JSON Schema defining the full instrument structure for the handler. Gives platforms a static, structural definition to validate required_fields paths against. No new operational overhead since platforms already fetch/evaluate handler schemas during discovery.
• required_fields (existing) — runtime per-merchant requirements, resolved per checkout via the existing available_instruments resolution flow.

I've also added normative language per your suggestion:

The business MUST only include paths in required_fields that correspond to valid properties defined in the applicable UCP instrument and credential schemas or the instrument_schema. The platform SHOULD validate accordingly.

The PR description and docs have been updated to reflect both properties and how they complement each other. Let me know what you think!

[raginpirate]

@jamesandersen @alexpark20 -- great discussion here! ❤️ I want to bring my perspective on this.

instrument_schema: the handler schema already carries instrument schema refs. I am not sure I see the value of bringing this top-level, because from my POV I think the handler must be understood by the platform before they can do anything with the instrument, meaning the discovery path for the schemas should be reasonable as they are today. Let me know what I might have failed to understand from your perspectives above 🤔

required_fields: payment_instrument.constraints already supports this power I believe. An example being, someone could add "requires_billing_address": boolean as a constraint on the card instrument to enforce it being provided, and they can do that today in their own handlers or extend that into the base card UCP schema as well to unify that with the protocol. Same for requires_cvv; but this one bends our abstraction a bit, let me expand.

In #187 we only pushed forward with instruments for the time being to apply constraints against. I heavily considered putting available_credentials on available_instruments which would allow this description at the right layer, but I was not confidant in my abstraction ahead of adoption. My main concern; if your handler supports a few different tokenization strategies, the concept of requires_cvv is likely independent of the tokenization strategy; meaning you'd want to convey it at the instrument level even if conceptually the credential is hiding the cvv, because the credential scheme chosen is actually irrelevant even if the credential holds the cvv.

So... on this topic, I'm not sure I see a gap this PR is currently solving. Instead, I'd frame this PR as searching for the right way to unify and distill constraint requirements and challenging if the current state is good enough, which it might be (similar goal as #187 actually!). WDYT?

[jamesandersen]

@raginpirate thanks for the thoughtful pushback — the tokenization example is a great illustration of why this is tricky. The core tension is: merchants need to express per-checkout (not per schema) requirements, but instruments and credentials are modeled as separate structures in UCP, so some requirements are naturally instrument-level (billing address) while others span the credential boundary (card verification).

I considered narrowing required_fields to instrument-level paths only (e.g., billing_address.postal_code) and using named constraints for cross-credential concerns like card verification. But that still requires constraints for the CVC case — which was the original motivation for this PR — and leaves you with two mechanisms to understand and implement.

I think the cleaner path is to standardize on constraints only: e.g. add new constraints fields like

• requires_card_verification,
• requires_billing_address, etc.

This gives us a single mechanism, consistent with #187. The tradeoff is that constraint semantics become implicit per credential scheme — requires_card_verification means "provide CVC" for raw cards but "provide cryptogram" for network tokens — so the spec needs to document those mappings. But one mechanism with clear documentation feels preferable to two mechanisms.

If this direction works for you and @alexpark20, I'll update the PR accordingly.

[kmcduffie]

@jamesandersen Based on your comment, I was reviewing the payment_instrument.json. The payment instrument contains a credential reference, so while they are separate structures, there's a hierarchy to the current modeling. Does this linkage help with them being separate object definitions? Can you help me understand the use case you're considering where the separate objects is causing a problem?

[jamesandersen]

@kmcduffie good question — you're right that payment_instrument references credential, so the hierarchy exists. The challenge is that card_credential models both raw cards and network tokens in a single type via the card_number_type discriminator (fpan | network_token | dpan). The fields that matter differ depending on which mode is in play:

• card_number_type: "fpan" → merchant may require cvc
• card_number_type: "network_token" → cryptogram and eci_value are relevant, but cvc is not

So the hierarchy tells the platform that a credential is attached, but since it's the same card_credential type either way, it can't distinguish which fields are actually required for a given checkout. A flat required_fields list like ["credential.cvc"] would incorrectly demand CVC even when the buyer is paying with a network token.

Full disclosure — this unified modeling initially threw me as well. In PR #296 I proposed a separate card_network_token_credential type, which would have naturally sidestepped this problem (distinct types = distinct requirements). But as @raginpirate pointed out there, UCP already models both modes in the unified card_credential — consistent with how many processor APIs handle it. Given that direction, the requirements-per-mode problem needs to be solved elsewhere, which is what led me toward named constraints like requires_card_verification: true. The spec would define what that means per card_number_type — "provide cvc" for fpan, "provide cryptogram/eci_value" for network_token — without the merchant needing to enumerate credential-level paths.

Quick illustration:

{
  "available_instruments": [{
    "type": "card",
    "constraints": {
      "brands": ["visa", "mastercard"],
      "requires_card_verification": true
    }
  }]
}

The platform sees requires_card_verification and knows from the spec to collect cvc for an FPAN or cryptogram/eci_value for a network token — one mechanism, consistent with #187.

[alexpark20]

Ah, I missed the purpose of constraints here and this is a good learning! thank you @raginpirate !

After reading comments and new context, here some thoughts:

On required_fields vs. constraints

I can see how constraints already has the power to express what required_fields is trying to do, and I agree we should use a single mechanism rather than introducing a parallel one 👍

That said, I think the implicit per-credential-scheme semantics (e.g., requires_card_verification meaning CVC for FPAN but cryptogram for network tokens) exposes a few gaps in the current modeling.

1. Instrument-credential binding is loose

From my understanding, the current type-specific mapping (card instrument → card credential) is convention, not schema enforced. When we start putting credential level requirements on instrument level constraints (like requires_card_verification), this loose binding becomes a real gap. There is nothing in the schema that formally ties which credential type applies to which instrument type.

As you mentioned already @raginpirate , should we consider introducing available_credentials to formalize this binding? Now that we have a concrete use case (credential-level requirements expressed at the instrument level) ? Or is there other nuances I might missed?

2. card_credential.json

Right now cvc, cryptogram, and eci_value are flat siblings on card_credential. The meaning of "card verification" is entirely implicit per card_number_type. I think we could make this more explicit by grouping them into a verification object (naming could be different) with conditionals that enforce which fields are required per mode:

"verification": {
    "type": "object",
    "description": "Card verification data. Required fields depend on card_number_type."
    "properties": {
      "cvc": {
        "type": "string",
        "maxLength": 4,
        "description": "Card verification code. Applicable to fpan."
      },
      "cryptogram": {
        "type": "string",
        "description": "Cryptogram provided with network tokens."
      },
      "eci_value": {
        "type": "string",
        "description": "Electronic Commerce Indicator provided with network tokens."
      }
    }
}
  
With

  {
    "if": { "properties": { "card_number_type": { "const": "fpan" } } },
    "then": { "properties": { "verification": { "required": ["cvc"] } } }
  },
  {
    "if": { "properties": { "card_number_type": { "const": "network_token" } } },
    "then": { "properties": { "verification": { "required": ["cryptogram", "eci_value"] } } }
  }

This way, requires_card_verification: true as a named constraint would have a clear and enforceable meaning. The verification object is required, and the schema handles which subfields are needed per mode. We can avoid relying on spec documentation to map implicit semantics.

---

On instrument_schema

@raginpirate , I get your point, and that's fair, and this isn't a hill I'll die on.

But I do want to make sure we're making this call with good reasoning. The current schema description on entity is "URL to JSON Schema defining this entity's structure and payloads", which doesn't clearly indicate it will include input schema for payment instruments when using this particular handler. In practice, the platform and business fetch the handler schema to build/verify the payment_handlers response in both well-known and checkout calls. An instrument_schema would serve a different purpose, which is building/verifying the instrument payload submitted. These are related but technically separated entities. Is the benefit of keeping both in the same schema simplicity? Convenience? Just want to understand the reasoning.

[jamesandersen]

Thanks @alexpark20 — the verification object proposal is a clean way to make the schema self-documenting per card_number_type. I think that's a valuable direction, though getting the modeling right there will take some more involved alignment across the group.

Would folks be open to landing this PR as a pragmatic step forward? Concretely, that would mean adding fields like requires_card_verification and requires_billing_address to payment_instrument.constraints, with spec language documenting the per-card_number_type semantics (CVC for FPAN, cryptogram/ECI for network tokens). This gives platforms a way to understand per-merchant requirements today, with fully self-documenting schema (the verification object, available_credentials formalization) as a potential follow-up PR.

I'd update this PR to drop required_fields and instrument_schema, and add the named constraints instead. @raginpirate @alexpark20 does that work?

[raginpirate]

Sorry for the very long circle back on this one @jamesandersen @alexpark20.

@jamesandersen I'm aligned with your proposal to add a few extra constraints for quick product wins 🚀

@alexpark20 responding to your thoughts, I love seeing you dive into this domain 🤿

An instrument_schema would serve a different purpose, which is building/verifying the instrument payload submitted. These are related but technically separated entities. Is the benefit of keeping both in the same schema simplicity? Convenience? Just want to understand the reasoning.

I think I get what you are saying, but how would we think about structuring that? 1 handler has N instrument schemas, so I view this just like how a capability defines N payload schemes under it; the problem seems to be the same there. I will not act as a blocker over the delivery of this if integrators agree this is important to optimize how they type-check and type-share across UCP, but I think this is not a problem isolated to payments... maybe we can chat about this problem deeper if you view one.

As you mentioned already @raginpirate , should we consider introducing available_credentials to formalize this binding? Now that we have a concrete use case (credential-level requirements expressed at the instrument level) ? Or is there other nuances I might missed?

Yeah this one is fair and makes instruments and credentials more expressive 😄 Its not a prioritized investment because most handlers we've looked at really just use a handful of instruments with single credentials right now, but happy to see that opened independently with a clear set of examples we're empowering and/or a real adopter!

This way, requires_card_verification: true as a named constraint would have a clear and enforceable meaning. The verification object is required, and the schema handles which subfields are needed per mode. We can avoid relying on spec documentation to map implicit semantics.

I think this schema proposal is fair but it doesn't match the shape industry payments APIs; folks keep those values flat on the card object, and I think you can still write a constraint regardless of how it's nested. I would advocate to not take on this refactor.

[jamesandersen]

PR updated — dropped required_fields and instrument_schema, replaced with three named constraints on card_payment_instrument.json:

• requires_card_verification
• requires_billing_address
• requires_billing_postal_code

Rebased on latest main, docs updated. Awaiting any further review or, if aligned, approval to merge. @raginpirate @alexpark20

[alexpark20]

Thanks for the updates @jamesandersen, and @raginpirate for the thoughts on my earlier point 👏

I am also aligned with landing this as named constraints on card_payment_instrument.json, which is consistent with #187. We can keep this PR tight.

---

Additional notes:

@raginpirate — fair point on instrument_schema, it is not isolated to payments. We can take that to a separate conversation if it turns out to be a real problem worth solving across the protocol 👍

On the verification object, I am not fully agree with the idea that constraints work regardless of how fields are nested. With the current flat structure, requires_card_verification still carries implicit per type semantics (CVC for FPAN, cryptogram for network tokens) that the spec has to document and implementors have to know. Grouping under a verification object with conditionals would make the schema self-enforcing rather than relying on that documentation.

Although, your point about matching industry payment API shapes is fair, and I don't think it needs to be solved here as part of this PR.

[alexpark20]

Thank you for iterating and addressing all the feedbacks 👏

[raginpirate]

great work, just sharing two notes about the constraints which feel odd.

[raginpirate]

For network tokens: cryptogram and ECI

This constraint description is a bit odd to me, because network tokens can be valid without either of these; a network token can use cvv. Might be worth focusing this only on the requirement of cvv for fpans in specific, and leaving network tokens as open to the platform to make the right decision on.

[raginpirate]

Is this better to represent as an address constraint with three example values (full_address, postal_code, nil)?

[jamesandersen]

@raginpirate thanks for the review and the approval from @alexpark20 — two good catches here.

1. requires_card_verification and network tokens

Agreed the current description is too prescriptive — happy to soften it. Before I update, I want to make sure I understand the scenario you're pointing to. My understanding has been that for CIT transactions with network tokens, the cryptogram and ECI are the expected verification mechanism — the cryptogram proves the token is being used by the authorized requestor for this specific transaction, and the ECI indicates the authentication level. Using CVV as an alternative to the cryptogram in a CIT flow is new to me. Is there a specific PSP or card network flow you're thinking of where that applies? Just want to make sure I get the description right and learn something in the process.

Either way, I think the fix is to, as you suggested, simplify the description to something like: "When true, the handler requires card verification data (e.g., CVC for FPAN credentials)" — and leave it to the platform to provide the appropriate verification for their credential mode, rather than the constraint trying to enumerate fields per card_number_type. The spec docs can provide guidance on common verification patterns without the schema itself being prescriptive.

2. Billing address — single enum vs. two booleans

I like this. The two booleans create an awkward "ignored when" relationship and a 4th combination (street-only without postal code) that doesn't map to how AVS is actually used by issuers. A single constraint with enumerated values aligns better with the practical AVS modes merchants configure:

"billing_address_requirement": {
  "type": "string",
  "enum": ["full", "postal_code"],
  "description": "When present, specifies the billing address data the handler requires. 'full' requires a complete billing address. 'postal_code' requires a billing postal code for AVS verification. When absent, no billing address data is required."
}

I'll hold off pushing changes until I hear back on #1 so I can address both together.

[raginpirate]

@jamesandersen Check out VGS's documentation on it :) https://docs.verygoodsecurity.com/agentic-commerce/provision-network-tokens-for-payments#types-of-cryptograms

and leave it to the platform to provide the appropriate verification for their credential mode

👍 totally agree!

[kmcduffie]

What do you think of merging this with required_billing_address?

If there was an enum for requires_billing_address_data: {FULL_ADDRESS, POSTAL_CODE, NONE}

It would avoid this situation where this property is ignored based on the value of requires_billing_address

[jamesandersen]

Yep - similar to the comment above - this is a good suggestion; I just updated the PR accordingly.

[jamesandersen]

@raginpirate ahh ... I see you're talking about the short-form cryptogram that might be suitable for browser "autofill" network tokens - gotcha.

@raginpirate / @kmcduffie - I've swapped to the enum based approach you both suggested. LMK if anything seems needed here (🤞 )

[raginpirate]

Sorry for a last round of nits here; expect significantly higher response time from me so we can close this out!

[gsmith85]

The billing_address_granularity enum is doing a lot of work for a concept that
UCP already expresses precisely. postal_address.json defines nine named, all-optional fields:

street_address, extended_address, address_locality, address_region, address_country, postal_code, first_name, last_name, phone_number.

The three-level enum collapses all of that into an abstraction that doesn't map cleanly to what PSPs actually require, particularly internationally:

• US AVS needs postal_code (full AVS adds street_address)
• UK AVS needs street_address + postal_code
• Billing name matching needs first_name + last_name
• full_address is ambiguous on whether name fields are included

Rather than a granularity level, consider a field-set constraint that uses the vocabulary postal_address.json already defines:

"required_billing_address_fields": {
  "type": "array",
  "items": { "type": "string" },
  "description": "Billing address fields the handler requires. Values correspond to field names in postal_address.json (e.g., 'postal_code', 'address_country', 'first_name')."
}

[gsmith85]

Covered by others (@raginpirate, @alexpark20), but I agree that requires_card_verification feels off. It's a boolean with no direct linkage to the field it's actually requiring — the platform is left to "know" that this means cvc for FPAN. For network tokens and DPANs, cryptogram and eci_value are structurally required regardless, so the boolean doesn't meaningfully apply.

Are there other examples you're aiming to solve for with requires_card_verification? Otherwise I think we can lean towards directly addressing the CVC case. See below for an idea on possible structuring.

[gsmith85]

Bringing it all together: The two new fields point toward a pattern worth making explicit. Rather than top-level boolean/enum fields on constraints, what if constraints used sub-objects that mirror the instrument's own property hierarchy?

Instead of:

"constraints": {
  "requires_card_verification": true,
  "billing_address_granularity": "postal_code"
}

Something like:

"constraints": {
  "credential": {
    "card_credential": {
      "required": ["cvc"]
    },
    "bank_account_credential": {
      "required": ["account_type"]
    }
  },
  "billing_address": {
    "required": ["postal_code"]
  }
}

The credential key mirrors the property on the instrument; the card_credential sub-key handles the polymorphic case, constraints are scoped to a specific subtype and can't bleed across incompatible schemas.

The required arrays use field names from the schemas they govern (card_credential.json, postal_address.json). No new vocabulary to maintain, no translation layer between granularity enum values and actual address fields.

[gsmith85]

@raginpirate curious if this fits the constraints model you had in mind in #187.

[jamesandersen]

@gsmith85 thanks for the detailed review! I want to make sure you have the full context on the discussion arc — I did force push and update the PR content mid-way through the discussion here, which makes it harder to follow the evolution from the diff alone. The comment thread tells the fuller story.

This PR originally proposed required_fields (an array of dot-notation paths like credential.cvc, billing_address.postal_code) — which is conceptually similar to the structured required arrays you're proposing. After discussion, @raginpirate pointed out that payment_instrument.constraints already has this power (see #187) and suggested using named constraints as a single mechanism consistent with that existing pattern. @alexpark20 aligned with landing named constraints on card_payment_instrument.json as consistent with #187.

So the current approach — flat named constraints — is the result of iterating away from the field-reference pattern toward something the maintainers felt was more consistent with the existing constraints model.

On your specific points:

requires_card_verification — The evolution here was: @raginpirate noted that the description was too prescriptive about network tokens (they can use CVV too), so I simplified it to just signal that card verification is required and leave it to the platform to provide the appropriate data for their credential mode. That's where it stands now — intentionally abstract rather than field-specific.

billing_address_granularity — Your point about international AVS variation is fair. The enum doesn't cover every combination. The tradeoff the group landed on was keeping this simple and extensible — full_address and postal_code cover the dominant patterns, and additional values can be added to the enum as real adopter needs emerge. That said, if @raginpirate thinks a field-set array like you're proposing would better fit the constraints model, I'm open to it — though it does circle back toward the required_fields approach we moved away from.

Structured sub-object constraints — This is the most interesting suggestion, but it's also the closest to what required_fields was originally doing (field-level references into the schema hierarchy). @raginpirate would have the best perspective on whether this fits the constraints model from #187 — I see you've already tagged him there.

Happy to iterate further if @raginpirate or @alexpark20 feel any of these proposals better serve the constraints direction. The goal has been to keep this PR tight and land incremental value, with room for richer constraint modeling in follow-ups.

[raginpirate]

Love the thinking here @gsmith85!
I'll augment @jamesandersen summary above to give my perspective on the feedback.

billing_address_granularity

Great push on this one; originally I also thought about just having a full-resolution answer of using billing_address and then specifying required fields under it, but I swayed away from it for a more payments-focused abstraction that matches how providers generally solve this problem; full, postal-only, and not required; keeps it simple. I do think this works for most if not all merchants.

But seeing this push again echo'd by you @gsmith85 makes me wonder more about constraints generally across UCP. I think it is right for us to build this as constraints for addresses, and to share this constraint primitive with other domains. Looking around, it seems like fulfillment actually has a gap where it does not expose any concept of address constraints, and we could be building a reasonable foundation here! With this we also future-proof ourselves; we don't have to maintain some payments constraint abstraction for addresses.

TLDR; agreed with this push, and we have an action to take back to the UCP TC to discuss how we share this into the fulfillment extension as an example 😄

requires_card_verification

For this one, agreed and we've discussed available_credentials needing to be advertised as well in UCP at some point. The nuance here is that although technically we want to describe this requirement about the raw credential here, you can have "credential inception" by which a provider token is what you support ingesting (no cvv field on it for example), but yet we're trying to communicate that we need a cvv on the raw card behind that credential. As well, you would have to redefine the same constraint N times for each credential type.

I see two options here:

• proceed with a proposal to push a simple, abstract helper to cover the concept of required verification across any used credential. This is simple, and generally fits what any merchant needs.
• dive deep here and solve this abstract concern, which I think bringing in a subtype of credentials I'd like to call the funding sources would solve this issue. Communicate available credential constraints as well as available funding source constraints; the two sets of types do not need to overlap.

I did some pairing with Claude and I opened this: #424 <-- PTAL @gsmith85 and @jamesandersen! Maybe we can just shift to a better state of the world with the abstract fundamentals here.