nick-doc/09 - Audits/Task 5.5 Telegram Payment and Wallet Strategy.md

title, tags, created, status

title	tags	created	status
Task 5.5 Telegram Payment and Wallet Strategy	taskmaster telegram payment wallet provider-adapter	2026-05-24	draft

Task 5.5 Telegram Payment and Wallet Strategy

Source: /.taskmaster/docs/prd-telegram-native-app-bot-wallet.md

1) Strategy principle for this track

For first release, Telegram-native payment initiation must feed the existing canonical payment system and must not bypass ledger-led state transitions. This means:

• payment proof and funds movement remain authorized by Funds Ledger and Escrow State Machine Specification,
• release/refund actions remain governed by service-layer guards and dispute holds,
• Telegram provider adapters are optional extensions, not a hard dependency.

In practice: Telegram can open payment flows through one canonical path first, and optional providers are layered later.

2) Option comparison

Option	Fit for Telegram UX	Funds correctness risk	Regulatory / abuse risk	Complexity	Decision
Bot API Payments / Telegram Stars	Moderate	High (revenue and settlement mapping differs from existing ledger assumptions)	Medium	Medium	Deferred
Wallet Pay	Moderate	Medium-High (token-specific proof path)	High	High	Deferred
TON Pay	Medium	Medium-High (provider proof consistency + chain mapping)	High	High	Deferred
TON Connect + direct wallet pay	Medium	Medium if proven; requires strict recipient+amount+memo checks	High	High	Deferred
Request Network links	High (already introduced)	Low-Medium (existing adapter/service contract)	Medium	Low	Primary for phase 1
Existing Web3/crypto checkout path	High	Medium (requires recipient/amount/network proof hardening)	High	Medium	Keep as fallback only

3) Selected phase-1 path

Primary phase-1 strategy

• Telegram bot/Mini App starts the payment by invoking the same canonical payment intent creation API used for web flows.
• Payment provider is written as metadata; provider-neutral adapter remains optional and feature-flagged.
• Telegram identity metadata is persisted with the intent:
  • provider (e.g., request_network or shkeeper)
  • telegramUserId
  • telegramChatId (if available)
  • launchSource (bot, mini_app, web_fallback)
  • paymentReference
  • invoiceId / orderId / requestId
  • currency, amount, expiresAt
  • idempotency key (request-scoped)

Optional providers

• Wallet Pay / TON Pay / TON Connect paths are documented as optional and must be implemented behind explicit feature flags and dedicated adapter configuration only when:
  • replay-safe proofs are standardized,
  • canonical refund/release reconciliation supports provider-native evidence,
  • monitoring/reporting has parity with existing paths.
• Until that date, these options are not required to merge for Task 5.1-5.9 handoff.

4) Data integrity requirements for any Telegram payment/Wallet path

Before any pay-in is accepted into escrow, enforce:

1. recipient validation (exact canonical recipient for the active escrow policy),
2. asset validation (supported chain + token),
3. amount validation against payment intent and currency precision,
4. memo/reference validation (idempotent and tamper-evident),
5. confirmation proof validation (confirmed, on-chain, or provider webhook),
6. canonical reconciliation step before mark-complete,
7. invariant re-check with ledger balances before release/refund operations.

These map directly to:

• Webhook Security Spec
• Payment Provider Adapter Spec (if optional provider is enabled)
• Funds Ledger and Escrow State Machine Specification (all financial state transitions).

5) Anti-divergence record model

Every Telegram payment intent should write a small canonical trace record with:

• canonical paymentId
• canonicalSourceChannel = telegram
• telegramContext payload hash
• provider and providerReference
• idempotencyKey
• createdFrom deep-link/command/callback identifier
• reconciliation status (created, started, confirmed, failed, reconciled)

This avoids duplicate checkout creation and makes Telegram callback replay and callback mismatch explainable in operations.

6) Refund/release compatibility

Refund/release logic remains unchanged from the canonical engine:

• cannot release funds not in releasable state,
• no release/release-amount mutation from Telegram without canonical precondition checks,
• disputed states block direct payout operations,
• release/refund events are only reflected after ledger updates succeed.

7) Open follow-up decisions

1. Decide whether to onboard Wallet Pay as phase-2 provider once adapter-level proof validation and reconciliation parity are met.
2. Decide whether to expose optional "wallet direct top-up" button in Mini App from day one or keep explicit link-first flow.
3. Finalize provider timeout and retry policy for Telegram-triggered intents under slow-network conditions.