docs(kyt): document KYT-screened payments as a use case + payee-destination field

[rodrigopavezi]

Adds end-to-end coverage of the KYT (Know Your Transaction) compliance
feature available today on payee destinations via the Auth API. Frames it
for merchants without naming the third-party screening provider.

New page: use-cases/compliance-gated-payments.mdx

• Explains what KYT is and isn't (transaction screening, not KYC)
• Audience: regulated fintech, marketplaces, B2B platforms
• Configure call (POST /v1/payee-destination with accessPolicy)
• Privacy options: hideUntilApproved + hidePayeeAddress
• Payer-side experience matrix (passes / fails / in-progress)
• Update/remove policy
• Honest "what KYT does not cover" section so merchants don't treat
  it as a complete compliance program

Touched:

• docs.json: added the new page to the Use Cases group
• api-features/payee-destinations.mdx: documented the optional
  accessPolicy ParamField on POST /v1/payee-destination, with the
  three sub-fields (mode, hideUntilApproved, hidePayeeAddress) and a
  link into the new use case page. Response example also includes the
  policy when set.
• tools/secure-payments.mdx: short payer-side note describing the
  compliance gate and the policy-failure outcome, with a pointer to
  the merchant-side guide.
• use-cases/welcome.mdx: KYT-screened payments added to the Use Cases
  card description.

Deliberately not mentioned: the third-party screening service we
integrate with — that's an internal implementation detail that
shouldn't appear in customer-facing docs.

[rodrigopavezi]

