Cryptanio
账户

如何在 Telegram 机器人中接受加密货币付款

将自有 Telegram 机器人的实物商品订单关联到 Cryptanio 付款账单，向买家发送付款链接并核实付款，同时遵守 Telegram Stars 和 Mini Apps 的限制。

更新日期:

您可以将加密货币付款与自有 Telegram 机器人的订单关联起来：服务器创建 Cryptanio 付款账单，机器人向买家发送链接，核实付款后再告知买家订单已受理。下面以销售实体商品的商店为例，例如印刷海报。机器人和订单处理逻辑仍需由您自行开发。

先确认 Telegram 的规则

在 Telegram 内销售数字商品和服务，必须使用以 XTR 表示的 Telegram Stars。例如，付费解锁机器人中的内容就属于这种情况。提供外部网站链接并不构成例外：对于此类购买，不能用加密货币替代 Stars。这些限制在 Telegram Stars 文档中有明确说明。

本指南的场景是没有 Mini App 的普通机器人，以及实物商品订单。Mini Apps 及其关联机器人还受额外的区块链集成限制，包括使用 TON 的要求。没有 Mini App 的普通机器人在 Telegram Blockchain Guidelines中被明确排除在这些规则之外。因此，未经额外核实，不能将本指南直接用于 Mini App。Telegram 规则的核实日期为 2026 年 11 月 13 日。

需要准备什么

准备好自有机器人、运行机器人的服务器、Cryptanio 账户，以及已启用 Payments 服务的项目。还需要已接入该项目 Payments 的收款地址，以及具有付款账单和相应服务权限的有效 API 密钥。

Telegram 机器人令牌、Cryptanio API 密钥和 webhook 验签密钥都应保存在服务器上。只向买家提供属于他的付款链接。本场景不包含能够自动创建商店并处理订单的现成集成。

1. 准备收款项目

在控制台启用 Payments，并将收款地址添加到该服务的地址池。仅将地址保存在地址簿中还不够。确认项目支持所需网络和资产；不要向买家承诺付款页面上没有提供的选项。

如果您还不清楚 USDT 与网络的区别，请先阅读《网络与代币》。付款账单将一笔具体的付款请求与其状态关联起来。

2. 将订单与买家关联

用户选好海报并确认订单后，由服务器创建内部订单编号。保存订单、Telegram 买家和即将创建的付款账单 ID 之间的对应关系。联系信息和收货地址应保存在您自己的系统中，不必将其放入技术链接或公开消息。

必须能够根据保存的付款账单 ID 唯一找到对应订单。这样，即使机器人重启，也能继续处理付款。

3. 创建单独的付款账单

在服务器上通过 API v1 调用创建付款账单操作。对于由买家选择网络和资产的场景，使用 invoice_currency 和 invoice_amount 设置订单报价。例如，USD 12.50 表示报价单位，实际付款则使用受支持的加密货币。这不代表接受美元，也不代表自动兑换资金。

以下引用的是文档目录中受支持的订单创建示例：

#!/usr/bin/env bash
set -euo pipefail
: "${CRYPTANIO_API_KEY:?Set CRYPTANIO_API_KEY}"
: "${CRYPTANIO_OPERATION_ID:?Set CRYPTANIO_OPERATION_ID}"
: "${CRYPTANIO_PROJECT_ID:?Set CRYPTANIO_PROJECT_ID}"
json_string() {
  local text="$1" char code index output='"'
  for ((index=0; index<${#text}; index++)); do
    char="${text:index:1}"
    case "$char" in
      '"'|'\') output+="\\$char" ;;
      *) printf -v code '%d' "'$char"
         if ((code < 32)); then printf -v char '\\u%04x' "$code"; fi
         output+="$char" ;;
    esac
  done
  printf '%s"' "$output"
}
response_file="$(mktemp)"
trap 'rm -f "$response_file"' EXIT
transfer_status=0
http_status="$(curl \
  --silent --show-error --max-time 30 --request POST \
  --header "Authorization: Bearer $CRYPTANIO_API_KEY" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header "Idempotency-Key: $CRYPTANIO_OPERATION_ID" \
  --data-binary '{"project":'"$(json_string "$CRYPTANIO_PROJECT_ID")"',"invoice_currency":"USD","invoice_amount":"12.50","reference":"order-42"}' \
  "https://api.cryptanio.com/v1/invoices" \
  --output "$response_file" --write-out '%{http_code}')" || transfer_status=$?
if [[ "$http_status" == 2?? ]]; then
  cat "$response_file"
  exit "$transfer_status"
fi
printf 'HTTP %s\n' "$http_status" >&2
cat "$response_file" >&2
exit 1

下载示例

传入您自己的订单参数。每个新操作都需要唯一的 Idempotency-Key；如果故障后重试同一个请求，应继续使用原来的密钥。这样可避免重复点击生成另一张账单。详细说明见订单确认指南。

4. 向买家发送链接

保存创建响应中的 checkout_url，并在私聊中通过链接按钮发送给买家。Bot API 支持 URL 按钮，详见 InlineKeyboardButton。买家打开 Cryptanio 页面后，可以选择可用的付款方式。

请原样传递收到的 URL。不要根据 ID 自行拼接链接：读取付款账单时返回的链接用于查看。要继续交互式付款，必须使用创建响应中保存的链接。

5. 在服务器上确认付款

将项目的 webhook 配置为指向您自己的处理程序，并基于请求的原始正文验证签名。将事件与已保存的付款账单匹配，再通过 API 检查付款账单当前状态。

只有在状态为成功的 paid 时，才能将订单交付后续处理。发现交易、买家返回聊天窗口，或收到“我已付款”的消息，都不能作为这种确认。部分付款、付款不足、超额付款或逾期付款可能需要单独决策，不要自动确认此类订单。重复 webhook 不应导致订单重复履行。

如何检查及排查错误

用您自己的订单检查完整流程：创建、打开链接、付款、状态变化，以及机器人消息。请考虑网络手续费；这种创建付款账单的方式使用真实数据。还应单独检查重复点击按钮和事件重复投递的情况。

如果资金已发送，但订单未确认，请核对网络、资产、付款信息和交易确认。如果状态已经是 paid，应检查订单与付款账单的关联以及机器人处理程序。发给商家本人的 Telegram 通知可以按照单独的指南配置，但这些通知本身不能代替服务器对订单的核实。

相关文章