Merchant APIの手数料と限度額

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

請求書の手数料

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

手数料は請求金額の1.5%です。すべての請求書に同じ料率が適用され、取引量に応じた割引はありません。

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

手数料は支払いの時点で確定します。あとで料率が変わっても、支払い済みの請求書には影響しません。
手数料は資産の最小単位に切り捨てられます。そのため、ごく少額の請求書では手数料がかからないこともあります。

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

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

サブスクリプションの課金にも加盟店側の手数料がかかる場合があります。現在は0%です。各課金の手数料は、subscription_chargedのWebhookのcharge.feeフィールドに記録されます。

送金の限度額

transferの送金ごとの限度額は、25,000ドルです。資産別の金額ではなく、米ドル相当額で設定されています。送金ごとの下限額が設定される場合もありますが、現在はありません。この制限で金額が拒否されたときに備え、連携側ではamount_too_big、下限額が導入された場合はamount_too_smallも処理してください（どちらも400です）。その時点で米ドルのレートがない資産には、上限は適用されません。

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

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

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

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

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

料率をコードに直接書き込んだり、額面から手数料差し引き後の金額を自分で計算したりしないでください。料率は変わることがあり、古い定数は気づかないうちに帳簿を狂わせます。毎回、請求書に記録された手数料を読んでください。