在Telegram机器人生态中，支付功能是变现和业务闭环的关键一环。无论是售卖虚拟商品、会员订阅，还是线下服务预约，通过机器人内置的支付接口，用户无需跳出聊天即可完成付费，体验极其流畅。然而，很多开发者被复杂的支付流程和API细节劝退。本文将从零开始，带你完整对接Telegram机器人支付接口，涵盖配置、编码、调试全流程，确保你能够顺利上线付费机器人。
一、支付接口对接前的基础准备
在动手写代码之前，你需要确保具备以下条件和权限：
- 一个已认证的Bot Token：通过BotFather创建机器人并获取Token。这是调用所有Telegram API的凭证。
- 支付渠道资格：Telegram支付目前支持多种支付提供商（如Stripe、Tron、PayMaster等），不同提供商有不同的入驻要求。对于中国大陆开发者，通常选择支持国际业务的提供商，或使用加密货币支付方案。
- 与BotFather绑定支付提供商：Telegram不会直接处理资金，你需要先在支付提供商平台创建账号并获取API密钥，然后在BotFather中发送
/payment指令进行关联。
注意：支付功能仅对公开的机器人开放，且机器人必须通过BotFather完成付款设置。
二、通过BotFather开通支付并获取Provider Token
这是最容易出错的一步，操作如下：
- 打开Telegram，搜索@BotFather，输入
/mybots，选择你的机器人。 - 点击Payment选项，进入支付设置。
- 选择可用的支付提供商，依据页面提示填入你在提供商平台获取的API密钥（如Stripe Secret Key）。
- 成功绑定后，BotFather会返回一个Provider Token，形如
284685063:TEST:Y2JhYjE3MjA。注意区分测试令牌和正式令牌，测试令牌用于沙箱环境。
获取到Provider Token后，将其放在服务端环境变量中，切勿暴露到客户端。
三、支付接口核心API解析
Telegram Bot API提供了三个关键的支付接口，理解它们才能正确串联支付流程：
sendInvoice：向用户发送一张电子发票（账单），包含商品名称、描述、价格、货币等参数。用户看到的是一个带价格标签的卡片。answerShippingQuery：当用户选择配送地址时触发，你需要回传可用的配送选项或错误提示（如果商品不需要物流，则无需配置）。answerPreCheckoutQuery：在用户确认支付前，Telegram会发送预结算请求，你的后端必须返回ok: true才能放行，否则支付中断。
此外还有setPassportDataErrors等，但支付核心就是这三个。每个接口的具体参数可以通过官方文档查询，下面提供实战示例。
四、Python实战：完整对接示例代码
下面以Python为例，使用requests库手动实现支付流，不依赖重型框架，便于理解底层逻辑。假设你已设置好环境变量BOT_TOKEN和PROVIDER_TOKEN。
import requests
import json
import time
BOT_TOKEN = "你的BOT_TOKEN"
PROVIDER_TOKEN = "你的PROVIDER_TOKEN"
API = f"https://api.telegram.org/bot"
def send_invoice(chat_id, title, description, payload, amount, currency="RUB"):
"""发送发票"""
data = {
"chat_id": chat_id,
"title": title,
"description": description[:255],
"payload": payload, # 自定义数据，用于关联订单
"provider_token": PROVIDER_TOKEN,
"currency": currency,
"prices": [{"label": title, "amount": int(amount * 100)}] # 注意金额以分为单位
}
r = requests.post(f"/sendInvoice", json=data)
return r.json()
def answer_pre_checkout(pre_checkout_id, ok=True, error_message=""):
"""响应预结算"""
data = {
"pre_checkout_query_id": pre_checkout_id,
"ok": ok
}
if not ok:
data["error_message"] = error_message
r = requests.post(f"/answerPreCheckoutQuery", json=data)
return r.json()
# 示例：获取更新的长轮询
def get_updates(offset):
r = requests.get(f"/getUpdates", params={"offset": offset, "timeout": 30})
return r.json()["result"]
def main():
offset = 0
while True:
try:
updates = get_updates(offset)
for upd in updates:
offset = upd["update_id"] + 1
# 处理消息或回调
if "message" in upd:
msg = upd["message"]
text = msg.get("text", "")
if text == "/pay":
# 发送一张售价10元的测试商品
send_invoice(
chat_id=msg["chat"]["id"],
title="测试商品",
description="一个测试虚拟商品",
payload="order_123",
amount=10,
currency="CNY"
)
elif "pre_checkout_query" in upd:
pcq = upd["pre_checkout_query"]
# 这里可以验证订单信息，如无问题则确认
answer_pre_checkout(pcq["id"], ok=True)
elif "successful_payment" in upd.get("message", {}):
# 支付成功通知
print("支付成功：", upd["message"]["successful_payment"])
except Exception as e:
print("Error:", e)
time.sleep(3)
if __name__ == "__main__":
main()上述代码演示了核心流程。注意：成功支付的消息类型为successful_payment，你需要在这个字段里确认订单并发放权益。另外，sendInvoice还支持添加photos、shipping_address等可选参数，使票据更美观或满足物流场景。
五、支付回调处理：确保订单状态同步
支付成功后的回调处理是业务的关键。Telegram会向你的Webhook或长轮询发送一条包含successful_payment的消息，其中含有payload（你自定义的订单号）、total_amount、currency等。你需要做到：
- 验签与幂等性：虽然Telegram的请求来自官方服务器，但为了安全，建议在你自己的数据库记录
payload，并在处理前检查该订单是否已处理，避免重复发货。 - 异步发放：如果发放权益涉及其他系统调用（如开通会员），建议异步处理并做好日志。
- 异常处理：如果处理失败，可给管理员发送告警，并在一段时间后重试。
对于Webhook模式，务必使用setWebhook并设置安全的秘密令牌（Secret Token），以便在请求头中验证来源。
六、常见问题与调试技巧
在实际对接中，你可能会遇到以下问题，这里提供快速解决方案：
- User not found for bot：通常是Provider Token与Bot不匹配，或者支付未开通。请回到BotFather检查。
- 货币不支持：部分支付提供商不支持某些货币，请确认你所用的货币代码是否在支持列表（如CNY可能出现不支持的情况，建议用USD或RUB）。
- 发票无法接收：检查Bot是否设置了隐私模式？支付消息与隐私无关，但若用户屏蔽了Bot则收不到。
- 预结算超时：需要在请求后及时响应
answerPreCheckoutQuery，最长等待时间为10秒，否则用户看到支付失败。
调试利器：使用BotFather提供的测试令牌（Test Provider Token）在沙箱环境中反复测试，并利用getUpdates的日志输出。另外，Telegram官方还提供sendInvoice的测试模式，无需真实扣款。
总结
Telegram机器人支付接口的对接并不复杂，核心在于理解Provider Token的绑定、三个关键API的调用顺序以及成功支付后的订单处理。按照本文的步骤，你可以在半小时内跑通一个简单的付费机器人。生产环境中，一定要重视安全性和幂等性，同时合理设计商品目录和库存体系。希望这篇指南能助你顺利实现商业变现，探索更多机器人应用场景。