docs(kyt): document KYT-screened payments as a use case + payee-destination field#94
docs(kyt): document KYT-screened payments as a use case + payee-destination field#94rodrigopavezi wants to merge 1 commit intodocs/revamp-redirect-urlfrom
Conversation
…nation field 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.
Greptile SummaryThis PR documents the KYT (Know Your Transaction) compliance feature for payee destinations, adding a new use-case guide, updating the payee-destinations API reference with the
Confidence Score: 3/5The new KYT guide is clear and accurate, but the API reference for PUT /v1/payee-destination omits The use-case guide explicitly directs merchants to use PUT to update or remove a KYT policy, yet the PUT endpoint in the API reference lists only api-features/payee-destinations.mdx — the PUT endpoint section needs Important Files Changed
Sequence DiagramsequenceDiagram
participant Merchant
participant AuthAPI as Auth API
participant Payer
participant SecurePayApp as Secure Payment App
participant KYTGate as KYT Compliance Gate
Merchant->>AuthAPI: POST /v1/payee-destination (accessPolicy: kyt_all_wallets)
AuthAPI-->>Merchant: destinationId + accessPolicy
Payer->>SecurePayApp: Opens payment link
SecurePayApp->>Payer: Wallet connect prompt
Payer->>SecurePayApp: Connects wallet
SecurePayApp->>KYTGate: Screen wallet address
alt Screening passes
KYTGate-->>SecurePayApp: PASS
SecurePayApp->>Payer: Show payment options (sign step)
Payer->>SecurePayApp: Signs and submits transaction
else Screening fails
KYTGate-->>SecurePayApp: FAIL
SecurePayApp->>Payer: Policy-failure view (sign disabled)
else Screening in progress
KYTGate-->>SecurePayApp: PENDING
SecurePayApp->>Payer: Brief loading state
end
Merchant->>AuthAPI: PUT /v1/payee-destination (accessPolicy: mode off)
AuthAPI-->>Merchant: Updated destination (screening removed)
|
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
| <ParamField body="accessPolicy" type="object"> | ||
| Optional KYT (Know Your Transaction) compliance policy applied to payments into this destination. When set, every payer wallet that connects to a payment link backed by this destination is screened before the payment can proceed. See [Compliance-gated payments](/use-cases/compliance-gated-payments) for the full guide. | ||
|
|
||
| | Sub-field | Type | Description | | ||
| | --- | --- | --- | | ||
| | `mode` | `"off"` \| `"kyt_all_wallets"` | `off` (default): no screening. `kyt_all_wallets`: every payer wallet is screened. | | ||
| | `hideUntilApproved` | `boolean` | When `true`, payment metadata is hidden in the payer UI until the wallet passes screening. | | ||
| | `hidePayeeAddress` | `boolean` | When `true`, the payee address is masked in the payer UI (no copy / no explorer link). | | ||
| </ParamField> |
There was a problem hiding this comment.
accessPolicy sub-fields are documented as a plain Markdown table inside the ParamField body. Per the AGENTS.md style guide, nested object properties should use the Expandable component with nested ParamField entries for consistent, scannable API docs.
| <ParamField body="accessPolicy" type="object"> | |
| Optional KYT (Know Your Transaction) compliance policy applied to payments into this destination. When set, every payer wallet that connects to a payment link backed by this destination is screened before the payment can proceed. See [Compliance-gated payments](/use-cases/compliance-gated-payments) for the full guide. | |
| | Sub-field | Type | Description | | |
| | --- | --- | --- | | |
| | `mode` | `"off"` \| `"kyt_all_wallets"` | `off` (default): no screening. `kyt_all_wallets`: every payer wallet is screened. | | |
| | `hideUntilApproved` | `boolean` | When `true`, payment metadata is hidden in the payer UI until the wallet passes screening. | | |
| | `hidePayeeAddress` | `boolean` | When `true`, the payee address is masked in the payer UI (no copy / no explorer link). | | |
| </ParamField> | |
| <ParamField body="accessPolicy" type="object"> | |
| Optional KYT (Know Your Transaction) compliance policy applied to payments into this destination. When set, every payer wallet that connects to a payment link backed by this destination is screened before the payment can proceed. See [Compliance-gated payments](/use-cases/compliance-gated-payments) for the full guide. | |
| <Expandable title="accessPolicy fields"> | |
| <ParamField body="mode" type='"off" | "kyt_all_wallets"'> | |
| `off` (default): no screening. `kyt_all_wallets`: every payer wallet is screened. | |
| </ParamField> | |
| <ParamField body="hideUntilApproved" type="boolean"> | |
| When `true`, payment metadata is hidden in the payer UI until the wallet passes screening. | |
| </ParamField> | |
| <ParamField body="hidePayeeAddress" type="boolean"> | |
| When `true`, the payee address is masked in the payer UI (no copy / no explorer link). | |
| </ParamField> | |
| </Expandable> | |
| </ParamField> |
Context Used: AGENTS.md (source)
Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!
| 1. Payer opens your payment link. | ||
| 2. Before the payment options view loads, Request Network's compliance gate screens the connected wallet (and, for smart-account payments, the parent EOA as well). | ||
| 3. If the screening **passes**, the payment continues normally. | ||
| 4. If the screening **fails**, the secure payment page shows a policy-failure view and the payer cannot reach the sign step. |
There was a problem hiding this comment.
<Steps> Mintlify component for "procedures and sequential instructions" to get consistent styling and scannability.
| 1. Payer opens your payment link. | |
| 2. Before the payment options view loads, Request Network's compliance gate screens the connected wallet (and, for smart-account payments, the parent EOA as well). | |
| 3. If the screening **passes**, the payment continues normally. | |
| 4. If the screening **fails**, the secure payment page shows a policy-failure view and the payer cannot reach the sign step. | |
| <Steps> | |
| <Step title="Payer opens your payment link" /> | |
| <Step title="Wallet screening"> | |
| Before the payment options view loads, Request Network's compliance gate screens the connected wallet (and, for smart-account payments, the parent EOA as well). | |
| </Step> | |
| <Step title="Screening passes"> | |
| The payment continues normally. | |
| </Step> | |
| <Step title="Screening fails"> | |
| The secure payment page shows a policy-failure view and the payer cannot reach the sign step. | |
| </Step> | |
| </Steps> |
Context Used: AGENTS.md (source)
Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!
1 participant
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
it as a complete compliance program
Touched:
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.
compliance gate and the policy-failure outcome, with a pointer to
the merchant-side guide.
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.