feat: add required_fields to available payment instruments

Enable payment handlers to declare which optional fields they require
for payment processing via a new `required_fields` property on
`available_payment_instrument.json`. Uses dot notation for nested
properties (e.g., `credential.cvc`, `billing_address.postal_code`).

This eliminates guesswork for agentic platforms — they can collect
exactly the right fields before attempting tokenization, avoiding
trial-and-error retries and unnecessary over-collection of buyer data.

Author: James Andersen

docs/specification/payment-handler-guide.md

@@ -197,6 +197,48 @@ instrument types defined by its handler schema. When present, it narrows the
 advertised types and/or applies additional constraints (e.g., limiting card
 brands to `["visa", "mastercard"]`).
 
+#### Required Fields
+
+Each entry in `available_instruments` **MAY** include a `required_fields`
+array that declares which optional fields from the instrument or credential
+schemas this handler requires for payment processing.
+
+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. Without `required_fields`, the platform must
+guess which optional fields the merchant actually needs — leading to
+trial-and-error tokenization or over-collection of buyer data.
+
+**Dot notation** identifies which layer a field belongs to:
+
+| Notation | Layer | Example |
+| :------- | :---- | :------ |
+| `credential.<field>` | Credential property | `credential.cvc`, `credential.name` |
+| `billing_address.<field>` | Billing address subfield | `billing_address.postal_code` |
+| `<field>` (no prefix) | Top-level instrument property | `billing_address` (full object) |
+
+**Example — CVC and postal-only AVS:**
+
+```json
+{
+  "available_instruments": [
+    {
+      "type": "card",
+      "required_fields": ["credential.cvc", "billing_address.postal_code"]
+    }
+  ]
+}
+```
+
+The platform reads `required_fields` from the resolved `available_instruments`
+in the response and knows exactly which fields to collect from the buyer
+before constructing the instrument — no guesswork, no retry loops.
+
+When `required_fields` is absent, the handler places no additional field
+requirements beyond what the schema already marks as required. Platforms fall
+back to existing behavior.
+
 ---
 
 #### Handler Declaration Variants
@@ -268,7 +310,8 @@ and typically includes different configuration:
       "type": "card",
       "constraints": {
         "brands": ["visa", "mastercard"]
-      }
+      },
+      "required_fields": ["credential.cvc", "billing_address.postal_code"]
     }
   ],
   "config": {
@@ -314,6 +357,11 @@ authoritative value returned in the `response_schema`.
 In this example, the business's PSP is not configured for Discover, so Discover
 is excluded from the response even though the platform supports it.
 
+`required_fields` participates in this resolution naturally: the business
+includes `required_fields` in the resolved `available_instruments` returned
+in the response. The platform reads these requirements at the same time it
+discovers which instruments are available — no additional round-trip needed.
+
 ---
 
 #### Defining the Schema
@@ -511,10 +559,10 @@ specifies what constraints are valid for that instrument type. For example,
 [`card_payment_instrument.json`](site:schemas/shopping/types/card_payment_instrument.json)
 defines `available_card_payment_instrument` with a `brands` constraint.
 
-| Schema                                                                                                 | Constraints                                                     |
-| :----------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------- |
-| [`available_payment_instrument.json`](site:schemas/shopping/types/available_payment_instrument.json)   | Base: type, constraints (open object)                           |
-| `card_payment_instrument.json#/$defs/available_card_payment_instrument`                                | Extends base with `constraints.brands` for card networks        |
+| Schema                                                                                                 | Constraints                                                              |
+| :----------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------- |
+| [`available_payment_instrument.json`](site:schemas/shopping/types/available_payment_instrument.json)   | Base: type, constraints (open object), required_fields (optional array)  |
+| `card_payment_instrument.json#/$defs/available_card_payment_instrument`                                | Extends base with `constraints.brands` for card networks                 |
 
 Handlers reference these instrument-defined schemas when declaring
 `available_instruments`. The **instrument schema authors** define what

source/schemas/shopping/types/available_payment_instrument.json

@@ -15,6 +15,15 @@
       "additionalProperties": true,
       "description": "Constraints on this instrument type. Structure depends on instrument type and active capabilities.",
       "minProperties": 1
+    },
+    "required_fields": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Optional fields from the instrument or credential schemas that this handler requires for payment processing. Uses dot notation for nested properties: credential fields use 'credential.' prefix (e.g., 'credential.cvc', 'credential.name'), billing address subfields use 'billing_address.' prefix (e.g., 'billing_address.postal_code'). Top-level instrument fields use their property name directly (e.g., 'billing_address' for the full object).",
+      "minItems": 1,
+      "uniqueItems": true
     }
   }
 }