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`で既定の有効期間。結果の`expiration_date`を確認してください
`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・400 unknown_asset・400 unsupported_fiat・400 paid_btn_url_required、レート固定では400 rate_lock_fiat_only・409 ratelock_disabled・409 rate_unavailable（対応資産の新しいレートがないとき。送り直してください）です。

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

支払者はミニアプリでウォレットの残高から支払います。十分な残高と支払いの確認が必要で、成立するとすぐに完了し、ネットワーク手数料はかかりません。外部のウォレットからの入金が選べる場合は、入金アドレスと支払い期限が表示されます。入金は支払者自身のウォレットに反映されます。自動支払いには、そのアドレスへの入金、十分な利用可能残高、送金・出金の制限がないこと、支払い要求と請求書の期限内であることが必要です。遅れて届いた入金は支払者のウォレットに残り、請求書の支払いが済んだことにはなりません。加盟店側では、通常と同じpaidの請求書になり、Webhook URLを設定していればinvoice_paidイベントを受け取ります。追加のパラメーターやフィールドはありません。

法定通貨建ての請求書では、支払い時点で暗号資産の金額を計算し、選んだ資産の最小単位に切り上げます。その金額から加盟店手数料が引かれます。有効な固定レートも最新のレートもない場合は、古いレートで成立させず、支払いは失敗します。

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

rate_lock_secondsを渡すと、作成の時点ですべての対応資産のレートが記録されます。固定が効いている間、支払者には記録された金額がそのまま表示され、支払いも記録されたレートで換算されます。その間のレート変動は加盟店側が引き受けます。指定した時間は、対応する範囲に調整されます。実際の期限は結果のrate_lock_untilを確認してください。

固定が切れても、期限内の請求書は支払い時点のレートで支払えます。両方の期限をそろえるには、固定できる時間の範囲内でexpires_inを指定し、レスポンスのexpiration_dateとrate_lock_untilが一致するか確認してください。

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に対する拡張です。実際に支払われた暗号資産の全額、またはその一部を、アプリの残高から支払った相手に返します。名前を伏せた相手にも、それが誰かを明かさずに返せます。法定通貨建ての請求書ではpaid_assetとpaid_amountを使い、法定通貨から再換算はしません。

パラメーター	型	必須	説明
`invoice_id`	integer	必須	支払い済みの請求書
`amount`	string	任意	返す暗号資産の金額。元の支払い資産（法定通貨建てでは`paid_asset`）で指定します。省略すると未返金の残り全額。一部返金の累計は、元の暗号資産の支払額を超えることはできません
`spend_id`	string	任意	べき等キー。タイムアウトした再送で二重に返金しないよう、指定してください

結果は、累計のrefunded_amount・refunded_minorが入った請求書オブジェクトです。 refunded_atは全額返金された時点で記録されます。ステータスはpaidのままです。サービス手数料は返りません。swap_toで別の資産に交換した場合も、元の支払い資産の残高を十分に用意する必要があります。受信を有効にしている場合は、返金のたびに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です。