---
title: Task 5.5 Telegram Payment and Wallet Strategy
tags: [taskmaster, telegram, payment, wallet, provider-adapter]
created: 2026-05-24
status: 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`](Funds%20Ledger%20and%20Escrow%20State%20Machine%20Specification.md),
- 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`](Webhook%20Security%20Spec.md)
- [`Payment Provider Adapter Spec`](Payment%20Provider%20Adapter%20Spec.md) (if optional provider is enabled)
- [`Funds Ledger and Escrow State Machine Specification`](Funds%20Ledger%20and%20Escrow%20State%20Machine%20Specification.md) (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.