docs: add WebView-based data collection docs #24

jakubuid · 2026-02-09T11:47:31Z

Summary

Replace native field-by-field data collection with WebView-based approach across all 17 documentation files
CollectDataAction model now uses url (WebView URL) and schema (JSON schema) instead of fields array
confirmPayment() no longer requires collectedData parameter when WebView is used — the WebView submits data directly
New PaymentResultInfo model added to ConfirmPaymentResponse with txId and optionAmount
New FAQ entries added to wallet overview covering custom UI vs. WebView trade-offs and pre-filling customer information

Files Changed

Category	Files	Count
New shared snippets	`snippets/webview-data-collection-*.mdx`	3
Standalone SDK docs	`payments/wallets/standalone/{kotlin,swift,react-native,flutter}.mdx`	4
WalletKit SDK docs	`payments/wallets/walletkit/{kotlin,swift,flutter,web}.mdx`	4
AI prompts	`payments/wallets/walletkit/ai-prompts/{kotlin,swift,flutter,react-native}.mdx`	4
Overview & API-first	`payments/wallets/{overview,api-first}.mdx`	2

What changed in each doc

flowchart TD
    A[Payment Options Response] --> B{collectDataAction.url present?}
    B -->|Yes| C[Display WebView]
    B -->|No| D[Skip to Confirm]
    C --> E[User fills form in WebView]
    E --> F{JS Bridge Message}
    F -->|IC_COMPLETE| G[Proceed to confirmPayment - no collectedData needed]
    F -->|IC_ERROR| H[Show error, allow retry]
    G --> I[Payment Complete]

Mermaid sequence diagrams: Updated to show WebView participant in data collection flow
"Collect User Data" step: Replaced with WebView URL loading + prefill mechanism
WebView Implementation section: Added platform-specific code (Android WebView, iOS WKWebView, Flutter webview_flutter, RN react-native-webview)
Data models: CollectDataAction → {url, schema}, removed CollectDataField/CollectDataFieldType
AI prompts: CollectingData state → WebViewDataCollection, added onWebViewComplete()/onWebViewError() handlers
Overview FAQ: Updated answers + added new FAQs (see below)

Platform-Specific Bridge Names

Platform	WebView Library	JS Bridge Name
Kotlin	`android.webkit.WebView`	`AndroidWallet`
Swift	`WKWebView`	`payDataCollectionComplete`
Flutter	`webview_flutter` (4.10+)	`ReactNativeWebView` (via JS bridge)
React Native	`react-native-webview` (13.16+)	`ReactNativeWebView` (native)

Updates since last revision

Added three FAQ entries to payments/wallets/overview.mdx:

"What is the WebView data collection approach?" — appended a recommendation to use WebView over custom native UI, noting that data collection requirements are regulation-driven and the hosted form is maintained centrally.
"Can wallets implement custom UI instead of the WebView form?" — new FAQ explaining that custom UI is possible but wallets assume responsibility for keeping forms in sync, and must ensure users accept WalletConnect T&C and Privacy Policy. References the collect_data schema.
"Can wallets pre-fill customer information?" — new FAQ confirming pre-fill is supported, with a note that wallets skipping the WebView must ensure T&C and Privacy Policy acceptance.

Review & Testing Checklist for Human

Verify the three new FAQ entries in payments/wallets/overview.mdx render correctly (AccordionGroup items) — run mint dev and check the overview page
Confirm the T&C and Privacy Policy links work: https://walletconnect.com/terms and https://walletconnect.com/privacy
Review FAQ wording for consistency with the rest of the WebView documentation (especially the custom UI vs. WebView trade-off messaging)

Test Plan

Run mint dev locally
Navigate to /payments/wallets/overview and expand each FAQ accordion
Click the T&C and Privacy Policy links to verify they resolve correctly

Notes

Link to Devin run: https://app.devin.ai/sessions/d3cc0fbeec8f4a368dd0616ffb154ba9
Requested by: @mirnab0

Replace native field-by-field data collection with WebView-based approach for Information Capture (IC). The CollectDataAction model now uses a `url` field pointing to a WalletConnect-hosted form. When present, wallets display it in a WebView instead of building native forms. The WebView handles form rendering, validation, T&C acceptance, and communicates completion via JS bridge messages (IC_COMPLETE / IC_ERROR). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…refill examples - Remove PaymentResultInfo from ConfirmPaymentResponse across all docs - Add resultInfo: PaymentResultInfo? to PaymentOptionsResponse in all platform docs and AI prompts - Add pobAddress field to all prefill data examples - Document that schema's required list can be used to determine prefill fields Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

ignaciosantise · 2026-02-09T14:35:43Z

payments/wallets/standalone/flutter.mdx

    }

