商户 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。

打款模式允许时，未知 username 会创建待领取打款，详见转账和红包。

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

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

每日打款限额

所有者可在应用的付款设置中设置滚动 24 小时限额。转账、红包及应用余额转出共用此限额。超出时返回 403 daily_cap_exceeded，批量打款会在第一笔执行前检查。退款不计入此限额。getMe 返回 daily_payout_max_usd_cents 和 daily_payout_spent_usd_cents。

所有者账户限制也可能阻止转账、红包和退款（403 verification_required）；临时暂停则返回 503 merchant_payouts_paused。

频率限制

涉及资金的方法按应用限流（该应用的所有令牌共用一份额度），每分钟的上限：createInvoice 和 createCheck 是 60，refundInvoice 是 30，transfer 是 30，transferBatch 是 10。updateApp 和 createSubscriptionPlan 也有限流，详见 API 参考。遇到 rate_limited 时，请逐步延长重试间隔。

幂等

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

哪些不收费

商户 API 里任何地方都没有网络手续费——账单、转账、红包全都在应用内部结清，不上链。账单和订阅扣款可能收取平台手续费，可选的自动兑换使用兑换报价。从外部钱包为付款人充值时，转出钱包或网络还可能收费。

⚠️ 千万别自己算手续费

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