APIリファレンス：請求書と返金

請求書のメソッドはcreateInvoice・getInvoices・deleteInvoice・refundInvoiceです。 共通の決まり（認証、レスポンスの形、金額、spend_id）はMerchant APIリファレンスにまとめています。 手順に沿った解説は請求書で支払いを受け取るです。

createInvoice

POST /pay/api/createInvoice、スコープはinvoices、上限は1分間に60回です。

パラメーター	型	必須	説明
currency_type	string	任意	crypto（既定）またはfiat
asset	string	cryptoモード	請求する資産（例USDT）。fiatとは併用できません
fiat	string	fiatモード	価格を表す法定通貨（getCurrenciesのis_fiatの行）
accepted_assets	string / array	任意	fiatモードのみ。支払者が使える資産を、カンマ区切りの文字列（"USDT,GRAM"）かJSON配列で指定します。省略するとすべての対応資産
amount	string	open_amountがなければ必須	正の10進数の文字列。cryptoモードでは資産の単位、fiatモードでは法定通貨の単位（小数点以下2桁まで）
open_amount	boolean	任意	拡張、cryptoモードのみ。金額を固定せず、支払者が支払い時に入力します（寄付やチップ向け）。amountとは併用できません
description	string	任意	1024文字まで。支払者に表示されます
hidden_message	string	任意	2048文字まで。支払いが終わったあとだけ支払者に表示されます
payload	string	任意	4096文字までの独自データ。請求書とWebhookにそのまま返ります
allow_comments	boolean	任意	支払者がコメントを付けられるようにします（既定はtrue）
allow_anonymous	boolean	任意	支払者が名前を伏せられるようにします（既定はtrue）
paid_btn_name	string	任意	支払い後のボタン。viewItem・openChannel・openBot・callbackのいずれか
paid_btn_url	string	任意	ボタンのhttp(s)のURL。paid_btn_nameを指定したときは必須
swap_to	string	任意	受け取った支払いをこの資産へ自動で交換します。ベストエフォートで、支払い時に交換できなければ、交換されないまま支払いは成立します
expires_in	integer	任意	請求書が期限切れになるまでの秒数。最大2678400（31日）。省略または0で無期限
rate_lock_seconds	integer	任意	拡張、fiatモードのみ。作成時の換算レートをこの秒数だけ固定します（下記）

結果、そしてinvoice_paidのWebhookのペイロードは、請求書オブジェクトです。 主なフィールドは次のとおりです。

• 識別とステータス：invoice_id、hash（pay_urlの中の公開ID）、status（active・paid・expired）、pay_url。 pay_urlは支払者に送るt.meのリンクです（bot_invoice_url・mini_app_invoice_url・web_app_invoice_urlは同じものの別名です）。
• 金額：amount（額面。法定通貨建ての請求書では法定通貨の単位、それ以外は暗号資産。金額を固定しない請求書が未払いの間はnull）、amount_minor、支払い済みの法定通貨建て請求書ではpaid_asset・paid_amount・paid_fiat_rate（実際に請求した暗号資産と、使われたレート）。
• 手数料：fee_asset・fee_amount。支払い時に記録され、帳簿にはこの値を使います（feeとusd_rateは非推奨のCrypto Bot互換の別名です）。手数料と限度額で説明しています。
• 支払者：paid_by_user_id（名前を伏せた場合はnull）・paid_anonymously・comment。
• 返金（拡張）：refunded_amount・refunded_minor（累計）とrefunded_at。 refunded_atは全額返金された時点で記録されます。
• レート固定（拡張）：rate_lock_untilとrate_lock_rates。 資産ごとに記録されたレートで、固定を指定しなかった場合はnullです。
• 作成時の内容：description・hidden_message・payload・paid_btn_name・paid_btn_url・expiration_date（expires_atは別名）と、交換関連のフィールド（swap_to・is_swapped・swapped_to・swapped_rate・swapped_outputなど）。

エラーは400 invalid_currency（assetとfiatの取り違え）・400 invalid_amount・404 unknown_asset・400 unsupported_fiat・400 paid_btn_url_required、レート固定では400 rate_lock_fiat_only・409 ratelock_disabled・409 rate_unavailable（対応資産の新しいレートがないとき。送り直してください）です。

請求書が支払われるしくみ

支払者は、ミニアプリでウォレットの残高から支払います。 すぐに完了し、ネットワーク手数料はかかりません。 外部のウォレットから請求書に入金することもできます。 アプリが入金アドレスを表示し、その送金は支払者自身のウォレットに届き、届いた時点で自動的に請求書が支払われます。 どちらの場合も加盟店から見えるものは同じで、paidの請求書とinvoice_paidのWebhookです。 追加で扱うパラメーターもフィールドもありません。

法定通貨建ての請求書では、暗号資産の金額は支払いの時点で計算され、加盟店に有利な方向へ切り上げられるので、法定通貨の額面を下回ることはありません。 新しいレートが手に入らない場合は、古いレートで成立させず、支払者の側で支払いが失敗します。

法定通貨建ての請求書でレートを固定する

rate_lock_secondsを渡すと、作成の時点ですべての対応資産のレートが記録されます。 固定が効いている間、支払者には記録された金額がそのまま表示され、支払いも記録されたレートで換算されます。 その間のレート変動は加盟店側が引き受けます。 固定できる時間は、60秒からプラットフォームの上限（現在は15分）までに収められます。

固定が切れても請求書は支払える状態のまま残り、静かに支払い時点の換算へ戻ります。 見積もりと一緒に請求書も終わらせたい場合は、expires_inに同じ値を設定してください。

getInvoices

GET /pay/api/getInvoices、スコープはreadです。 絞り込みはasset・fiat・invoice_ids（カンマ区切り）・status（active・paid・expired。expiredは拡張で、activeは期限を過ぎた請求書を含みません）と、offset・countです。 {"items": [invoice, …]}を新しい順に返します。

deleteInvoice

POST /pay/api/deleteInvoice、スコープはinvoicesです。 パラメーターはinvoice_idの1つです。 未払いの請求書をキャンセルしてtrueを返します。 エラーは404 invoice_not_found・409 invoice_already_paidです。 支払い済みの請求書は削除できません。資金がすでに動いているからです。

refundInvoice

POST /pay/api/refundInvoice、スコープはrefunds、上限は1分間に30回です。Crypto Botに対する拡張です。 支払い済みの請求書の額面、またはその一部を、アプリの残高から支払った相手に返します。 名前を伏せた相手にも、それが誰かを明かさずに返せます。

パラメーター	型	必須	説明
invoice_id	integer	必須	支払い済みの請求書
amount	string	任意	返す金額。請求書の資産で指定します。省略すると未返金の残り全額。一部返金は額面に達するまで積み上がります
spend_id	string	任意	べき等キー。タイムアウトした再送で二重に返金しないよう、指定してください

結果は、累計のrefunded_amount・refunded_minorが入った請求書オブジェクトです。 refunded_atは全額返金された時点で記録されます。 ステータスはpaidのままです。 サービス手数料は返りません。 返金のたびに、選んで受け取るrefund_completedのWebhookが発火します。

エラーは404 invoice_not_found・409 invoice_not_paid・409 already_refunded（返す残りがない）・409 amount_too_big（未返金の残りを超えている）・409 insufficient_funds・400 invalid_amountと、spend_idの409 idempotency_conflict・409 idempotency_in_progressです。