商户 API 的费用和限额 · TgPay Crypto API

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

账单手续费

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

费率为账单金额的 1.5%，所有账单统一按这一费率收取，没有按流水的优惠。

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

费率在付款时确定并锁定。 之后的费率变化不会影响已支付的账单。
手续费按币种的最小单位向下取整，所以金额很小的账单可能完全不收手续费。

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

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

订阅扣款也可能收取商户手续费，目前为 0%。每次扣款的实际手续费都会记录在 subscription_charged webhook 的 charge.fee 字段中。

转账限额

transfer 的单笔转账上限为 25,000 美元，按美元等值金额计算，而不是为每个币种单独设定金额。平台也可以设置单笔下限，目前没有下限。集成时请处理超限导致的 amount_too_big；如果日后设置了下限，也应处理 amount_too_small（两者都是 400）。当前没有美元报价的币种不受该上限约束。

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

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

您在该币种下的应用余额不足，
收款人从未打开过 TgPay Crypto——打给一个不存在或打错的 Telegram ID 会报错，而不是给一个没人会打开的钱包入账，
收款人的账号被封了——返回同样的 404 user_not_found。

每日打款限额

所有者可在应用的付款设置中设置滚动 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 里任何地方都没有网络手续费——账单、转账、红包全都在应用内部结清，不上链。账单和订阅扣款可能收取平台手续费，可选的自动兑换使用兑换报价。从外部钱包为付款人充值时，转出钱包或网络还可能收费。

⚠️ 千万别自己算手续费

别把一个百分比写死，也别从票面金额倒推净额。费率可能变化，继续使用过时的常数会导致账目出错，而且不易察觉。每一次都从账单上读取记录下来的费用。