Merchant APIリファレンス

すべてのメソッドに共通する決まりと、読み取り専用のカタログ系メソッドをまとめます。 メソッドごとのページは請求書と返金、送金と送金リンク、サブスクリプション、Webhookです。

このAPIはCrypto Bot互換です。 既存のCrypto Bot向けの実装は、ベースURLとトークンを変えるだけで動きます。 その範囲を超える部分は、以下で拡張と記します。

API全体を記述した機械可読のOpenAPI 3.1仕様も、これらのページとあわせて公開しています。 すべてのメソッド、オブジェクト、エラー名、Webhookが入っています。crypto-pay-openapi.yaml・crypto-pay-openapi.jsonです。 コードジェネレーター、APIクライアント、AIツールに読み込ませてください。

ベースURLと認証

すべてのメソッドはhttps://app.tgpaycrypto.com/pay/api/<methodName>にあります。

リクエストは必ず**TgPayCrypto-API-Token**ヘッダーのトークンで認証します（Crypto-Pay-API-Tokenも互換の別名として受け付けます。両方送られた場合は正式なほうが優先されます）。 トークンがない、無効、無効化済み、または削除されたアプリのトークンだった場合は、401 unauthorizedが返ります。

トークンは<app_id>:<secret>という形で、作成時と再発行時に一度だけ表示されます。 サーバーはハッシュだけを保存します。開発者向けのはじめかたで説明しています。

トークンとスコープ

認証のしかたが同じ、2種類の資格情報があります。

• メイントークン：すべてのメソッドを呼べます。Webhookに署名できる鍵は、これだけです。
• 制限付きトークン（拡張）：アプリごとに最大10個まで持てます。 その他 → Merchant APIの制限付きトークンから作成し、それぞれにラベルとスコープの組み合わせを設定します。1つを無効化してもほかには影響せず、メイントークンを再発行しても制限付きトークンは変わりません。

スコープ	呼べるメソッド
（有効なトークンであればどれでも）	getMe, getCurrencies, getExchangeRates
read	getBalance, getStats, getInvoices, getChecks, getTransfers, getSubscriptionPlans, getSubscriptions
invoices	createInvoice, deleteInvoice
refunds	refundInvoice
payouts	transfer, transferBatch
checks	createCheck, deleteCheck
subscriptions	createSubscriptionPlan, archiveSubscriptionPlan, cancelSubscription

スコープは足し算で、それぞれ独立しています。 invoicesはreadを含まないので、請求書を作るだけのサーバーには、何も読めないトークンを渡せます。 トークンが持たないスコープのメソッドを呼ぶと、403 scope_requiredが返ります。 getMeは今のトークンのscopes（メイントークンではnull）とtoken_nameを返すので、手元のトークンが何かはいつでも確かめられます。

リクエストとレスポンス

• **読み取り系のメソッドはGET**で、パラメーターはクエリ文字列で渡します。資金を動かすメソッドはPOSTのみで、パラメーターはJSONボディ、form-urlencoded、クエリパラメーターのいずれでも渡せます（食い違う場合はボディが優先されます）。multipart/form-dataは受け付けません。
• レスポンスはすべて、同じ形のJSONです。 成功は{"ok": true, "result": …}、エラーは{"ok": false, "error": {"code": <HTTP status>, "name": "<error_name>"}}です。 分岐はerror.nameで行ってください。これが機械可読の、変わらない文字列です。
• 例外が1つあります。GETメソッドのクエリの値が型として不正な場合（たとえばoffset=abc）は、この形の外側で{"detail": …}のボディとともにHTTP 422が返ります。クエリの値は型を合わせて送ってください。

金額

