商户 API 的费用和限额

账单要收一笔平台手续费，从您到手的那部分里出；转账和红包则受金额上下限的约束。下面这些数字是 当前的设置，不是合同条款——跟您在应用里看到的对不上时，以应用为准，而最靠得住的依据永远是 您自己那些已付账单。

账单手续费

付款人付的永远是账单的票面金额。费用出在商户这一侧：您的应用余额入账的是扣费之后 的数额。

费率是账单金额的 3%，并且随着您过去 30 天的收款流水自动往下走：

有两条规则比这个数字更要紧：

• 费率在付款那一刻就确定并锁死了。 之后费率怎么变，都碰不到一张已经付掉的账单。
• 您的费率会随流水变动。 滚动 30 天窗口里收款流水上去了，就会自动落到更低的一档。 不用申请，也没有什么要配置的。

想知道到底扣了多少，请从已付账单上读 fee_asset 和 fee_amount——从 invoice_paid 的 webhook payload 里读，或用 getInvoices 取。那才是您记账时的权威数字。

退款不退手续费：refundInvoice 发给付款人的资金出自您的余额，手续费不退——部分退款也一样。

订阅扣款同样带一笔商户侧费用；每一次扣款都在 subscription_charged webhook 的 charge.fee 字段里报出自己的数字。

转账限额

transfer 受每笔的最低额和最高额约束，按当前行情折算成美元等值来算，不是按各币种单独 定的数。超出这个范围的金额会被明确报错拒掉，所以请在您的集成里处理 amount_too_small 和 amount_too_big。

下面几种情况转账也会失败：

• 您那个币种上的应用余额不够，
• 收款人不是本应用的用户——打给一个不存在或打错的 Telegram ID 会报错，而不是给一个 没人会打开的钱包入账，
• 收款人的账号被封了。

频率限制

涉及资金的方法按应用限流（该应用的所有令牌共用一份额度），每分钟的上限：createInvoice 和 createCheck 是 60，refundInvoice 和 transfer 是 30，transferBatch 是 10。 读取类方法不限。行为正常的集成根本遇不到；不断重试的循环则会触发——请在 rate_limited 时 退避，不要持续重试。

幂等

transfer 要求您自己生成一个 spend_id；createCheck 和 refundInvoice 也接受它。 用同一个值重复调用，返回的是原来那次的结果，资金不会再动一次——所以一个超时的请求，用同一个 spend_id 重试是安全的，只有真正新的一笔打款才配一个新的。

哪些不收费

商户 API 里任何地方都没有网络手续费——账单、转账、红包全都在应用内部结清，不上链。账单上 那笔平台手续费是唯一的收费。

⚠️ 千万别自己算手续费

别把一个百分比写死，也别从票面金额倒推净额。档位和费率是会变的，一个过期的常数 会不知不觉地弄错您的账目。每一次都从账单上把记录下来的费用读出来。