Merchant APIの手数料と限度額

請求書には、受け取る金額から引かれるサービス手数料がかかります。 送金と送金リンクには、金額の制限があります。 以下の数値は現在の設定であって、契約の条件ではありません。 表示と食い違う場合はアプリが正しく、いちばん確かなのは自分の支払い済みの請求書です。

請求書の手数料

支払者は必ず請求書の額面を支払います。 手数料は加盟店の側から引かれ、アプリの残高には手数料を引いた額が入ります。

取引量に応じた段階を適用する前の手数料は、請求金額の**3%**です。実際の料率は、設定されている段階と直近30日間の支払い済み請求書の決済額によって決まります。

数字そのものより大事な決まりが2つあります。

• **手数料は支払いの時点で確定します。**あとで料率が変わっても、支払い済みの請求書には影響しません。
• **決済額が増えると料率が変わります。**直近30日間の決済額が増えると、自動的に下の段階に移ります。 申請するものも、設定するものもありません。

実際にいくら引かれたかは、支払い済みの請求書のfee_assetとfee_amountでわかります。 invoice_paidのWebhookのペイロードからでも、getInvoicesからでも読めます。 帳簿にはこの値を使ってください。

返金では手数料は戻りません。 refundInvoiceが支払者に送る金額はアプリの残高から出て、手数料は返らないままです。 一部返金でも同じです。

サブスクリプションの課金にも、加盟店の側の手数料がかかります。 課金ごとの金額は、subscription_chargedのWebhookのcharge.feeに入っています。

送金の限度額

transferには1回あたりの最小額と最大額があります。 資産ごとの数値ではなく、米ドル換算額で示されます。 この限度額により拒否された場合に備え、amount_too_smallとamount_too_bigを実装で扱ってください。

未登録のusername宛てでは、支払いモードが許可していれば保留中の送金が作成されます。送金と送金リンクをご覧ください。

送金は次の場合にも失敗します。

• その資産のアプリの残高が足りないとき
• user_idで指定した受取人がアプリのユーザーではないとき。存在しないTelegram IDや打ち間違えたIDへの支払いは、誰も開かないウォレットに入金されるのではなく、エラーになります
• 受取人のアカウントがブロックされているとき

1日の支払限度額

所有者は、アプリの送金設定で直近24時間の限度額を設定できます。送金、送金リンク、アプリ残高からの支払いは、この限度額を共有します。超える場合は403 daily_cap_exceededが返り、バッチでは最初の支払い前に確認されます。返金はこの限度額に含みません。getMeでdaily_payout_max_usd_centsとdaily_payout_spent_usd_centsを取得できます。

所有者の制限により、送金、送金リンク、返金が拒否される場合もあります（403 verification_required）。一時停止中は503 merchant_payouts_pausedが返ります。

呼び出し回数の制限

資金を動かすメソッドには、アプリごとに、そのアプリの全トークンで共有する回数制限があります。1分間の上限は、createInvoiceとcreateCheckが60、refundInvoiceが30、transferが30、transferBatchが10です。updateAppとcreateSubscriptionPlanにも上限があります。APIリファレンスをご覧ください。rate_limitedが返ったら、再試行までの間隔を延ばしてください。

べき等性

transferでは、自分で生成した**spend_id**が必須です。 createCheckとrefundInvoiceでも渡せます。 同じ値と同じパラメーターを使うと、資金がもう一度動くことはなく、元の結果が返ります。 タイムアウトしたリクエストは同じspend_idで安全に再送でき、本当に新しい支払いだけが新しい値を使います。

費用がかからないもの

Merchant APIには、ネットワーク手数料はどこにもありません。 請求書も送金も送金リンクも、すべてアプリの中、オフチェーンで完結します。 請求書とサブスクリプションの課金には、サービス手数料がかかる場合があります。任意の自動交換には、その交換の見積もりが適用されます。支払者が外部ウォレットから入金する場合は、送金元やネットワークの手数料がかかる場合があります。

⚠️ 手数料を自分で計算しない

料率を決め打ちで書いたり、額面から差し引き後の金額を組み立て直したりしないでください。 段階も料率も変わるので、古い定数は気づかないうちに帳簿を狂わせます。 毎回、請求書に記録された手数料を読んでください。