docs: use collectData.schema as source of truth for native UI, deprecate fields

payments/psps/headless-sdk/implementation.mdx

@@ -306,8 +306,10 @@ switch (snapshot.state) {
     return <Empty label="No payment options for this wallet." />
 
   case 'InformationCapture':
-    // Render snapshot.collectData.fields, then:
-    return <KycForm fields={snapshot.collectData?.fields} onSubmit={submitInfoCapture} />
+    // Render a form from snapshot.collectData.schema — a JSON Schema whose top-level
+    // "required" array and conditional "anyOf" groups define every mandatory field.
+    // Do not render from the deprecated collectData.fields array: it omits required fields.
+    return <KycForm schema={snapshot.collectData?.schema} onSubmit={submitInfoCapture} />
 
   case 'OptionSelected':
   case 'RequiresApproval':

payments/wallets/api-first.mdx

@@ -215,7 +215,11 @@ Data collection is per-option — each payment option may independently have a `
 
 If the selected option's `collectData` has a `url` field, display it in a WebView before confirming. The URL is already scoped to that option's account. The WebView handles form rendering, validation, and T&C acceptance. When the WebView signals completion (`IC_COMPLETE` via JS bridge), proceed to confirm — no need to include `collectedData` in the request.
 
-If you choose not to use the WebView and instead build your own form, use the `collectData.schema` JSON schema to determine the required fields, collect the values, and pass them as `collectedData` in the confirm request.
+If you choose not to use the WebView and instead build your own form, `collectData.schema` is the single source of truth for which fields to render. Parse the JSON Schema: render an input for each entry in `properties`, treat every field in the top-level `required` array as mandatory, and honor conditional `anyOf` groups (for example, the schema may require **either** place-of-birth or place-of-residence fields). Collect the values and pass them as `collectedData` in the confirm request.
+
+<Warning>
+Do not build forms from the deprecated `collectData.fields` array. It is retained for backward compatibility only and does not include all required fields (for example, country of residence or birth) — forms built from it will collect incomplete compliance data.
+</Warning>
 
 ### Expiration handling
 

payments/wallets/overview.mdx

@@ -194,7 +194,7 @@ Wallets can earn interchange-like revenue on eligible WalletConnect Pay payments
     - [WalletConnect Terms and Conditions](https://walletconnect.com/terms)
     - [WalletConnect Privacy Policy](https://walletconnect.com/privacy)
 
-    The required user information can be sent to WalletConnect using schema in the `collect_data` object.
+    When building custom UI, the JSON Schema in `collectData.schema` is the single source of truth for which fields to render: treat every field in its top-level `required` array as mandatory and honor conditional `anyOf` groups (for example, the schema may require either place-of-birth or place-of-residence fields). Do **not** build forms from the deprecated `fields` array — it does not include all required fields. Submit the collected values as `collectedData` when confirming the payment.
 
     We strongly recommend using the WebView-based flow over building custom native UI. Data collection requirements are driven by regulation and can evolve. The hosted WebView form is maintained and updated centrally so that wallets can automatically pick up changes.
   </Accordion>

payments/wallets/standalone/flutter.mdx

@@ -665,11 +665,15 @@ class WalletRpcAction {
 
 ```dart
 class CollectDataAction {
-  final String url;                // WebView URL for data collection
-  final String? schema;            // JSON schema describing required fields
+  final String url;                // WebView URL for data collection (recommended)
+  final String? schema;            // JSON Schema — source of truth for native-UI forms (parse required + anyOf)
 }
 ```
 
+<Warning>
+`CollectDataAction` also exposes a deprecated `fields` property. Do not use it to build native UI — it does not include all required fields. Use `url` for the WebView flow (recommended) or parse `schema` for native forms.
+</Warning>
+
 ## Error Handling
 
 The SDK throws specific exception types for different error scenarios. All errors extend the abstract `PayError` class, which itself extends `PlatformException`:

payments/wallets/standalone/kotlin.mdx

@@ -656,11 +656,15 @@ sealed class RequiredAction {
 
 ```kotlin
 data class CollectDataAction(
-    val url: String,               // WebView URL for data collection
-    val schema: String?            // JSON schema describing required fields
+    val url: String,               // WebView URL for data collection (recommended)
+    val schema: String?            // JSON Schema — source of truth for native-UI forms (parse required + anyOf)
 )
 ```
 
+<Warning>
+`CollectDataAction` also exposes a deprecated `fields` property. Do not use it to build native UI — it does not include all required fields. Use `url` for the WebView flow (recommended) or parse `schema` for native forms.
+</Warning>
+
 **Pay.ConfirmPaymentResponse**
 
 ```kotlin

payments/wallets/standalone/react-native.mdx

@@ -297,7 +297,7 @@ const result = await client.confirmPayment({
   paymentId: options.paymentId,
   optionId: options.options[0].id,
   signatures,
-  collectedData, // Include if collectData was present
+  collectedData, // Native UI only — omit when using the WebView flow; build from collectData.schema
 });
 
 if (result.status === "succeeded") {
@@ -734,13 +734,17 @@ interface BuyerInfo {
 
 ```typescript
 interface CollectDataAction {
-  /** URL for data collection (displayed in WebView) */
+  /** URL for data collection (displayed in WebView) — recommended */
   url: string;
-  /** JSON schema describing required fields */
+  /** JSON Schema — source of truth for native-UI forms (parse required + anyOf) */
   schema?: string;
 }
 ```
 
+<Warning>
+`collectData` in the API response also contains a deprecated `fields` array. Do not use it to build native UI — it does not include all required fields. Use `url` for the WebView flow (recommended) or parse `schema` for native forms.
+</Warning>
+
 ## Error Handling
 
 The SDK throws typed errors for different failure scenarios:

payments/wallets/standalone/swift.mdx

@@ -709,11 +709,15 @@ struct WalletRpcAction {
 
 ```swift
 struct CollectDataAction {
-    let url: String                    // WebView URL for data collection
-    let schema: String?                // JSON schema describing required fields
+    let url: String                    // WebView URL for data collection (recommended)
+    let schema: String?                // JSON Schema — source of truth for native-UI forms (parse required + anyOf)
 }
 ```
 
+<Warning>
+`CollectDataAction` also exposes a deprecated `fields` property. Do not use it to build native UI — it does not include all required fields. Use `url` for the WebView flow (recommended) or parse `schema` for native forms.
+</Warning>
+
 **ConfirmPaymentResultResponse**
 
 ```swift

payments/wallets/standalone/web.mdx

@@ -294,7 +294,7 @@ const result = await client.confirmPayment({
   paymentId: options.paymentId,
   optionId: options.options[0].id,
   signatures,
-  collectedData, // Include if collectData was present
+  collectedData, // Custom form UI only — omit when using the iframe flow; build from collectData.schema
 });
 
 if (result.status === "succeeded") {
@@ -691,13 +691,17 @@ interface BuyerInfo {
 
 ```typescript
 interface CollectDataAction {
-  /** URL for data collection (displayed in iframe) */
+  /** URL for data collection (displayed in iframe) — recommended */
   url: string;
-  /** JSON schema describing required fields */
+  /** JSON Schema — source of truth for custom form UI (parse required + anyOf) */
   schema?: string;
 }
 ```
 
+<Warning>
+`collectData` in the API response also contains a deprecated `fields` array. Do not use it to build custom form UI — it does not include all required fields. Use `url` for the iframe flow (recommended) or parse `schema` for custom forms.
+</Warning>
+
 ## Error Handling
 
 The SDK throws typed errors for different failure scenarios:

payments/wallets/walletkit/ai-prompts/flutter.mdx

@@ -207,7 +207,7 @@ class PaymentResultInfo {
 
 class CollectDataAction {
   final String url;                // WebView URL for data collection
-  final String? schema;            // JSON schema describing required fields
+  final String? schema;            // JSON Schema — source of truth for native-UI forms (parse required + anyOf); never use the deprecated `fields` property
 }
 
 class PaymentInfo {

payments/wallets/walletkit/ai-prompts/kotlin.mdx

@@ -165,7 +165,7 @@ data class PaymentOption(
 // Data collection action (for KYC/compliance via WebView)
 data class CollectDataAction(
     val url: String,           // WebView URL for data collection
-    val schema: String?        // JSON schema describing required fields
+    val schema: String?        // JSON Schema — source of truth for native-UI forms (parse required + anyOf); never use the deprecated `fields` property
 )
 
 // Transaction result details (present when payment already completed)

payments/wallets/walletkit/ai-prompts/react-native.mdx

@@ -550,7 +550,7 @@ interface PayAmount {
 
 interface CollectDataAction {
   url: string;                  // WebView URL for data collection
-  schema?: string;              // JSON schema describing required fields
+  schema?: string;              // JSON Schema — source of truth for native-UI forms (parse required + anyOf); never use the deprecated `fields` array
 }
 
 interface Action {

payments/wallets/walletkit/ai-prompts/swift.mdx

@@ -639,7 +639,7 @@ struct WalletRpcAction {
 
 struct CollectDataAction {
     let url: String                    // WebView URL for data collection
-    let schema: String?                // JSON schema describing required fields
+    let schema: String?                // JSON Schema — source of truth for native-UI forms (parse required + anyOf); never use the deprecated `fields` property
 }
 
 struct ConfirmPaymentResultResponse {

payments/wallets/walletkit/flutter.mdx

@@ -607,11 +607,15 @@ enum PaymentStatus {
 
 ```dart
 class CollectDataAction {
-  final String url;                // WebView URL for data collection
-  final String? schema;            // JSON schema describing required fields
+  final String url;                // WebView URL for data collection (recommended)
+  final String? schema;            // JSON Schema — source of truth for native-UI forms (parse required + anyOf)
 }
 ```
 
+<Warning>
+`CollectDataAction` also exposes a deprecated `fields` property. Do not use it to build native UI — it does not include all required fields. Use `url` for the WebView flow (recommended) or parse `schema` for native forms.
+</Warning>
+
 ## Error Handling
 
 The SDK throws specific exception types for different error scenarios. All errors extend the abstract `PayError` class, which itself extends `PlatformException`:

payments/wallets/walletkit/kotlin.mdx

@@ -666,11 +666,15 @@ data class WalletRpcAction(
 
 ```kotlin
 data class CollectDataAction(
-    val url: String,               // WebView URL for data collection
-    val schema: String?            // JSON schema describing required fields
+    val url: String,               // WebView URL for data collection (recommended)
+    val schema: String?            // JSON Schema — source of truth for native-UI forms (parse required + anyOf)
 )
 ```
 
+<Warning>
+`CollectDataAction` also exposes a deprecated `fields` property. Do not use it to build native UI — it does not include all required fields. Use `url` for the WebView flow (recommended) or parse `schema` for native forms.
+</Warning>
+
 **Wallet.Model.ConfirmPaymentResponse**
 
 ```kotlin

payments/wallets/walletkit/react-native.mdx

@@ -279,7 +279,7 @@ const result = await walletkit.pay.confirmPayment({
   paymentId: options.paymentId,
   optionId: options.options[0].id,
   signatures,
-  collectedData, // Optional, if collectData was present
+  collectedData, // Native UI only — omit when using the WebView flow; build from collectData.schema
 });
 
 // result.status - "succeeded" | "processing" | "failed" | "expired"
@@ -635,13 +635,17 @@ interface AmountDisplay {
 
 ```typescript
 interface CollectDataAction {
-  /** WebView URL for data collection */
+  /** WebView URL for data collection — recommended */
   url: string;
-  /** JSON schema describing required fields */
+  /** JSON Schema — source of truth for native-UI forms (parse required + anyOf) */
   schema?: string;
 }
 ```
 
+<Warning>
+`collectData` in the API response also contains a deprecated `fields` array. Do not use it to build native UI — it does not include all required fields. Use `url` for the WebView flow (recommended) or parse `schema` for native forms.
+</Warning>
+
 ## Error Handling
 
 Handle errors gracefully in your payment flow:

payments/wallets/walletkit/swift.mdx

@@ -659,11 +659,15 @@ struct WalletRpcAction {
 
 ```swift
 struct CollectDataAction {
-    let url: String                    // WebView URL for data collection
-    let schema: String?                // JSON schema describing required fields
+    let url: String                    // WebView URL for data collection (recommended)
+    let schema: String?                // JSON Schema — source of truth for native-UI forms (parse required + anyOf)
 }
 ```
 
+<Warning>
+`CollectDataAction` also exposes a deprecated `fields` property. Do not use it to build native UI — it does not include all required fields. Use `url` for the WebView flow (recommended) or parse `schema` for native forms.
+</Warning>
+
 **ConfirmPaymentResultResponse**
 
 ```swift

payments/wallets/walletkit/web.mdx

@@ -285,7 +285,7 @@ const result = await walletkit.pay.confirmPayment({
   paymentId: options.paymentId,
   optionId: options.options[0].id,
   signatures,
-  collectedData, // Optional, if collectData was present
+  collectedData, // Custom form UI only — omit when using the iframe flow; build from collectData.schema
 });
 
 // result.status - "succeeded" | "processing" | "failed" | "expired"
@@ -627,13 +627,17 @@ interface AmountDisplay {
 
 ```typescript
 interface CollectDataAction {
-  /** URL for data collection (displayed in iframe) */
+  /** URL for data collection (displayed in iframe) — recommended */
   url: string;
-  /** JSON schema describing required fields */
+  /** JSON Schema — source of truth for custom form UI (parse required + anyOf) */
   schema?: string;
 }
 ```
 
+<Warning>
+`collectData` in the API response also contains a deprecated `fields` array. Do not use it to build custom form UI — it does not include all required fields. Use `url` for the iframe flow (recommended) or parse `schema` for custom forms.
+</Warning>
+
 ## Error Handling
 
 Handle errors gracefully in your payment flow:

snippets/webview-data-collection-overview.mdx

@@ -54,3 +54,19 @@ The top-level `collectData` on the payment options response is still available f
 <Warning>
 Do **not** pass `collectedData` to `confirmPayment()` when using the embedded form. The form handles data submission directly.
 </Warning>
+
+<Accordion title="Building native UI instead">
+  WalletConnect Pay strongly recommends the embedded form: data collection requirements are driven by regulation and can change, and the hosted form is updated centrally. Wallets that build native UI instead must use `collectData.schema` as the single source of truth for which fields to render:
+
+  <Warning>
+  Do **not** build native forms from the deprecated `fields` array on `collectData`. It is retained for backward compatibility only and does not include all required fields (for example, country of residence or birth). Forms built from `fields` will collect incomplete compliance data.
+  </Warning>
+
+  1. Parse `schema` — a [JSON Schema](https://json-schema.org/) (draft 2020-12) string
+  2. Render an input for each entry in `properties` (each has a `title`, `description`, `type`, and format constraints)
+  3. Treat every field in the top-level `required` array as mandatory
+  4. Honor conditional requirements in `anyOf` — for example, the schema may require **either** place-of-birth (`pobCountry` + `pobAddress`) **or** place-of-residence (`porCountry` + `porAddress`)
+  5. Validate values against the schema constraints (`pattern`, `format`, `minLength`, `maxLength`)
+  6. Ensure the user accepts the [WalletConnect Terms and Conditions](https://walletconnect.com/terms) and [Privacy Policy](https://walletconnect.com/privacy) (`tosConfirmed`)
+  7. Pass the collected values as `collectedData` to `confirmPayment()` — required when using native UI
+</Accordion>