API リファレンス

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

本ページでは、マーチャント連携向けのエンドポイントを一覧します。専用ページがないエンドポイントは、関連するコンセプトページで説明しています。

/b2b/v1/* 配下のエンドポイントは、あなたの シークレット キー (sk_…) で HMAC 署名します。これはあなたのバックエンドが呼び出すサーフェスです。マーチャントダッシュボードとホスト型チェックアウトはそれぞれ独自のエンドポイントを使用しており、連携用 API には含まれません。

チェックアウト

メソッド	パス	目的	備考
`POST`	`/b2b/v1/checkout-sessions/quick`	1 回の呼び出しでセッションを作成 — 注文 + チェックアウトセッションを同時に発行。	リクエストボディとサンプルはクイックスタートを参照。
`POST`	`/b2b/v1/checkout-sessions`	既存の注文に対してセッションを作成。プラットフォームが既に独自の注文モデルを持っていて、試行ごとに 1 セッションを発行したい場合に使用。	2 ステップフロー。
`GET`	`/b2b/v1/checkout-sessions/by-order/{order_id}`	注文に対して発行された全セッションを一覧表示。	バイヤーがセッションを放棄して、過去の試行をダッシュボードに表示したい場合に便利。

注文

注文は時間を超えた請求対象エンティティです。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 を届けるだけです。トークンはバックエンド (下記) またはマーチャントダッシュボードから発行できます。再発行とキャンセルはダッシュボードで処理します。

メソッド	パス	認証	目的
`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`) を発火。

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

両方のフローに適用。以下のエンドポイントは返金そのもの (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 Pay が決済可能なすべてのチェーン (mainnet + testnet、環境でフィルタ)。
`GET`	`/v1/supported/tokens`	それらのチェーン上のすべてのステーブルコイン。
`GET`	`/v1/supported/currencies`	`order.currency` で受け入れる通貨。

ヘルス

メソッド	パス	認証	目的
`GET`	`/health`	なし (公開)	死活確認。`{"status":"ok"}` を返します。死活監視はここを指してください。

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

すべてのリストエンドポイントは同じクエリパラメータを受け取り、同じエンベロープを返します。カーソルは不透明で、オフセットの代わりに使われるため、ページング中に新しい行が追加されてもページはずれません。

クエリパラメータ	型	デフォルト	備考
`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 のときは省略されます。カーソルは不透明な文字列として扱ってください。

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

本ページはマーチャント連携向けのエンドポイントを対象としています。掲載されていないエンドポイントや OpenAPI スペックが必要な場合は、サポートにご連絡ください。