用账单收款

账单是您向 Telegram 用户收钱的方式。您通过 API 开一张，把链接发给付款人，付款成功后，扣除商户手续费的款项计入您的应用余额。

整个流程

1. 用 createInvoice 开账单，给出币种和金额（或一个法币价格——见下）。
2. 把响应里的链接发给付款人。他打开就进到应用里的支付页面。
3. 他确认，用自己的余额付掉——瞬间完成，没有网络手续费。该选项可用时，余额不足的付款人可以从外部钱包充值来支付账单。自动付款要求截止时间前已有足够资金入账，且付款人无转出限制。仅有充值并不能证明账单已付。
4. 您收到通知。 如果配置了 webhook URL，付款后会将 invoice_paid 事件加入投递队列。款项扣除手续费后计入应用余额。
5. **交付订单。**先验证 webhook 签名，将账单与订单匹配，并确认状态为 paid。也可用 getInvoices 查询状态，无需再等待区块链确认。

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

按法币计价

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

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

还可设置 swap_to，在兑换可用时将收入换成同一种资产。若无法兑换，付款仍会以原资产成功完成；请检查 is_swapped 和 swapped_* 字段。

几个好用的账单选项

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

说明、隐藏内容和付款后按钮可能在内容审核通过前对付款人隐藏。不要假定创建账单后就会立即显示。

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

退款

refundInvoice 会从应用余额向原付款人退还实际支付的加密货币——也可只退其中一部分。匿名付款同样可退，且不会暴露付款人身份。多次部分退款累计不得超过原支付的加密货币金额，账单通过 refunded_amount 记录。法币账单退款使用 paid_asset 和 paid_amount，而非法币面值。即使付款后自动兑换过，应用也必须有足够的原付款资产。请传一个 spend_id，以便超时后重试时返回原结果，避免重复退款。 平台手续费不退。

⚠️ 发货之前先验 webhook 签名

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