• 暗号資産の金額は、コイン単位の10進数の文字列です（"10.5"）。JSONの数値ではありません。レスポンスにはamount_minor（拡張）も入ります。これは最小単位の整数を文字列にしたもので、wei規模の整数はJavaScriptのNumberでは表しきれないためです。
• 資産ごとのdecimalsはgetCurrenciesから取れます。決め打ちにせず、ここを基準に金額の計算を組んでください。
• 法定通貨の金額は、小数点以下2桁までです。
• レートは固定小数点の文字列で、数値ではありません。

ページネーション

一覧系のメソッド（getInvoices・getChecks・getTransfers・getSubscriptions）は、offset（既定は0）とcount（既定は100、最大1000。getSubscriptionsは最大500）を受け取り、{"items": […]}を新しい順に返します。IDでの絞り込み（invoice_ids・check_ids・transfer_ids）は、カンマ区切りの整数のリストです。 日時はどこでもISO 8601の文字列です。

べき等性：spend_id

資金を動かすメソッドは、呼び出す側が生成する**spend_id**キー（1〜64文字）を受け取ります。 transferとtransferBatchの各項目では必須、createCheckとrefundInvoiceでは任意です（拡張。任意でも使ってください）。 同じキーと同じパラメーターで送り直すと、資金を二重に動かさず、元の結果をそのまま返すので、タイムアウトしたリクエストはいつでも安全に再送できます。 同じキーで違うパラメーターを送ると409 idempotency_conflictが返り、元の処理がまだ動いているうちに送り直すと409 idempotency_in_progressが返ります。

呼び出し回数の制限

アプリごとで、そのアプリのすべてのトークンで共有します。 超えると429 rate_limitedが返ります。

メソッド	上限
createInvoice, createCheck	1分間に60回
refundInvoice, transfer	1分間に30回
transferBatch	1分間に10回

読み取り系のメソッドに制限はありません。 プラットフォームのメンテナンス中は、書き込み系のメソッドが503 maintenanceを返し、読み取りは動き続けます。

カタログとアカウントのメソッド

getMe

GET /pay/api/getMe、パラメーターはありません。 アプリの情報を返します。 app_id・name・payment_processing_bot_username・webhook_url・webhook_events（アプリが選んだ拡張のWebhook種別）と、前述のトークンのscopes・token_nameです。

getBalance

GET /pay/api/getBalance、パラメーターはありません。 対応するすべての資産について、残高が0でも1行ずつ返します。 currency_code・available（使える残高）・onhold（発行済みの送金リンクで押さえられている資金）・amount_minorです。

getCurrencies

GET /pay/api/getCurrencies、パラメーターはありません。APIが対応しているものの正式な一覧です。 暗号資産の行（is_blockchain: true）と、請求書の値づけに使える法定通貨の行（is_fiat: true）が入ります。 どの行にもcode・name・decimalsとis_stablecoinフラグがあります。

getExchangeRates

GET /pay/api/getExchangeRates、パラメーターはありません。 暗号資産から法定通貨への交換レートを返します。 source・target・rate（固定小数点の文字列）・is_validです。 is_validがfalseのときは、表全体が古いキャッシュから返っています。 そのレートは目安としてだけ扱ってください。

getStats

GET /pay/api/getStats、start_atとend_atは任意です（ISO 8601。既定の期間は直近24時間）。 volume（期間内に支払われた請求書の米ドル換算額）・conversion（作成に対する支払い済みの割合、パーセント）・unique_users_count・created_invoice_count・paid_invoice_countと、実際の期間の範囲を返します。 日付を読み取れない場合は、400 invalid_dateが返ります。

すべてのメソッドが返しうるエラー

HTTP	error.name	発生する場面
401	unauthorized	トークンがない、無効、または無効化済み
403	scope_required	トークンにそのメソッドのスコープがない
400	invalid_request	パラメーターを読み取れない、または不正（POST）
429	rate_limited	回数の上限を超えた
503	maintenance	プラットフォームのメンテナンス中（書き込み系のメソッド）
500	internal_error	予期しないサーバーエラー

メソッドごとのエラーは、それぞれのメソッドのページにまとめています。