用账单收款

账单是您向 Telegram 用户收钱的方式。您通过 API 开一张，把链接发给付款人，他一确认，您的应用 余额当即入账。

整个流程

1. 用 createInvoice 开账单，给出币种和金额（或一个法币价格——见下）。
2. 把响应里的链接发给付款人。他打开就进到应用里的支付页面。
3. 他确认，用自己的余额付掉——瞬间完成，没有网络手续费。余额不够的付款人可以从外部钱包充值 来支付这张账单；他的转账一到就自动结清，在您这一侧看起来没有任何区别。
4. 您收到通知。 invoice_paid webhook 触发，金额进您的应用余额。
5. 发货。 不需要再等任何别的东西；到这一步付款就是最终的。

如果您更想轮询而不是接 webhook，getInvoices 会返回您的账单和它们当前的状态。webhook 是更快 的那条路——轮询是兜底方案。

按法币计价

账单可以按加密货币计价，也可以按一种法币计价，同时给出一份接受的币种清单。付款人届时用 自己持有的、清单上的某一种结算，按付款时的汇率折算。目录以现实货币标价的商店，一般都选 这一种。

如果您更想给出一个固定报价，rate_lock_seconds 会在开单时把折算汇率锁定一小段时间——付款人 看到的就是锁定的那几个数额，这几分钟里的汇率风险由您承担。细节见账单参考。

您还可以设 swap_to，让进来的付款在到账时统一换成某一种资产——想把余额留在稳定币里、又不想 自己去做兑换时很有用。

几个好用的账单选项

• description——在支付页面上显示给付款人。
• hidden_message——付款人付完才看得到。这就是您不另设发货渠道也能交付一个码、一把钥匙 或一条链接的办法。
• payload——您自己的不透明字符串，会在 webhook 里原样回传。把您的订单号放这儿。
• expires_in——一个时限，过了这张账单就付不了了。
• paid_btn_name / paid_btn_url——付款人付完之后看到的那个按钮，把他送回您的机器人、频道 或商品页。
• open_amount——不定额；付款人在付的时候自己填。打赏和捐款天然适合这种形式。

没付掉的账单可以用 deleteInvoice 取消。

退款

refundInvoice 把一张已付账单的票面金额——或其中任意一部分——从您的应用余额退还给 付款人，匿名付款的也能退，而且不会暴露他是谁。部分退款可以累加到票面金额为止；账单在 refunded_amount 里记着这个数。请传一个 spend_id，好让超时重试变成重放而不是退两次。 平台手续费不退。

⚠️ 发货之前先验 webhook 签名

任何人都能往您的 webhook URL 上 POST。在把一笔付款当真之前，请检查 TgCryptoPay-API-Signature 请求头——对原始请求体做 HMAC-SHA256，密钥是您 API 令牌的 SHA-256——并且拿 update_id 去重，免得一次重试把订单发两遍。