docs: clean up Payment Detection use case page

[MantisClone]

Problem

Payment Detection use case page had AI warnings, inaccurate claims, and duplicated content across sections.

Proposed Solution

Applied Invoicing page cleanup template with additional refinements:

Content accuracy:

• Removed AI warning
• Updated chain count: "10+ EVM chains" → "9 EVM chains"
• Updated currency count to "150+ currencies" for consistency
• Used "Request ID" terminology (user-facing) - payment reference implementation details reserved for API Features page

Section improvements:

• Overview: Rewritten to lead with problem/solution (crypto payments lack context)
• When to Use: Refocused on problem signals (Payment Collisions, High Volume, Wallet Overhead, Cross-chain) instead of generic benefits
• Common Scenarios: Reduced to 3 focused scenarios (E-commerce, SaaS, Invoices) - removed donations
• How It Works: Simplified to 4 clear steps, technically accurate but high-level

Removed sections:

• Detection Features (belongs in API Features page)
• Detection-Only vs Full Workflows Tabs (confusing framing)
• Implementation code examples (belongs in API Reference)
• Supported Networks section (have dedicated page)

Additions:

• Tooltips for technical terms (transaction hash, blockchain, webhooks, confirmations)
• Info callouts linking to API Features page for technical details
• Link to welcome page payment collision demo

Results:

• Page reduced from ~310 lines to ~149 lines (52% reduction)
• No duplication between sections
• Clear problem → solution → implementation journey
• All claims verified and accurate

Considerations

• Request ID vs Payment Reference terminology strategy documented in planning doc
• API Features page will explain payment reference derivation and technical implementation
• Maintains consistency with Welcome page vocabulary (Request IDs)
• "When to Use" section helps users self-identify problems rather than listing benefits

Closes #29
Part of #18

Summary by CodeRabbit

• Documentation
  • Restructured payment detection documentation with business-context focus including Request IDs and webhooks
  • Simplified workflow steps for improved clarity (Create Request → Customer Pays → Automatic Detection → Get Notified)
  • Enhanced multi-chain monitoring and cross-chain payment guidance
  • Updated API features reference and supported chains information

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Note

Other AI code review bot(s) detected

CodeRabbit has detected other AI code review bot(s) in this pull request and will avoid duplicating their findings in the review comments. This may lead to a less comprehensive review.

Walkthrough

The Payment Detection use-case documentation page is substantially restructured to emphasize business-context workflows, request-based attribution, and multi-chain monitoring. Overview, step sequences, and section organization are rewritten; marketing language is replaced with factual benefits; speculative and AI-generated content is removed; and new sections consolidate cross-use-case references and API features.

Changes

Cohort / File(s)

Change Summary

Payment Detection Page Restructuring use-cases/payment-detection.mdx

