Telegram Stars

Telegram Stars (XTR) — встроенная валюта Telegram для цифровых товаров и донатов. В отличие от обычных платежей через провайдеров, Stars не требуют настройки provider_token, работают во всех странах и берут на себя KYC/AML. Комиссия Telegram — 30% (как в App Store/Google Play), остальное попадает к разработчику. Вывод средств доступен через Fragment (в Toncoin) или на рекламу в Telegram Ads.

Отправка инвойса в Stars

Метод sendInvoice с валютой XTR. Параметр provider_token опускается — Stars — нативный метод. Цены указываются в минимальных единицах (1 Star = 1 XTR, дробные части не поддерживаются).

Хелпер telegramApi() описан в главе Первый запрос: getMe.

<?php
function sendStarsInvoice(int $chatId, string $title, string $description, string $payload, int $amount, array $prices): array {
    return telegramApi('sendInvoice', [
        'chat_id' => $chatId,
        'title' => $title,
        'description' => $description,
        'payload' => $payload,           // ваш внутренний ID заказа
        'currency' => 'XTR',             // Telegram Stars
        'prices' => $prices,             // [['label' => 'Подписка на месяц', 'amount' => $amount]]
        'start_parameter' => 'stars_' . $payload,
        'provider_data' => json_encode([]), // пустой объект, обязателен для XTR
    ]);
}

// Пример вызова
$prices = [['label' => 'Premium на 30 дней', 'amount' => 150]]; // 150 Stars
sendStarsInvoice($chatId, 'Premium доступ', 'Без рекламы и лимитов', 'premium_30d', 150, $prices);
?>

Обработка pre_checkout_query

Telegram шлёт pre_checkout_query за 10 секунд до списания. Бот должен проверить наличие товара и ответить answerPreCheckoutQuery с ok: true. Если товара нет — ok: false с error_message.

<?php
function handlePreCheckout(array $update): void {
    $query = $update['pre_checkout_query'];
    $payload = $query['invoice_payload']; // ваш payload из sendInvoice
    
    // Проверка: товар доступен, пользователь не купил уже и т.д.
    $available = checkProductAvailable($payload, $query['from']['id']);
    
    telegramApi('answerPreCheckoutQuery', [
        'pre_checkout_query_id' => $query['id'],
        'ok' => $available,
        'error_message' => $available ? null : 'Товар временно недоступен, попробуйте позже',
    ]);
}

function checkProductAvailable(string $payload, int $userId): bool {
    // Ваша логика: проверка БД, лимитов, подписок
    return true;
}
?>

Обработка successful_payment

После успешного списания приходит обновление с объектом successful_payment. Поле currency будет XTR, total_amount — в Stars. Это момент выдачи товара.

<?php
function handleSuccessfulPayment(array $update): void {
    $payment = $update['message']['successful_payment'];
    $payload = $payment['invoice_payload'];
    $userId = $update['message']['from']['id'];
    $stars = $payment['total_amount']; // уже в Stars, не в копейках
    
    // Выдача товара
    grantProduct($userId, $payload, $stars);
    
    // Подтверждение пользователю
    telegramApi('sendMessage', [
        'chat_id' => $update['message']['chat']['id'],
        'text' => "✅ Оплата прошла успешно! Списано {$stars} ⭐. Товар выдан.",
        'reply_to_message_id' => $update['message']['message_id'],
    ]);
}

function grantProduct(int $userId, string $payload, int $stars): void {
    // Ваша логика: активация подписки, выдача ключа, начисление баланса
}
?>

Возврат Stars

Метод refundStarPayment возвращает Stars пользователю. Работает только для платежей в Stars, не требует провайдера. Telegram удерживает свою комиссию (30%) при возврате — разработчик получает назад 70%.

<?php
function refundStars(int $userId, string $telegramPaymentChargeId): array {
    return telegramApi('refundStarPayment', [
        'user_id' => $userId,
        'telegram_payment_charge_id' => $telegramPaymentChargeId,
    ]);
}

// telegram_payment_charge_id берётся из successful_payment.telegram_payment_charge_id
// Сохраняйте его в БД при обработке successful_payment
?>

История транзакций Stars

Метод getStarTransactions возвращает список входящих/исходящих операций бота. Полезно для отчётов и сверки.

<?php
function getStarTransactions(int $offset = 0, int $limit = 100): array {
    return telegramApi('getStarTransactions', [
        'offset' => $offset,
        'limit' => $limit,
    ]);
}

// Ответ содержит массив StarTransaction с полями:
// id, amount, date, type (incoming/outgoing/refund), user, invoice_payload, telegram_payment_charge_id
?>

Вывод Stars

Прямого API для вывода на банковскую карту нет. Два пути:

1. Fragment — обмен Stars на Toncoin (через @Fragment bot или API Fragment), затем вывод на кошелёк.
2. Telegram Ads — тратить Stars на рекламу бота/канала прямо в Telegram Ads.

Для автоматизации обмена на Toncoin используйте неофициальные библиотеки Fragment API или ручной вывод через бота @Fragment.

Ограничения и нюансы

• Минимальная сумма инвойса — 1 Star.
• Максимальная сумма одного инвойса — 10 000 Stars.
• Stars не работают для физических товаров (требуется need_shipping_address и провайдер). Только цифровые товары, донаты, подписки.
• provider_data обязателен, но должен быть пустым JSON-объектом {}.
• В successful_payment нет provider_payment_charge_id — только telegram_payment_charge_id.

Дальше: Inline mode