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

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

資金を外へ出す3つのメソッドはすべて、アプリの支払いモードに従います。 新しいアプリは最初から誰にでも支払えます。所有者が絞り込んだ場合は、一覧にある受取人にしか支払えないか（403 recipient_not_allowed）、誰にも支払えません（403 payouts_disabled）。 モードは所有者がミニアプリで設定します。APIからは変更できません。 どのような目的の支払いが認められるかは、Merchant API利用規約に定めています。

transfer

POST /pay/api/transfer、スコープはpayouts、1分間の上限：30。 既存のユーザーにはすぐに反映されます。まだ登録されていないusernameを指定すると、pendingの送金が作成されます。資金は、そのユーザー名の受取人がボットを開くまでエスクローで保留されます。未受取の資金は、30日の期限（expires_at）が過ぎるとアプリの残高に戻ります。会計処理に反映する前に、status: "returned"で返金を確認してください。 invite_urlは受取人に直接共有してください。一度もボットを起動していない相手には、ボットからメッセージを送れません。最終的なステータスはcompletedまたはreturnedです。transfer_completed・transfer_returnedのWebhookの受信を有効にするか、getTransfersで定期的に確認してください。

パラメーター	型	必須	説明
user_id	integer	user_idかusernameのどちらか一方	受取人のTelegramユーザーID。受取人はすでにアプリのユーザーである必要があります
username	string	user_idかusernameのどちらか一方	受取人のユーザー名。@は省略できます。まだ登録されていないユーザー名を指定すると、送金は保留中になります
asset	string	必須	資産コード
amount	string	必須	正の10進数の文字列。1回あたりの最小額と最大額（現在のレートでの米ドル換算額）が定められています
spend_id	string	必須	べき等キー。1〜64文字で、支払いごとに重複しない値
comment	string	任意	1024文字まで。受取人に表示されます
disable_send_notification	boolean	任意	trueにすると、即時に完了する送金では受取人への通知を送りません。保留中の送金を受け取ったときは、この設定にかかわらず通知を送ります

user_idとusernameは、どちらか一方だけ指定してください。どちらも指定しない場合や両方を指定した場合は、パラメーターが不正として拒否されます。

結果は送金オブジェクトです。 transfer_id・hash・user_id・recipient_username・asset・amount・amount_minor・spend_id・comment・status（pending・completed・returned）・created_at・completed_at・expires_at・invite_urlです。新しい受取人を待っている間、user_idはnullの場合があります。completed_atは完了するまでnullです。

エラーは403 payouts_disabled・403 recipient_not_allowed（支払いモードによる）・404 user_not_found（IDが不明、または受取人が利用できない状態）・400 invalid_recipient（受取人のユーザー名の形式が不正）・400 amount_too_smallと400 amount_too_big（1回あたりの範囲外）・409 insufficient_funds・400 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またはusername、asset・amount・spend_idと、任意のcomment・disable_send_notification）です。 同じバッチ内でspend_idを重複させることはできません。 重複していると、何も実行されないまま400 duplicate_spend_idで呼び出し全体が失敗します。項目の構造が不正な場合や、支払いモード・1日の支払限度額に合わない場合も、送金前にリクエスト全体が拒否されることがあります。受け付けられると、結果はresult.itemsに返ります。

各項目は独立して、順番に処理されます。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（完全一致。指定したキーで支払いを検索できます）・status（pending・completed・returned）と、offset・countです。 {"items": [transfer, …]}を新しい順に返します。

createCheck

POST /pay/api/createCheck、スコープはchecks、1分間の上限：60。 既定では、アプリの残高から資金を確保して、1回だけ使える送金リンクを作ります。recipientsの拡張では、受取人の一覧とそれぞれの金額を指定できます。 リンクを持っている人なら誰でも、または指定した相手だけが、自分のウォレットに受け取れます。 合計額は作成時に確保されます（getBalanceのavailableからonholdへ移ります）。送金リンクの作成には、送金と同じ金額の範囲と1日の支払限度額が適用されます。

パラメーター	型	必須	説明
asset	string	必須	資産コード
amount	string	recipientsがなければ必須	正の10進数の文字列。recipientsを指定した場合は、その一覧から合計額が計算されます
pin_to_user_id	integer	任意	このTelegramユーザーIDの相手だけが受け取れます
pin_to_username	string	任意	この@usernameの相手だけが受け取れます（@は省略できます。pin_to_user_idも指定した場合は無視されます）。そのユーザー名は、アプリの既存のユーザーのものである必要があります
spend_id	string	任意	べき等キー（拡張）。指定してください
recipients	array	任意	拡張。1〜100件。それぞれにuser_idまたはusernameと、正の10進数の文字列のamountを指定します。単独の受取人指定とは併用できません
password	string	任意	拡張。受取時に必要なパスワード。64文字まで
expires_in	integer	任意	拡張。有効期間（秒）。省略または0で無期限

結果は送金リンクオブジェクトです。 check_id・hash・asset・amount・amount_minor・bot_check_url（t.meの受け取りリンク）・status（active・activated）・pin_to_user_id・created_at・activated_at・expires_at・recipientsです。通常のリンクのrecipientsはnullで、受取人一覧がある場合は各項目にuser_id・username・amount・amount_minor・claimed_atが入ります。受け取るたびに、受信を有効にしていればcheck_activatedのWebhookが送信されます。受取人一覧のあるリンクではactivated_slotも含まれます。期限切れになると未受取分が返金され、受取人一覧のあるリンクではcheck_expiredが送信される場合があります。

現在のレスポンスでは、期限切れを含め、全額が受け取られていないリンクはstatus: "active"になります。expires_atも確認し、activeだけで受取可能と判断しないでください。

エラーは403 payouts_disabled・403 recipient_not_allowed（支払いモードによる。allowlistモードでは、単独指定でも一覧指定でも、すべての受取人が許可された一覧に載っている必要があります）・400 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, …]}を新しい順に返します。 削除された送金リンクは返りません。