# DigiDala — технический план `/paysupport`

**Тип документа:** внутренний
**Редакция:** 1.1
**Дата:** 03.10.2026

## 1. Назначение

`/paysupport` — основной пользовательский канал для обращений по платежам Telegram Stars и цифровым покупкам DigiDala.

Для публичной продажи цифровых товаров и услуг реализация платёжной поддержки должна быть завершена до включения соответствующего сценария в боевой эксплуатации.

## 2. Текущее состояние на 03.10.2026

Платёжная модель DigiDala уже хранит сведения, необходимые для сверки операций:

- пользователя;
- назначение операции (`project_support` / `pix_purchase`);
- сумму в Stars;
- invoice payload;
- статус `pending` / `paid` / `expired`;
- `telegram_payment_charge_id`;
- даты создания и оплаты.

`telegram_payment_charge_id` должен сохраняться, поскольку Telegram использует его для возврата конкретной операции.

`/paysupport` подключён как пользовательская точка входа в платёжную поддержку. Полностью автоматизированный workflow возврата и отдельная таблица возвратов в текущей версии ещё не реализованы.

## 3. Целевой пользовательский поток

1. Пользователь отправляет `/paysupport` в личном чате с `@PixDala_bot`.
2. Бот показывает последние оплаченные операции или предлагает указать нужный платёж.
3. Пользователь выбирает операцию и кратко описывает проблему.
4. Заявка сохраняется как платёжное обращение и передаётся на рассмотрение.
5. Оператор/администратор проверяет:
   - существование платежа;
   - пользователя;
   - назначение;
   - сумму;
   - текущий статус;
   - `telegram_payment_charge_id`;
   - факт предоставления цифровой ценности;
   - наличие подтверждённой технической ошибки или иной причины для возврата.
6. При одобрении возврата сервер вызывает механизм Telegram для возврата Stars по исходному пользователю и `telegram_payment_charge_id`.
7. Только после успешного ответа Telegram операция помечается как возвращённая.
8. Если возвращается покупка Pix, должна быть создана обратная/компенсирующая запись в Pix ledger, если это необходимо для сохранения целостности баланса.
9. Повторный возврат той же операции должен быть запрещён на уровне backend и базы данных.
10. В аудите сохраняются причина возврата, дата, оператор, исходный платёж и результат возвратной операции.

## 4. Почему решение о возврате не должно приниматься только по команде пользователя

Платёжная ошибка, непредоставление цифровой ценности, неверное количество и простое изменение решения пользователя — разные ситуации.

Поэтому `/paysupport` создаёт обращение, но окончательное решение о возврате принимает Оператор после проверки операции и с учётом обязательных требований закона и правил Telegram.

## 5. Telegram-механизм возврата

Telegram предоставляет отдельный механизм возврата Stars и требует для конкретной операции идентификатор пользователя и `telegram_payment_charge_id`.

Должна учитываться возможность повторного запроса: сервер обязан сделать возврат идемпотентным и корректно обрабатывать ответ Telegram о том, что операция уже была возвращена.

## 6. Рекомендуемая модель данных

Рекомендуется отдельная таблица `payment_refunds`, связанная с исходным платежом, с полями не менее:

- `payment_id`;
- `user_id`;
- `refund_status`;
- `refund_requested_at`;
- `refund_reason`;
- `refund_amount_stars`;
- `refunded_at`;
- `refunded_by`;
- `telegram_payment_charge_id`;
- `error_code` / `error_message` при неуспешном запросе.

## 7. Pix ledger

Возврат оплаченной покупки Pix не должен выполняться простым удалением исходной записи.

Для сохранения аудита и целостности баланса используется компенсирующая операция, которая связывается с исходной покупкой и записью возврата.

Повторный запуск обработчика не должен создавать повторное списание Pix.

## 8. Подтверждение поддержки

После успешного решения пользователь должен получить понятное сообщение о результате:

- платёж возвращён;
- платёж не подлежит возврату с указанием причины в допустимой форме;
- требуется дополнительная проверка;
- произошла техническая ошибка, и обращение передано на дополнительное рассмотрение.

## 9. До следующего этапа публичной эксплуатации

Необходимо:

- сохранить и проверить рабочий `/paysupport`;
- поддерживать публичные ссылки на Terms / Rules / Privacy / Payments & Refunds;
- реализовать подтверждение ознакомления с условиями перед первой платной операцией в требуемом сценарии;
- реализовать ручное решение о возврате и аудит;
- добавить тесты возврата и идемпотентности;
- проверить реальный возврат в Telegram Stars в доступной тестовой среде;
- проверить компенсирующую операцию Pix ledger;
- проверить, что повторное выполнение обработчика не меняет итог второй раз.