開発者向けのはじめかた

ミニアプリで加盟店アプリを作成し、APIトークンを一度だけコピーすれば、APIを呼び出せます。設定はすべてその他 → Merchant APIにあります。

手順

その他 → Merchant APIを開き、アプリの作成を選びます。
アプリ名（たとえば「My Store」）を入力します。必要であれば**Webhook URL（任意）**も入力します。
フォームの利用規約に同意し、アプリを作成をタップします。求められた場合はPINまたは生体認証で確認します。アプリを作成すると、Merchant API利用規約に同意したことになります。APIを何に使ってよく、何に使ってはいけないかを定めたものです。
**APIトークンをその場でコピーしてください。**表示されるのは一度だけです。アプリはトークンのハッシュしか保存しません。
TgPayCrypto-API-Tokenヘッダーにトークンを入れて、最初のリクエストを送ります。

最初のリクエスト

APIのベースURLはhttps://app.tgpaycrypto.com/pay/apiです。まずgetMeを呼んで、トークンが有効かどうかを確かめてください。 getBalanceはアプリの残高を、getCurrenciesは使える資産を返します。

読み取り系のメソッドはGETです。書き込み系のメソッド（createInvoice・transfer・createCheck・deleteInvoice・deleteCheckなど）はPOSTのみです。パラメーターはJSONボディ、form-urlencoded、クエリパラメーターのいずれでも送れます。金額とべき等キーをURLのアクセスログに残さないよう、リクエストボディで送ることを推奨します。

テストネット

まずはテストネットで開発してください。APIもミニアプリも同じで、テスト用の暗号資産に金銭的価値はありません。

	メインネット	テストネット
ボット	@tgpaycryptobot	@tgpaycrypto_testnet_bot
ベースURL	`https://app.tgpaycrypto.com/pay/api`	`https://testnet.tgpaycrypto.com/pay/api`
MCPサーバー	`https://app.tgpaycrypto.com/mcp`	`https://testnet.tgpaycrypto.com/mcp`

アプリとトークンは別です。テストネットのトークンはメインネットでは使えず、その逆も同じです。資金を用意するには、テストネットのミニアプリを開き、ホーム画面のテストコインを受け取るをタップします。テスト用の資産が通常の入金として反映されます。無効なネットワークの資産は対象外です。反映された内容と、次に受け取れる時刻はアプリに表示されます。自分のもう1つのアカウントを、テストの請求書を支払う顧客にできます。

入金と出金はシミュレーションで、実際のブロックチェーン取引は行われません。テストネットの入金アドレスに実際の資金を送らないでください。APIの仕様は共通ですが、利用できる機能、レート、限度額はメインネットと異なる場合があります。開発が終わったら、@tgpaycryptobotで本番用のアプリを作成し、ベースURLを切り替えてください。

アプリの管理

Merchant APIでアプリを開くと、アプリIDと残高を確認でき、次の操作ができます。

Webhook URLの設定と変更：Webhookで入力して保存します。
追加のWebhookイベントを選ぶ：Webhookの項目にある追加のWebhookイベントのトグルで、invoice_paid以外のイベント種別も受け取れます（Webhookリファレンスを確認してください）。
APIが支払える相手を絞る：送金設定にあるAPI経由の送金は、新しいアプリではすべてのユーザーです。一覧のユーザーのみに切り替えて受取人を一覧に登録するか、誰にも支払わない実装なら無効にしてください。トークンが漏れた場合の備えです（支払いモードを確認してください）。
制限付きトークンを作る：アクセスとトークンを開き、制限付きトークンからAPIトークンを追加で発行できます。それぞれ選んだスコープだけに絞られます（APIリファレンスを確認してください）。
トークンを再発行：アクセスとトークンで新しいトークンを発行し、古いトークンをその場で無効にします。トークンが漏れたときに使ってください。新しいトークンも、作成時と同じく一度だけ表示されます。
削除：先に利用可能な残高を払い出してください。残っているとapp_has_balanceで拒否されます。未受取の送金リンクや保留中の送金も、削除前に解決してください。削除すると一覧から消え、トークンは使えなくなります。支払い履歴は保持されます。

Webhook

Webhook URLを設定すると、署名付きのJSONボディがそのURLへPOSTされます。

{ "update_id": …, "update_type": "invoice_paid", "request_date": …, "payload": { … } }

署名はTgPayCrypto-API-Signatureヘッダーに入ります（TgCryptoPay-API-SignatureとCrypto-Pay-API-Signatureも互換の別名です）。生のボディに対するHMAC-SHA256で、鍵はメインAPIトークンのSHA-256です。ペイロードの中身を信用する前に、必ず検証してください。

配信に失敗した場合は、間隔を延ばしながら上限回数まで再送されます。その間update_idは変わりません。重複の排除はこの値を基準にして、ハンドラーはべき等にしてください。

Webhook URLを設定していれば、invoice_paidに個別の受信設定は不要です。それ以外の種別、期限切れの請求書・受け取られた送金リンク・返金・サブスクリプションのイベントは、追加のWebhookイベントのトグルで選んで受け取ります。全一覧とペイロードの形、再送の間隔はWebhookリファレンスにあります。

⚠️ APIトークンは秘密鍵と同じように守る

このトークンは、アプリの残高からの支払いを許可します。自分のサーバーに置き、モバイルアプリ、フロントエンドのバンドル、リポジトリに入る設定ファイルには絶対に置かないでください。漏れたかどうか判断がつかないときは、再発行してください。再発行はすぐ終わり、費用もかかりません。そして、それぞれのサーバーには必要な権限だけを渡してください。 invoicesスコープだけを持つ制限付きトークンは、請求書を作成・削除できますが、送金、送金リンクの作成、返金はできません。