Telegramボットの暗号資産決済：請求書・Webhook・送金
Merchant APIは、ボットやサービス向けのTgPay Crypto決済APIです。アプリとトークンを作成し、コードから請求書を発行して、署名付きの支払い通知をWebhookで受信できます。対応するMCPエージェントに連携作業を依頼することもできます。ウォレット残高からの支払いはサービス内で処理されます。ブロックチェーンからの支払いには、選択したネットワークの承認が必要です。
APIベースURL：app.tgpaycrypto.com/pay/api・テストネット：testnet.tgpaycrypto.com
トークン取得から決済まで4つの手順
請求書を作成し、リンクを提示して、支払いイベントを受信します。
アプリを作成
ボットで「その他→Merchant API」を開き、名前とWebhookのURLを入力します。トークンは一度だけ表示されるため、サーバー側で保管してください。
請求書を作成
createInvoiceへのPOSTリクエストで、暗号資産または法定通貨の金額、説明、期限を指定します。レスポンスに支払いリンクが含まれます。
支払いリンクを表示
ボットのボタンやリンクから、ウォレット残高で支払えます。高額な支払いはPINまたはFace IDで確認します。
Webhookを処理
HMAC-SHA256で署名されたinvoice_paidを受信します。署名を検証し、update_idで重複を除外してから商品を提供します。
AIエージェントに連携の準備を依頼
Merchant APIにはMCPサーバーがあります。対応するエージェントクライアントで接続すると、ドキュメントの参照、アプリ作成の申請、Webhook設定、連携コードの作成支援を行えます。アプリはTelegramで承認し、結果を確認してテストしてください。
- 手順 1
エージェントに依頼を送信
お使いのアカウントやワークスペースでリモートMCPを利用できるエージェントクライアントを使用してください。依頼文はアプリの「その他→Merchant API→AIエージェントを連携」にもあります。
- 手順 2
Telegramでアプリを承認
エージェントがt.meリンクを提示します。ボットに表示された依頼を確認して承認します。リンクは1回限り有効で、承認するまでアプリは作成されません。
- 手順 3
連携を完了してテスト
エージェントは限定権限のトークンを受け取り、請求書、サブスクリプションプラン、Webhookの設定を支援します。Webhook署名用の鍵を取得するには、アプリでメイントークンを再発行し、自分のサーバー上で安全に保管してください。
この手順で発行されるトークンは、支払いの受付とWebhook設定に対応します。送金、送金リンクの発行、返金はできません。資金を外へ動かす操作には、別途管理する権限が必要です。
エージェントでの導入手順はドキュメントへConnect the MCP server (https://app.tgpaycrypto.com/mcp) and integrate payments via the Merchant API.
claude mcp add --transport http tgpay https://app.tgpaycrypto.com/mcp
クライアントの設定でapp.tgpaycrypto.com/mcpをMCPサーバーとして追加
https://testnet.tgpaycrypto.com/mcp
手数料と上限
このページの作成時点で公開されている上限カタログの値です。最新の条件はアプリで確認してください。
Merchant APIの機能
アプリにはウォレットと別の残高があります。請求書の支払いが反映され、送金や送金リンクの作成で引き落とされます。
請求書と返金
暗号資産の固定金額、法定通貨での価格、支払者が決める金額に対応します。匿名の支払者を含め、全額または一部の返金ができます。
サブスクリプション
利用者がプランに一度同意すると、以降は各期間の料金を自動で引き落とし、毎回イベントを送信します。
送金と送金リンク
アプリ残高からTelegram利用者に送金できます。設定された条件を満たす人が受け取れる送金リンクも作成できます。
Webhook
invoice_paidは常に送信されます。請求書や送金リンクの期限切れ、送金リンクの受取、返金、一括送金、サブスクリプションのイベントは、アプリごとに通知を有効にできます。
テストネット
@tgpaycrypto_testnet_botで同じAPIとミニアプリを使えます。ホーム画面のボタンから、1時間に1回テスト用の暗号資産を受け取れます。
AIエージェントとMCP
リモートMCPに対応したエージェントクライアントでapp.tgpaycrypto.com/mcpを接続してください。Telegramで承認すると、エージェントがアプリを作成し、連携作業を支援できます。利用前に結果を確認し、テストしてください。
Crypto Bot APIとの互換性
メソッド名、{ok, result}形式、Webhookの署名方式に互換性があります。ベースURLとトークンを変更し、使用するメソッドの動作を確認してください。
トークンの権限を管理
権限を限定したトークン、即時更新、指定利用者のみへの送金や送金停止、漏えいに備えた1日あたりの送金限度額を設定できます。
APIについての質問
トークン、Webhook署名、テスト、他のAPIからの移行についてまとめています。
適用中のルールによっては、本人確認の完了が必要です。本人確認エラーで作成できない場合は、アプリで確認を済ませて再試行してください。
TgPayCrypto-API-Signatureヘッダーは、メイントークンのSHA-256を鍵に、リクエスト本文のHMAC-SHA256を計算した値です。本文の元のバイト列で検証してください。検証が成功するまでは商品を提供したり、支払い済みにしたりしないでください。
Merchant APIはCrypto Bot APIのメソッド、{ok, result}形式、10進文字列の金額、署名方式に対応します。ベースURLとトークンを変更したうえで、連携をテストしてください。Crypto-Pay-API-Tokenヘッダーも別名として利用できます。
テストネットでは同じAPIとミニアプリを利用できます。ボットは@tgpaycrypto_testnet_bot、ベースURLはtestnet.tgpaycrypto.com/pay/apiです。ホーム画面のボタンから1時間に1回、テスト用の1,000USDT、1,000GRAM、0.01BTCを受け取れます。本番用とテスト用のトークンは共用できません。
エージェントは権限を限定したトークンで、請求書やサブスクリプションプランの作成、残高や統計の確認、Webhook設定を行います。送金、送金リンク、返金には追加の権限と対象機能の有効化が必要です。
Merchant APIの公開ドキュメント
docs.tgpaycrypto.comにメソッド一覧、OpenAPI仕様、導入手順を掲載しています。