Вроде бы есть у ЮКассы неплохая документация о настройке платежей через ТГ-бота, есть в интернете и несколько статей на эту тему, но все-таки на практике сталкиваешься со множеством неочевидных нюансов…
Опишу по шагам процесс подключения платежей для Python-бота на aiogram 3, при условии, что у его владельца уже оформлена самозанятость.
Тестовый режим
Итак, заходим в диалог с BotFather, выбираем своего бота и нажимаем кнопку Payments.
Выбираем из списка провайдеров ЮKassa, а в появившемся диалоге – Connect ЮKassa Test.
Получаем настройки для тестирования – стандартные идентификаторы и данные тестовой карты.
Возвращаемся в BotFather и обнаруживаем, что там кое-что изменилось:
Скопируем этот токен в файл .env нашего бота. Мне удобнее хранить два токена – тестовый и реальный для лучшей взаимозаменяемости. Пока что они совпадают, т.к. реального у нас пока нет.
PROVIDER_TOKEN = "381764678:TEST:100037"
TEST_PROVIDER_TOKEN = "381764678:TEST:100037"Сразу же стоит добавить туда валюту будущих платежей в формате ISO-4217 и размер платежа, обязательно в копейках, а не в рублях.
CURRENCY = "RUB"
PRICE = "9900"Далее эти значения нужно загрузить. У меня для этой цели есть датакласс.
import json
from environs import Env
from dataclasses import dataclass
@dataclass
class Config:
__instance = None
def __new__(cls):
if cls.__instance is None:
env: Env = Env()
env.read_env()
cls.__instance = super(Config, cls).__new__(cls)
…
cls.__instance.provider_token = env('PROVIDER_TOKEN')
cls.__instance.currency = env('CURRENCY')
cls.__instance.price = env.int('PRICE')
provider_data = {
"receipt": {
"items": [
{
"description": "Подписка на месяц",
"quantity": "1.00",
"amount": {
"value": f"{cls.__instance.price / 100:.2f}",
"currency": cls.__instance.currency
},
"vat_code": 1
}
]
}
}
cls.__instance.provider_data = json.dumps(provider_data)
return cls.__instance
config = Config()Здесь все очевидно, кроме provider_data. В соответствии с 54-ФЗ за каждый платеж нужно выдавать чек. Я переложила эту задачу на ЮKassa, поэтому мне пришлось заготовить данные для формирования чеков:
items– список товаров в заказе, для самозанятых – не более 6;description– описание товара длиной до 128 символов;quantity– количество, для самозанятых – обязательно целое (а так хотелось продать только треть подписки))));value– цена товара в рублях. Но мы-то храним цену в копейках, поэтому делим ее на 100 и обязательно указываем спецификатор формата (.2f), чтобы не потерять солидную сумму 00 копеек;currency– код валюты;vat_code– ставка НДС, для самозанятых пишем 1.
Главное – не перепутать, где цена в рублях, а где в копейках. Но почему такое расхождение? Оно восходит к Telegram Bot API, где объект LabeledPrice, содержащий цену товара, хранит ее в минимальных единицах валюты – центах, копейках и т.д. Если указать в чеке значение env.int('PRICE'), то платеж просто не пройдет.
Теперь создадим обработчик команды /buy, которая будет использоваться для покупок в нашем боте.
@router.message(Command(commands=['buy']))
async def buy_subscription(message: Message, state: FSMContext):
try:
# Проверка состояния и его очистка
current_state = await state.get_state()
if current_state is not None:
await state.clear() # чтобы свободно перейти сюда из любого другого состояния
from config import config
if config.provider_token.split(':')[1] == 'TEST':
await message.reply("Для оплаты используйте данные тестовой карты: 1111 1111 1111 1026, 12/22, CVC 000.")
prices = [LabeledPrice(label='Оплата заказа', amount=config.price)]
await state.set_state(FSMPrompt.buying)
await bot.send_invoice(
chat_id=message.chat.id,
title='Покупка,
description='Оплата бота',
payload='bot_paid',
provider_token=config.provider_token,
currency=config.currency,
prices=prices,
need_phone_number=True,
send_phone_number_to_provider=True,
provider_data=config.provider_data
)
except Exception as e:
logging.error(f"Ошибка при выполнении команды /buy: {e}")
await message.answer("Произошла ошибка при обработке команды!")
current_state = await state.get_state()
if current_state is not None:
await state.clear()Здесь я использую машину состояний aiogram, чтобы отслеживать, находится ли бот в режиме оплаты. Состояние чистится при входе и при аварийном выходе из обработчика.
Чтобы данные тестовой карты были всегда под рукой, я отправляю их пользователю в том случае, если в настройках бота задан тестовый платежный токен.
Далее создаем массив объектов LabeledPrice для передачи в метод отправки инвойсов, т.е. счетов на оплату. Кроме того, в этот метод передаются значения, сохраненные ранее в настройках бота, а также обязательный параметр payload (строка, которую API заставляет нас использовать для наших внутренних процессов, нисколько не интересуясь, нужна ли она нам вообще).
Отдельно стоит остановиться на параметрах need_phone_number и send_phone_number_to_provider. Они нужны для отправки покупателям вышеупомянутых электронных чеков.
Если вы настроили фискализацию через ЮKassa, то у вас два пути для получения контактов пользователя:
запросить e-mail/телефон заранее и передать это значение в
provider_data.receipt.email/provider_data.receipt.phone;задать параметрам
need_phone_number/need_emailиsend_phone_number_to_provider/send_email_to_providerзначение True. Тогда ЮKassa запросит соответствующее значение при оплате.
В моем коде используется второй способ.
Следующий метод, который нам необходимо реализовать, будет универсальным. Это стандартный код для обработки апдейта типа PreCheckoutQuery, на который нам необходимо ответить в течение 10 секунд.
@router.pre_checkout_query()
async def process_pre_checkout_query(pre_checkout_query: PreCheckoutQuery):
try:
await bot.answer_pre_checkout_query(pre_checkout_query.id, ok=True) # всегда отвечаем утвердительно
except Exception as e:
logging.error(f"Ошибка при обработке апдейта типа PreCheckoutQuery: {e}")Сам PreCheckoutQuery – это объект, содержащий информацию о входящем запросе на предварительную проверку и содержащий знакомые нам параметры currency, total_amount и снова обязательный payload.
Теперь обработаем успешный платеж. Чтобы отловить его, нам понадобится магический фильтр F.successful_payment.
@router.message(F.successful_payment)
async def process_successful_payment(message: Message, state: FSMContext, db: Database):
await message.reply(f"Платеж на сумму {message.successful_payment.total_amount // 100} "
f"{message.successful_payment.currency} прошел успешно!")
await db.update_payment(message.from_user.id)
logging.info(f"Получен платеж от {message.from_user.id}")
current_state = await state.get_state()
if current_state is not None:
await state.clear() # чтобы свободно перейти сюда из любого другого состоянияДля вящей точности данные об уплаченной сумме (в копейках) и о валюте расчетов берутся из сервисного сообщения об успешном платеже. Все это мы докладываем пользователю, сохраняем где-то в базе данных информацию об оплате (не зря же он платил?) и очищаем состояние.
Но если фильтр успешной оплаты не сработал, а бот находится в состоянии покупки, то, значит, произошла какая-то ошибка, о чем надо уведомить пользователя. Вот зачем мне понадобилась машина состояний.
@router.message(StateFilter(FSMPrompt.buying))
async def process_unsuccessful_payment(message: Message, state: FSMContext):
await message.reply("Не удалось выполнить платеж!")
current_state = await state.get_state()
if current_state is not None:
await state.clear() # чтобы свободно перейти сюда из любого другого состоянияФильтр здесь, в сущности, дефолтный, поэтому этот обработчик должен стоять самым последним во всем фрагменте кода, относящемся к приему платежей.
Последний штрих – проверим, что поллинг запускается без пропуска непрочитанных апдейтов, накопившихся ко времени запуска.
await dp.start_polling(bot, skip_updates=False)Так повелось для работы с платежами еще со времен aiogram 2.
Теперь можно запустить бота, отправить ему команду /buy и проверить, что тестовый платеж успешно проходит.
Полноценный режим
Чтобы настроить реальные платежи, нужно зарегистрироваться в ЮKassa, добавить данные о своей организации и своем магазине. Правда, у нас бот, а не магазин, но все равно менеджеры запрашивают какой-нибудь интерфейс, где виден список товаров с ценами. Я отправила скрин справки, которую мой бот выдавал по команде /help.
Результатом всех этих формальностей станет ваш собственный ShopID, который вы увидите в личном кабинете.
Вернемся теперь к нашему диалогу с BotFather.
Снова выберем ЮKassa и Connect ЮKassa Live. Бот запросит shopId и shopArticleId (в качестве которого советует отправить просто 0). Отправив их, вернемся к BotFather, где появится теперь уже реальный платежный токен вида x:LIVE:y. Осталось записать его в PROVIDER_TOKEN в файле .env и…
И ничего не работает!
Дело в том, что для приема платежей в Telegram нужно перевести магазин на email-протокол. Для этого напишите письмо на ecommerce@yoomoney.ru с указанием своего ShopID. ЮKassa привычна к таким запросам и оперативно их выполняет.
Теперь все в порядке!
Резюме
В этой статье я постаралась собрать воедино всю информацию о настройке интеграции с ЮKassa, которую мне удалось собрать в интернете, при переписке с техподдержкой и по личному опыту. А опыт этот показывает, что достаточно упустить малейший нюанс, как от ЮKassa приходит сообщение об ошибке платежа без подробностей. Надеюсь, что моя статья немного исправит эту ситуацию.
