<!-- Source: https://docs.infraio.xyz/ja/api-reference -->
<!-- Last updated: 2026-10-04 -->

# API リファレンス

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

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

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

## チェックアウト

| メソッド | パス | 目的 | 備考 |
| --- | --- | --- | --- |
| `POST` | `/b2b/v1/checkout-sessions/quick` | 1 回の呼び出しでセッションを作成 — 注文 + チェックアウトセッションを同時に発行。 | リクエストボディとサンプルは [クイックスタート](https://docs.infraio.xyz/ja/get-started/quickstart#2-create-a-checkout-session-server) を参照。 |
| `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}` | あなたの注文をカーソルページネーションで一覧表示。 | カーソルプロトコルは [カーソルページネーション](#cursor-pagination) を参照。 |
| `PATCH` | `/b2b/v1/orders/{id}/cancel` | 未払いの注文をキャンセル済みにマーク。`order.canceled` を発火。 | 既に支払い済みの注文では失敗。 |
| `PATCH` | `/b2b/v1/orders/{id}/reopen` | 自動キャンセル (`canceled_reason=payment_timeout`) を取り消し。 | TTL 切れ後にバイヤーが戻ってきた場合に便利。 |

## 返金

サガフローとトークンライフサイクルは [返金コンセプトページ](https://docs.infraio.xyz/ja/concepts/refunds)
を参照してください。

### マーチャント開始

| メソッド | パス | 目的 | 備考 |
| --- | --- | --- | --- |
| `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` | — | サポートされている場合のフリーテキストフィルタ。 |

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

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

`has_next` は常に存在します。`next_cursor` は `has_next` が `false` の
ときは省略されます。カーソルは不透明な文字列として扱ってください。

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

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