Telegram Bot支付接口接入教程：从创建发票到完成收款

Telegram Bot不仅是聊天和自动化的利器，还支持原生支付功能。通过Bot API的支付接口，你可以让用户直接在聊天窗口中完成商品购买、会员开通或服务付费，无需跳转外部页面。本教程将带你从零开始接入Telegram Bot支付接口，涵盖关键步骤、代码示例与常见问题，确保你的机器人能够安全、高效地收款。

一、接入前的准备工作

在编写代码之前，你需要完成以下前置条件：

1. 创建Bot并获取令牌：在Telegram中联系@BotFather，创建你的Bot，并记下API令牌（格式如123456789:ABCdef... ）。这是所有API调用的凭证。
2. 开通支付权限：同样在@BotFather中，使用/mybots选择你的Bot，进入Bot Settings → Payments，按照提示选择支付提供商。Telegram支持多家第三方支付服务商（如Stripe、Sberbank等），或者使用Telegram Stars虚拟货币进行小额支付。
3. 获取支付提供商令牌：如果你选择了第三方支付服务商，需要在服务商后台创建应用并获取对应的支付令牌（通常是Provider Token）。例如，在Stripe中创建Telegram Bot专用的令牌。若使用Telegram Stars，则无需额外的提供商令牌。
4. 设置支付回调URL：部分支付服务商要求填写Webhook回调地址，用于同步支付结果。Telegram的Bot API本身通过getUpdates或Webhook发送支付状态，因此需确保你的Bot接收更新正常。

二、创建并发送发票

发票（Invoice）是支付的核心实体，通过sendInvoice方法发送给用户。你需要构造一个包含商品信息、价格、货币等参数的请求。

sendInvoice参数详解

• chat_id：目标用户的ID（必须双方已开始对话）。
• title：商品标题，1-32个字符。
• description：商品描述，1-255个字符。
• payload：自定义数据（如订单号），支付成功后原样返回给Bot。
• provider_token：支付提供商令牌。使用Telegram Stars时留空。
• currency：货币代码，如USD、CNY（需提供商支持）。
• prices：价格数组，由label和amount组成，金额单位是“分”（例如$9.99 → amount: 999）。
• start_parameter：深层链接参数，可选。

示例代码（Python）

import requests

TOKEN = '你的BOT令牌'
PROVIDER_TOKEN = '你的支付提供商令牌'

url = f'https://api.telegram.org/bot/sendInvoice'
payload = {
    'chat_id': 123456789,
    'title': '高级会员（1个月）',
    'description': '解锁全部高级功能，按月自动续费',
    'payload': 'order_001',
    'provider_token': PROVIDER_TOKEN,
    'currency': 'USD',
    'prices': [
        {'label': '会员费用', 'amount': 999},
        {'label': '税', 'amount': 100}
    ],
    'start_parameter': 'pay_member'
}
response = requests.post(url, json=payload)
print(response.json())

发送成功后，用户会在聊天中看到一张带“支付”按钮的发票卡片，点击后由Telegram或其支付服务商完成扣款。

三、处理预付款回调

用户点击支付按钮后，Telegram会向你的Bot发送一个pre_checkout_query更新。你必须在10秒内调用answerPreCheckoutQuery来确认订单（或拒绝）。这是合法拦截无效订单的最后机会。

接收预付款查询

通过getUpdates长轮询或Webhook接收更新。当update.pre_checkout_query存在时，提取其id和total_amount等字段。

确认或拒绝

# 处理 pre_checkout_query
def handle_pre_checkout(query_id, ok=True, error_message=""):
    url = f'https://api.telegram.org/bot/answerPreCheckoutQuery'
    data = {
        'pre_checkout_query_id': query_id,
        'ok': ok,
        'error_message': error_message
    }
    requests.post(url, json=data)

建议：在确认前主动校验商品库存、订单金额是否正确。若出现任何异常，返回false并提供简短错误描述，用户将看到支付失败提示，不会扣款。

四、处理支付成功通知

支付成功并确认后，Telegram会向Bot发送一条message，其中包含successful_payment字段。该字段包含支付信息（如currency、total_amount、invoice_payload），你需要在此刻向用户发放权益（如开通会员、发送数字商品）。

示例：解析成功支付

def handle_message(message):
    if 'successful_payment' in message:
        payment = message['successful_payment']
        payload = payment['invoice_payload']
        amount = payment['total_amount']
        # 根据payload发放权益，比如更新数据库中的用户会员到期时间
        send_confirmation(message['chat']['id'], payload, amount)

务必保证该处理逻辑具备幂等性，即同一订单重复回调不会重复发放权益。

五、使用Telegram Stars（可选）

如果你的业务偏向虚拟商品或小额打赏，Telegram Stars是一种简便的选择。在@BotFather开通Stars支付后，`sendInvoice`中省略`provider_token`，并设置`currency`为XTR。Stars支付不依赖第三方服务商，到账快，适合数字内容销售。但请留意Telegram的政策，实物商品可能不允许使用Stars。

六、安全与合规注意事项

• 验证令牌与请求来源：所有与Bot API的交互必须使用HTTPS，并确保`provider_token`不泄露。不要将令牌硬编码在前端。
• 签名校验（Webhook模式）：如果使用Webhook，Telegram允许自定义请求头`X-Telegram-Bot-Api-Secret-Token`，你可以在设定Webhook时传入，并在回调中校验该头，防止伪造请求。
• 欺诈防护：在`answerPreCheckoutQuery`前务必进行业务校验，防止恶意用户篡改金额或数量。收款后及时通过`getChatMember`等接口验证用户身份。
• 合规性：确保你的商品或服务符合Telegram服务条款及当地法律法规。对于实物商品，需要向用户收集收货地址（通过Telegram内置的`request`接口），并遵守隐私政策。
• 日志记录：记录所有支付的请求与响应，便于对账和排错。但需注意日志中不要包含完整的用户敏感信息。

七、实际应用场景与扩展

支付接口可以用于：

• 付费订阅：按天/月/年收取订阅费，配合定时任务检查到期状态。
• 数字商品下载：付款后自动发送文件、邀请链接、激活码等。
• 服务预约：先支付定金再确认预约，减少爽约率。
• 打赏与捐赠：为内容创作者提供便捷的打赏入口。

你还可以将支付流程与Bot的键盘菜单、内联模式结合，构建更完整的使用体验。

八、常见问题速查

Q1：用户点击支付后一直没反应？

检查你的`pre_checkout_query`回调是否及时响应，以及`answerPreCheckoutQuery`中`ok`是否为`true`。同时确保`provider_token`正确且账户余额充足。

Q2：支付成功后没收到消息？

确认你是否正确使用了`getUpdates`或Webhook，并且没有遗漏`successful_payment`字段的类型判断。部分情况下Telegram可能延迟几秒，建议在日志中打印消息ID。

Q3：用户要求退款怎么办？

Telegram Bot API没有直接的退款接口，你需要通过支付提供商（如Stripe）的后台手动退款，或通过人工协调。Stars支付目前不允许退款，请在商品描述中明确说明。

总结

接入Telegram Bot支付接口并不复杂，核心是理解`sendInvoice`、`answerPreCheckoutQuery`和成功支付消息这三大环节。本教程给出了完整的接入思路与示例代码，你只需根据自身业务调整商品参数和权益发放逻辑即可。记得在实际运营中不断优化安全策略，并关注Telegram官方文档的更新。愿你的机器人早日实现盈利！