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は実装で扱ってください。

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

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

呼び出し回数の制限

資金を動かすメソッドには、アプリごと（そのアプリのすべてのトークンで共有）の回数制限があります。 1分間あたりの上限は、createInvoiceとcreateCheckが60、refundInvoiceとtransferが30、transferBatchが10です。 読み取り系のメソッドに制限はありません。 きちんと作られた実装が引っかかることはありませんが、再送を繰り返すループは引っかかります。 rate_limitedが返ったら、続けて叩かずに間隔を空けてください。

べき等性

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

費用がかからないもの

Merchant APIには、ネットワーク手数料はどこにもありません。 請求書も送金も送金リンクも、すべてアプリの中、オフチェーンで完結します。 費用は請求書のサービス手数料だけです。

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

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