APIリファレンス：送金と送金リンク

支払いを出すためのメソッドです。 送金は、アプリの残高からTelegramユーザーのウォレットへ直接資金を送ります。 送金リンクは、先に資金を確保しておく、受け取り可能なリンクです。 共通の決まり（認証、レスポンスの形、金額、spend_id）はMerchant APIリファレンスにまとめています。

transfer

POST /pay/api/transfer、スコープはpayouts、上限は1分間に30回です。 すぐに、まとめて完了します。保留の状態はありません。

パラメーター	型	必須	説明
user_id	integer	必須	受取人のTelegramユーザーID。受取人はすでにアプリのユーザーである必要があります。知らないIDへの支払いは、誰も開かないウォレットに入金されるのではなく、エラーになります
asset	string	必須	資産コード
amount	string	必須	正の10進数の文字列。1回あたりの最小額と最大額（現在のレートでの米ドル換算の目安）にも従います
spend_id	string	必須	べき等キー。1〜64文字で、支払いごとに重複しない値
comment	string	任意	1024文字まで。受取人に表示されます
disable_send_notification	boolean	任意	trueにすると、Telegramで受取人に通知しません

結果は送金オブジェクトです。 transfer_id・hash・user_id・asset・amount・amount_minor・spend_id・comment・status（常にcompleted）・created_at・completed_atです。

エラーは404 user_not_found（受取人がアプリを使ったことがない）・409 recipient_blocked・400 amount_too_smallと400 amount_too_big（1回あたりの範囲外）・409 insufficient_funds・404 unknown_asset・400 invalid_amountと、spend_idの409 idempotency_conflict・409 idempotency_in_progressです。

transferBatch

POST /pay/api/transferBatch、スコープはpayouts、上限は1分間に10回です。 大量の支払いのための拡張で、1回の呼び出しで最大100件送れます。

パラメーターはitemsの1つです。 配列の各項目が、transferのパラメーター一式（user_id・asset・amount・spend_idと、任意のcomment・disable_send_notification）です。 spend_idは同じ一括の中で重複できません。 重複していると、何も実行されないまま400 duplicate_spend_idで呼び出し全体が失敗します。

各項目は独立して、順番に処理されます。1件失敗しても、ほかの項目が巻き戻ることはありません。 一部の項目が失敗しても、呼び出し自体はHTTP 200とok: trueを返すので、必ず項目ごとに確かめてください。

• 成功：{"ok": true, "spend_id": "…", "result": <transfer object>}
• 失敗：{"ok": false, "spend_id": "…", "error": {"code": …, "name": "…"}}。エラー名は単体のtransferと同じです

一括の項目は、単体の送金とべき等性の名前空間を共有します。 一括全体を送り直しても、1件を同じspend_idで単体のtransferとして送り直しても、二重に支払われず元の結果が返ります。

getTransfers

GET /pay/api/getTransfers、スコープはreadです。 絞り込みはasset・transfer_ids（カンマ区切り）・spend_id（完全一致。自分のキーで支払いを引けます）と、offset・countです。 {"items": [transfer, …]}を新しい順に返します。

createCheck

POST /pay/api/createCheck、スコープはchecks、上限は1分間に60回です。 アプリの残高から資金を確保して、1回だけ使える送金リンクを作ります。 リンクを持っている人なら誰でも、または指定した相手だけが、自分のウォレットに受け取れます。 金額は作成した瞬間に確保されます（getBalanceのavailableからonholdへ移ります）。

パラメーター	型	必須	説明
asset	string	必須	資産コード
amount	string	必須	正の10進数の文字列
pin_to_user_id	integer	任意	このTelegramユーザーIDの相手だけが受け取れます
pin_to_username	string	任意	この@usernameの相手だけが受け取れます（@は省略できます。pin_to_user_idも指定した場合は無視されます）。そのユーザー名は、アプリの既存のユーザーのものである必要があります
spend_id	string	任意	べき等キー（拡張）。指定してください

結果は送金リンクオブジェクトです。 check_id・hash・asset・amount・amount_minor・bot_check_url（t.meの受け取りリンク）・status（active・activated）・pin_to_user_id・created_at・activated_atです。 受け取られると、選んで受け取るcheck_activatedのWebhookが発火します。

エラーは404 unknown_asset・400 invalid_amount・404 user_not_found（指定したユーザー名が誰とも一致しない）・409 insufficient_fundsと、spend_idのエラーです。

deleteCheck

POST /pay/api/deleteCheck、スコープはchecksです。 パラメーターはcheck_idの1つです。 まだ受け取られていない送金リンクをキャンセルし、確保していた金額をアプリの残高に戻してtrueを返します。 エラーは404 check_not_found・409 check_not_active（すでに受け取られた、または削除済み）です。

getChecks

GET /pay/api/getChecks、スコープはreadです。 絞り込みはasset・check_ids（カンマ区切り）・status（active・activated）と、offset・countです。 {"items": [check, …]}を新しい順に返します。 削除された送金リンクは返りません。