開発者向けのはじめかた

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

手順

1. その他 → Merchant APIを開きます。
2. アプリ名（たとえば「My Store」）を入力します。必要であればWebhook URLも入力します。
3. アプリを作成をタップします。
4. **APIトークンをその場でコピーしてください。**表示されるのは一度だけです。 アプリはトークンのハッシュしか保存しません。
5. TgCryptoPay-API-Tokenヘッダーにトークンを入れて、最初のリクエストを送ります。

最初のリクエスト

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

読み取り系のメソッドはGETです。 資金を動かすメソッド、つまりcreateInvoice・transfer・createCheckとそれぞれの削除メソッドは、意図的にPOSTのみにしてあります。 金額とべき等キーをアクセスログに残さないためです。 パラメーターはJSONボディ、form-urlencoded、クエリパラメーターのいずれでも送れます。

アプリの管理

Merchant APIにあるアプリのカードには、アプリIDと残高が表示され、次の操作ができます。

• Webhook URLの設定と変更：入力して保存します。
• 追加のWebhookイベントを選ぶ：Webhook URLを設定すると追加のWebhookイベントのトグルが使えるようになり、invoice_paid以外のイベント種別も受け取れます（Webhookリファレンスを確認してください）。
• 制限付きトークンを作る：制限付きトークンからAPIトークンを追加で発行できます。 それぞれ選んだスコープだけに絞られます（APIリファレンスを確認してください）。
• トークンを再発行：新しいトークンを発行し、古いトークンをその場で無効にします。 トークンが漏れたときに使ってください。 新しいトークンも、作成時と同じく一度だけ表示されます。
• 削除：アプリは認証できなくなりますが、残高と支払い履歴は残ります。 アプリを削除しても、資金が消えることはありません。

Webhook

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

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

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

配信は指数バックオフで長い時間をかけて再送され、その間update_idは変わりません。 重複の排除はこの値を基準にして、ハンドラーはべき等にしてください。

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

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

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