• docs(review): apply Tristan's two must-fix items from the final review #97
• docs(review): address Greptile review feedback across the stack #96
• docs(feedback): apply Tristan's revisions from RequestNetwork/request-api#806 #95
• docs(kyt): document KYT-screened payments as a use case + payee-destination field #94 👈 (View in Graphite)
• docs(secure-payments): document redirectUrl + redirectLabel #93
• docs(verify): fix broken cross-refs surfaced by mintlify broken-links #92
• docs(scripts): add Playwright screenshot capture scaffolding #91
• docs(content): add use-case pages, Dashboard + Secure Payment tools pages #90
• docs(content): refresh Tron coverage, batch-payment EVM scope, webhook 12-event list #89
• docs(nav): restructure navigation, remove legacy pages, retire Portal #88
• docs: fix broken links and clarify edge cases #87
• docs: add missing feature documentation for recent API changes #86
• docs: fix implementation discrepancies across API docs #85
• docs: remove beta banner and legacy SDK tab #78
• Remove AI-generated content warnings and update internal links #77
• docs(lifecycle): replace external image with local asset and remove AI-generated warning #76
• docs: remove AI-generated content warnings and simplify Request Scan page #75
• docs(resources): remove community page from navigation #74
• docs(supported-chains): add Tron network support and enhance currency documentation #73
• docs(supported-chains): streamline supported chains and currencies documentation #72
• docs(api-reference): add v2 endpoints overview and switch docs OpenAPI to v2-only spec Improve API Reference navigation by introducing a dedicated Endpoints Overview page in docs and wiring Mintlify OpenAPI rendering to a local v2-only spec. - add `api-re #71
• docs(authentication): simplify auth guide with API key vs Client ID methods and remove AI-generated content #70
• docs(fee-breakdowns): rewrite to focus on API response locations and reconciliation usage #69
• docs(protocol-fees): add protocol fees documentation and navigation #68
• docs(platform-fees): simplify configuration guide and remove AI-generated content warning #67
• docs(query-payments): rewrite with practical implementation focus and remove AI warning #66
• docs(query-requests): simplify and refactor query requests documentation for practical implementation #65
• docs(payment-detection): simplify content and remove AI warning #64
• docs(partial-payments): rewrite with step-by-step implementation guide and clarify API usage #63
• docs(standard-payments): remove AI warning, restructure content with step-by-step flow, and update API references #62
• docs(conversion-payments): rewrite with step-by-step implementation guide and remove AI-generated warning #61
• docs(payment-types): simplify overview and add payment type selection guidance #60
• docs(crypto-to-fiat): expand comprehensive guide with sandbox access, compliance flows, and implementation details #59
• docs(recurring-payments): rewrite with comprehensive workflow, security details, and practical implementation guide #58
• docs(batch-payments): add comprehensive implementation guide with examples, workflow diagrams, and demo videos #57
• docs(crosschain-payments): replace AI-generated content with comprehensive implementation guide #56
• docs(create-requests): rewrite with workflows, examples, and remove AI warning #55
• feat: add complete integration tutorial with Node.js backend and React frontend #54
• docs(getting-started): remove AI warning and refactor to focus on practical payment integration #53
• docs(api-portal): remove AI warning, add local screenshot, and update .gitignore #52
• docs: remove release notes section and streamline use cases to core features #51
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[greptile-apps]

Greptile Summary

This PR adds end-to-end documentation for the KYT (Know Your Transaction) compliance feature: a new use-case guide, accessPolicy coverage on the POST payee-destination endpoint, a payer-side note in the secure-payments tool page, and nav wiring.

• New page (use-cases/compliance-gated-payments.mdx): covers what KYT is, how to configure a gated destination, privacy options, the payer experience matrix, and the "what KYT doesn't cover" disclaimer.
• API reference update (api-features/payee-destinations.mdx): adds accessPolicy as an optional body parameter with sub-field descriptions and an updated response example; the PUT endpoint remains missing the accessPolicy parameter (noted in a previous review).
• Nav + cross-links: docs.json, use-cases/welcome.mdx, and tools/secure-payments.mdx all updated with appropriate pointers.

Confidence Score: 4/5

The documentation is largely accurate and well-structured, but two unresolved gaps need to be reconciled before merchants in regulated environments act on this page.

The new compliance guide's 'How it works' section and 'What payers experience' table give merchants contradictory information about which wallet is the connected one versus the additionally screened one for smart-account payments. The PUT endpoint gap — no accessPolicy parameter documented — is also still open.

use-cases/compliance-gated-payments.mdx (smart-account screening terminology at lines 19 and 73) and api-features/payee-destinations.mdx (PUT endpoint missing accessPolicy documentation)

Important Files Changed

Filename	Overview
use-cases/compliance-gated-payments.mdx	New use-case guide for KYT-gated payments; smart-account screening terminology is inconsistent between the 'How it works' step 2 and the 'What payers experience' table note (lines 19 vs 73)
api-features/payee-destinations.mdx	Adds accessPolicy to POST /v1/payee-destination; PUT endpoint still does not document accessPolicy, leaving merchants without a reference for how to update or remove a policy via PUT
tools/secure-payments.mdx	Adds a short payer-side note on compliance-gated payments with a pointer to the merchant guide; change is accurate and self-contained
docs.json	Adds the new compliance-gated-payments page to the Use Cases nav group; no issues
use-cases/welcome.mdx	Appends KYT-screened payments to the Use Cases card description; clean one-line change

Sequence Diagram

sequenceDiagram
participant M as Merchant
participant API as Auth API
participant P as Payer
participant Gate as KYT Compliance Gate
M->>API: POST /v1/payee-destination (accessPolicy: kyt_all_wallets)
API-->>M: destinationId + accessPolicy
P->>Gate: Open payment link (wallet connects)
Gate->>Gate: Screen wallet address
alt Passes screening
Gate-->>P: Show payment options
P->>Gate: Sign and submit payment
else Fails screening
Gate-->>P: Policy-failure view (sign disabled)
else In progress
Gate-->>P: Loading state
end
M->>API: PUT /v1/payee-destination (accessPolicy mode off)
API-->>M: Updated destination (policy removed)

Loading

_{Reviews (2): Last reviewed commit: "docs(kyt): document KYT-screened payment..." | Re-trigger Greptile}

[rodrigopavezi]

Merge activity

• May 12, 4:02 PM UTC: A user started a stack merge that includes this pull request via Graphite.
• May 12, 5:18 PM UTC: Graphite rebased this pull request as part of a merge.
• May 12, 5:18 PM UTC: @rodrigopavezi merged this pull request with Graphite.

[greptile-apps]

Smart-account screening terminology contradicts the later description

Line 19 says the gate screens "the connected wallet (and, for smart-account payments, the parent EOA as well)" — framing the smart account as the connected wallet and the EOA as an additional screen. Line 73, however, says "the gate screens both the connected EOA and the smart-account wallet." These two framings are directly inconsistent about which wallet the payer "connects" with. Merchants building compliance workflows for EVM smart-account payments need an unambiguous answer: which addresses are checked, and which one is the one the user authenticates with?