-    // Step 6: Confirm payment
+    // Step 6: Confirm payment (no collectedData when WebView is used)


Suggested change

// Step 6: Confirm payment (no collectedData when WebView is used)

// Step 6: Confirm payment

Fixed in 3bb4277

ignaciosantise · 2026-02-09T14:39:51Z

payments/wallets/standalone/kotlin.mdx

                    }

-                    // Step 5: Confirm payment
+                    // Step 5: Confirm payment (no collectedData when WebView is used)


Suggested change

// Step 5: Confirm payment (no collectedData when WebView is used)

// Step 5: Confirm payment

Fixed in 3bb4277

ignaciosantise · 2026-02-09T14:40:51Z

payments/wallets/standalone/react-native.mdx

      }

-      // Step 6: Confirm payment
+      // Step 6: Confirm payment (no collectedData when WebView is used)


Suggested change

// Step 6: Confirm payment (no collectedData when WebView is used)

// Step 6: Confirm payment

Fixed in 3bb4277

ignaciosantise · 2026-02-09T14:41:29Z

payments/wallets/standalone/swift.mdx

-        
-        // 6. Confirm payment
+
+        // 6. Confirm payment (no collectedData when WebView is used)


Suggested change

// 6. Confirm payment (no collectedData when WebView is used)

// 6. Confirm payment

Fixed in 3bb4277

