Telegramボットの暗号資産決済：請求書・Webhook・送金
Merchant APIは、ボットやサービス向けのTgPay Crypto決済APIです。ボットでアプリとトークンを作成し、コードから請求書を発行して、支払い時に署名付きWebhookを受信できます。MCPサーバーを使ってAIエージェントに連携を依頼することもできます。決済はサービス内で行うため、ネットワーク手数料や承認待ちはありません。
APIベースURL：app.tgpaycrypto.com/pay/api・テストネット：testnet.tgpaycrypto.com
トークン取得から決済まで4つの手順
請求書を作成し、リンクを提示して、支払いイベントを受信します。
アプリを作成
ボットで「その他→Merchant API」を開き、名前とWebhookのURLを入力します。トークンは一度だけ表示されるため、サーバー側で保管してください。
請求書を作成
createInvoiceへのPOSTリクエストで、暗号資産または法定通貨の金額、説明、期限を指定します。レスポンスに支払いリンクが含まれます。
支払いリンクを表示
ボットにボタンやリンクを設置します。利用者はウォレット残高から支払えます。
Webhookを処理
HMAC-SHA256で署名されたinvoice_paidを受信します。署名を検証し、update_idで重複を除外してから商品を提供します。
AIエージェントに連携の準備を依頼
Merchant APIにはMCPサーバーがあります。URLを渡すと、エージェントがドキュメントを読み、承認後にアプリを作成し、Webhookとコードを準備します。トークンを手動でコピーする必要はありません。
- 手順 1
エージェントに依頼を送信
Claude Code、claude.ai、Claude Desktop、ChatGPTなどのMCPクライアントを利用できます。アプリの「その他→Merchant API→AIエージェントを連携」にも同じ依頼文があります。
- 手順 2
Telegramでアプリを承認
エージェントがt.meリンクを提示します。ボットに表示された依頼を確認して承認します。リンクは1回限り有効で、承認するまでアプリは作成されません。
- 手順 3
エージェントが設定を完了
限定権限のトークンを受け取り、請求書、サブスクリプションプラン、Webhookを設定します。Webhook署名用の鍵はアプリで管理できます。
この手順で発行されるトークンは、支払いの受付とWebhook設定に対応します。送金、送金リンクの発行、返金はできません。資金を外へ動かす操作には、別途管理する権限が必要です。
エージェントでの導入手順はドキュメントへConnect the tgpay MCP server (https://app.tgpaycrypto.com/mcp) and integrate payments via the TgPay 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
app.tgpaycrypto.com/mcpをエージェントに渡すと、アプリ作成、Webhook設定、連携コードの準備を行います。アプリ作成はボットで承認します。
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仕様、導入手順を掲載しています。