Aiogram 3.x测试支付后F.successful_payment处理器未触发问题

环境信息 #

• Python 3.11
• Aiogram 3.4
• 支付令牌：BotFather提供的Smart Glocal TEST令牌

问题现象 #

发票正常显示，测试支付已完成（Telegram端显示“Payment successful”），但代码中successful_payment处理器始终未触发，无打印输出也没有回复消息。

代码片段 #

from aiogram import Router, F
from aiogram.types import Message, LabeledPrice, PreCheckoutQuery

router = Router()

@router.callback_query(F.data == "buy")
async def subscribe(callback):
    price = [LabeledPrice(label="Test", amount=1000)]
    await callback.message.answer_invoice(
        title="Test Sub",
        description="Test invoice",
        payload="test_payload",
        provider_token="TEST:xxx",
        currency="USD",
        prices=price
    )

@router.pre_checkout_query()
async def pre_checkout(pre_checkout_query: PreCheckoutQuery):
    await pre_checkout_query.answer(ok=True)

@router.message(F.successful_payment)
async def success(message: Message):
    print("Payment successful")
    await message.answer("✅ Paid!")

预期结果 #

测试支付完成后，success处理器正常执行，打印日志并回复用户“✅ Paid!”。

实际情况 #

Telegram显示支付成功，但处理器未被调用，无任何打印输出。

已尝试操作 #

• 切换使用BotFather提供的Smart Glocal和Stripe TEST令牌
• 尝试USD和INR两种货币
• 预检查（pre_checkout_query）处理器运行正常
• 仅使用测试模式，未测试生产令牌

核心疑问 #

这是Telegram测试模式的限制，还是Aiogram代码存在问题？如何正确测试F.successful_payment处理器？

问题排查与解决方案 #

1. 确认Router已挂载到Dispatcher
   确保你的router已经被正确添加到Dispatcher实例中，否则处理器不会被注册：

   from aiogram import Dispatcher
   
   dp = Dispatcher()
   dp.include_router(router)
   

2. 检查事件拦截情况
   如果存在全局的message处理器（比如@router.message()），它会优先捕获所有消息，导致F.successful_payment的处理器无法触发。可以暂时注释全局处理器，或者给它添加更严格的过滤条件。

3. 验证事件是否被接收
   添加一个全局消息捕获器，打印所有收到的消息，确认Telegram是否发送了successful_payment事件：

   @router.message()
   async def catch_all_messages(message: Message):
       print("Received message:", message.model_dump_json())
   

   完成测试支付后，查看输出中是否包含successful_payment字段。如果没有，说明Telegram未发送该事件，需检查支付流程或测试令牌配置；如果有，说明是Aiogram的处理器匹配问题。

4. 优先使用长轮询测试
   如果使用Webhook模式，可能存在网络、反向代理或SSL证书问题导致事件无法到达。测试阶段建议切换到长轮询模式，排除Webhook的干扰：

   async def main():
       bot = Bot(token="YOUR_BOT_TOKEN")
       await dp.start_polling(bot)
   

5. 使用官方测试卡号
   确保使用Telegram官方认可的测试卡号完成支付，比如：

   • 卡号：4242 4242 4242 4242
   • 到期日：任意未来月份/年份
   • CVV：任意3位数字
     部分第三方测试令牌可能需要特定的测试卡信息，可参考BotFather提供的支付提供商文档。

6. 升级Aiogram版本
   尝试升级到Aiogram最新稳定版，避免旧版本中存在的支付事件处理bug：

   pip install --upgrade aiogram
   

内容的提问来源于stack exchange，提问作者user31301872