Overview reframed around Request IDs and business attribution (instead of generic "automatic detection"); Step sequence renamed from Initiated/Monitored/Detected/Notified to Create Request/Customer Pays/Automatic Detection/Get Notified; Multiple sections removed (Detection Features, API Integration, Detection-Only vs Full Workflows, Implementation Example); Marketing language replaced with factual, benefits-focused copy; New sections added (What's Next?, Key API Features, unified card grid); Cards and scenarios regrouped to emphasize cross-chain payments and operational overheads; AI-generated warning box and speculative content removed; Placeholder links addressed; Next Steps expanded with three-column card layout; Inline information blocks with cross-use-case references added throughout.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

• Careful content review required to verify factual accuracy against actual API capabilities (chain counts, token counts, detection speeds)
• Scope spans significant restructuring across multiple sections, but changes are cohesive within a single file
• Primary review focus: verify claims about supported chains (9 EVM, not "10+"), token counts, and detection performance; ensure marketing language removal; confirm all placeholder links are addressed per issue requirements

Pre-merge checks and finishing touches

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly describes the main change: cleanup of the Payment Detection use case documentation page.
Linked Issues check	✅ Passed	Changes address all key objectives from issue #29: removed AI warning, corrected chain count to 9, replaced marketing language with factual content, verified claims, added tooltips, and applied cleanup template.
Out of Scope Changes check	✅ Passed	All changes are directly aligned with issue #29 requirements. Page restructuring, content removal, and accuracy fixes stay within the documented scope.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch cleanup/payment-detection-page-29

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 557868d and 91939ab.

📒 Files selected for processing (1)

• use-cases/payment-detection.mdx (1 hunks)

🧰 Additional context used

🪛 GitHub Check: Mintlify Validation (requestnetwork-docs-cleanup-invoicing-use-case) - vale-spellcheck

use-cases/payment-detection.mdx

[warning] 9-9: use-cases/payment-detection.mdx#L9
Did you really mean 'crypto'?

---

[warning] 29-29: use-cases/payment-detection.mdx#L29
Did you really mean 'crypto'?

---

[warning] 37-37: use-cases/payment-detection.mdx#L37
Did you really mean 'blockchains'?

---

[warning] 44-44: use-cases/payment-detection.mdx#L44
Did you really mean 'crypto'?

---

[warning] 46-46: use-cases/payment-detection.mdx#L46
Did you really mean 'crypto'?

---

[warning] 49-49: use-cases/payment-detection.mdx#L49
Did you really mean 'crypto'?

---

[warning] 53-53: use-cases/payment-detection.mdx#L53
Did you really mean 'Crypto'?

---

[warning] 54-54: use-cases/payment-detection.mdx#L54
Did you really mean 'crypto'?

---

[warning] 56-56: use-cases/payment-detection.mdx#L56
Did you really mean 'PDFs'?

---

[warning] 56-56: use-cases/payment-detection.mdx#L56
Did you really mean 'crypto'?

🔇 Additional comments (5)

use-cases/payment-detection.mdx (5)

7-19: Overview clearly frames problem and value proposition.

The rewritten section effectively establishes the problem (manual reconciliation challenges), introduces Request IDs as the solution, and lists concrete benefits. The narrative flow and business-context framing align well with the PR cleanup objectives.

One item for verification: Line 19's link points to /use-cases/welcome to demo "Request IDs prevent payment collisions." Confirm this page exists and contains the referenced collision demo—otherwise adjust the link or anchor text.

---

21-60: Strong problem-signal framing and realistic use-case scenarios.

The "When to Use" section reframes cards around customer pain points (Payment Collisions, Volume, Wallet Overhead, Cross-chain) rather than features—this helps readers self-identify fit. The three Common Scenarios are concrete, grounded in real workflows, and avoid feature-list inflation.

One suggestion for consistency: Line 59 and lines 82–84 each contain an <Info> callout linking to /api-features/payment-detection. While both serve a purpose, consider whether a single consolidated link placement would improve scannability.

Verify that the following link targets exist:

• /api-features/payment-detection (lines 59, 83)
• /use-cases/{invoicing, payouts, payroll, checkout, subscriptions} (line 83)

---

62-84: Workflow steps are clear and well-sequenced.

The four-step sequence (Create Request → Customer Pays → Automatic Detection → Get Notified) provides an easy-to-follow overview of the payment detection lifecycle. Step descriptions are concise and focused. The cross-use-case callout on line 83 effectively ties Payment Detection to the broader platform (Invoicing, Payouts, Payroll, Checkout, Subscriptions).

Verify the following links exist and are correct:

• /api-features/payment-detection (line 83)
• /use-cases/{invoicing, payouts, payroll, checkout, subscriptions} (line 83)

---

86-148: API features and next-steps cards are well-organized and action-oriented.

The Key API Features section (lines 86–120) clearly maps detection workflows to their corresponding APIs, and the three-column What's Next layout provides a logical progression from onboarding (Get API Keys) to technical details (Payment Detection Details) to reference (Supported Chains & Currencies). Card text and icon choices are appropriate.

Verify that all href targets exist and are reachable:

• /api-features/payment-detection (lines 91, 135)
• /api-features/webhooks-events (line 99)
• /api-features/query-requests (line 107)
• /api-features/query-payments (line 115)
• /api-setup/getting-started (line 127)
• /resources/supported-chains-and-currencies (line 143)

---

9-9: Vale-spellcheck warnings are false positives in technical content.

The static analysis tool flags "crypto," "blockchains," and "PDFs" as potential misspellings. However, these are standard terminology and acronyms in cryptocurrency/blockchain and fintech documentation:

• "crypto" is a standard abbreviation for "cryptocurrency" used throughout the industry and docs
• "blockchains" is the correct plural of "blockchain"
• "PDFs" is a standard acronym for Portable Document Format

No changes needed. These terms are appropriate and widely recognized in the target audience.

Also applies to: 29-29, 37-37, 44-44, 46-46, 49-49, 53-53, 54-54, 56-56, 74-74

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Copilot]

Pull request overview

This PR refactors the Payment Detection use case page by removing AI-generated content warnings, streamlining structure, and improving clarity. The page is reduced from ~310 lines to ~180 lines (42% reduction) by eliminating duplicated technical content that belongs in API feature documentation.

Key changes:

• Rewrites Overview section to lead with problem/solution format emphasizing Request ID context
• Adds tooltips for technical terms (transaction hash, blockchain, webhooks, confirmations)
• Removes duplicated sections (Detection Features, code examples, network lists) in favor of links to API documentation
• Adds Info callouts explaining that Payment Detection powers all Request Network use cases

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[MantisClone]

@coderabbitai full review

[coderabbitai]

✅ Actions performed

Full review triggered.