Выбираем продукт и условия доступа
Для цифровых товаров и услуг внутри Telegram используется валюта XTR — Telegram Stars. В этой статье разовая покупка без автопродления. Не переносите пример как готовую реализацию ежемесячной подписки: у неё другой жизненный цикл продления и окончания доступа.
Продукт в примере один: course-php. После оплаты бот разрешает читать короткий урок из приватного текстового файла. Это позволяет проверить весь путь без внешней системы обучения. В рабочем практикуме тот же hasCourseAccess можно вызывать перед выдачей каждого материала либо перед открытием страницы после подтверждённого входа пользователя.
Перед покупкой укажите, что именно получит человек, на какой срок и как обратиться за помощью или возвратом. Для примера доступ действует до возврата. Команда /paysupport должна вести к реальному каналу поддержки; её обработчик будет ниже. Уже полученный текст невозможно стереть у пользователя — возврат закрывает дальнейшую выдачу материалов.
Подготавливаем тестовую среду и файлы
Используем PHP 8.3+ с curl, pdo_sqlite и mbstring, одного бота и одну приватную SQLite-БД. Создайте отдельного бота в выделенной тестовой среде Telegram: она отличается от обычного аккаунта и обычного «тестового бота» в production. В ней можно пройти покупку Stars без рабочей оплаты. Инструкцию входа для своего клиента возьмите из документации Telegram.
Выделенная тестовая среда Telegram
stars-demo/ common.php stars.php schema.sql init.php setup-webhook.php refund.php private/course.txt public/webhook.php
Сайт должен отдавать только public. В private/course.txt сохраните UTF-8-текст тестового урока длиной до 3000 единиц UTF-16. Например: «Урок 1. Значения SQL передавайте через параметры PDO::prepare, а не вставляйте в строку запроса». Это демонстрационный материал: замените его содержимым своего продукта. Файл не должен скачиваться напрямую через веб-сервер.
export BOT_TOKEN='ТОКЕН_БОТА_ИЗ_TEST_СРЕДЫ' export TELEGRAM_TEST_ENV=1 export WEBHOOK_SECRET='СЛУЧАЙНЫЙ_СЕКРЕТ_ИЗ_ЛАТИНИЦЫ_ЦИФР_И_ПОДЧЕРКИВАНИЙ' export BOT_DB_PATH='/srv/stars-demo/private/stars.sqlite' export COURSE_TEXT_PATH='/srv/stars-demo/private/course.txt' export PAY_SUPPORT_CONTACT='@your_real_support' export WEBHOOK_URL='https://stars.example.com/webhook.php'
Пути, контакт и HTTPS-адрес замените своими. PHP-FPM и CLI должны получать одинаковое окружение. В отдельном FPM-пуле переменные задаются через env[ИМЯ]; файл .env сам по себе обычный PHP не читает. На рабочем запуске используйте production-токен, TELEGRAM_TEST_ENV=0 и отдельную рабочую БД, сохранив тестовые данные в тестовом окружении.
common.php переключает только фиксированный префикс прямого Bot API: /test/ для тестовой среды и / для рабочей. Токен не отправляется в браузер. Входящий webhook проверяется по отдельному secret_token. Для одного бота и одной БД достаточно charge_id; при объединении нескольких ботов добавьте bot_id в ключи платежей и заказов.
<?php
declare(strict_types=1);
function database(): PDO
{
$path = getenv('BOT_DB_PATH');
if (!$path || !is_file($path)) throw new RuntimeException('Создайте БД и задайте BOT_DB_PATH');
$db = new PDO('sqlite:'.$path, null, null, [PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION]);
$db->exec('PRAGMA foreign_keys = ON');
$db->exec('PRAGMA busy_timeout = 1000');
return $db;
}
/** @template T
* @param callable(): T $work
* @return T
*/
function atomic(PDO $db, callable $work): mixed
{
$db->exec('BEGIN IMMEDIATE');
try {
$result = $work();
$db->exec('COMMIT');
return $result;
} catch (Throwable $error) {
$db->exec('ROLLBACK');
throw $error;
}
}
/** @return array<string, int|string|null>|false */
function row(PDOStatement $query): array|false
{
$value = $query->fetch(PDO::FETCH_ASSOC);
if ($value === false) return false;
if (!is_array($value)) throw new RuntimeException('Некорректная строка БД');
foreach ($value as $key => $field) {
if (!is_string($key) || !(is_int($field) || is_string($field) || $field === null)) {
throw new RuntimeException('Некорректное поле БД');
}
}
return $value;
}
/** @param array<string, mixed> $params
* @return array{state: string, result?: mixed, code?: int, retry_after?: int}
*/
function telegram(string $method, array $params, int $timeout = 8): array
{
$token = getenv('BOT_TOKEN');
if (!$token) throw new RuntimeException('Задайте BOT_TOKEN');
$prefix = getenv('TELEGRAM_TEST_ENV') === '1' ? '/test/' : '/';
$curl = curl_init('https://api.telegram.org/bot'.$token.$prefix.$method);
curl_setopt_array($curl, [CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true,
CURLOPT_CONNECTTIMEOUT => 2, CURLOPT_TIMEOUT => $timeout,
CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode($params, JSON_THROW_ON_ERROR)]);
$raw = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
unset($curl);
$body = is_string($raw) ? json_decode($raw, true) : null;
if ($status >= 200 && $status < 300 && is_array($body) && ($body['ok'] ?? null) === true) {
return ['state' => 'ok', 'result' => $body['result'] ?? null];
}
if ($status < 500 && is_array($body) && ($body['ok'] ?? null) === false
&& is_int($body['error_code'] ?? null)) {
$parameters = $body['parameters'] ?? [];
$wait = is_array($parameters) ? ($parameters['retry_after'] ?? 60) : 60;
return ['state' => 'rejected', 'code' => $body['error_code'],
'retry_after' => is_int($wait) ? max(1, $wait) : 60];
}
return ['state' => 'unknown'];
}
/** @return array<array-key, mixed> */
function incomingUpdate(): array
{
$secret = getenv('WEBHOOK_SECRET');
$provided = $_SERVER['HTTP_X_TELEGRAM_BOT_API_SECRET_TOKEN'] ?? '';
if ($_SERVER['REQUEST_METHOD'] !== 'POST' || !$secret
|| !is_string($provided) || !hash_equals($secret, $provided)) {
http_response_code(403);
exit;
}
$raw = file_get_contents('php://input', false, null, 0, 1024 * 1024 + 1);
if (!is_string($raw) || strlen($raw) > 1024 * 1024) {
http_response_code(413);
exit;
}
$update = json_decode($raw, true, 64, JSON_THROW_ON_ERROR);
if (!is_array($update) || !is_int($update['update_id'] ?? null)) {
throw new InvalidArgumentException('Некорректное событие');
}
return $update;
}
Разделяем заказ, платёж и право доступа
Счёт связан с локальным заказом через случайный payload. Платёж хранится по telegram_payment_charge_id, а право доступа ссылается на этот платёж. Так можно отдельно ответить на вопросы «пользователь собирался купить», «деньги подтверждены» и «материал разрешено выдавать».
CREATE TABLE star_orders ( payload TEXT PRIMARY KEY, user_id INTEGER NOT NULL, sku TEXT NOT NULL, stars INTEGER NOT NULL CHECK (stars > 0), expires_at INTEGER NOT NULL, state TEXT NOT NULL DEFAULT 'pending', charge_id TEXT UNIQUE ); CREATE INDEX star_orders_owner ON star_orders(user_id, sku, state); CREATE TABLE star_payments ( charge_id TEXT PRIMARY KEY, payload TEXT NOT NULL, user_id INTEGER NOT NULL, currency TEXT NOT NULL, amount INTEGER NOT NULL, state TEXT NOT NULL, reason TEXT, received_at INTEGER NOT NULL ); CREATE TABLE star_access ( charge_id TEXT PRIMARY KEY REFERENCES star_payments(charge_id), user_id INTEGER NOT NULL, sku TEXT NOT NULL, active INTEGER NOT NULL DEFAULT 1 ); CREATE INDEX star_access_owner ON star_access(user_id, sku, active); CREATE TABLE star_refunds ( charge_id TEXT PRIMARY KEY REFERENCES star_payments(charge_id), state TEXT NOT NULL DEFAULT 'sending', requested_at INTEGER NOT NULL );
star_payments сохраняет и платежи, требующие сверки: например, пришла другая сумма или неизвестный payload. Такой факт нельзя терять только потому, что доступ выдавать пока нельзя. Оператор разбирает state = review и reason. Срок хранения платёжного журнала и доступ сотрудников задайте в правилах своего сервиса.
<?php
declare(strict_types=1);
if (PHP_SAPI !== 'cli') exit(1);
$path = getenv('BOT_DB_PATH');
if (!$path || file_exists($path)) throw new RuntimeException('Нужен путь к новой БД');
$db = new PDO('sqlite:'.$path, null, null, [PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION]);
$db->exec('PRAGMA foreign_keys = ON');
$db->exec(file_get_contents(__DIR__.'/schema.sql'));
echo "База создана\n";
php init.php
SQLite удобна для небольшого примера: BEGIN IMMEDIATE получает право записи до чтения состояния. Все финансовые изменения ниже короткие, без внешних запросов внутри транзакции. Для нескольких серверов используйте общую БД с аналогичной атомарностью и уникальными ключами. Не копируйте синтаксис SQLite в другую СУБД без адаптации.
Создаём заказ и формируем счёт в Stars
Начните stars.php следующим блоком. Все следующие фрагменты этого файла дописывайте в его конец, без нового открывающего тега PHP. Цена 100 задаётся в коде каталога на сервере и сохраняется в заказе. Для XTR сумма здесь равна 100 Stars; умножать её на 100 как рубли на копейки не нужно. prices содержит одну позицию, provider_token пустой. В payload передаётся только случайный ID заказа.
<?php
declare(strict_types=1);
require_once __DIR__.'/common.php';
function courseText(): string
{
$path = getenv('COURSE_TEXT_PATH');
if (!$path || !is_readable($path)) throw new RuntimeException('Материал недоступен');
$text = file_get_contents($path, false, null, 0, 12001);
if (!is_string($text) || trim($text) === '' || strlen($text) > 12000 || !mb_check_encoding($text, 'UTF-8')
|| strlen(mb_convert_encoding($text, 'UTF-16LE', 'UTF-8')) / 2 > 3000) {
throw new RuntimeException('Проверьте UTF-8 и длину материала');
}
return $text;
}
function hasCourseAccess(PDO $db, int $userId, string $sku = 'course-php'): bool
{
$q = $db->prepare('SELECT 1 FROM star_access WHERE user_id = ? AND sku = ? AND active = 1 LIMIT 1');
$q->execute([$userId, $sku]);
return $q->fetchColumn() !== false;
}
/** @return array<string, mixed> */
function invoiceFor(PDO $db, int $userId): array
{
if ($userId <= 0) throw new InvalidArgumentException('Нужен пользователь');
return atomic($db, function () use ($db, $userId): array {
if (hasCourseAccess($db, $userId)) throw new DomainException('Доступ уже открыт');
$q = $db->prepare("SELECT * FROM star_orders WHERE user_id = ? AND sku = 'course-php'
AND state = 'pending' AND expires_at > ? ORDER BY expires_at DESC LIMIT 1");
$q->execute([$userId, time()]);
$order = row($q);
if (!$order) {
$order = ['payload' => bin2hex(random_bytes(16)), 'stars' => 100];
$db->prepare('INSERT INTO star_orders (payload, user_id, sku, stars, expires_at)
VALUES (?, ?, ?, ?, ?)')->execute([$order['payload'], $userId, 'course-php', 100, time() + 1200]);
}
return ['chat_id' => $userId, 'title' => 'Доступ к PHP-практикуму',
'description' => 'Однократная оплата без автопродления. После оплаты отправьте /access для получения урока.',
'payload' => $order['payload'], 'provider_token' => '', 'currency' => 'XTR',
'prices' => [['label' => 'Практикум', 'amount' => (int) $order['stars']]],
'start_parameter' => 'course_php'];
});
}
Повтор /buy в течение 20 минут использует прежний неоплаченный заказ. Если доступ уже есть, новый счёт не создаётся. Пересланная карточка не должна давать доступ постороннему: помимо start_parameter, на предварительной проверке мы сравним плательщика с владельцем заказа.
Тело результата invoiceFor передаётся в sendInvoice. Только ответ ok=true подтверждает создание сообщения со счётом. Даже этот ответ ещё ничего не говорит об оплате. Если отправка неизвестна, пользователь может запросить /buy снова; карточек может оказаться несколько, поэтому доступ всё равно защищён платёжным журналом и проверкой состояния заказа.
Быстро отвечаем на предварительную проверку
После подтверждения счёта пользователем приходит pre_checkout_query. Ответ answerPreCheckoutQuery должен успеть в десятисекундное окно Telegram. Не ставьте его за обычной рассылкой или долгой задачей CRM: здесь нужны короткая проверка локального заказа и быстрый HTTP-ответ API.
/** @param array<string, mixed> $query */
function preCheckout(PDO $db, array $query): bool
{
$from = $query['from'] ?? null;
$userId = is_array($from) ? ($from['id'] ?? null) : null;
$payload = $query['invoice_payload'] ?? null;
if (!is_int($userId) || !is_string($payload) || ($query['currency'] ?? null) !== 'XTR'
|| !is_int($query['total_amount'] ?? null)) return false;
$q = $db->prepare("SELECT * FROM star_orders WHERE payload = ? AND user_id = ? AND state = 'pending'");
$q->execute([$payload, $userId]);
$order = row($q);
if ($order && !is_string($order['sku'])) throw new RuntimeException('Некорректный товар в БД');
return $order && (int) $order['expires_at'] > time()
&& (int) $order['stars'] === $query['total_amount'] && !hasCourseAccess($db, $userId, $order['sku']);
}
Проверяем владельца, валюту, сумму, состояние и срок счёта. Общий webhook дополнительно проверит наличие материала перед согласием. Если материал временно недоступен или счёт устарел, возвращаем ok=false с понятной причиной. При ok=true право доступа пока не записывается.
Срок счёта ограничивает разрешение новой попытки оплаты. Если успешный платёж уже произошёл и его событие задержалось, истёкший expires_at не является основанием забыть деньги: обработчик successful_payment ниже проверяет оплаченный заказ и сохраняет факт платежа.
Открываем доступ только по успешному платежу
Допишите в stars.php функцию recordPayment. Её вызывают только для платёжного служебного сообщения из проверенного webhook. В примере покупка идёт в личном чате: владельца определяет message.chat.id. Для уведомления о возврате не полагайтесь на from.id — обработка опирается на сохранённый заказ, чат и идентификатор платежа.
/** @param array<string, mixed> $payment */
function recordPayment(PDO $db, int $userId, array $payment, bool $refund = false): string
{
$charge = $payment['telegram_payment_charge_id'] ?? null;
$payload = $payment['invoice_payload'] ?? null;
$currency = $payment['currency'] ?? null;
$amount = $payment['total_amount'] ?? null;
if (!is_string($charge) || $charge === '' || !is_string($payload) || $payload === ''
|| !is_string($currency) || $currency === '' || !is_int($amount) || $amount <= 0) {
throw new InvalidArgumentException('Некорректный платёж');
}
$payment = ['telegram_payment_charge_id' => $charge, 'invoice_payload' => $payload,
'currency' => $currency, 'total_amount' => $amount];
return atomic($db, function () use ($db, $userId, $payment, $refund): string {
$charge = $payment['telegram_payment_charge_id'];
$payload = $payment['invoice_payload'];
$q = $db->prepare('SELECT * FROM star_payments WHERE charge_id = ?');
$q->execute([$charge]);
$existing = row($q);
if ($existing && !is_string($existing['state'])) throw new RuntimeException('Некорректный статус в БД');
if ($existing && ((int) $existing['user_id'] !== $userId || $existing['payload'] !== $payload
|| $existing['currency'] !== $payment['currency'] || (int) $existing['amount'] !== $payment['total_amount'])) {
throw new RuntimeException('Конфликт идентификатора платежа: нужна сверка');
}
if ($existing && (!$refund || $existing['state'] === 'refunded')) return $existing['state'];
$q = $db->prepare('SELECT * FROM star_orders WHERE payload = ?');
$q->execute([$payload]);
$order = row($q);
if ($order && !is_string($order['sku'])) throw new RuntimeException('Некорректный товар в БД');
$matches = $order && (int) $order['user_id'] === $userId && $payment['currency'] === 'XTR'
&& (int) $order['stars'] === $payment['total_amount'];
$duplicatePurchase = $matches && !$refund &&
(($order['charge_id'] !== null && $order['charge_id'] !== $charge)
|| hasCourseAccess($db, $userId, $order['sku']));
$state = $refund ? 'refunded' : ($matches && !$duplicatePurchase ? 'paid' : 'review');
$reason = !$matches ? 'order_mismatch' : ($duplicatePurchase ? 'extra_payment' : null);
$db->prepare('INSERT INTO star_payments
(charge_id, payload, user_id, currency, amount, state, reason, received_at)
VALUES (?, ?, ?, ?, ?, ?, ?, ?)
ON CONFLICT(charge_id) DO UPDATE SET state = excluded.state, reason = excluded.reason')
->execute([$charge, $payload, $userId, $payment['currency'], $payment['total_amount'], $state, $reason, time()]);
if ($refund) {
$db->prepare('UPDATE star_access SET active = 0 WHERE charge_id = ?')->execute([$charge]);
$db->prepare("UPDATE star_refunds SET state = 'done' WHERE charge_id = ?")->execute([$charge]);
}
if ($matches && $state === 'paid') {
$db->prepare('INSERT INTO star_access (charge_id, user_id, sku) VALUES (?, ?, ?)')
->execute([$charge, $userId, $order['sku']]);
}
if ($matches && in_array($state, ['paid', 'refunded'], true)) {
$db->prepare('UPDATE star_orders SET state = ?, charge_id = ?
WHERE payload = ? AND (charge_id IS NULL OR charge_id = ?)')
->execute([$state, $charge, $payload, $charge]);
}
return $state;
});
}
Новый подходящий successful_payment создаёт строку платежа и право доступа одной транзакцией. Если запись доступа не сохранилась, откатывается и платёж: webhook вернёт ошибку, а повтор можно обработать заново. Повтор с тем же charge_id возвращает уже сохранённое состояние без второй выдачи.
Другой charge_id по тому же заказу или оплата второго счёта при уже открытом доступе сохраняются как review. Это реальный дополнительный платёж, а не дубликат webhook: его нужно сверить и при необходимости вернуть. Уникальный update_id сам по себе такую ситуацию не решает.
Возврат может быть обработан раньше успешной оплаты, например после задержки или повторной доставки событий. Тогда сохранится refunded, а поздний successful_payment не откроет доступ снова. Возврат старой покупки также не выключает новую: отключается право, связанное с конкретным charge_id.
Соединяем команды и платёжные события
Создайте public/webhook.php. Это точка входа прямого webhook Telegram. /buy проверяет доступность урока и отправляет счёт, /access проверяет право перед каждой выдачей текста. Платёжная ветка сохраняет результат в БД без дополнительной отправки: после оплаты пользователь видит квитанцию Telegram и следует подсказке /access из описания счёта.
<?php
declare(strict_types=1);
require dirname(__DIR__).'/stars.php';
try {
$update = incomingUpdate();
$db = database();
if (is_array($update['pre_checkout_query'] ?? null)) {
$q = $update['pre_checkout_query'];
$ok = preCheckout($db, $q);
try { courseText(); } catch (RuntimeException) { $ok = false; }
$answer = ['pre_checkout_query_id' => $q['id'], 'ok' => $ok];
if (!$ok) $answer['error_message'] = 'Счёт недоступен. Откройте /access или запросите новый /buy.';
$result = telegram('answerPreCheckoutQuery', $answer, 4);
if ($result['state'] !== 'ok') throw new RuntimeException('Ответ на проверку не подтверждён');
} else {
$m = $update['message'] ?? [];
$userId = $m['chat']['id'] ?? null;
if (($m['chat']['type'] ?? null) === 'private' && is_int($userId) && $userId > 0) {
if (isset($m['successful_payment'])) {
recordPayment($db, $userId, $m['successful_payment']);
} elseif (isset($m['refunded_payment'])) {
recordPayment($db, $userId, $m['refunded_payment'], true);
} elseif (($m['text'] ?? '') === '/buy') {
try {
courseText();
telegram('sendInvoice', invoiceFor($db, $userId));
} catch (DomainException) {
telegram('sendMessage', ['chat_id' => $userId, 'text' => 'Доступ уже открыт: /access']);
}
} elseif (($m['text'] ?? '') === '/access') {
telegram('sendMessage', ['chat_id' => $userId, 'text' => hasCourseAccess($db, $userId)
? courseText() : 'Оплата не подтверждена: /buy']);
} elseif (($m['text'] ?? '') === '/paysupport') {
telegram('sendMessage', ['chat_id' => $userId,
'text' => 'Вопросы об оплате: '.getenv('PAY_SUPPORT_CONTACT').'. Укажите дату покупки и свой Telegram ID.']);
}
}
}
http_response_code(200);
} catch (Throwable) {
http_response_code(503);
}
Для отправки большого курса замените выдачу одного текста своим контроллером материалов. Само право доступа уже хранится в star_access. На сайте проверяйте его по пользователю из подтверждённой сессии, а не по user_id из URL. Публичная ссылка на PDF без проверки доступа позволит обойти оплату.
Авторизация пользователя Mini App и проверка владельца на сервере
<?php
declare(strict_types=1);
if (PHP_SAPI !== 'cli') exit(1);
require __DIR__.'/common.php';
$url = getenv('WEBHOOK_URL');
$secret = getenv('WEBHOOK_SECRET');
if (!$url || !str_starts_with($url, 'https://') || !$secret) {
throw new RuntimeException('Задайте HTTPS URL и WEBHOOK_SECRET');
}
$answer = telegram('setWebhook', ['url' => $url, 'secret_token' => $secret,
'allowed_updates' => ['message', 'pre_checkout_query']]);
if ($answer['state'] !== 'ok' || $answer['result'] !== true) {
throw new RuntimeException('Webhook не подтверждён; проверьте getWebhookInfo');
}
echo "Webhook установлен\n";
После размещения файлов установите webhook командой ниже. В allowed_updates обязательно входят message и pre_checkout_query: успешная оплата находится внутри message, а не в отдельном типе update. Откройте чат бота именно в выбранной тестовой среде, отправьте /buy и пройдите оплату.
php setup-webhook.php
При ошибке сохранения возвращается 503, а не ложный успешный ответ. Если запросы повторяются, проверьте доступ к БД и журнал технических ошибок; не записывайте в открытый лог токен, секрет webhook или весь платёжный update. Для рабочего приложения добавьте мониторинг 5xx, review-платежей и времени ответа pre-checkout.
Возвращаем Stars и закрываем дальнейший доступ
Возврат запускает уполномоченный сотрудник по сохранённому платежу. Пользовательская кнопка не должна принимать произвольные charge_id и user_id для этой операции. В примере административный вход — CLI-скрипт на сервере; публичного маршрута возврата нет.
/** @param callable(string, array<string, mixed>): array{state: string, result?: mixed, code?: int, retry_after?: int} $call */
function refundPayment(PDO $db, string $charge, callable $call): string
{
$payment = atomic($db, function () use ($db, $charge) {
$q = $db->prepare("SELECT * FROM star_payments WHERE charge_id = ? AND state IN ('paid', 'review') AND currency = 'XTR'");
$q->execute([$charge]);
$payment = row($q);
if (!$payment) return null;
$q = $db->prepare('INSERT INTO star_refunds (charge_id, requested_at) VALUES (?, ?) ON CONFLICT DO NOTHING');
$q->execute([$charge, time()]);
return $q->rowCount() === 1 ? $payment : null;
});
if (!$payment) return 'already_processed_or_requires_review';
$result = $call('refundStarPayment', ['user_id' => (int) $payment['user_id'],
'telegram_payment_charge_id' => $charge]);
if ($result['state'] === 'ok' && ($result['result'] ?? null) === true) {
recordPayment($db, (int) $payment['user_id'], [
'telegram_payment_charge_id' => $charge, 'invoice_payload' => $payment['payload'],
'currency' => $payment['currency'], 'total_amount' => (int) $payment['amount'],
], true);
return 'refunded';
}
$state = $result['state'] === 'rejected' ? 'failed' : 'unknown';
$db->prepare("UPDATE star_refunds SET state = ? WHERE charge_id = ? AND state = 'sending'")
->execute([$state, $charge]);
return $state;
}
<?php
declare(strict_types=1);
if (PHP_SAPI !== 'cli') exit(1);
require __DIR__.'/stars.php';
$charge = $argv[1] ?? '';
if ($charge === '') throw new InvalidArgumentException('Передайте telegram_payment_charge_id');
echo refundPayment(database(), $charge, 'telegram').PHP_EOL;
После проверки обращения найдите telegram_payment_charge_id в star_payments и передайте его скрипту. Следующая команда действительно вызывает возврат выбранной оплаты в том окружении, которое задано конфигурацией:
php refund.php 'TELEGRAM_PAYMENT_CHARGE_ID'
refundStarPayment возвращает всю выбранную оплату; параметра частичной суммы в этом вызове нет. После подтверждённого результата true функция сохраняет refunded и выключает связанное право. Служебное сообщение refunded_payment проходит через ту же обработку, поэтому повтор не меняет итог.
Если ответ потерян, заявка на возврат остаётся unknown, а при падении процесса — sending. Доступ до подтверждения возврата в этой модели сохраняется. Повторный запуск CLI не отправит второй запрос автоматически. При необходимости отдельного временного ограничения доступа оформите его как самостоятельное административное решение, не называя его уже выполненным возвратом.
Сверяем неизвестный результат и поддерживаем покупателя
Для зависших возвратов используйте сохранённое служебное сообщение и журнал getStarTransactions. Сверяйте charge_id, направление операции, пользователя и сумму; проходите нужные страницы по offset и limit. Идентификатор операции возврата совпадает с исходным, поэтому одного совпавшего ID недостаточно: исходящий возврат отличается от входящей покупки.
$page = telegram('getStarTransactions', ['offset' => 0, 'limit' => 100]);
if ($page['state'] !== 'ok') {
throw new RuntimeException('Журнал не получен: повторите чтение позже');
}
$transactions = $page['result']['transactions'] ?? [];
// Сопоставьте записи с локальным charge_id и типом source/receiver.
// Отсутствие в одной странице не означает отсутствие операции.
Если исход подтверждён журналом, уполномоченный обработчик применяет те же переходы БД. Если данных недостаточно, оставьте статус на разборе и сообщите клиенту, что проверка продолжается. Не переводите неизвестный возврат в failed только по таймауту и не удаляйте строку star_refunds ради нового POST.
Команда /paysupport в примере показывает настроенный контакт. Проверьте его до открытия продаж: человек должен получить ответ и возможность связать обращение с покупкой. Для полноценного кабинета сохраняйте обращения, решения и состояние возврата отдельно от истории платежей.
Проверяем покупку, дубли и возврат
Вызовите /buy и закройте окно оплаты: /access не выдаёт урок, star_access остаётся пустой.
Подтвердите pre_checkout_query на тестовых данных, но не добавляйте successful_payment: доступ всё ещё закрыт.
Оплатите в test-среде: появляется один платёж и одно право; /access возвращает урок.
Повторите успешное событие на изолированной БД: число прав не увеличивается. Другой charge_id по тому же заказу попадает в review.
Передайте неверную сумму, валюту или чужого плательщика: pre-checkout отклоняется. Если уже пришёл успешный платёж с несоответствием, он сохраняется для разбора без выдачи доступа.
Выполните возврат: /access перестаёт выдавать материал. Повтор successful_payment после refunded не восстанавливает право.
Имитируйте потерянный ответ refundStarPayment: сохраняется unknown, автоматического повторного возврата нет.
После новой покупки повторите возврат старой: новое право доступа сохраняется.
Локальные проверки с фиктивными событиями подтверждают правила вашей БД. Реальный прогон в тестовой среде нужен отдельно: он проверяет счёт, поступление pre_checkout_query, получение successful_payment, возврат и правильность токена окружения. Перед рабочим запуском также измерьте полное время предварительной проверки, включая доставку webhook.
Где в платёжном сценарии применяется BotGate
Исходящие методы рабочего Bot API можно вызывать через BotGate: меняются адрес и авторизация транспорта, а payload, XTR и привязка к charge_id остаются частью вашего приложения. Для входящих обновлений проверяйте подпись BotGate по его документации. Показанная выделенная test-среда использует прямой Bot API.
Шлюз не подтверждает покупку вместо successful_payment и не хранит права доступа к вашему практикуму. Для pre_checkout_query проверьте задержку всего пути через доставку webhook: десятисекундное окно сохраняется. Разделите этот быстрый обработчик и долгие задания обычной очереди.
Документация BotGate API и webhook
Telegram Stars: оплата цифровых товаров и поддержка покупателей