ignaciosantise · 2026-02-09T14:42:01Z

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

 ```

-### Step 5: Handle Data Collection (Optional)
+### Step 5: Handle Data Collection via WebView (Optional)


Suggested change

### Step 5: Handle Data Collection via WebView (Optional)

### Step 5: Handle Data Collection via WebView

Fixed in 3bb4277

ignaciosantise · 2026-02-09T14:44:51Z

snippets/webview-data-collection-best-practices.mdx

+- **Handle errors**: Listen for `IC_ERROR` messages and display a user-facing error message with an option to retry
+- **External links**: Open Terms & Conditions and Privacy Policy links in the system browser rather than navigating within the WebView
+- **Domain restriction**: Only allow navigation to WalletConnect pay domains and HTTPS URLs
+- **Back navigation**: Handle back/dismiss gracefully — confirm cancellation with the user before closing the WebView mid-flow


We should also add an item for devs to test how the app behaves when the keyboard is opened. If its not well handled, the keyboard could show above the inputs

Added keyboard behavior testing item to best practices in 3bb4277

ganchoradkov · 2026-02-09T14:48:08Z

payments/wallets/standalone/react-native.mdx

+    pobAddress: "123 Main St, New York, NY 10001",
+  };
+  const prefillBase64 = btoa(JSON.stringify(prefillData));
+  const webViewUrl = `${options.collectData.url}?prefill=${prefillBase64}`;


Suggested change

const webViewUrl = `${options.collectData.url}?prefill=${prefillBase64}`;

const webViewUrl = `${options.collectData.url}&prefill=${prefillBase64}`;

I think the url already contains parameters so the prefix has to be added with &, only the first param is set with ?

in react-native sample wallet we have this util code

function buildUrlWithPrefill(baseUrl: string): string { const prefillJson = JSON.stringify(PREFILL_DATA); const prefillBase64 = btoa(prefillJson); if (baseUrl.includes('prefill=')) { return baseUrl.replace(/prefill=([^&]*)/, `prefill=${prefillBase64}`); } const separator = baseUrl.includes('?') ? '&' : '?'; return `${baseUrl}${separator}prefill=${prefillBase64}`; }

it checks if there is already ?

Fixed in 3bb4277 — updated all platforms to use proper URL builders that handle existing query parameters (Uri.buildUpon for Kotlin, URLComponents for Swift, Uri.replace for Flutter, separator check for JS/RN)

Thanks! Applied the pattern across all platforms using platform-native URL builders in 3bb4277

- Remove Sdk-Name/Sdk-Version/Sdk-Platform headers (internal SDK use only) - Remove Client-Id header (internal use only) - Add optional App-Id header to all endpoints - Add url and schema fields to CollectData schema - Add account field to PaymentOption schema - Add networkIconUrl to AmountDisplay schema - Update confirm endpoint description (commitment point) - Update API-first page with Api-Key prerequisite and Sdk-* warning Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…nfirm example - Reorder API-first flow diagram: data collection now happens before option selection - Remove Sdk-* warning block from API-first page - Add tosConfirmed field to confirm payment request example Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

… comments - Remove "(no collectedData when WebView is used)" from confirm payment step comments - Remove "(Optional)" from Flutter AI prompt WebView step heading - Add keyboard behavior testing to WebView best practices - Fix prefill URL construction to handle existing query parameters using platform-native URL builders (Uri.buildUpon for Kotlin, URLComponents for Swift, Uri.replace for Flutter, separator check for JS/RN) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…tion Co-Authored-By: mirna@reown.com <mirna@reown.com>

chris13524 · 2026-02-10T12:21:05Z

payments/wallets/overview.mdx

+    Yes.
+
+    Wallets that choose to implement custom UI assume responsibility for keeping their forms in sync with changes, which can introduce delays and potential jurisdictional blockers. Wallets also must ensure the user has accepted:
+    - [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.
+
+    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.


Suggested change

Yes.

Wallets that choose to implement custom UI assume responsibility for keeping their forms in sync with changes, which can introduce delays and potential jurisdictional blockers. Wallets also must ensure the user has accepted:

- [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.

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.

Yes, with a caveat.

Wallets that choose to implement custom UI assume responsibility for keeping their forms in sync with these changes. When changes are rolled out, wallets must implement them immediately. If the provided data is not what is requested, users in the relevant jurisdiction(s) will be unable to pay until the custom integration is updated. The WebView approach eliminates this overhead and ensures a consistent, up-to-date experience with minimal integration effort.

Wallets also must ensure the user has accepted:

- [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.

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.

chris13524 · 2026-02-10T12:23:11Z

api/walletconnect-pay-gateway.yaml

        - Gateway
      summary: Confirm a payment
-      description: This endpoint confirms a payment and submits it to the blockchain for processing.
+      description: "This endpoint confirms a payment and submits it to the blockchain for processing. This is the COMMITMENT point - after this succeeds, the payment is durable."


We don't need to say this. This is internal information. Looks like it came from our spec, I'll remove.

Suggested change

description: "This endpoint confirms a payment and submits it to the blockchain for processing. This is the COMMITMENT point - after this succeeds, the payment is durable."

description: "This endpoint confirms a payment and submits it to the blockchain for processing."

Based on patterns from the WCPay SDK (Yttrium): payment link detection, action resolution, result submission, polling, retry strategy, data collection, and expiration handling. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

mintlify bot deployed to staging February 9, 2026 11:48 View deployment

mintlify bot deployed to staging February 9, 2026 12:07 View deployment

jakubuid requested review from ganchoradkov and riveign February 9, 2026 12:10

ignaciosantise reviewed Feb 9, 2026

View reviewed changes

ganchoradkov reviewed Feb 9, 2026

View reviewed changes

mintlify bot deployed to staging February 10, 2026 07:55 View deployment

jakubuid requested a review from chris13524 February 10, 2026 07:55

mintlify bot deployed to staging February 10, 2026 08:06 View deployment

mintlify bot deployed to staging February 10, 2026 08:14 View deployment

Add note about skipping collectedData when WebView is used for IC

2a71316

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

mintlify bot deployed to staging February 10, 2026 08:22 View deployment

docs: add FAQ entries for custom UI, pre-fill, and WebView recommenda…

23c26c4

…tion Co-Authored-By: mirna@reown.com <mirna@reown.com>

mintlify bot deployed to staging February 10, 2026 09:46 View deployment

devin-ai-integration bot changed the title ~~Add WebView-based data collection docs~~ docs: add WebView-based data collection docs Feb 10, 2026

chris13524 reviewed Feb 10, 2026

View reviewed changes

jakubuid requested a review from mirnab0 February 10, 2026 13:09

mintlify bot deployed to staging February 10, 2026 14:34 View deployment

ganchoradkov approved these changes Feb 10, 2026

View reviewed changes

	// Step 6: Confirm payment (no collectedData when WebView is used)
	// Step 6: Confirm payment

	// Step 5: Confirm payment (no collectedData when WebView is used)
	// Step 5: Confirm payment


		// 6. Confirm payment

		// 6. Confirm payment (no collectedData when WebView is used)

	### Step 5: Handle Data Collection via WebView (Optional)
	### Step 5: Handle Data Collection via WebView

	const webViewUrl = `${options.collectData.url}?prefill=${prefillBase64}`;
	const webViewUrl = `${options.collectData.url}&prefill=${prefillBase64}`;

	description: "This endpoint confirms a payment and submits it to the blockchain for processing. This is the COMMITMENT point - after this succeeds, the payment is durable."
	description: "This endpoint confirms a payment and submits it to the blockchain for processing."

docs: add WebView-based data collection docs #24

Are you sure you want to change the base?

docs: add WebView-based data collection docs #24

Uh oh!

Conversation

jakubuid commented Feb 9, 2026 • edited by devin-ai-integration bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Files Changed

What changed in each doc

Platform-Specific Bridge Names

Updates since last revision

Review & Testing Checklist for Human

Test Plan

Notes

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

jakubuid commented Feb 9, 2026 •

edited by devin-ai-integration bot

Loading