API リファレンス

以下のエンドポイントはすべて JSON を扱い、https://api.infraio.xyz (本番) または https://api-dev.infraio.xyz (テスト) の配下にあり、 HMAC-SHA256 で認証します — 署名手順は認証、エラーエンベロープの形はエラーを参照。

本ページはインデックスです。各行は既存の解説のうち最も深いものへリンクします; パスのみを参照している行は、エンドポイントは現存するものの、専用のリファレンスページではなく関連コンセプトページ内でインラインにドキュメント化されています。

ゲートウェイのパスプレフィックスとその認証モデル:

/b2b/v1/* — シークレット キー (sk_…) で HMAC 署名。マーチャントバックエンドのサーフェス。
/payment/v1/* — Bearer JWT (ダッシュボードセッション)。マーチャントダッシュボードのフロントエンドが使用; サードパーティ統合者向けではありません。
/pub/v1/* — パス内に bearer-of-truth (返金リクエストの rfqt_… トークン)。資格情報なし。ブラウザからの呼び出しでも安全。
/checkout/:key/* — ホスト型チェックアウトフロー用の公開プレフィックス。key は作成時に返される cst_… セッションキー; 呼び出し元はバイヤーのブラウザのみ。資格情報なし。

チェックアウト

メソッド	パス	目的	備考
`POST`	`/b2b/v1/checkout-sessions/quick`	1 回の呼び出しでセッションを作成 — 注文 + チェックアウトセッションを同時に発行。	リクエストボディとサンプルはクイックスタートを参照。
`POST`	`/b2b/v1/checkout-sessions`	既存の注文に対してセッションを作成。プラットフォームが既に独自の注文モデルを持っていて、試行ごとに 1 セッションを発行したい場合に使用。	2 ステップフロー。
`GET`	`/b2b/v1/checkout-sessions/by-order/{order_id}`	注文に対して発行された全セッションを一覧表示。	バイヤーがセッションを放棄して、過去の試行をダッシュボードに表示したい場合に便利。
`GET`	`/checkout/{session_key}`	公開 — ホスト型チェックアウトページがこれを取得。バイヤー向けのフィールドのみ (内部参照なし)。	署名なし; `session_key` を bearer-of-truth として扱う。
`POST`	`/checkout/{session_key}/intent`	公開 — ホストされたページで決済方法を選択。デポジットアドレス付きの `PaymentIntent` を発行。	checkout-web からユーザの方法選択時に呼び出される。
`POST`	`/checkout/{session_key}/verify`	公開 — バイヤーが tx ハッシュを貼り付けて確認待ちをショートカット。	ハッシュが誤っていればチェーンウォッチャーに引き継がれる。

注文

注文は時間を超えた請求対象エンティティです。1 つの注文が複数のチェックアウトセッションに紐付くこともあります (例: バイヤーが放棄してリトライ)。

メソッド	パス	目的	備考
`POST`	`/b2b/v1/orders`	セッションを伴わずに注文を作成。	すぐにリダイレクトせず、バイヤーに後で支払いリンクを送りたい場合に使用。
`GET`	`/b2b/v1/orders/{id}`	1 件の注文を行明細 + ステータス付きで読み取り。	ステータス: `PENDING` → `PAID` \| `PARTIAL_PAID` \| `CANCELED`。返金後: `PARTIALLY_REFUNDED` \| `REFUNDED`。
`GET`	`/b2b/v1/orders/by-merchant/{merchant_id}`	あなたの注文をカーソルページネーションで一覧表示。	カーソルプロトコルはカーソルページネーションを参照。
`PATCH`	`/b2b/v1/orders/{id}/cancel`	未払いの注文をキャンセル済みにマーク。`order.canceled` を発火。	既に支払い済みの注文では失敗。
`PATCH`	`/b2b/v1/orders/{id}/reopen`	自動キャンセル (`canceled_reason=payment_timeout`) を取り消し。	TTL 切れ後にバイヤーが戻ってきた場合に便利。

返金

サガフローとトークンライフサイクルは返金コンセプトページを参照してください。

マーチャント開始

メソッド	パス	目的	備考
`POST`	`/b2b/v1/merchants/{merchant_id}/refunds`	マーチャント開始の返金。自動承認 (`PENDING` をスキップ)。	即座に `payment.refund.approved` を発火。

カスタマー開始 — 返金リクエストトークン

バイヤーは当方のホスト型ページで返金フォームに記入します; あなたはトークンを発行して URL を届けるだけです。発行パスは 2 つ (バックエンド向けの HMAC、ダッシュボード向けの JWT)、公開トークンパスは 3 つ (コンテキスト読み取り、提出、再発行リクエスト)、ダッシュボード専用パスが 2 つ (再発行の処理) あります。

メソッド	パス	認証	目的
`POST`	`/b2b/v1/merchants/{merchant_id}/refund-requests`	HMAC (`sk_…`)	バックエンドからトークンを発行。ボディ: `{ref_type, ref_value, amount, ttl_seconds?, metadata?, hide_summary?, hide_header?}`。`ref_type` は `order_id` / `order_number` / `session_id` / `session_key` のいずれか; `ref_value` は対応する識別子。`amount` は必須で、バイヤーが提出できる最大額をロックします。デフォルト TTL 30 分。`refund_request.created` (`source: b2b`) を発火。
`POST`	`/payment/v1/merchants/{merchant_id}/refund-requests`	JWT (ダッシュボード)	マーチャントダッシュボードの Issue Refund モーダルからトークンを発行。ボディ形は B2B 版と同じ。デフォルト TTL 24 時間。`refund_request.created` (`source: dashboard`) を発火。
`GET`	`/pub/v1/refund-requests/{token}`	パス内トークン	公開 — checkout-web がフォームコンテキストを読み取る (注文サマリ、ロック額、現在の有効状態)。
`POST`	`/pub/v1/refund-requests/{token}/submit`	パス内トークン	公開 — バイヤーがフォームを提出。ボディ: `{reason, refund_to_address, amount?, metadata?}`。`amount` は任意 — 省略時はマーチャントがロックしたリンク額を使用; 指定時はサーバーが `amount ≤ ロック額` を強制。`Refund` 行を作成、`payment.refund.requested` を発火、レシートページ用に `{link_token, refund_id}` を返却。
`POST`	`/pub/v1/refund-requests/{token}/request-renewal`	パス内トークン	公開 — 期限切れ後にバイヤーが新しいリンクを要求。ボディ: `{customer_note?}`。`refund_request.renewal_requested` を発火。
`GET`	`/payment/v1/merchants/{merchant_id}/refund-requests/renewals`	JWT (ダッシュボード)	マーチャント再発行ウィジェット用に保留中の `RENEWAL_REQUESTED` トークンを一覧表示。カーソルページネーション。
`POST`	`/payment/v1/merchants/{merchant_id}/refund-requests/renewals/{token}/issue-new`	JWT (ダッシュボード)	再発行を承認 — 新しい `ACTIVE` トークンを発行し、古いものを廃止。`refund_request.renewed` + `refund_request.created` (`source: renewal`) を発火。
`GET`	`/payment/v1/merchants/{merchant_id}/refund-requests/by-order/{order_id}`	JWT (ダッシュボード)	注文に対して発行された全返金リクエストトークンを有効状態付きで一覧表示。最新順。
`POST`	`/payment/v1/merchants/{merchant_id}/refund-requests/{token}/send-email`	JWT (ダッシュボード)	返金リクエストリンクをメールで顧客に配信するキューを投入。ボディ: `{to}`。`refund_request.email_send_requested` を発火。
`POST`	`/payment/v1/merchants/{merchant_id}/refund-requests/{token}/cancel`	JWT (ダッシュボード)	マーチャントのキルスイッチ — `ACTIVE` または `RENEWAL_REQUESTED` を `CANCELED` に遷移。ボディ: `{reason?}`。冪等: ステータスが既に遷移済みの場合の二度目の呼び出しは再発火せず成功を返す。最初の遷移時に `refund_request.canceled` を発火。

返金ライフサイクル (作成後)

両方のフローに適用。以下のエンドポイントは Refund 行 (id は rfn_… で始まる) を対象とし、リクエストトークンではありません。

メソッド	パス	目的	備考
`GET`	`/b2b/v1/refunds/{id}`	1 件の返金を読み取り。	ステータス: `PENDING` → `APPROVED` → `EXECUTED` \| `REJECTED`。
`GET`	`/b2b/v1/refunds/by-merchant/{merchant_id}`	あなたの返金をカーソルページネーションで一覧表示。	—
`POST`	`/b2b/v1/refunds/{id}/approve`	`PENDING` の返金を承認 (カスタマー開始のみ — マーチャント開始は既に `APPROVED` で着地)。	暗号資産: `APPROVED` で着地、次に `/submit-tx` を呼び出す。
`POST`	`/b2b/v1/refunds/{id}/reject`	`PENDING` の返金を拒否。	`payment.refund.rejected` を発火。
`POST`	`/b2b/v1/refunds/{id}/submit-tx`	暗号資産のみ — ブロードキャストしたオンチェーン tx ハッシュをスタンプ。	ボディ: `{tx_hash, network, token_address}` — 3 つすべて必須。

カタログ (読み取り専用)

メソッド	パス	目的
`GET`	`/v1/supported/networks`	InfraIO が決済可能なすべてのチェーン (mainnet + testnet、環境でフィルタ)。
`GET`	`/v1/supported/tokens`	それらのチェーン上のすべてのステーブルコイン。
`GET`	`/v1/supported/currencies`	`order.currency` で受け入れる法定通貨。
`GET`	`/v1/merchants/payment-methods`	このマーチャントが有効化している方法 — プラットフォームカタログ + マーチャント別トグルの結合。checkout-web が使用。
`GET`	`/v1/public/merchants/{merchant_id}/branding`	公開 — チェックアウトページが自身のスキニング用に読み取る情報。

ヘルス

メソッド	パス	認証	目的
`GET`	`/health`	なし (公開)	単純な liveness プローブ — `{"status":"ok"}` を返します。これ (`/v1` プレフィックスなし) が唯一の認証不要なヘルスエンドポイントです — k8s / 死活監視はここを指してください。
`GET`	`/payment/v1/merchants/{merchant_id}/health`	ダッシュボード JWT	マーチャント別ヘルスビュー — 最近のインテント精算率、sweep バックログ。自分のステータスページに便利。ダッシュボードのセッショントークンが必要で、B2B API キーではありません。`/payment/` ゲートウェイプレフィックス配下でのみ到達可能 — 素の `/v1/...` パスは公開ルーティングされていません。
`GET`	`/payment/v1/stats/health`	ダッシュボード JWT	マーチャントのワークスペースツリー全体の集約ヘルス。公開の liveness プローブではありません — `/payment/` ゲートウェイプレフィックス配下で他と同じ JWT 認証の背後にあります。

カーソルページネーション

すべてのリストエンドポイントは同じクエリパラメータを受け取り、同じエンベロープを返します。スクロール中に行が着地してもページがずれないよう、オフセットではなく不透明カーソル (base64url エンコードされた (created_at, id)) を使います。

クエリパラメータ	型	デフォルト	備考
`cursor`	`string`	—	不透明 — 直前のレスポンスの `next_cursor` をそのままコピー。
`limit`	`int`	`20`	`1..100`。
`sort_dir`	`'asc' \| 'desc'`	`desc`	`(created_at, id)` でソート。
`from` / `to`	`RFC3339`	—	任意の時間ウィンドウフィルタ。
`search`	`string`	—	サポートされている場合のフリーテキストフィルタ。

レスポンスエンベロープ:


{
  "orders": [ /* page rows */ ],
  "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wNS0...",
  "has_next": true
}

has_next は常に存在します。next_cursor は has_next が false のときは省略されます。カーソルをパースしようとしないでください — その形は内部のものであり、変更される可能性があります。

このページに含まれないもの

このインデックスはマーチャント向けサーフェスを対象とします — /admin/* 配下のエンドポイント (ダッシュボードツール、KYB レビュー、ネットワーク管理) と内部 gRPC ルートは意図的に掲載していません。 swag が生成する OpenAPI スペックは全サーフェスをカバーします; 必要であればサポートに連絡いただければ最新スナップショットを共有します。